Lokalisierung statischer Inhalte

Die Lingo.dev CLI übersetzt statische Dateien in deinem Repository – Markdown, MDX, Markdoc, JSON, YAML, Untertitel und mehr – über eine konfigurierte Lokalisierungs-Engine. Zeige einfach auf deine Inhalte, führe sie einmal aus, und du erhältst die übersetzten Dateien direkt neben den Quelldateien.

Unterstützte Inhaltstypen#

Die CLI erkennt das Format jeder Datei automatisch an der Dateiendung – ein Bucket-Typ muss nicht konfiguriert werden. Die Sprache steckt im Pfad (content/en/x.md wird zu content/de/x.md), daher ist kein [locale]-Platzhalter nötig.

Die vollständige Liste aller unterstützten Dateitypen finden Sie in der Format-Referenz.

Voraussetzungen#

Bei jedem Durchlauf werden Inhalte über eine Lokalisierungs-Engine verarbeitet — die Konfiguration, die festlegt, welches LLM-Modell, Glossar, welche Markenstimme und welche Regeln gelten. Erstelle sie im Lingo.dev-Dashboard und richte dann die CLI (Node 22+) ein:

npm install -g @lingo.dev/cli
lingo login
lingo init
lingo link

lingo init und lingo link erstellen .lingo/config.json und verbinden die CLI mit Ihrer Organisation und Engine. Committen Sie diese Datei, damit in jeder Umgebung dieselbe Konfiguration verwendet wird.

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "docs/en/getting-started.md" }]
}

Überspringen Sie in CI lingo login und stellen Sie stattdessen LINGO_API_KEY als Umgebungsvariable bereit. Erzeugen Sie sie über API keys.

Dokumentationssites#

Die meisten Dokumentations-Frameworks organisieren übersetzte Inhalte in sprachspezifischen Verzeichnissen. Fügen Sie in files pro Quelldatei ein Muster (oder ein Glob) hinzu. Die CLI bewahrt Frontmatter, Codeblöcke und Komponenten-Syntax, während Markdown, MDX und Markdoc übersetzt werden.

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [
    { "pattern": "docs/en/getting-started.md" },
    { "pattern": "docs/en/setup.mdx" }
  ]
}

Starten Sie die erste Übersetzung und füllen Sie dabei alle Zielsprachen auf:

lingo push --backfill-missing --wait

Bei späteren Ausführungen übersetzt lingo push --wait nur noch die Änderungen. Ohne --wait sammeln Sie die Ausgaben mit lingo pull aus demselben Checkout ein.

Passen Sie den Quellpfad an die Verzeichnisstruktur Ihres Frameworks an:

Strukturierte Daten#

JSON- und YAML-Dateien werden anhand ihrer Dateiendung automatisch übersetzt. Mit Schlüsselsteuerungen stellen Sie sicher, dass nicht übersetzbare Werte (IDs, URLs, Konfigurations-Flags) nicht verändert werden.

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [
    { "pattern": "content/en.json" },
    { "pattern": "data/en.yaml" }
  ]
}

Generisches YAML benötigt kein format-Feld. Nur yaml-openapi, yaml-root-key und android erfordern eine explizite "format" im Dateieintrag.

Untertitel#

SRT-Untertiteldateien werden anhand ihrer Dateiendung übersetzt. Die CLI bewahrt alle Zeitdaten, Cue-Indizes und Formatierungs-Tags – übersetzt wird nur der Textinhalt.

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "subs/en/intro.srt" }]
}

Arbeiten mit großen Inhaltsmengen#

Repos mit statischen Inhalten können Tausende von Dateien enthalten. Die CLI geht damit effizient um:

Um zu prüfen, ob Übersetzungen aktuell sind, ohne Dateien zu schreiben – praktisch als CI-Gate – führen Sie lingo check aus.

Nächste Schritte#