Astro-Integration
Verwenden Sie ai-i18n-tools mit Astro in zwei gängigen Setups: Astro Starlight Dokumentationsseiten und reinen Astro Marketing- oder App-Seiten. Beide verwenden Dokumente (translate-docs) für den Seiteninhalt; reine Astro-Seiten kombinieren dies oft mit UI-Strings (extract / translate-ui) für t()-Strings in Frontmatter und gemeinsamen Daten.
Siehe auch UI-Strings, Dokumente und die unten stehenden ausführbaren Beispiele.
Astro Starlight
Verwenden Sie init -t ui-starlight und docsOutput.style: "astro-starlight" für Astro Starlight-Dokumentationsseiten. Das Preset ist ein Alias für doc-system mit einem leeren localeSubpath – übersetzte Seiten landen unter src/content/docs/<locale>/ neben dem Quell-Locale-Baum. sourceLocale kann jede Sprache sein.
Schnellstart
ai-i18n-tools init -t ui-starlight -P cheaperinference
# edit ai-i18n-tools.config.json (targetLocales, providers, contentPaths)
pnpm run i18n:sync # or: ai-i18n-tools sync
pnpm dev # Starlight dev server (project-specific script)Seitenlayout
Englische Markdown- und MDX-Dateien befinden sich im Starlight-Inhaltsstamm (typischerweise src/content/docs/). Übersetzte Kopien werden neben dem Quellbaum geschrieben:
src/content/docs/quick-start.md → src/content/docs/de/quick-start.md
src/content/docs/guide/setup.mdx → src/content/docs/fr/guide/setup.mdxKonfigurieren Sie einen docs[]-Block:
{
"contentPaths": ["src/content/docs/"],
"outputDir": "src/content/docs",
"docsOutput": {
"style": "astro-starlight",
"docsRoot": "src/content/docs"
}
}Richten Sie contentPaths auf die in sourceLocale geschriebenen .md- / .mdx-Dateien und -Verzeichnisse. Diese Sprache kann jede beliebige Sprache sein. Setzen Sie docsRoot auf denselben Ordner, den Starlight als seinen Inhalts-Root verwendet.
Starlight UI-Overrides können bei Bedarf src/content/i18n/en.json mit jsonPathTemplate in einem separaten docs[]-Block verwenden – siehe Dokumente – Initialisierung für die Dokumentation.
Starlight liefert integrierte UI-Strings für viele Sprachen (Navigationsbeschriftungen, Such-Platzhalter, Inhaltsverzeichnis usw.). Es gibt keine separate Shell-/Theme-Pipeline zum Konfigurieren – verwenden Sie translate-docs nur für Seiteninhalte. Für andere Frameworks siehe Framework-Shell-Übersetzung.
Explizite Sidebar-labels, die Site-title und social[].label in astro.config.mjs sind englische Literale, die dieses Tool nicht übersetzt. Bevorzugen Sie slug-Einträge, damit das Label aus dem übersetzten Frontmatter der Seite stammt (title). Eine Gruppe oder ein externer Link, der eine eigene Formulierung benötigt, verwendet Starlights pro-Locale-translations-Map (label für das Standard-Locale, translations['pt-BR'] für die anderen). social[].label hat kein Übersetzungsfeld im aktuellen Starlight-Schema; es bleibt wie geschrieben. Siehe Starlight-Sidebar und examples/astro-docs/astro.config.mjs, das slug-Einträge verwendet.
i18n auf einer bestehenden Site aktivieren
Die erstmalige Einrichtung erfolgt über die Eingabeaufforderung unter i18n zu einer Website oder Dokumentationsseite hinzufügen. Die folgende Checkliste beschreibt dieselbe Arbeit, manuell ausgeführt.
localesin der Starlight-Konfiguration, einschließlich einesroot-Eintrags, wenn Englisch ohne Präfix sein soll (labelund erforderlicheslang).defaultLocale: 'root', wenn die Standardsprache dieses Root-Locale ist. Lassen SiedefaultLocalenur weg, wenn Starlights Standard bereits übereinstimmt.- Englische Seiten bleiben in
src/content/docs/;translate-docsschreibtsrc/content/docs/<locale>/. targetLocalesausgerichtet an den Nicht-Root-Locale-Schlüsseln (achten Sie auf die Groß-/Kleinschreibung: Starlight-Verzeichnisschlüssel sind oft klein geschrieben, wie z.B.pt-br).
Beispielprojekt
examples/astro-docs – englische Quellen unter src/content/docs/, übertragene Übersetzungen unter src/content/docs/<locale>/, RTL-Gebietsschema (ar) und Glossar-gesteuerte Übersetzung. Führen Sie pnpm dev auf Port 3050 aus.
Reines Astro (Marketing- und App-Seiten)
Für statische Astro-Marketing- oder App-Websites (nicht Starlight) kombinieren Sie Astro integriertes i18n-Routing mit ai-i18n-tools. Die erstmalige Einrichtung erfolgt über die Eingabeaufforderung unter i18n zu einer Website oder Dokumentationsseite hinzufügen. Die Referenzimplementierung ist examples/astro-website: Englisch unter /, Zielsprachen unter /{locale}/.
Die meisten Teams verwenden eine Hybridlösung aus zwei Pipelines auf derselben Seite:
| Pipeline | Verwendung für | Befehle | Ausgabe |
|---|---|---|---|
| Seiten-HTML | Überschriften, Absätze, Navigationsbezeichnungen, inline-Arrays im Vorlagen-Body | translate-docs | src/pages/{locale}/index.astro pro Sprache |
UI-Strings (t()) | Frontmatter-Daten, Tab-Labels, gemeinsame Arrays | extract → translate-ui | public/locales/{locale}.json (Quellsprachen-String als Schlüssel) |
Schnellstart
ai-i18n-tools init -t ui-astro-website -P ollama
# enable features.translateDocs and add a docs[] block for page HTML (see below)
pnpm run i18n:sync
pnpm devErstellen Sie ein Gerüst für die UI-Extraktion mit init -t ui-astro-website -P ollama und führen Sie dann einen docs[]-Block zusammen, wenn Sie auch Seiten-HTML übersetzen:
{
"features": {
"translateUIStrings": true,
"translateDocs": true
},
"ui": {
"sourceRoots": ["src/"],
"stringsJson": "public/locales/strings.json",
"flatOutputDir": "public/locales/"
},
"docs": [{
"contentPaths": ["src/pages/index.astro"],
"outputDir": "src/pages",
"docsOutput": {
"style": "astro-starlight",
"docsRoot": "src/pages"
},
"addFrontmatter": false
}]
}Halten Sie drei Listen synchron, wenn Sie eine Sprache hinzufügen oder entfernen: targetLocales in ai-i18n-tools.config.json, i18n.locales in astro.config.mjs (Astro verwendet Kleinbuchstaben für Routencodes wie pt-br) und ui-languages.json (über generate-ui-languages). Flat-Bundle-Dateinamen verwenden die Konfigurationsschreibweise (pt-BR.json); ordnen Sie die Astro-Route pt-br dieser Datei über Ihr Manifest-Feld code zu.
Lösen Sie t('…') zur Build-Zeit, indem Sie das Quellsprachen-Literal als Schlüssel nachschlagen — siehe examples/astro-website/src/i18n/t.ts. sourceLocale kann jede Sprache sein. Das Beispiel verwendet Englisch. Sie benötigen ai-i18n-tools/runtime oder i18next nicht für eine statische Site, es sei denn, Sie fügen Client-Islands hinzu, die die Sprache nach dem Laden wechseln.
Beispielprojekt
examples/astro-website – hybride Landingpage mit HTML über translate-docs und Screenshot-Tab-Labels über t() + translate-ui.
Beispielprojekte
| Projekt | Anwendungsfall | Port |
|---|---|---|
| examples/astro-docs | Starlight-Dokumentation | 3050 |
| examples/astro-website | Einfache Astro-Marketing-Website (HTML + t() hybrid) | (siehe README) |
Vergleichen Sie examples/astro-docs mit examples/docusaurus-docs – ähnlicher Tutorial-Inhalt, Docusaurus-Ausgabestil anstelle von Starlight.