Sprachwechsler (languageListBlock)
Verwenden Sie docsOutput.postProcessing.languageListBlock, wenn übersetzte Markdown-Dateien eine Zeile mit Links „In anderen Sprachen lesen“ enthalten sollen – ein Link pro Gebietsschema, wobei die href-Werte relativ zu jeder Ausgabedatei berechnet werden.
Dieses Repository verwendet es für README.md (flache Ausgabe unter translated-docs/). Nach translate-docs erhält jede übersetzte Kopie einen aktualisierten Block; zum Beispiel verlinkt translated-docs/README.de.md auf gleichgeordnete Gebietsschema-Dateien unter translated-docs/ und zurück zur englischen Quelle im Repo-Stammverzeichnis.
Erfordert docsOutput.style = "flat" (oder ein anderes Layout, bei dem gleichrangige Sprachdateien über relative Pfade adressierbar sind). Siehe Ausgabe-Layouts. Wenn Sie dies zum ersten Mal zu einem Repository-README hinzufügen: Fügen Sie i18n zu Ihrem README und Ihren Markdown-Dokumenten hinzu.
1. Block in der Quell-Markdown-Datei markieren
Umschließen Sie den Sprachwechsler mit HTML (oder beliebigen Zeilen), die durch die Unterzeichenketten-Marker start und end begrenzt sind. Dieses Repository verwendet:
<small>**Read in other languages:** </small>
<small id="lang-list">[English (GB)](/de/) · [Deutsch](./README.de.md) · …</small>Der anfängliche Link-Text ist nur ein Platzhalter. translate-docs ersetzt den gesamten Abschnitt von der ersten Zeile, die start enthält, bis zur ersten späteren Zeile, die end enthält (Marker innerhalb von Codeblöcken werden ignoriert, sodass Konfigurationsbeispiele in derselben Datei nicht berücksichtigt werden).
2. Block konfigurieren
start und end sind beliebige Unterzeichenketten-Marker – sie müssen nicht <small id="lang-list"> / </small> sein. Wählen Sie beliebigen öffnenden und schließenden Text, der nur im Sprachwechsler-Abschnitt vorkommt: ein anderes HTML-Tag (<div class="lang-switcher"> … </div>), HTML-Kommentare (<!-- lang-list --> … <!-- /lang-list -->) oder rein Markdown-Grenzen (zum Beispiel eine Zeile **Languages:** bis zu einer Zeile ---). Legen Sie start und end in der Konfiguration exakt so fest, wie sie in der Quelldatei stehen.
Stammkonfiguration (ai-i18n-tools.config.json):
"postProcessing": {
"languageListBlock": {
"start": "<small id=\"lang-list\">",
"end": "</small>",
"separator": " · "
}
}| Feld | Funktion |
|---|---|
start | Unterzeichenkette, die die öffnende Zeile des Blocks identifiziert |
end | Unterzeichenkette in der schließenden Zeile (kann dieselbe Zeile wie start sein, wenn beide auf einer Zeile stehen) |
separator | Text zwischen den generierten [label](href)-Links (dieses Repository verwendet " · ") |
label | Optional: "local" (Standard) verwendet den Endonymen jedes Gebietsschemas aus dem Manifest; "english" verwendet englishName |
3. Was zur Laufzeit passiert
- Extraktion — der Sprachlisten-Slice wird nicht an das Modell gesendet (
translatable: false). - Pro übersetzter Datei — nach der Segmentübersetzung und optionalem Umschreiben von Flat-Links baut
postProcessingden Block neu auf: ein Markdown-Link pro Sprache, Beschriftungen ausui-languages.json, falls vorhanden (ansonsten gebündelter Masterkatalog, ansonstenlocaleDisplayNames), Pfade relativ zur geschriebenen Datei. - Quellaktualisierung — am Ende eines
translate-docs- /sync-Dokumentationsdurchlaufs wird derselbe kanonische Block zurück in die Quellsprachen-Dateien incontentPathsgeschrieben, sodass das Hinzufügen einer Sprache den Switcher im Repository aktualisiert, ohne jeden Link manuell bearbeiten zu müssen. Diese Dateien werden insourceLocalegeschrieben, was jede beliebige Sprache sein kann.
Wenn eine Datei keinen passenden Block enthält, protokolliert die CLI eine Warnung (wenn --verbose) und lässt den Inhalt unverändert.
4. Label-Manifest
Für Endonym-Labels (label: "local") generieren oder pflegen Sie ui-languages.json über generate-ui-languages (geschrieben in languagesManifestPath, das standardmäßig auf {ui.flatOutputDir}/ui-languages.json festgelegt ist). Die Dokumenten-Konfiguration dieses Repositorys hat keine UI-Pipeline und keine Projektmanifest-Datei auf der Festplatte, sodass die Labels aus dem mitgelieferten Masterkatalog für sourceLocale + targetLocales stammen.
5. Beispiele in diesem Repository
| Beispiel | Dateien |
|---|---|
| Dieses Paket (flaches README + VitePress-Site) | ai-i18n-tools.config.json (README-Block: docsOutput.style = "flat"; Site-Block: docsOutput.style = "vitepress" + vitepressThemeCatalog) |
| Flaches README + Docusaurus-Dokumentation | examples/nextjs-app/ai-i18n-tools.config.json (zweiter Block: docsOutput.style = "flat"; erster Block: docsOutput.style = "docusaurus") |
| Nur Docusaurus-Dokumente | examples/docusaurus-docs/ai-i18n-tools.config.json (docsOutput.style = "docusaurus" + docusaurusCatalogDir) |
| VitePress-Dokumentation (Minimal-Demo) | examples/vitepress-docs/ai-i18n-tools.config.json (docsOutput.style = "vitepress" + vitepressThemeCatalog) |
Die Zeile unmittelbar vor <small id="lang-list"> (z. B. **Read in other languages:**) ist ein normaler übersetzbarer Abschnitt und wird in jedem Zielgebietsschema lokalisiert; nur die Link-Zeile innerhalb der Marker wird wortwörtlich neu generiert, abgesehen von href und manifestgesteuerten Bezeichnungen.
HTML-Seiten
Einfache HTML-Dokumente verwenden ein anderes Kommentarpaar, <!-- ai-i18n:lang-list --> und <!-- ai-i18n:hreflang -->. Die Sprachliste kann aus Links oder einem <select> bestehen, und hreflang-Alternativen werden sowohl in die Quellsprachen-Datei als auch in jede Zielsprachen-Datei geschrieben. Siehe HTML-Seiten.