Skip to content

Dokumente ​

Referenz für translate-docs, die Pipeline für Markdown, MDX, .astro und einfache HTML-Seiten, die in docs[]-Konfigurationsblöcken aufgeführt sind. Das Feld contentPaths jedes Blocks listet die zu übersetzenden Dateien oder Ordner auf. Diese Dateien sind in sourceLocale geschrieben, was jede Sprache sein kann. Englisch in den Beispielen ist nur ein Muster. Fügen Sie zum ersten Mal Sprachen zu einer Website hinzu? Beginnen Sie bei i18n zu einer Website oder Dokumentationsseite hinzufügen. Eine Repository-README und andere Markdown-Dateien, normalerweise neben einer App: i18n zu Ihrer README und Markdown-Dokumentation hinzufügen. Einfache HTML-Seiten (eine Datei pro Gebietsschema) werden in HTML-Seiten beschrieben.

Framework-Shell-Strings (Navigationsleiste, Seitenleiste, Theme) werden im selben Durchlauf übersetzt, nicht durch eine separate Pipeline. Die Framework-Anleitungen in der folgenden Tabelle beschreiben, wie jedes Framework dies handhabt: docusaurusCatalogDir für Docusaurus, docsOutput.vitepressThemeCatalog für VitePress, docs[].nextraDictionaryPath für Nextra, docsOutput.fumadocsUiCatalog für Fumadocs. Nextra _meta.ts und Fumadocs meta.json Seitenleistenbeschriftungen werden automatisch gesammelt. Astro Starlight liefert integrierte UI-Strings für viele Gebietsschemata, und optionale Überschreibungen können jsonPathTemplate in einem docs[]-Block verwenden.

Für PNG und andere Rasterbilder, die in Markdown eingebettet sind, siehe Bilder & Screenshots. translate-docs übersetzt nur den Alternativtext; es kopiert keine Rasterdateien.

Für einen optionalen Sprachumschalter-Block in README oder Docs setzen Sie docsOutput.style auf "flat" – siehe Sprachumschalter.

SVG-Dateien werden über translate-svg übersetzt, wenn features.translateSVG aktiviert ist – nicht über docs[] / contentPaths.

Beliebige verschachtelte UI-JSON-Bundles, die nicht mit den Shell-/Theme-Strings eines Dokumentations-Frameworks zusammenhängen, gehören in die JSON-Pipeline, nicht in docs[].

Jeder UI-Block enthält standardmäßig die strings.json als Glossarhinweise für die Dokumentation (uiGlossary, Standard true). translate-docs verwendet diese Übersetzungen als Hinweise in LLM-Prompts wieder, wenn übereinstimmende Begriffe in einem Segment erscheinen. Setzen Sie uiGlossary auf false für einen Katalog, der aus Dokument-Prompts ausgeschlossen bleiben soll. Optional fügt glossary.userGlossary CSV-Überschreibungen für Produktbegriffe hinzu (gemeinsam genutzt mit translate-ui und proofread-ui). Kompakte Abkürzungen für UI-Labels, die für schmale Spalten verwendet werden (zum Beispiel Size → Tam), bleiben für die UI-Übersetzung verfügbar, werden aber aus den Glossarhinweisen für Dokumente ausgelassen. Generieren Sie eine Start-CSV mit glossary-generate, bearbeiten Sie Zeilen im Reiter Glossar des Übersetzungs-Dashboards oder lesen Sie Konfiguration — glossary und Glossar.

Modellüberschreibungen pro Gebietsschema ​

translate-docs und der docs-Schritt von sync lösen Modelle pro Ziel-Gebietsschema auf: zuerst localeModels(locale), wenn konfiguriert, dann die globale translationModels-Kette des Anbieters. Verwenden Sie dies, wenn eine bestimmte Sprache ein anderes Modell als Ihre Standard-Fallback-Liste benötigt – zum Beispiel, wenn Gemini für die pt-BR-Dokumentation bevorzugt wird, wenn die globale Kette mit Portugiesisch Schwierigkeiten hat. Siehe KI-Modelle und Konfiguration – localeModels.

Welchen Leitfaden Sie lesen sollten ​

