--- title: Internationalisierung description: >- Stelle deine Dokumentation in mehreren Sprachen bereit – mit locale-bewusstem Routing, sprachspezifischer Navigation, übersetzter Benutzeroberfläche und SEO – alles konventionsbasiert. --- Blume stellt ein Projekt in vielen Sprachen bereit. Lege übersetzte Dateien an der richtigen Stelle ab, und Blume verdrahtet Routing, den Sprachumschalter, die Navigation pro Locale und SEO für dich – es gibt keine separate Routing-Ebene zu pflegen. Es ist optional: Ohne einen `i18n`-Block bleibt deine Website genau wie zuvor einsprachig. Es lässt sich außerdem mit [Versionierung](/docs/content/versioning) kombinieren – ein eingefrorener Snapshot behält seine Übersetzungen, und der Locale-Fallback funktioniert innerhalb jeder Version. ## Aktivieren [#enable-it] Füge einen `i18n`-Block hinzu, der deine Locales auflistet und angibt, welche die Standard-Locale ist: ```ts blume.config.ts lineNumbers i18n: { defaultLocale: "en", locales: [ { code: "en", label: "English" }, { code: "fr", label: "Français" }, { code: "ar", label: "العربية", dir: "rtl" }, ], } ``` Jede Locale hat einen `code` (wird in URLs verwendet), ein `label` (wird im Sprachumschalter angezeigt) und ein optionales `dir` für Rechts-nach-links-Schriften (standardmäßig `"ltr"`). Ein optionales `style` gibt [`blume translate`](/docs/reference/translate) freie Hinweise für die Locale – Register, Dialekt, Terminologie, z. B. `"Brazilian Portuguese, informal você"` – sodass die Wahl von der allerersten Übersetzung an festgelegt ist, statt vom Agenten entschieden zu werden. ## Übersetzte Inhalte organisieren [#organize-translated-content] Die Standard-Locale liegt im Stammverzeichnis deiner Inhalte. Jede weitere Locale ist ein Ordner der obersten Ebene, benannt nach ihrem `code`, der die Standardstruktur spiegelt: ```txt docs/ index.mdx -> / guides/quickstart.mdx -> /guides/quickstart fr/ index.mdx -> /fr guides/quickstart.mdx -> /fr/guides/quickstart ar/ index.mdx -> /ar ``` | Datei | Route | | ------------------------------- | ----------------------- | | `docs/index.mdx` | `/` | | `docs/guides/quickstart.mdx` | `/guides/quickstart` | | `docs/fr/guides/quickstart.mdx` | `/fr/guides/quickstart` | Du übersetzt nur die Dateien, die du möchtest – alles andere greift automatisch auf einen Fallback zurück (siehe [Fallbacks](#fallbacks)). ### Dateinamen-Suffixe [#filename-suffixes] Du möchtest Übersetzungen lieber neben dem Original behalten? Setze `parser: "dot"` und benenne Dateien mit einem Locale-Suffix, statt Ordner zu verwenden: ```txt docs/ guides/quickstart.mdx -> /guides/quickstart (default) guides/quickstart.fr.mdx -> /fr/guides/quickstart (French) ``` Gut geeignet für spärliche Übersetzungen – lege die wenigen übersetzten Seiten daneben ab, ohne den gesamten Baum zu spiegeln. ### Gemeinsame Dateien [#shared-files] Für Inhalte, die in jeder Sprache gleich sind – ein Changelog, eine Statusseite – füge einen `$`-Marker hinzu, damit eine Datei alle Locales ohne Duplikate bedient: ```txt docs/changelog.$.mdx -> /changelog and /fr/changelog (same content) docs/guides/meta.$.ts (folder meta applied to every locale) ``` Eine locale-spezifische `meta.ts` überschreibt die gemeinsame für diese Sprache weiterhin. ## URLs der Standard-Locale [#default-locale-urls] Standardmäßig hat die Standard-Locale kein URL-Präfix (`/`, `/guides/quickstart`), während andere Locales ein Präfix erhalten (`/fr/…`). So bleiben die URLs deiner Hauptsprache sauber. Um jeder Locale ein Präfix zu geben, einschließlich der Standard-Locale: ```ts blume.config.ts lineNumbers i18n: { // … hideDefaultLocalePrefix: false, // /en/…, /fr/… } ``` ## Navigation pro Locale [#per-locale-navigation] Jede Sprache erhält ihre eigene Seitenleiste, aufgebaut aus den Dateien dieser Locale – so können Übersetzungen in Struktur, Reihenfolge oder Beschriftungen abweichen. Auch [`meta.ts`](/docs/content/meta)-Dateien von Ordnern werden pro Locale aufgelöst: Lege unter dem Standard-Parser `dir` eine `meta.ts` in `fr/guides/` ab, um die französische Gruppe unabhängig zu sortieren. Unter dem `dot`-Parser liegen Übersetzungen neben den Originalen, sodass die `meta.ts` eines Ordners für jede Locale gilt. Alles andere zur [Navigation](/docs/content/navigation) funktioniert genauso, pro Sprache. Header-Tabs werden konfiguriert und nicht aus dem Inhalt abgeleitet, daher werden ihre Beschriftungen in `blume.config.ts` lokalisiert: Ein Tab-`label` akzeptiert neben der einfachen String-Form auch eine Zuordnung pro Locale (`{ en: "Docs", fr: "Documentation" }`) und greift für Locales, die du nicht ausgefüllt hast, auf den Eintrag der Standard-Locale zurück. Siehe [Tabs](/docs/content/navigation#tabs). ## Fallbacks Wenn eine Seite noch nicht übersetzt ist, rendert Blume den Inhalt der Fallback-Locale unter der lokalisierten URL – so funktioniert der Link, die Seite wird vollständig vorgerendert, und Suchmaschinen landen nicht in einer Sackgasse. Der Fallback ist standardmäßig deine `defaultLocale`: ```ts blume.config.ts lineNumbers i18n: { // … fallbackLocale: "en", // default; set to null to 404 instead } ``` Fallback-Seiten werden vom Suchindex ausgeschlossen und in `hreflang` nicht als echte Übersetzungen ausgewiesen, sodass unübersetzte Inhalte nicht um das Ranking konkurrieren. Sie erscheinen weiterhin in der Seitenleiste dieser Locale, sodass die Navigation vollständig bleibt – eine Leserin oder ein Leser erreicht jede Seite in jeder Sprache. :::tip Beginne damit, deine wichtigsten Seiten zu übersetzen – die Startseite, den Schnellstart und die wichtigsten Anleitungen – und lass den Rest auf den Fallback zurückgreifen. Du kannst Übersetzungen mit der Zeit ergänzen, ohne Links zu beschädigen. ::: ## Links über Locales hinweg [#links-across-locales] Schreibe interne Links so, wie du es in der Standard-Locale tun würdest – `[Setup](/guides/setup)`, `` – und zwar in jeder Sprache, auch auf übersetzten Seiten. Wenn eine Seite unter einem Locale-Präfix gerendert wird, verschiebt Blume jeden wurzelrelativen Seitenlink in diese Locale (`/fr/guides/setup`), sofern die Route dort bereitgestellt wird – als echte Übersetzung oder als Fallback-Seite. Ein Link ohne Variante pro Locale – eine benutzerdefinierte Seite, eine generierte Route oder eine fehlende Übersetzung auf einer Website mit deaktivierten Fallbacks – behält sein ursprüngliches Ziel, statt auf einen 404 zu zeigen, und ein Link, der bereits ein Locale-Präfix trägt (`/de/guides/setup`), bleibt unangetastet, sodass Links über Locales hinweg explizit bleiben. Anker wandern mit dem Link mit, daher müssen Heading-IDs über alle Sprachen hinweg übereinstimmen. [`blume translate`](/docs/reference/translate) erledigt das für dich: Jede übersetzte Überschrift wird mit einem angehängten `[#id]`-Marker an die ID ihrer Quellüberschrift gebunden. Bei einer von Hand geschriebenen Übersetzung bindest du die Überschriften selbst mit demselben [`[#custom-id]`-Marker](/docs/content/syntax#custom-anchors) – sonst passt `#ordering` nicht zum automatisch generierten `#ordre` der französischen Seite, und `blume validate` meldet die Abweichung gegenüber der übersetzten Seite, auf der eine Leserin oder ein Leser tatsächlich landet. ## Übersetzen mit einem Agenten [#translating-with-an-agent] Du musst die Locales nicht von Hand ausfüllen. [`blume translate`](/docs/reference/translate) findet jede Seite, die in einer Locale fehlt oder veraltet ist, und übersetzt sie mit einer lokalen Agenten-CLI ([Claude Code](https://claude.com/claude-code) oder [Codex](https://developers.openai.com/codex/cli)): ```bash blume translate --claude ``` Blume validiert die Struktur jedes Ergebnisses – Frontmatter, Code-Fences, Links – und schreibt die Dateien selbst; der Agent übersetzt nur Text. Ein eingecheckter Ledger (`blume.translations.json`) verfolgt, aus welcher Quellrevision jede Übersetzung stammt, sodass erneute Läufe nur ändern, was sich geändert hat, und von Hand geschriebene Übersetzungen unverändert übernommen und nie überschrieben werden. In der CI schlägt `blume translate --check` fehl, wenn eine Quellseite ihren Übersetzungen vorausgeeilt ist. ## Der Sprachumschalter [#the-language-switcher] Wenn i18n aktiviert ist, erscheint automatisch ein Sprachumschalter im Header, generiert aus deinen `locales`. Für jede Seite verlinkt er die passende Übersetzung in jeder Sprache; wo eine Übersetzung fehlt, verlinkt er die Fallback-Seite und kennzeichnet sie als nicht übersetzt. Es gibt nichts zu konfigurieren. ## Übersetzte Benutzeroberfläche [#translated-ui] Blume liefert integrierte Übersetzungen für seine eigene Oberfläche mit – „Auf dieser Seite“, „Suchen“, „Auf GitHub bearbeiten“ und den Rest – sodass eine Locale mit integriertem Paket von Haus aus eine übersetzte Oberfläche erhält. **Du übersetzt nur deine Inhalte.** Pakete gibt es für über 30 Sprachen – Arabisch, Bengalisch, Bulgarisch, Katalanisch, Chinesisch (vereinfacht und traditionell), Kroatisch, Tschechisch, Dänisch, Niederländisch, Finnisch, Französisch, Deutsch, Griechisch, Hebräisch, Hindi, Ungarisch, Indonesisch, Italienisch, Japanisch, Koreanisch, Norwegisch, Persisch, Polnisch, Portugiesisch (und brasilianisches Portugiesisch), Rumänisch, Russisch, Serbisch, Slowakisch, Spanisch, Schwedisch, Thailändisch, Türkisch, Ukrainisch und Vietnamesisch. Sie werden von der Community gepflegt – öffne einen PR, um eine Locale hinzuzufügen oder eine Übersetzung zu verbessern. Fehlende oder nicht mitgelieferte Strings greifen auf die Standard-Locale zurück, dann auf Englisch. Um einen String zu überschreiben oder deine eigene Sprache bereitzustellen, setze `i18n.ui`, aufgeschlüsselt nach Locale: ```ts blume.config.ts lineNumbers i18n: { // … ui: { fr: { search: { button: "Rechercher", placeholder: "Rechercher…" }, page: { previous: "Précédent", next: "Suivant" }, }, }, } ``` ## SEO Lokalisiertes SEO wird für dich erledigt – keine Metadaten pro Seite zu schreiben: - `` und `dir` werden anhand der aktiven Locale gesetzt. - `hreflang`-Alternates verlinken jede echte Übersetzung einer Seite, plus ein `x-default`, das auf die Standard-Locale zeigt. - Kanonische URLs sind locale-korrekt, und JSON-LD führt `inLanguage`. Setze [`deployment.site`](/docs/deployment), damit diese als absolute URLs ausgegeben werden können. ## Suche [#search] Die Suche ist auf die aktive Sprache beschränkt: Auf einer `/fr/…`-Seite liefert der Dialog französische Ergebnisse, mit einem Umschalter **Alle Sprachen**, um auf einmal über alle Locales zu suchen. Der Standardindex (Orama) und der FlexSearch-Index filtern im Browser; gehostete Anbieter führen eine `locale`-Facette auf jedem Datensatz. ## Rechts-nach-links [#right-to-left] Setze `dir: "rtl"` auf einer Locale, und Blume spiegelt die gesamte Oberfläche – die Seitenleiste, den Header, das Inhaltsverzeichnis, die Seitennavigation, die Suche und die Menüs – und setzt `` entsprechend. Zwei Dinge bleiben bewusst von links nach rechts: **Code-Blöcke** (Code liest sich in jeder Sprache LTR) und **Fallback-Inhalte** – eine unübersetzte Seite behält die Richtung der Sprache, in der sie tatsächlich geschrieben ist, sodass unter einer RTL-Locale angezeigtes Englisch weiterhin korrekt lesbar ist, während die umgebende Oberfläche gespiegelt wird. ## Wie geht es weiter [#where-to-next] **[Navigation](/docs/content/navigation)** Gestalte Seitenleiste, Reihenfolge und Tabs für jede Locale. **[Auffindbarkeit](/docs/discoverability)** Sitemaps, Open Graph und strukturierte Daten.