# Asciidoctor PDF: Kapitel bleibt „Chapter“ – Fehleranalyse & Workaround

## 🧩 Problem

Beim Generieren von PDFs mit `asciidoctor-pdf` (Version 2.3.19) wird die Kapitelüberschrift trotz korrekt gesetztem deutschen Theme und Sprache **nicht lokalisiert**:

```text
Chapter 1. Einführung
```

…statt:

```text
Kapitel 1. Einführung
```

---

## ✅ Erwartete Konfiguration

Folgendes wurde korrekt gesetzt:

- `chapter.title: "Kapitel {counter:chapter-number}. "` im Theme
- `locale: lang` im Theme
- Fonts korrekt eingebunden
- `:lang: de` entfernt aus `.adoc` (zur Sicherheit)
- Keine `de.yml` verwendet
- Keine Snap-Version oder Paketkonflikte
- Theme definitiv geladen (`font_size`, `base`, etc. wirksam)

---

## ❌ Ergebnis

Trotz aller Korrektheit:

- Ausgabe bleibt auf Englisch
- Lokalisierung über Theme wird ignoriert
- Das Verhalten ist **reproduzierbar auf mehreren Rechnern und Installationen**

---

## 🧨 Vermutete Ursache

Ein Bug oder ein Regressionseffekt in `asciidoctor-pdf` ab Version `2.3.0`, bei dem:

- entweder `chapter.title` aus Theme nicht mehr greift  
- oder durch eine andere Sprachverarbeitung überschrieben wird  

---

## ✅ Workaround

Statt auf automatische Kapitelüberschriften zu setzen, diese manuell überschreiben:

### Im `.adoc`:

```asciidoc
:sectnums!:

[discrete]
== Kapitel 1. Einführung
```

→ So wird die Kapitelzeile manuell gesetzt und `sectnums` deaktiviert.

---

## 📌 Empfehlung

- In Projekten mit PDF-Export: Immer testen, ob `theme.yml` wirklich angewendet wird
- Optional: eigene `make test-theme` Ziel im Makefile zur Überprüfung einbauen
- Bis Bug behoben ist: Kapitel manuell beschriften oder alternative Engine verwenden

---

## 🔗 Betroffene Versionen

- `asciidoctor-pdf 2.3.19`
- `asciidoctor 2.0.23`
- `ruby 3.1.x`
- UTF-8 / Linux / WSL – identisches Verhalten