Schlüsselsteuerung

In den meisten Fällen soll jede Zeichenkette in einer Datei übersetzt werden. Für Ausnahmen — Markennamen, Feature-Flags, Rechtstexte, internen Ballast — bietet die CLI drei dateispezifische Steuerungen, die Sie in einem files[]-Eintrag in .lingo/config.json festlegen.

Alle drei verwenden Schlüsselpfade in Punkt-/Klammernotation, die die Struktur der Datei abbilden:

{
  "files": [
    {
      "pattern": "content/en/app.json",
      "lockedKeys": ["meta.version"],
      "preservedKeys": ["legal.terms"],
      "ignoredKeys": ["internal.debug"]
    }
  ]
}

Sperren — den Wert überall identisch halten#

lockedKeys kopiert den Quellwert unübersetzt in jede Zieldatei. Verwenden Sie es für Werte, die sprachübergreifend Byte für Byte identisch bleiben müssen:

{
  "pattern": "content/en/app.json",
  "lockedKeys": ["meta.version", "config.apiUrl"]
}

de.json und fr.json werden mit meta.version befüllt — exakt der Quellzeichenkette. Ändern Sie die Quelle, übernimmt das nächste lingo push den neuen Wert in jede Sprache, weiterhin unübersetzt.

Beibehalten — ein manuell gepflegtes Ziel schützen#

preservedKeys weist die Engine an, einen bereits vorhandenen Zielwert nie zu überschreiben. Verwenden Sie es, wenn ein Schlüssel eine menschliche Übersetzung braucht — Rechtstexte, Compliance-Texte oder alles, was Sie geprüft haben und das das Modell nicht anfassen soll:

{
  "pattern": "content/en/settings.jsonc",
  "preservedKeys": ["featureFlags"]
}

Die Engine initialisiert den Schlüssel bei der ersten Übersetzung aus der Quelle und lässt Ihre Änderungen bei allen weiteren Durchläufen unberührt. Vergleichen Sie das unten mit overrides.

Ignorieren — den Schlüssel aus der Ausgabe weglassen#

ignoredKeys entfernt den Schlüssel vollständig aus den Zieldateien — er wird weder übersetzt noch kopiert noch geschrieben. Verwenden Sie es für Debug-Zeichenketten, interne Flags und Testdaten, die nie in einem übersetzten Build landen sollen:

{
  "pattern": "content/en/app.json",
  "ignoredKeys": ["internal.debug", "dev.testData"]
}

Overrides vs. Beibehalten#

Es gibt zwei Möglichkeiten, wie ein vorhandener Zielwert einen Durchlauf übersteht:

• Beibehalten (preservedKeys) — deklarativ. Der Schlüssel ist per Konfiguration geschützt, in jeder Sprache, dauerhaft.
• Lokale Änderungen — lingo push vergleicht den Hash jedes Ziels mit der Lockfile. Wenn Sie eine Zieldatei manuell bearbeitet haben, meldet push sie als skipped (local edits) und lässt sie unberührt. Mit --force (inklusive Scope) überschreiben Sie sie. Siehe lingo push.

Greifen Sie zu preservedKeys, wenn der Schutz dauerhaft und sprachübergreifend gelten soll; für einmalige manuelle Anpassungen reicht die Erkennung lokaler Änderungen.

Migration von der Legacy-CLI#

Die Legacy-CLI konnte auch Schlüssel umbenennen (eine Übersetzung übernehmen, wenn sich die Schlüssel-ID geändert hat). Das gehört nicht zur aktuellen CLI — der Übersetzungsstatus wird pro Datei-Hash verfolgt, sodass ein umbenannter Schlüssel beim nächsten Push erneut übersetzt wird. Sperren, Beibehalten und Ignorieren bleiben erhalten, mit einer Änderung: Pfade verwenden Punkt-/Klammernotation (meta.version) statt der früheren Slash-Notation (meta/version).