CLI-Konfiguration

Lege in .lingo/config.json fest, wie Quelldateien gefunden werden, welche Übersetzungsoptionen gelten und wo Zieldateien abgelegt werden.

.lingo/config.json beschreibt, welche Dateien ein Projekt übersetzt und wo die Zieldateien abgelegt werden. Die CLI sucht vom Arbeitsverzeichnis aus in den übergeordneten Verzeichnissen nach der nächstgelegenen Konfiguration. Projektrelative Pfade löst sie ausgehend von diesem Stammverzeichnis auf. Wenn keine Konfiguration vorhanden ist, verwenden lokale Katalogbefehle cwd.

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "locales/en.json" }]
}

Führe link aus, um die IDs der Organisation und der Lokalisierungs-Engine für die Remote-Übersetzung hinzuzufügen. Für die lokale Extraktion lassen sich die i18n-Einstellungen auch ohne diese IDs nutzen. Verwende strikt gültiges JSON: Kommentare und abschließende Kommas sind hier nicht zulässig.

Felder auf oberster Ebene #

FeldBedeutung
orgId, engineIdNicht leere Ressourcen-IDs; zusammen bilden sie die Remote-Verknüpfung.
sourceLocaleNicht leere Zeichenfolge für die Quellsprache.
targetLocalesEinträge aus nicht leeren Zeichenfolgen; zur Laufzeit werden Duplikate und der exakt mit der Quellsprache übereinstimmende Eintrag entfernt.
filesDie unten beschriebenen Quelleinträge.
i18n.messagesPathKatalogverzeichnis für Extraktion, Kontrolle und Bereinigung; Standard: locales.
i18n.typesPathDeklarationspfad für Extraktion und Kontrolle; Standard: lingo.d.ts.
github.workflows.onPushToDefaultBranch.enabledOptionaler Integrationsauslöser für den Standard-Branch.
github.workflows.onPullRequest.enabledOptionaler Integrationsauslöser für Pull Requests.
github.safety.requireApprovalOptionale Einstellung zur Freigabe von Integrationsausführungen.

Unbekannte Schlüssel auf oberster Ebene und in Dateieinträgen lösen eine Warnung aus und werden ignoriert. Bei einem Tippfehler kann dadurch weiterhin der Standardwert gelten, statt dass die gesamte Datei abgelehnt wird.

Init schreibt die Lokalisierungseinstellungen, link die Verknüpfungs-IDs; unlink entfernt nur diese IDs. Schreiboperationen behalten die übrigen Abschnitte auf oberster Ebene bei. init --force erstellt jedoch die Dateieinträge neu, wobei erweiterte Optionen verloren gehen. Die GitHub-Einstellungen installieren weder die App noch bewirken sie, dass ein CLI-Push die Repository-Automatisierung auslöst. Nutze dafür die Integrationseinrichtung.

Felder in Dateieinträgen #

FeldBedeutung
patternEin einzelnes, nicht leeres Quellmuster.
includeQuellmuster; diese Angabe hat Vorrang vor pattern, auch wenn sie leer ist.
excludeMuster, die für diesen Eintrag ausgeschlossen werden.
formatExplizites Format aus der folgenden Liste unterstützter Formate.
localeFormatPfaddarstellung als bcp47, underscore oder android.
targetPath, sourceRootAusgabevorlage und optionales Präfix, das für [path] entfernt wird.
translateFrontmatterFieldsMetadatenfelder, die Handler der Markdown-Familie auswählen.
translateComponentPropsProp-Namen oder nach Komponenten gefilterte Prop-Regeln.
lockedKeys, preservedKeys, ignoredKeysNicht leere Schlüsselpfad-Arrays für Handler, die diese unterstützen.
injectLocaleBoolescher Wert oder { "enabled": true, "key": "language" }.
keyColumnNur CSV: Überschrift der Schlüsselspalte; standardmäßig die erste Zelle der Kopfzeile.
lockedPatternsNur für Properties: Reguläre Ausdrücke in RE2-Syntax bleiben in Werten unübersetzt.

