Was ai-i18n-tools mit Assets macht (und nicht macht)
translate-docs übersetzt Markdown/MDX-Inhalte – einschließlich alternativer Bildtexte – kopiert, generiert oder gibt aber keine Rasterdateien aus. Wenn eine übersetzte Seite einen sprachspezifischen Screenshot benötigt, müssen Sie die Datei an dem Pfad ablegen, auf den das übersetzte Markdown verweisen wird.
translate-svg ist der einzige Befehl, der sprachspezifische Binärdateien ausgibt. Er liest Quell-SVG-Dateien, übersetzt Textelemente (<text>, <title>, <desc>) und schreibt pro Sprache eine Ausgabe-SVG. Rasterdateien (PNG, JPEG, WebP, GIF) werden niemals vom Tool geschrieben.
Von Anfang an für i18n konzipieren
Die Wahl des richtigen Verzeichnislayouts, bevor überhaupt Screenshots existieren, ist der entscheidende Faktor dafür, wie problemlos sprachspezifische Assets später zu handhaben sind. Ein Nachrüsten des Layouts, nachdem Dutzende Screenshots committet wurden, bedeutet, Pfade umzustrukturieren und jeden Markdown-Verweis zu aktualisieren.
Markdown mit docsOutput.style = "flat" (README, USER-GUIDE)
Screenshots von Anfang an in einem sprachcodierten Unterverzeichnis speichern:
images/screenshots/en-GB/translate.png
images/screenshots/en-GB/settings.pngWenn Sie später i18n hinzufügen, schreibt Ihr take-screenshots-Skript für jede Sprache in images/screenshots/<locale>/, und eine einzige regexAdjustments-Regel behandelt alle:
{
"search": "images/screenshots/[^/]+/",
"replace": "images/screenshots/${translatedLocale}/"
}Der generische [^/]+-Regex stimmt mit jedem Namen eines Gebietsschema-Ordners überein – codieren Sie Ihr Quellgebietsschema (z. B. screenshots/en-GB/) nicht fest, da dies zu Problemen führt, wenn sich sourceLocale jemals ändert.
Wenn Sie mit Pfaden beginnen, die das Unterverzeichnis des Gebietsschemas (images/screenshots/translate.png) weglassen, müssen Sie den gesamten Baum umstrukturieren, bevor die Umschreibung pro Gebietsschema-Ordner funktionieren kann.
Doc-System-Websites (docsOutput.style = "doc-system")
Verwenden Sie dies für statische Dokumentationsseiten, die übersetzte Seiten in einem sprachpräfixierten Verzeichnisbaum speichern – Docusaurus i18n, Astro Starlight und benutzerdefinierte Generatoren, die demselben Aufbau folgen. Dateien unter docsRoot werden geschrieben nach:
{outputDir}/{locale}/[localeSubpath/]{relativeToDocsRoot}Setzen Sie docs[].docsOutput.docsRoot auf das Stammverzeichnis der in sourceLocale geschriebenen Dateien (zum Beispiel "docs" oder "src/content/docs"). sourceLocale kann eine beliebige Sprache sein. Wenn Sie style: "doc-system" direkt festlegen, müssen Sie auch localeSubpath auf das Pfadsegment setzen, das Ihre Website zwischen {locale}/ und der übersetzten Datei verwendet. Die Aliase "docusaurus", "astro-starlight" und "vitepress" sind voreingestellte doc-system-Layouts mit Standardwerten für localeSubpath (siehe Ausgabe-Layouts).
| Voreingestellter Alias | Standard-localeSubpath | Beispiel-Ausgabe |
|---|---|---|
"docusaurus" | docusaurus-plugin-content-docs/current | i18n/de/docusaurus-plugin-content-docs/current/guide.md |
"astro-starlight" | "" (leer) | src/content/docs/de/guide.md |
"vitepress" | "" (leer) | docs/de/guide/quick-start.md |
Der flache Link-Umschreiber wird nicht für doc-system ausgeführt (im Gegensatz zu "flat"). postProcessing.regexAdjustments erhält die ursprüngliche URL aus dem Quell-Markdown – typischerweise ein absoluter Pfad oder ein Pfad ab Stammverzeichnis der Seite wie /img/screenshots/en-GB/foo.png.
Das Pro-Gebietsschema-Ordner-Layout gilt, wenn Screenshots in einem gemeinsamen statischen URL-Baum liegen: Verwenden Sie von Anfang an einen sprachcodierten Ordner und eine generische screenshots/[^/]+/ → screenshots/${translatedLocale}/-Regel (siehe Konfiguration – Dokumentsystem).
Kollokierte Screenshots werden angewendet, wenn die übersetzten Dokumente jedes Gebietsschemas Assets neben dem Markdown speichern (keine URL-Umschreibung). Ihr Screenshot-Skript muss PNGs in Pfade schreiben, die von {outputDir}, {locale} und {localeSubpath} abgeleitet sind – das unten stehende Docusaurus-Preset ist das Referenzlayout.
Docusaurus-Voreinstellung
Zwei Gewohnheiten beim Projektaufbau vermeiden später alle Regex-Brückenschläge:
Erstellen Sie einen symbolischen Link
documentation/docs/assets → ../static/assets, bevor Sie Screenshots hinzufügen. Docusauruses Webpack verfolgt standardmäßig symbolische Links, wodurch Quelldokumente relative Pfade verwenden können, die auch von übersetzten Dokumenten genutzt werden.Legen Sie alle Dokumentations-Assets – PNGs und SVGs – in
static/assets/(ein Verzeichnis). Teilen Sie sie nicht aufstatic/img/(SVGs) undstatic/assets/(PNGs) auf. Ein einheitlicher Speicherort bedeutet, dass jede Dokumentationsseite, sowohl im Quellsprachgebiet als auch übersetzt, denselben relativen Pfad../assets/name.extreferenzieren kann.
Referenzieren Sie jedes Asset mit dem stabilen relativen Pfad ../assets/name.ext im Quell-Markdown. Verwenden Sie niemals absolute /img/- oder /assets/-URLs für Dokumentations-Assets – diese URLs unterscheiden sich zwischen den Seiten des Quellsprachgebiets (bereitgestellt von static/) und den übersetzten Sprachgebieten (zusammen mit den übersetzten Dokumenten), was eine regexAdjustments-Regel erzwingt, um sie zu überbrücken.
Wenn Sie später i18n hinzufügen, übernimmt das Screenshot-Skript die getScreenshotDir-Aufteilung (siehe Kollokierte Screenshots) und translate-svg verwendet ein pathTemplate. Es sind keine Regex-Anpassungen erforderlich.
Hinweis:
resolve.symlinks = falsein einemnext.config.tsdeaktiviert die Auflösung symbolischer Links nur für den Next.js-Anwendungs-Webpack-Build. Es hat keine Auswirkungen auf den Docusaurus-Dokumentationsseiten-Build, der eine separate Webpack-Instanz verwendet.
Astro/Starlight-Voreinstellung
Entspricht docsOutput.style = "doc-system" mit localeSubpath: "" – übersetzte Seiten liegen direkt unter {outputDir}/{locale}/.
Screenshots von Anfang an unter einem sprachcodierten Pfad speichern:
public/img/screenshots/en-GB/screenshot.pngVerwenden Sie den generischen Regex in regexAdjustments:
{
"search": "screenshots/[^/]+/",
"replace": "screenshots/${translatedLocale}/"
}Webanwendungen (Next.js, Vite, etc.) mit SVG-Assets
Halten Sie die SVG-Quelldateien in einem dedizierten Quellverzeichnis (z. B. images/ oder src/assets/) und konfigurieren Sie svg.outputDir auf ein separates Ausgabeverzeichnis (z. B. public/assets/). Mischen Sie niemals Quell-SVGs und translate-svg-Ausgabedateien im selben Ordner – es wird unmöglich, zu unterscheiden, welche Dateien generiert wurden.
Gestalten Sie SVGs von Anfang an für die Übersetzung: verwenden Sie <text>, <title> und <desc>-Elemente für alle menschlichen Lesetexte. Vermeiden Sie es, Text als Pfaddaten einzubetten.
Aktivieren Sie forceLowercase: true im svg-Konfigurationsblock, um Probleme mit Groß-/Kleinschreibung über verschiedene Dateisysteme und CDNs hinweg zu vermeiden.
Entscheidungshilfe
Ist das Asset ein SVG mit übersetztem Text oder Beschriftungen?
- Ja → Web-App-SVG oder Kolokalisierter SVG
- Nein (Rasterscreenshot oder dekoratives SVG) →
- Ist die Dokumentations-Website mit Assets kolokalisiert neben den übersetzten Dokumenten?
- Ja → Kolokalisierte Screenshots (Raster) + Kolokalisierter SVG (SVGs)
- Nur eine Sprache benötigt das Bild (keine sprachspezifischen Varianten)?
- Ja → Gemeinsames Bild
- Andernfalls → Sprachspezifischer Ordner
- Ist die Dokumentations-Website mit Assets kolokalisiert neben den übersetzten Dokumenten?
SVG-Layouts werden im Leitfaden SVG-Übersetzung behandelt.
| Layout | Asset-Typ | Website-Typ | Tool-Mechanism |
|---|---|---|---|
| Kolokalisierte Screenshots | Raster (kolokalisiert) | "doc-system" mit kolokalisierten Assets (Docusaurus-Preset) | Screenshot-Skript platziert Dateien; kein Regex |
| Pro Gebietsschema-Ordner | Raster (pro Gebietsschema) | "flat" oder "doc-system" (inkl. "docusaurus", "astro-starlight") | regexAdjustments Gebietsschema-Segmenttausch |
| Gemeinsames Bild | Raster (gemeinsam) | docsOutput.style = "flat"-Dokumente | Per-Datei-Link-Überschreiber; in der Regel kein Regex |
| Kollokiertes SVG | SVG (übersetzt, kollokiert) | "doc-system" mit kollokierten Assets (Docusaurus-Preset) | translate-svg mit svg.style = "nested" + pathTemplate |
| Web-App-SVG | SVG (übersetzt) | Web-App | translate-svg mit svg.style = "flat" |