Skip to content

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:

markdown
<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):

json
"postProcessing": {
  "languageListBlock": {
    "start": "<small id=\"lang-list\">",
    "end": "</small>",
    "separator": " · "
  }
}
FeldFunktion
startUnterzeichenkette, die die öffnende Zeile des Blocks identifiziert
endUnterzeichenkette in der schließenden Zeile (kann dieselbe Zeile wie start sein, wenn beide auf einer Zeile stehen)
separatorText zwischen den generierten [label](href)-Links (dieses Repository verwendet " · ")
labelOptional: "local" (Standard) verwendet den Endonymen jedes Gebietsschemas aus dem Manifest; "english" verwendet englishName

3. Was zur Laufzeit passiert ​

  1. Extraktion — der Sprachlisten-Slice wird nicht an das Modell gesendet (translatable: false).
  2. Pro übersetzter Datei — nach der Segmentübersetzung und optionalem Umschreiben von Flat-Links baut postProcessing den Block neu auf: ein Markdown-Link pro Sprache, Beschriftungen aus ui-languages.json, falls vorhanden (ansonsten gebündelter Masterkatalog, ansonsten localeDisplayNames), Pfade relativ zur geschriebenen Datei.
  3. Quellaktualisierung — am Ende eines translate-docs- / sync-Dokumentationsdurchlaufs wird derselbe kanonische Block zurück in die Quellsprachen-Dateien in contentPaths geschrieben, sodass das Hinzufügen einer Sprache den Switcher im Repository aktualisiert, ohne jeden Link manuell bearbeiten zu müssen. Diese Dateien werden in sourceLocale geschrieben, 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 ​

BeispielDateien
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-Dokumentationexamples/nextjs-app/ai-i18n-tools.config.json (zweiter Block: docsOutput.style = "flat"; erster Block: docsOutput.style = "docusaurus")
Nur Docusaurus-Dokumenteexamples/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.

Veröffentlicht unter der MIT-Lizenz.