Internationalisierung

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.

Aktivieren

Füge einen i18n-Block hinzu, der deine Locales auflistet und angibt, welche die Standard-Locale ist:

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 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

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:

docs/
  index.mdx               ->  /
  guides/quickstart.mdx   ->  /guides/quickstart
  fr/
    index.mdx             ->  /fr
    guides/quickstart.mdx ->  /fr/guides/quickstart
  ar/
    index.mdx             ->  /ar

Du übersetzt nur die Dateien, die du möchtest – alles andere greift automatisch auf einen Fallback zurück (siehe Fallbacks).

Dateinamen-Suffixe

Du möchtest Übersetzungen lieber neben dem Original behalten? Setze parser: "dot" und benenne Dateien mit einem Locale-Suffix, statt Ordner zu verwenden:

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

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:

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

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:

i18n: {
  // …
  hideDefaultLocalePrefix: false, // /en/…, /fr/…
}

Navigation pro Locale

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-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 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.

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:

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.

Übersetzen mit einem Agenten

Du musst die Locales nicht von Hand ausfüllen. blume translate findet jede Seite, die in einer Locale fehlt oder veraltet ist, und übersetzt sie mit einer lokalen Agenten-CLI (Claude Code oder Codex):

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

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

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:

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:

• <html lang> 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, damit diese als absolute URLs ausgegeben werden können.

Suche

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

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 <html dir> 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