Statische Inhalte lokalisieren
Ordne übersetzte Dokumente und Kataloge den Dateien zu, die deine Website oder dein Renderer einliest, und kontrolliere anschließend Struktur, Links und das ausgelieferte Ergebnis.
Die Quellstruktur deiner Website verknüpft Artikel bereits mit Routen, Metadaten, Navigation und einem Renderer. Füge übersetzte Dateien dort hinzu, wo dieses System sie laden kann. Das erste brauchbare Ergebnis ist eine vollständige Seite in der Zielsprache unter der vorgesehenen Route – mit funktionierenden Links und denselben Codebeispielen wie im Original.
Dateien nach dem verarbeitenden System erfassen #
Trenne längere Dokumente von strukturierten Katalogen und spezialisierten Ressourcen. Markdown, MDX und Markdoc benötigen einen Renderer und ein Schema. JSON-, YAML-, TypeScript- und PHP-Kataloge benötigen einen Loader. PO und XLIFF sind an ihre jeweiligen Nachrichtensysteme angebunden. SRT gehört zu einem Workflow für zeitgesteuerte Medien.
Wähle aus jeder Gruppe eine repräsentative Quelldatei aus und bestimme den Ausgabepfad sowie den Loader, der sie einlesen wird. Sorge dafür, dass generierte Zieldateien nicht von den Mustern für Quelldateien erfasst werden. Lass Dokument-IDs, URLs, Codebeispiele, Katalogschlüssel und Komponentenattribute, deren Werte das Verhalten steuern, unverändert.
Wähle unter Formate den passenden Handler aus. Gewöhnliches YAML unterscheidet sich von YAML mit einer Sprache als Wurzelschlüssel und von OpenAPI-YAML. .xml erkennt eine Android-Ressource nicht automatisch. Dieselbe Dateiendung ist kein Beleg dafür, dass ein Handler die Struktur deines Dokuments versteht.
Der Verzeichniskonvention der Website folgen #
Gleiche diese Entscheidungen zur Verzeichnisstruktur mit dem Loader deines Projekts ab:
| Website | Was vor der Übersetzung zu klären ist |
|---|---|
| Docusaurus | Welche Quelldokumente zu Dateien unter i18n/<locale>/docusaurus-plugin-content-docs/current/ werden und welche versionierten Dokumente oder Theme-Texte separate Eingaben benötigen. |
| Nextra | Ob die installierte Konfiguration sprachspezifische Seiten, Wörterbücher oder eine andere Inhaltsstruktur lädt; ordne jede Eingabe separat zu. |
| Hugo | Welche Dateien unter content/<locale>/ denselben Inhalt in verschiedenen Sprachen darstellen und wie Sprachlinks aufgelöst werden. |
| Astro | Welche sprachspezifischen Inhaltssammlungen und UI-Wörterbücher die Inhalte für die einzelnen Routen liefern. |
| VitePress | Welches sprachspezifische Verzeichnispräfix und welche Navigationskonfiguration die übersetzten Seiten erzeugen. |
| MkDocs | Welches i18n-Plugin und welche sprachspezifische Dokumentationsstruktur das installierte Projekt verwendet. |
Für ein Docusaurus-Beispiel mit Quelldokumenten unter docs/ installierst und verknüpfst du die CLI vom Stammverzeichnis des Projekts aus:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'docs/**/*.md' --yes
lingo linkBehalte die IDs der Organisation und der Lokalisierungs-Engine in .lingo/config.json bei. Da diese Quellpfade keine Sprache enthalten, ersetze den Dateieintrag durch eine explizite Ausgabevorlage:
{
"pattern": "docs/**/*.md",
"sourceRoot": "docs",
"targetPath": "i18n/[locale]/docusaurus-plugin-content-docs/current/[path]"
}Für docs/setup/install.md wird [path] zu setup/install.md, sodass die spanische Ausgabe unter i18n/es/docusaurus-plugin-content-docs/current/setup/install.md landet. Stelle sicher, dass das installierte Plugin in der verwendeten Version dieses Verzeichnis einliest. Konfiguration erläutert die Vorlagenvalidierung und die Kollisionsregeln.
Sichtbare Dokumentfelder gezielt übersetzen #
Wähle bei Markdown die Frontmatter-Felder aus, die für die Leserschaft sichtbar sind, etwa Titel und Beschreibung. Lass Identitäts- und Veröffentlichungsmetadaten unverändert. Bestimme bei MDX und Markdoc außerdem die sichtbaren Komponenten-Props, etwa den Titel eines Hinweisblocks. Verhaltenssteuernde Props und Komponentennamen gehören zum Anwendungsschema.
Verwende den passenden Handler, statt davon auszugehen, dass alle Dateien aus der Markdown-Familie austauschbar sind. Ein als .md gespeichertes Markdoc-Dokument benötigt die explizite Formatangabe markdoc, um als Markdoc verarbeitet zu werden. Unter Markdown, MDX und Markdoc findest du die Grenzen der Auswahl und Rekonstruktion. Lass Codeblöcke als ausführbare Belege unverändert; übersetze die Erläuterungen rundherum, statt die Befehle zu ändern.
Führe einen Lauf zum Nachgenerieren fehlender Dateien aus:
lingo push --backfill-missing --waitErstelle nach Abschluss den Build der Website und öffne die generierte Zielroute. Kontrolliere Titel, Beschreibung, Haupttext, benutzerdefinierte Komponenten, Codeblock und einen Link. Wenn Überschriften-IDs aus dem Text abgeleitet werden, folge gezielt den übersetzten Fragmentlinks. Auch eine unveränderte URL braucht ein vorhandenes Ziel. Die Anleitung zu Markdoc mit Next.js zeigt ein Beispiel für sprachspezifisches Laden.
Formatvorgaben strukturierter Kataloge einhalten #
Übersetze Zeichenfolgenwerte in JSON und generischem YAML und schütze dabei IDs, Endpunkte und andere nichtsprachliche Daten mit den Steuerungsoptionen für Schlüssel des Handlers. Setze format: "yaml" für generisches YAML in der Quellkonfiguration der aktuellen CLI explizit: Die Erkennung anhand der Dateiendung allein reicht nicht aus, um eine nicht konfigurierte YAML-Quelle für einen Push zuzulassen. Verwende yaml-root-key, wenn die Sprache der Wurzelschlüssel ist, und yaml-openapi, wenn es sich um ein OpenAPI-Dokument handelt. Beschränke TypeScript und PHP auf die unterstützten Katalogformen; die Übersetzung einer Datei bedeutet nicht, dass beliebiger Quellcode sicher ausgewertet werden kann.
Behalte bei PO Nachrichtenidentitäten, Kontext, Pluralstruktur und den vom Zielsystem verwendeten Kompilierungsschritt bei. Lass bei XLIFF die Quell-/Zielstruktur und die Platzhalterstruktur der unterstützten Variante unverändert. Verifiziere den Import oder Build des Systems, das die Dateien tatsächlich verarbeitet, statt nur nachzusehen, ob eine Ausgabedatei vorhanden ist.
Reine .txt-Textdateien, etwa App-Store-Beschreibungen, werden zeilenweise übersetzt. Dabei bleibt die Zeilenstruktur der Quelle erhalten. Nehmen Sie .txt in das Dateimuster auf, wie in metadata/en/*.txt, oder legen Sie "format": "txt" fest: Ein weit gefasstes Muster wie docs/en/**/* erfasst diese Dateien nicht. Weitere Informationen finden Sie unter Reiner Text. Eine CSV-Tabelle mit einer Spalte pro Sprache wird direkt in der Datei übersetzt: Nehmen Sie .csv in das Muster auf oder legen Sie "format": "csv" fest, wie unter CSV beschrieben. Die aktuelle CLI bietet weder eine CSV-Datei pro Sprache noch WebVTT oder Java .properties als konfigurierbare Formate an. Die Formatreferenz für CLI v0 richtet sich an alle, die diese älteren Workflows in bestehenden Installationen nutzen; die dort beschriebenen Befehle und die Konfiguration sind versionsspezifisch. Nutzen Sie die Migrationsreferenz, um einen unterstützten Weg zu wählen, ohne diese Ressourcen unbemerkt auszulassen.
Untertitel zusammen mit den Medien ansehen #
Übersetze bei SRT den Text der Untertiteleinträge und vergleiche ihre Nummerierung und Zeitangaben mit der Quelle. Spiele repräsentative Szenen mit den übersetzten Untertiteln ab. Kontrolliere Textlänge, Zeilenumbrüche, Sprecherkontext und Formatierungs-Tags im tatsächlich verwendeten Player. Unveränderte Zeitstempel belegen nicht, dass ein übersetzter Untertiteleintrag innerhalb seines Zeitfensters lesbar ist. Unter SubRip findest du die Formatvorgaben; ersetze SRT nicht durch WebVTT, nur weil beide Untertitelformate sind.
Auf Basis des bewährten Auslieferungswegs skalieren #
Halte Konfiguration, Quellen, akzeptierte Zieldateien und das CLI-Lockfile zusammen. Verwende nach der Änderung eines Absatzes lingo push --wait für den regulären Änderungslauf und vergleiche anschließend diesen Absatz sowie einen unveränderten Abschnitt in der Zieldatei. Bewahre die vorherige Quelle zusammen mit der zugehörigen Zieldatei auf; umstrukturierte Dokumente können die Wiederverwendung uneindeutig machen. Bei einem positionsbasierten Muster gelten andere Regeln für die Planung innerhalb des festgelegten Umfangs. Nutze den Schätzungs-Workflow vor einer umfassenden Neuübersetzung und betrachte Schätzungen als Planungsinformationen, nicht als Preisangebote.
Wenn lokale Korrekturen an Zieldateien vor divergierenden Änderungen geschützt werden müssen, übermittle sie ohne --wait und sieh dir vor dem Abruf lingo pull --dry-run an; beim direkten Zurückschreiben nach dem Warten fehlt diese Schranke. Folge der Anleitung Übersetzungen nach der Prüfung bewahren.
Wähle die GitHub App oder die CI-Rezepte, sobald der Build für eine Gruppe korrekt funktioniert. Behalte den Website-Build, die Schemavalidierung, Linkkontrollen und die Prüfung der Inhalte in diesem Zyklus bei; lingo check belegt nicht die Vollständigkeit eines Dokuments. Jede Aktualisierung sollte eine lesbare Zielseite und eine Quellrevision hinterlassen, die das Team für die nächste Änderung verwenden kann.