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.
| Inhaltstyp | Format | Beispielpfad |
|---|---|---|
| Dokumentation | Markdown | docs/en/getting-started.md |
| Dokumentation | MDX | docs/en/getting-started.mdx |
| Dokumentation | Markdoc | docs/en/getting-started.mdoc |
| Strukturierte Daten | JSON | data/en.json |
| Strukturierte Daten | YAML | data/en.yaml |
| Blogartikel | Markdown / MDX | blog/en/post-slug.md |
| Lokalisierung | Gettext PO | locale/en/messages.po |
| Lokalisierung | XLIFF | locale/en.xliff |
| Untertitel | SRT | subs/en/intro.srt |
Die vollständige Liste aller unterstützten Dateitypen finden Sie in der Format-Referenz.
In der neuen CLI noch nicht unterstützt
CSV (csv-per-locale), VTT-Untertitel, einfacher Text .txt und Java .properties werden von der neuen CLI noch nicht unterstützt. Verwende diese Dateien vorerst weiterhin in der legacy CLI und behalte das Changelog für Updates im Blick.
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 linklingo 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-missingBei späteren Läufen übersetzt lingo push nur das, was sich geändert hat. Mit lingo pull rufen Sie Übersetzungen ab, die an anderer Stelle erstellt wurden.
Passen Sie den Quellpfad an die Verzeichnisstruktur Ihres Frameworks an:
| Framework | Verzeichniskonvention pro Sprache | Referenz |
|---|---|---|
| Docusaurus | i18n/[locale]/docusaurus-plugin-content-docs/current/ | Docusaurus i18n-Guide |
| Nextra | Seiten pro Sprache oder JSON-Wörterbücher | Nextra-Dokumentation |
| Hugo | content/[locale]/ | Hugo-Guide für Mehrsprachigkeit |
| Astro | src/content/[locale]/ oder JSON-Wörterbücher | Astro i18n-Guide |
| VitePress | Verzeichnispräfix [locale]/ | VitePress i18n |
| MkDocs | Sprachspezifisches docs/ mit i18n-Plugin | MkDocs i18n-Plugin |
MDX-Komponenten
Bei der MDX-Übersetzung bleibt die JSX-Komponenten-Syntax erhalten. Benutzerdefinierte Komponenten wie <Callout>, <Tabs> und <CodeBlock> werden unverändert übernommen – nur der darin enthaltene Text wird übersetzt.
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.
YAML mit Sprache als Root-Key
YAML-Dateien, die den Sprachcode als Root-Key verwenden (üblich in Rails und Hugo), benötigen eine explizite "format": "yaml-root-key" — der Root-Key wird auf die Zielsprache umgeschrieben. Siehe die Format-Referenz.
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" }]
}VTT noch nicht unterstützt
WebVTT-Untertitel (.vtt) werden von der neuen CLI noch nicht unterstützt. Verwenden Sie für VTT-Dateien vorerst die legacy CLI und behalten Sie das Changelog im Blick.
Arbeiten mit großen Inhaltsmengen#
Repos mit statischen Inhalten können Tausende von Dateien enthalten. Die CLI geht damit effizient um:
| Mechanismus | So hilft es |
|---|---|
| Laufstatus | .lingo/lock.json verfolgt Fingerprints des Quellinhalts, sodass lingo push nur neue oder geänderte Dateien übersetzt. Committen Sie die Datei – sie wird bei jedem Push neu generiert. |
| Serverseitige Parallelisierung | Die Engine parallelisiert die Übersetzung automatisch – es gibt kein Concurrency-Flag, das Sie anpassen müssen. |
| Gezielte Läufe | Mit einem Glob begrenzen Sie einen Lauf auf bestimmte Dateien: lingo push "docs/en/**". |
Um zu prüfen, ob Übersetzungen aktuell sind, ohne Dateien zu schreiben – praktisch als CI-Gate – führen Sie lingo check aus.
