title | description |
---|---|
Internationalisierung (i18n) |
Lerne, wie du deine Starlight-Website so konfigurierst, dass sie mehrere Sprachen unterstützt. |
import { FileTree, Steps } from '@astrojs/starlight/components';
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.
-
Teile Starlight mit, welche Sprachen du unterstützt, indem du
locales
unddefaultLocale
an die Starlight Integration übergibst:// astro.config.mjs 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:- src/
- content/
- docs/
- ar/
- en/
- zh-cn/
- docs/
- content/
- src/
-
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
unden/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.
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'
.
// astro.config.mjs
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:
- src/
- content/
- docs/
- index.md
- zh-cn/
- index.md
- docs/
- content/
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:
// astro.config.mjs
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.
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.
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:
// astro.config.mjs
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' },
},
}),
],
});
import LanguagesList from '/components/languages-list.astro';
import UIStringsList from '/components/ui-strings-list.astro';
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.
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 insrc/content.config.ts
, wenn sie nicht bereits konfiguriert ist:// src/content.config.ts 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:- src/
- content/
- i18n/
- ar.json
- zh-CN.json
- i18n/
- content/
- src/
-
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:
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]..." }
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:
// src/content.config.ts
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.
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'));
};
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:
<!-- src/components/Example.astro -->
<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:
<!-- src/components/Example.astro -->
<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.
Die Funktion locals.t.all()
gibt ein Objekt zurück, das alle für das aktuelle Gebietsschema verfügbaren UI-Strings enthält.
---
// src/components/Example.astro
const allStrings = Astro.locals.t.all();
// ^
// {
// "skipLink.label": "Zum Inhalt springen",
// "search.label": "Suche",
// …
// }
---
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.
---
// src/components/Example.astro
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.
Die Funktion locals.t.dir()
gibt die Textrichtung des aktuellen oder eines bestimmten Gebietsschemas zurück.
---
// src/components/Example.astro
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.
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:
---
// src/components/AboutLink.astro
import { getRelativeLocaleUrl } from 'astro:i18n';
---
<a href={getRelativeLocaleUrl(Astro.currentLocale ?? 'en', 'about')}>Über uns</a
>