Ihr SetupHier starten
Docusaurus-Websiteinit -t ui-docusaurus, docsOutput.style = "docusaurus" - Docusaurus
VitePress-Websiteinit -t ui-vitepress + vitepressThemeCatalog für Theme - VitePress
Nextra-Websiteinit -t ui-nextra + nextraDictionaryPath für Wörterbuch (Seitenleiste _meta.ts ist automatisch) - Nextra
Fumadocs-Websiteinit -t ui-fumadocs + fumadocsUiCatalog für UI (Seitenleiste meta.json ist automatisch) - Fumadocs
Astro Starlightinit -t ui-starlight - Astro Starlight
Reine HTML-Seiteninit -t docs-plain-html - HTML-Seiten
Flache Dokumente (README, Changelogs usw.)i18n zu Ihrer README und Markdown-Dokumentation hinzufügen — init -t docs-markdown oder --with-readme. Layout: Ausgabe-Layouts, Sprachumschalter
Wo übersetzte Dateien landenAusgabe-Layouts
Seitenübergreifende #anchor-LinksAnker-Links
Umschreiben von Link- und Asset-URLs (regexAdjustments)Link-Umschreibung
Screenshots in DocsBilder & Screenshots
Produktterminologie und Konsistenz zwischen UI und DokumentationKonfiguration — glossary, Glossar
translate-docs-Flags und CacheCLI-Optionen

Schritt 1: Initialisierung für die Dokumentation ​

bash
ai-i18n-tools init -t ui-docusaurus -P openai

Für Astro Starlight-Dokumentationsseiten:

bash
ai-i18n-tools init -t ui-starlight -P cheaperinference

Für VitePress-Dokumentationsseiten:

bash
ai-i18n-tools init -t ui-vitepress -P anthropic

Setzen Sie docsOutput.vitepressThemeCatalog für Navigations-/Seitenleisten-/Fußzeilen-Strings – siehe VitePress-Integration.

Für Nextra-Dokumentationsseiten:

bash
ai-i18n-tools init -t ui-nextra -P gemini

Setzen Sie docs[].nextraDictionaryPath für Theme-Wörterbuch-Strings – siehe Nextra-Integration. Seitenleisten-_meta.ts-Beschriftungen werden automatisch gesammelt.

Für Fumadocs-Dokumentationsseiten:

bash
ai-i18n-tools init -t ui-fumadocs -P groq

Setzen Sie docsOutput.fumadocsUiCatalog für UI-Überschreibungen – siehe Fumadocs-Integration. Seitenleisten-meta.json-Beschriftungen werden automatisch gesammelt.

Für einfache Astro-Website-Oberflächen (ohne Starlight):

bash
ai-i18n-tools init -t ui-astro-website -P ollama

Diese Vorlage ermöglicht nur die UI-Extraktion. Für die HTML-Seitenübersetzung setzen Sie auch features.translateDocs und fügen Sie einen docs[]-Block hinzu (siehe Astro-Website-Seiten (parse-and-replace)). Die examples/astro-website-Konfiguration zeigt beide Pipelines zusammen.

Bearbeiten Sie die generierte ai-i18n-tools.config.json:

  • provider und providers – init -P <provider> erstellt dafür ein Grundgerüst; legen Sie den API-Schlüssel vor translate-docs oder sync fest (Ollama benötigt keinen Schlüssel). Siehe Anbieter und API-Schlüssel, LLM-Anbieter und KI-Modelle.
  • sourceLocale – Quellsprache (muss mit defaultLocale in docusaurus.config.js übereinstimmen).
  • targetLocales – Array mit BCP-47-Gebietsschemacodes (z. B. ["de", "fr", "es"]).
  • cacheDir – Gemeinsames SQLite-Cache-Verzeichnis für alle Pipelines (und Standard-Logverzeichnis für --write-logs).
  • docs – Array von Dokumentationsblöcken. Jeder Block hat optionale description, contentPaths (String oder Array; Datei, Verzeichnis oder Glob), outputDir, optional docusaurusCatalogDir, docsOutput, optional segmentSplitting, translateFrontmatterFields, protectAttributes, protectKeys, targetLocales, addFrontmatter usw.
  • docs[].description – Optionale kurze Notiz für Wartungspersonal. Wenn festgelegt, erscheint sie in der Überschrift translate-docs und in den Abschnittsüberschriften status.
  • docs[].contentPaths – Markdown/MDX/.astro-Quellen (und optional docusaurusCatalogDir für Docusaurus-Shell-JSON).
  • docs[].outputDir – Übersetztes Ausgabe-Root für diesen Block.
  • docs[].docsOutput.style - "nested" (Standard), "flat", "doc-system" oder Aliase "docusaurus" / "astro-starlight" / "vitepress" / "nextra" / "fumadocs" (siehe Ausgabelayouts).
  • ui[].uiGlossary - wenn true (Standard), liefert strings.json dieses Blocks Terminologiehinweise für Dokumentsegmente (siehe Konfiguration — ui).
  • glossary.userGlossary - optionale CSV für Übersetzungen fester Produktbegriffe; wird auch von UI-Pipelines verwendet und kann im Dashboard-Reiter Glossar bearbeitet werden.

