Internationalisierung (i18n)

Starlight bietet eingebaute Unterstützung für mehrsprachige Seiten, einschließlich Routing, Fallback-Inhalte und vollständige Unterstützung von rechts-nach-links (RTL) Sprachen.

Konfiguriere i18n

Teile Starlight mit, welche Sprachen du unterstützt, indem du locales und defaultLocale an die Starlight Integration übergibst:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Meine Dokumentation',
      // Lege Englisch als Standardsprache für diese Website fest.
      defaultLocale: 'en',
      locales: {
        // Englische Dokumente in `src/content/docs/en/`
        en: {
          label: 'English',
        },
        // Vereinfachte chinesische Dokumente in `src/content/docs/zh-cn/`
        'zh-cn': {
          label: '简体中文',
          lang: 'zh-CN',
        },
        // Arabische Dokumente in `src/content/docs/ar/`
        ar: {
          label: 'العربية',
          dir: 'rtl',
        },
      },
    }),
  ],
});

Dein defaultLocale wird für Fallback-Inhalte und UI-Labels verwendet, wähle also die Sprache, in der du am ehesten mit dem Schreiben von Inhalten beginnen wirst oder für die du bereits Inhalte hast.

Erstelle ein Verzeichnis für jede Sprache in src/content/docs/. Für die oben gezeigte Konfiguration erstellst du zum Beispiel die folgenden Verzeichnisse:
- Directorysrc/
  - Directorycontent/
    Directorydocs/
    Directoryar/
    …
    Directoryen/
    …
    Directoryzh-cn/
    …
Du kannst nun Inhaltsdateien in deinen Sprachverzeichnissen hinzufügen. Verwende den gleichen Dateinamen, um Seiten in verschiedenen Sprachen zuzuordnen und nutze Starlights volle i18n-Funktionen, einschließlich Fallback-Inhalte, Übersetzungshinweise und mehr.

Erstelle zum Beispiel ar/index.md und en/index.md, um die Homepage für Arabisch bzw. Englisch darzustellen.

Für fortgeschrittene i18n-Szenarien unterstützt Starlight auch die Konfiguration der Internationalisierung mit Astro’s i18n-Konfigurationsoption.

Verwende ein Root-Verzeichnis

Du kannst ein Root-Verzeichnis verwenden, um eine Sprache ohne i18n-Präfix in ihrem Pfad anzubieten. Wenn zum Beispiel Englisch dein Stammverzeichnis ist, würde ein englischer Seitenpfad unter /about anstelle von /en/about zu finden sein.

Um ein Stammverzeichnis festzulegen, verwende den Key root in deiner locales-Konfiguration. Wenn das Root-Verzeichnis auch das Standard-Verzeichnis für deinen Inhalt ist, entferne defaultLocale oder setze es auf 'root'.

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Meine Dokumentation',
      defaultLocale: 'root', // optional
      locales: {
        root: {
          label: 'English',
          lang: 'en', // lang ist für Stammverzeichnis erforderlich
        },
        'zh-cn': {
          label: '简体中文',
          lang: 'zh-CN',
        },
      },
    }),
  ],
});

Wenn du ein root-Verzeichnis verwendest, speichere die Seiten für diese Sprache direkt in src/content/docs/, anstatt in einem speziellen Sprachordner. Zum Beispiel sind hier die Homepage-Dateien für Englisch und Chinesisch, wenn man die obige Konfiguration verwendet:

Directorysrc/
- Directorycontent/
  - Directorydocs/
    index.md
    Directoryzh-cn/
    index.md

Einsprachige Seiten

Standardmäßig ist Starlight eine einsprachige (englische) Website. Um eine einsprachige Website in einer anderen Sprache zu erstellen, setze diese als root in Ihrer locales Konfiguration:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      locales: {
        root: {
          label: '简体中文',
          lang: 'zh-CN',
        },
      },
    }),
  ],
});