Jeder Eintrag benötigt pattern oder include; ein leeres include wählt nichts aus. Die Optionen stammen aus dem ersten passenden Eintrag. Schlüsselsteuerung erläutert die Zuständigkeit für Werte und die Grenzen der Formate.

Dateimuster #

Der Musterabgleich unterstützt * innerhalb eines Segments und **/ über Verzeichnisse hinweg. Verwende docs/en/**/* für einen rekursiven Teilbaum; ein abschließendes ** allein hat nicht dieselbe Bedeutung. Gehe nicht davon aus, dass geschweifte Klammern oder extglob genauso funktionieren wie in einer anderen Glob-Bibliothek.

json
{
  "sourceLocale": "en",
  "targetLocales": ["de"],
  "files": [
    {
      "include": ["docs/en/**/*.md", "docs/en/**/*.mdx"],
      "exclude": ["docs/en/private/**/*"]
    }
  ]
}

Ein Ausschluss gilt nur für den jeweiligen Eintrag; ein anderer Eintrag kann die Datei weiterhin einschließen. Die Dateierkennung überspringt .git und node_modules, aber nicht alles in .gitignore. Als positionale Argumente übergebene Push-Muster beschränken die konfigurierten Quellen zusätzlich auf die Schnittmenge und ändern den Planungsmodus. Setze diese Muster in der Shell in Anführungszeichen.

Formatauswahl #

Die konfigurierten Formate sind json, jsonc, md, mdx, markdoc, yaml-openapi, po, flutter, xcode-strings, yaml, android, typescript, xcode-xcstrings, srt, xliff, xcode-stringsdict, php, yaml-root-key, html, txt, csv und properties.

DateiendungAbgeleitetes Format
.json, .jsoncJSON oder JSONC.
.md, .mdx, .mdocMarkdown, MDX, Markdoc.
.html, .htmHTML.
.po, .arbGettext, Flutter.
.strings, .xcstrings, .stringsdictEntsprechendes Apple-Format.
.ts, .mts, .ctsTypeScript.
.srt, .xlf, .xliff, .phpSubRip, XLIFF, PHP.
.txtKlartext, nur bei einem Muster mit der Endung .txt oder bei Auswahl des Formats txt.
.csvCSV, nur bei einem Muster mit der Endung .csv oder bei Auswahl des Formats csv.
.propertiesJava-Properties, nur bei einem Muster, das auf das Format .properties oder properties endet.
.yaml, .ymlLege yaml, yaml-root-key oder OpenAPI auf Basis von yaml explizit fest.
.xmlLege android explizit fest; generisches XML wird nicht unterstützt.

Für OpenAPI lautet die exakte Kennung yaml-openapi. Auch bei expliziter Formatauswahl bleibt die Dateierkennung auf die unterstützten Dateiendungen beschränkt. Eine .txt-, .csv- oder .properties-Datei wird nur einem Eintrag zugeordnet, dessen Muster auf die jeweilige Dateiendung endet oder der das entsprechende Format txt, csv oder properties festlegt. Ein solcher Eintrag wählt ausschließlich Dateien mit dieser Dateiendung aus. .js-, .tsx-, .pot-, MJML- und VTT-Dateien sind nicht als CLI-Eingabedateien konfiguriert. Die Extraktion aus React-TSX-Dateien ist ein separater Vorgang.

Bei der HTML-Übersetzung werden ausgewählte Texte und Attribute direkt in der ursprünglichen Quelle ersetzt. Unberührtes Markup, Kommentare und Formatierungen bleiben erhalten. Bei einem expliziten <html>-Element wird die Zielsprache in das lang-Attribut eingetragen; Fragmente bleiben Fragmente. Unter HTML findest du Details zur Textauswahl und zum Ausgabeverhalten.

Formate beschreibt das Verhalten der Parser, einschließlich übersprungener Strukturen und Grenzen bei der Rekonstruktion. Gemeinsam genutzte Server-Handler erweitern diese CLI-Formatliste nicht.

Ausgabepfade #