Primär vs. ergänzend: Konzentrieren Sie sich auf contentPaths für lokalisierte Seiten. Legen Sie docusaurusCatalogDir fest, wenn Sie zusätzlich Docusaurus-Shell-JSON aus write-translations benötigen. Lassen Sie docusaurusCatalogDir weg, wenn Sie nur Seiten übersetzen.

Schritt 2: Dokumente übersetzen ​

bash
ai-i18n-tools translate-docs

Dies übersetzt alle Dateien in jedem docs[]-Block contentPaths (und Docusaurus-Katalog-JSON, wenn docusaurusCatalogDir gesetzt ist) in alle effektiven Dokumentations-Locales. Bereits übersetzte Segmente werden aus dem SQLite-Cache bereitgestellt – nur neue oder geänderte Segmente werden an das LLM gesendet.

So übersetzen Sie eine einzelne Lokalisierung:

bash
ai-i18n-tools translate-docs --locale de

So prüfen Sie, was übersetzt werden muss:

bash
ai-i18n-tools status

Informationen zu Flags, Cache-Verhalten und Batch-Prompt-Format finden Sie unter CLI-Optionen.

Komplexes Markdown und fehlgeschlagene Qualitätsprüfungen ​

translate-docs prüft, ob jedes übersetzte Segment die Markdown-Struktur (einschließlich der aus dem Dokument geparsten Hervorhebung) beibehält und ob interne Platzhalter-Tokens sauber wiederhergestellt werden. Absätze, die viele bold-Spans um `inline code` stapeln, Backticks in Fettschrift verschachteln (z. B. Template-Literale wie `fetch(\`/locales/${code}.json\`)`) oder Fettschrift und Code durch einen langen Satz weben, sind anfällig: Einige Sprachen benötigen eine andere Wortreihenfolge, was die Ausrichtung von ** und ` nach der Übersetzung ändern und CLI-Fehler wie AST mismatch auslösen kann.

Nach der Wiederherstellung lehnt translate-docs auch Segmente ab, in denen HTML-Tag-Platzhalter wiederverwendet oder gelöscht wurden (sodass wiederhergestellte Tags nicht mehr der Quellzuordnung entsprechen) oder in denen das Modell übrig gebliebene doppelte Klammer-Tokens erfunden hat, die nicht in der Quelle vorhanden waren (z. B. ein erfundenes Glossar-ähnliches Token). Vor der Wiederherstellung erforderliche Prüfungen erfordern dieselbe Multimenge von {{…}}-Tokens und dieselbe geordnete Teilsequenz von strukturellen Tokens ({{HTM_N}}, Admonitions-Marker); Inhalts-Tokens wie {{ILC_N}}, {{URL_N}} und Hervorhebungs-Marker wie {{SE}} können sich mit der natürlichen Wortreihenfolge bewegen, wenn die Anzahl der IDs/Typen immer noch übereinstimmt. Diese Fehler verwenden denselben Modell-Fallback-Pfad wie übrig gebliebene offizielle interne Tokens.

Wenn Sie auf eine solche Validierungsfehler stoßen, sollten Sie den Ausgangstext vereinfachen – teilen Sie den Absatz auf, verschieben Sie ein Beispiel in einen umzäunten Codeblock oder beschreiben Sie dieselbe Idee mit weniger geschichteten Fett-/Code-Paaren – anstatt zu erwarten, dass jedes Modell und jede Locale dichte Inline-Markups perfekt reproduziert.

Wenn die für ein Segment verwendeten Modelle mit einem AST mismatch fehlschlagen, kann translate-docs dieses Segment automatisch in kleinere Teile aufteilen (zuerst am Listenmittelpunkt, dann in einzelne Listenelemente oder kürzere Absatzblöcke), jeden Teil mit dem ersten Modell erneut versuchen und das Ergebnis unter dem ursprünglichen Segment-Cache-Schlüssel wieder zusammenführen. Derselbe Qualitätsfehler beendet die Modellliste nach dreimaligem Auftreten vorzeitig; ein anderer Fehler führt zur Fortsetzung. Dies ist standardmäßig aktiviert (segmentSplitting.qualityRetrySplit); setzen Sie es auf false, um nach dem Ende der Modellliste zu stoppen. Die Ausführungszusammenfassung meldet Quality split retries, wenn dieser Fallback ausgeführt wird.

Um zu sehen, welche Segmente fehlgeschlagen sind, wie oft und die gespeicherten Qualitäts-/Fehlermeldungen, verwenden Sie die Registerkarte Fehler des Übersetzungs-Dashboards (Übersetzungs-Dashboard → Fehler).

Veröffentlicht unter der MIT-Lizenz.