Dies ermöglicht es dir, die Standardsprache von Starlight zu überschreiben, ohne andere Internationalisierungsfunktionen für mehrsprachige Seiten zu aktivieren, wie z.B. die Sprachauswahl.

Fallback-Inhalt

Starlight erwartet, dass du äquivalente Seiten in allen deinen Sprachen erstellst. Wenn du zum Beispiel eine de/about.md Datei hast, erstelle eine about.md für jede andere Sprache, die du unterstützt. Dies ermöglicht Starlight, automatisch Ersatzinhalte für Websiten zu liefern, die noch nicht übersetzt wurden.

Wenn für eine Sprache noch keine Übersetzung verfügbar ist, zeigt Starlight den Lesern den Inhalt dieser Seite in der Standardsprache (eingestellt über defaultLocale). Wenn du z.B. noch keine französische Version Ihrer “About”-Website erstellt hast und deine Standardsprache Englisch ist, werden Besucher von /fr/about den englischen Inhalt von /en/about sehen, mit einem Hinweis, dass diese Seite noch nicht übersetzt wurde. Auf diese Weise kannst du Inhalte in deiner Standardsprache hinzufügen und sie dann nach und nach übersetzen, wenn du Lust dazu hast.

Übersetze den Seitentitel

Standardmäßig verwendet Starlight denselben Titel für alle Sprachen. Wenn du den Titel für jedes Gebietsschema anpassen möchtest, kannst du in den Optionen von Starlight ein Objekt an title übergeben:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      title: {
        en: 'My Docs',
        'zh-CN': '我的文档',
      },
      defaultLocale: 'en',
      locales: {
        en: { label: 'English' },
        'zh-cn': { label: '简体中文', lang: 'zh-CN' },
      },
    }),
  ],
});

Starlights UI übersetzen

Starlight bietet nicht nur übersetzte Inhaltsdateien, sondern auch die Möglichkeit, die Standard-Benutzeroberfläche zu übersetzen (z.B. die Überschrift “Auf dieser Seite” im Inhaltsverzeichnis), so dass deine Leser deine Website vollständig in der ausgewählten Sprache erleben können.

Arabisch, Chinesisch, Chinesisch (Taiwan), Dänisch, Deutsch, Englisch, Französisch, Galicisch, Hebräisch, Hindi, Indonesisch, Italienisch, Japanisch, Katalanisch, Koreanisch, Niederländisch, Norwegisch (Bokmål), Persisch, Polnisch, Portugiesisch, Rumänisch, Russisch, Schwedisch, Slowakisch, Spanisch, Tschechisch, Türkisch, Ukrainisch und Vietnamesisch werden standardmäßig übersetzt, und wir freuen uns über Beiträge zur Aufnahme weiterer Standardsprachen.

Du kannst Übersetzungen für zusätzliche Sprachen, die du unterstützt, über die i18n Datensammlung zur Verfügung stellen - oder unsere Standardbezeichnungen überschreiben.

Konfiguriere die i18n Datensammlung in src/content.config.ts, wenn sie nicht bereits konfiguriert ist:

import { defineCollection } from 'astro:content';
import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
  i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
};

Erstelle eine JSON-Datei in src/content/i18n/ für jedes zusätzliche Gebietsschema, für das du UI-Übersetzungsstrings bereitstellen möchtest. Dies würde zum Beispiel Übersetzungsdateien für Arabisch und vereinfachtes Chinesisch hinzufügen:
- Directorysrc/
  - Directorycontent/
    Directoryi18n/
    ar.json
    zh-CN.json

Füge Übersetzungen für die Schlüssel hinzu, die in den JSON-Dateien übersetzt werden sollen. Übersetze nur die Werte und belasse die Schlüssel auf Englisch (z.B. "search.label": "Buscar").

Dies sind die englischen Standardwerte der vorhandenen Strings, mit denen Starlight ausgeliefert wird:

{
  "skipLink.label": "Skip to content",
  "search.label": "Search",
  "search.ctrlKey": "Ctrl",
  "search.cancelLabel": "Cancel",
  "search.devWarning": "Search is only available in production builds. \nTry building and previewing the site to test it out locally.",
  "themeSelect.accessibleLabel": "Select theme",
  "themeSelect.dark": "Dark",
  "themeSelect.light": "Light",
  "themeSelect.auto": "Auto",
  "languageSelect.accessibleLabel": "Select language",
  "menuButton.accessibleLabel": "Menu",
  "sidebarNav.accessibleLabel": "Main",
  "tableOfContents.onThisPage": "On this page",
  "tableOfContents.overview": "Overview",
  "i18n.untranslatedContent": "This content is not available in your language yet.",
  "page.editLink": "Edit page",
  "page.lastUpdated": "Last updated:",
  "page.previousLink": "Previous",
  "page.nextLink": "Next",
  "page.draft": "This content is a draft and will not be included in production builds.",
  "404.text": "Page not found. Check the URL or try using the search bar.",
  "aside.note": "Note",
  "aside.tip": "Tip",
  "aside.caution": "Caution",
  "aside.danger": "Danger",
  "fileTree.directory": "Directory",
  "builtWithStarlight.label": "Built with Starlight"
}

Die Codeblöcke von Starlight werden von der Expressive Code Bibliothek unterstützt. Du kannst die Übersetzungen für die UI-Strings in derselben JSON-Datei mit Hilfe von expressiveCode-Schlüsseln festlegen:

{
  "expressiveCode.copyButtonCopied": "Copied!",
  "expressiveCode.copyButtonTooltip": "Copy to clipboard",
  "expressiveCode.terminalWindowFallbackTitle": "Terminal window"
}

Die Suchfunktion von Starlight wird von der Pagefind-Bibliothek unterstützt. Du kannst die Übersetzungen für Pagefinds UI in der gleichen JSON Datei mit pagefind-Schlüsseln setzen:

{
  "pagefind.clear_search": "Clear",
  "pagefind.load_more": "Load more results",
  "pagefind.search_label": "Search this site",
  "pagefind.filters_label": "Filters",
  "pagefind.zero_results": "No results for [SEARCH_TERM]",
  "pagefind.many_results": "[COUNT] results for [SEARCH_TERM]",
  "pagefind.one_result": "[COUNT] result for [SEARCH_TERM]",
  "pagefind.alt_search": "No results for [SEARCH_TERM]. Showing results for [DIFFERENT_TERM] instead",
  "pagefind.search_suggestion": "No results for [SEARCH_TERM]. Try one of the following searches:",
  "pagefind.searching": "Searching for [SEARCH_TERM]..."
}

Übersetzungsschema erweitern

Füge benutzerdefinierte Schlüssel zu den Übersetzungswörterbüchern deiner Website hinzu, indem du die Option extend in den i18nSchema()-Optionen setzt. Im folgenden Beispiel wird ein neuer, optionaler Schlüssel custom.label zu den Standardschlüsseln hinzugefügt:

import { defineCollection, z } from 'astro:content';
import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
  i18n: defineCollection({
    loader: i18nLoader(),
    schema: i18nSchema({
      extend: z.object({
        'custom.label': z.string().optional(),
      }),
    }),
  }),
};

Mehr über Inhaltssammlungsschemata erfährst du in „Ein Sammelschema definieren“ in den Astro-Dokumenten.

UI-Übersetzungen verwenden

Du kannst auf Starlights eingebaute UI-Strings sowie auf benutzerdefinierte und plugin-provided UI-Strings über eine einheitliche API zugreifen, die von i18next unterstützt wird. Dazu gehört die Unterstützung von Funktionen wie Interpolation und Pluralisierung.

In Astro-Komponenten ist diese API als Teil des globalen Astro-Objekts als Astro.locals.t verfügbar:

<p dir={Astro.locals.t.dir()}>
  {Astro.locals.t('404.text')}
</p>

Du kannst die API auch bei Endpunkten verwenden, wo das Objekt locals als Teil des Endpunkt-Kontextes verfügbar ist:

export const GET = (context) => {
  return new Response(context.locals.t('404.text'));
};

Rendering eines UI-Strings

Rendere UI-Strings mit der Funktion locals.t(). Dies ist eine Instanz der i18next-Funktion t(), die einen UI-String-Schlüssel als erstes Argument nimmt und die entsprechende Übersetzung für die aktuelle Sprache zurückgibt.

Nehmen wir zum Beispiel eine benutzerdefinierte Übersetzungsdatei mit folgendem Inhalt:

{
  "link.astro": "Astro Dokumentation",
  "link.astro.custom": "Astro-Dokumentation für {{feature}}"
}

Der erste UI-String kann gerendert werden, indem man 'link.astro' an die Funktion t() übergibt:

<a href="https://docs.astro.build/">
  {Astro.locals.t('link.astro')}
</a>
<!-- Rendert: <a href="...">Astro Dokumentation</a> -->

Der zweite UI-String verwendet die Interpolationssyntax von i18next für den Platzhalter {{feature}}. Der Wert für feature muss in einem Optionsobjekt gesetzt werden, das als zweites Argument an t() übergeben wird:

<a href="https://docs.astro.build/en/guides/astro-db/">
  {Astro.locals.t('link.astro.custom', { feature: 'Astro DB' })}
</a>
<!-- Rendert: <a href="...">Astro-Dokumentation für Astro DB</a> -->

In der i18next-Dokumentation findest du weitere Informationen darüber, wie du die Funktion t() mit Interpolation, Formatierung und mehr verwenden kannst.

Fortgeschrittene APIs

`t.all()`

Die Funktion locals.t.all() gibt ein Objekt zurück, das alle für das aktuelle Gebietsschema verfügbaren UI-Strings enthält.

---
const allStrings = Astro.locals.t.all();
//    ^
//    {
//      "skipLink.label": "Zum Inhalt springen",
//      "search.label": "Suche",
//      …
//    }
---

`t.exists()`

Um zu überprüfen, ob ein Übersetzungsschlüssel für eine Sprache existiert, verwende die Funktion locals.t.exists() mit dem Übersetzungsschlüssel als erstem Argument. Übergib ein optionales zweites Argument, wenn du die aktuelle Sprache neu definieren musst.

---
const keyExistsInCurrentLocale = Astro.locals.t.exists('a.key');
//    ^ true
const keyExistsInFrench = Astro.locals.t.exists('another.key', { lng: 'fr' });
//    ^ false
---

Siehe Verweis auf exists() in der i18next-Dokumentation für weitere Informationen.

`t.dir()`

Die Funktion locals.t.dir() gibt die Textrichtung des aktuellen oder eines bestimmten Gebietsschemas zurück.

---
const currentDirection = Astro.locals.t.dir();
//    ^
//    'ltr'
const arabicDirection = Astro.locals.t.dir('ar');
//    ^
//    'rtl'
---

Weitere Informationen findest du in der dir()-Referenz in der i18next-Dokumentation.

Zugriff auf das aktuelle Gebietsschema

Du kannst Astro.currentLocale verwenden, um das aktuelle Gebietsschema in .astro Komponenten zu lesen.

Das folgende Beispiel liest das aktuelle Gebietsschema aus und verwendet es mit Hilfe der getRelativeLocaleUrl()-Methode, um einen Link zu einer Informationsseite in der aktuellen Sprache zu erzeugen:

---
import { getRelativeLocaleUrl } from 'astro:i18n';
---

<a href={getRelativeLocaleUrl(Astro.currentLocale ?? 'en', 'about')}>Über uns</a
>