Verwende eine explizite Vorlage, wenn die Sprache nicht aus den Quellpfaden hervorgeht:

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [
    {
      "pattern": "docs/**/*.md",
      "sourceRoot": "docs",
      "targetPath": "i18n/[locale]/docs/[path]"
    }
  ]
}

docs/start.md wird zu i18n/de/docs/start.md und i18n/fr/docs/start.md. [locale] verwendet die Sprachdarstellung des Eintrags; [path] entfernt das Quellstammverzeichnis unter Berücksichtigung der Segmentgrenzen. Ein Stammverzeichnis docs entfernt keinen Teil von docsite.

Vorlagen erfordern [locale], Glob-Eingaben zusätzlich [path]. Andere Platzhalter gibt es nicht. Absolute Pfade, .., Glob-Stammverzeichnisse, Stammverzeichnisse außerhalb der Eingaben und Ausgaben, die erneut als konfigurierte Quellen erkannt werden, werden abgelehnt. sourceRoot ohne targetPath ist ungültig. Push erkennt außerdem Ausgabekollisionen unabhängig von der Groß- und Kleinschreibung.

Push, Pull und Purge berücksichtigen auch das Dateisystem: Wird eine Quelle, ein Ziel, .lingo/lock.json oder .lingo/config.json zu einem Pfad außerhalb des Projektstammverzeichnisses oder innerhalb von .git aufgelöst, etwa über einen symbolischen Link, bricht der Befehl mit einem Fehler ab, bevor dort etwas gelesen, geschrieben oder gelöscht wird. Links, die innerhalb des Projekts bleiben, funktionieren weiterhin. Ist jedoch ein Ziel oder ein Lockfile selbst ein Link, wird nicht über diesen Link geschrieben. Führe den Befehl in einem Monorepo von einem Stammverzeichnis aus, das die gemeinsam genutzten Dateien enthält, statt aus einem Paket heraus auf sie zu verlinken.

Ohne Vorlage versucht die Pfadableitung zunächst ein Quellsprachverzeichnis, dann den vollständigen Dateinamen ohne Endung, anschließend plattformspezifische Strukturen und zuletzt ein eingefügtes Sprachverzeichnis, wobei eine Warnung ausgegeben wird. Beispiele sind locales/en.json → locales/de.json, app_en.arb → app_de.arb, Base.lproj → ein Ziel .lproj und Android values → sprachspezifische Ressourcen. Lies die Warnungen und vergewissere dich, dass die Anwendung dieses Ziel lädt.

XCStrings und CSV speichern alle Sprachen in der Quelldatei und lehnen targetPath ab. Mehrere Sprachausgaben teilen sich absichtlich diese Datei; dass sie existiert, belegt nicht, dass jede Sprache darin vorhanden ist. Purge überspringt die gemeinsam genutzte Datei und kann daher keine einzelnen Spracheinträge entfernen.

Metadaten und Komponententext auswählen #

Bei Formaten der Markdown-Familie werden die Frontmatter-Felder title und description zur Übersetzung ausgewählt, wenn die Option nicht angegeben ist. Eine leere Liste deaktiviert die Auswahl; mit einer expliziten Liste wählst du andere Felder aus. Verschachtelte Skalar- und Array-Pfade erfordern Frontmatter, das sich parsen lässt. Bei fehlerhaftem Frontmatter kann stattdessen auf oberster Ebene gesucht werden.

json
{
  "pattern": "docs/en/**/*.mdx",
  "translateFrontmatterFields": ["title", "description"],
  "translateComponentProps": ["aria-label", { "component": ["Card", "Callout"], "props": ["title"] }]
}

Eine Zeichenfolge wählt ein Prop ohne Komponentenfilter aus. Ein Objekt wählt props aus und kann die Auswahl auf bestimmte Komponentennamen beschränken. Diese Regeln wählen wörtlich angegebenen, übersetzbaren Inhalt aus, nicht Komponentencode oder sämtliche Attribute. Markdown, MDX und Markdoc unterscheiden sich; sieh beim Wechsel der Pfade im jeweiligen Handler nach.

