--- title: Internationalisierung (i18n) order: 8 icon: phosphor-duotone:translate tags: [anleitungen, i18n] --- # Internationalisierung (i18n) Übersetze deine Docs in andere Sprachen, jede mit ihrem eigenen URL-Präfix, ihrem eigenen `` und einem automatischen Sprachumschalter - kein Plugin, kein separater Build-Schritt nötig. ## Eine Locale hinzufügen Übersetzte Inhalte liegen unter `docs/i18n//`, wobei sie deinen regulären `docs/`-Baum Seite für Seite spiegeln: ``` docs/ ├── index.md ├── guides/ │ └── setup.md └── i18n/ ├── es/ │ ├── index.md │ └── guides/ │ └── setup.md └── ar/ └── index.md ``` `` wird sowohl zum Ordnernamen als auch zum gebauten URL-Präfix (`docs/i18n/es/guides/setup.md` → `/es/guides/setup/`), halte ihn daher kurz - ein reiner Sprachcode (`es`, `fr`) oder ein Sprach-Region-Paar (`pt-BR`, `zh-Hans`) funktionieren beide, nur Buchstaben/Ziffern/Bindestriche. Dein regulärer `docs/`-Baum ist immer die **Standard-Locale**, unpräfixiert an der Wurzel der Website gebaut, genau wie heute - das Hinzufügen von `docs/i18n/` ändert daran nichts. Gib jeder Locale ein Anzeige-Label (und, für eine Rechts-nach-links-Sprache, ihre eigene Schreibrichtung) in `bxsites.json`: ```json { "i18n": { "defaultLocale": { "code": "en", "label": "English" }, "locales": [ { "code": "es", "label": "Español" }, { "code": "ar", "label": "العربية", "dir": "rtl" } ] } } ``` `defaultLocale` muss nur gesetzt werden, wenn deine Standard-Locale nicht Englisch ist; `locales` ist die Liste von allem anderen. Jeder `docs/i18n//`-Ordner wird automatisch gebaut, sobald er existiert - `locales` liefert nur sein Anzeige-Label und seine Textrichtung. Ein Ordner ohne passenden `locales`-Eintrag wird trotzdem gebaut (mit seinem reinen Code als eigenem Label), das ist also Metadaten, nicht das, was die Funktion ein- oder ausschaltet. ## Was gebaut wird Jede Locale ist ein echter, vollständig unabhängiger Build - eigene `search-index.json`, eigene `assets/`, alles, was ein normaler Build erzeugt - geschrieben unter `site//` (`site/es/`, `site/ar/`). Nichts muss pro Locale aktiviert werden: sobald `docs/i18n/es/` existiert, übernimmt `bxSites build` das von selbst. ## Nicht übersetzte Seiten Eine Locale muss nicht jede Seite übersetzt haben, um nutzbar zu sein. Eine Seite, die in `docs/i18n/es/` fehlt, wird trotzdem unter ihrer erwarteten URL gebaut - sie zeigt den Inhalt der Standard-Locale, mit einem kleinen Hinweis oben auf der Seite, dass sie noch nicht übersetzt wurde. Nichts liefert einen 404, nichts sieht halbfertig aus, während eine Übersetzung noch in Arbeit ist. Die Navigation jeder Locale hat immer genau dieselbe Form wie die der Standard-Locale - dieselben Seiten, dieselbe Reihenfolge, dieselbe Verschachtelung (was auch immer die eigene Ordnerstruktur von `docs/`, oder eine explizite [`nav`](../configuration.md#nav), bereits erzeugt) - nur mit Titel/Inhalt jeder Seite, aus ihrer eigenen Übersetzung eingesetzt, wo eine existiert. Das ist auch das, was den Sprachumschalter funktionieren lässt: ein Sprachwechsel bringt dich auf *dieselbe Seite*, übersetzt oder nicht, niemals auf die Startseite dieser Locale. ## Der Sprachumschalter Sobald mehr als eine Locale existiert, rendert jedes Theme automatisch ein Sprach-Dropdown in der Kopfzeile - nichts, wozu man sich anmelden müsste, genau wie beim [Versionsumschalter](../configuration.md#versionierung). Wähle eine Locale, die du gerade nicht baust, und sie wird einfach gar nicht gerendert. ## Versionierte und übersetzte Docs Siehe [Versionierung](versioning.md) für `docs/versions//` selbst. Versionen und Locales lassen sich auf einer Ebene kombinieren: lege einen `docs/versions//i18n//`-Ordner neben die eigenen Seiten einer Version, der die eigene Struktur dieser Version genau so spiegelt, wie ein oberstes `docs/i18n//` `docs/` selbst spiegelt: ```text title="docs/versions/2.0/-Layout" docs/ versions/ 2.0/ index.md guides/ setup.md i18n/ es/ index.md # translated guides/ setup.md # untranslated pages still fall back, same as top-level i18n ``` Das baut `site/versions/2.0/es/`. Die eigenen Seiten der Standard-Locale einer Version (`site/versions/2.0/`) erhalten ebenfalls einen Sprachumschalter, der nur die Locales listet, für die *diese Version selbst* Übersetzungen hat - eine Version ohne eigenen `i18n/`-Unterordner wird genau so gerendert wie vorher, kein Umschalter gezeigt. Ein Versionswechsel fällt immer auf die eigene Standard-Locale dieser Version zurück (nimmt nie an, dass die Zielversion dieselbe Übersetzung hat); ein Locale-Wechsel bleibt immer auf der aktuellen Version. ## Was (vorerst) außen vor bleibt - **Theme-Chrome bleibt auf Englisch.** "Edit this page", "Last updated", der Suchplatzhalter und ähnliche UI-Texte werden noch nicht pro Locale übersetzt - nur dein eigener Seiteninhalt wird es. Die eigentliche Leseerfahrung einer Locale ist vollständig übersetzt; das umgebende Theme-Beiwerk nicht. - **Die RTL-Layout-Spiegelung ist grundlegend, nicht pixelgenau.** `dir="rtl"` wird korrekt gesetzt, und Sidebar/Kopfzeile spiegeln sich tatsächlich, aber ein paar dekorative Details (etwa die Seite des Akzentbalkens einer Admonition) drehen sich noch nicht mit. - **Keine automatische Übersetzung.** Jede Datei unter `docs/i18n//` wird von Hand verfasst, genau wie jede andere Markdown-Seite - es gibt keinen maschinellen Übersetzungsschritt. ## Eigene Icons und Includes Ein `custom:`-Icon-Verweis und ein `::: include` lösen beide gegen die eigenen `docs/assets/`/wiederverwendbaren Inhalte deines Projekts auf, unabhängig davon, welche Locale gerade gebaut wird - das sind gemeinsam genutzte Assets, nichts, was ein Übersetzer pro Locale duplizieren müsste. ## SEO Die Seiten jeder Locale sind neben denen der Standard-Locale in `sitemap.xml` und `llms.txt` enthalten, genauso wie es [versionierte](../configuration.md#versionierung) Seiten sind.