Platziere Übersetzungshinweise in JSONC mit @context unmittelbar vor der zugehörigen Zeichenfolge. Die allgemeine JSONC-Ausgabe behält @orphan-Markierungen bei, entfernt aber andere Kommentare. Richte dich für die @src-Metadaten von React daher nach der Richtlinie zum Laden von Katalogen, statt davon auszugehen, dass Pull sie beibehält.

Wähle bei Dokumentationsframeworks die tatsächlichen Quell- und Ausgabeverzeichnisse unabhängig vom Routing. OpenAPI verwendet yaml-openapi, Sprachstammverzeichnisse im Rails-Stil verwenden yaml-root-key und generisches YAML verwendet yaml. Eine passende Dateiendung allein reicht nicht aus, um die richtige Semantik auszuwählen.

Sprachen #

Die Konfiguration validiert, dass Zeichenfolgen nicht leer sind, statt sie mit einer vollständigen Liste zulässiger Sprachen abzugleichen. Verwende die Bezeichner, die dein Modell und deine Anwendung benötigen, einschließlich Region oder Schriftsystem. localeFormat steuert die Pfade: bcp47 behält Bindestriche bei, underscore erzeugt pt_BR und android erzeugt Formen wie pt-rBR oder b+zh+Hans. Das Android-Format verwendet die Android-Darstellung, sofern sie nicht überschrieben wird; das beeinflusst auch den Quellabgleich.

Schließe ausstehende reguläre Quellaktualisierungen ab, bevor du eine Zielsprache hinzufügst und ihre fehlenden Dateien nachträglich erzeugst. Eine Sprache hinzufügen erklärt, wie diese Reihenfolge bestehende Sprachen aktuell hält. Wenn du eine Zielsprache entfernst, wird sie künftig nicht mehr ausgewählt; vorhandene Dateien bleiben erhalten. Für eingebettete Sprachmetadaten und gemeinsam genutzte Kataloge gelten die Regeln des jeweiligen Handlers. Ein korrekt geschriebener Pfad legt weder die Schreibrichtung noch das Routing oder die Sprachqualität fest.

Katalogpfade #

Bei Extraktion und Kontrolle haben explizite Angaben für --out/--types Vorrang vor den i18n-Einstellungen; danach gelten die Standardwerte. --source-locale verwendet standardmäßig en, unabhängig von sourceLocale für die Lokalisierung. Eine Änderung von messagesPath aktualisiert files[] nicht. Wähle den erzeugten JSONC-Pfad für die Übersetzung aus.

Monorepos #

Mit einer Konfiguration im Stammverzeichnis lassen sich Sprachen und eine Lokalisierungs-Engine über rekursive oder explizite Paketpfade hinweg gemeinsam nutzen. Separate Paketkonfigurationen halten dagegen Sprachen, Konfiguration und Lockfiles unabhängig voneinander. Führe den Befehl vom vorgesehenen Paketstammverzeichnis aus, damit die Suche nach der nächstgelegenen Konfiguration nicht unerwartet eine Konfiguration in einem übergeordneten Verzeichnis auswählt.

Eine CI-Verzeichnismatrix sollte die gesammelte Ausgabe jedes Projekts erhalten und überlappende Schreiboperationen vermeiden. Im lokalen Benutzerverzeichnis gespeicherte Ausführungsverweise hängen von absoluten Stammverzeichnissen ab und werden nicht über ein Lockfile geteilt. lingo check vergleicht jede von files ausgewählte Quelle auf Dateiebene mit dem Lockfile; die Schlüssel innerhalb der Dateien werden dabei nicht kontrolliert.

Scoring-Konfiguration #

lingo score verwendet die ausführbare Datei lingo.config.ts, die über Jiti geladen wird. Diese Konfiguration ist vom Projekt-JSON getrennt und registriert keine beliebigen lokalen Formatlader. Halte vertrauenswürdige Scoring-Plugins und Einstellungen zur Remote-Dateilokalisierung getrennt.