Übersetzungsumfang

Dateien und stabile Schlüssel auswählen – und inkrementelle Aktualisierungen, die Abdeckung der Zielsprachen und gezielte Neugenerierung getrennt steuern.

Eine Lokalisierungsänderung kann eine Datei, eine Sprache oder eine Gruppe von Texten betreffen. Die CLI wählt diese Bereiche auf unterschiedliche Weise aus: Die Projektkonfiguration legt Dateien und Zielsprachen fest; Muster als Positionsargumente grenzen die Dateiauswahl ein und verändern die Planung; --key wählt Texte anhand stabiler Schlüssel aus.

Die Dateiauswahl verändert die Planung #

sh
lingo push 'locales/en.json' --wait

Das Muster grenzt die Auswahl der konfigurierten Quelldateien ein. Bei einem Format mit separaten Dateien erstellt dieser Befehl fehlende Zieldateien und lässt vorhandene unverändert – selbst wenn sich die Quelle geändert hat. Bleiben dabei konfigurierte Sprachen vom Auftrag ausgeschlossen, bleibt eine vorhandene Quellbasis erhalten, damit ein späterer einfacher Push diese Änderungen weiterhin verarbeiten kann. Gibt es noch keine Quellbasis, kann der Befehl sie initialisieren.

Für reguläre Quelländerungen verwenden Sie einfach lingo push --wait. Um bei Formaten mit separaten Dateien gezielt ganze Dateien zu ersetzen, grenzen Sie die Auswahl über Positionsargumente ein und geben Sie --force an. Beachten Sie dabei, dass die erzwungene Verarbeitung den vorhandenen Zielkontext verwirft. XCStrings-Kataloge können eingebettete Übersetzungen weiterhin wiederverwenden; siehe Katalogaktualisierungen. Die Ziele stammen immer aus targetLocales; für Push gibt es weder die Option --locale noch --target-locale.

Neugenerierung anhand stabiler Schlüssel #

sh
lingo push 'locales/en.json' --key 'checkout.title' --key 'checkout.submit' --wait

Geben Sie --key mehrfach an, um mehrere Auswahlen zu treffen. Ein Schlüssel ist ein Pfad in Punkt- oder Klammernotation, etwa checkout.title oder items[0].title. Die Auswahl eines Objekts schließt alle darunterliegenden Zeichenfolgen ein. So umfasst auth.login auch auth.login.title, ohne auth.login_url auszuwählen. * steht für ein vollständiges Segment und [] für jedes Array-Element; Teilplatzhalter wie auth.log* werden abgewiesen. Ein Muster, das mit $. oder $[ beginnt, wird als JSONPath-Abfrage weitergegeben. Setzen Sie Platzhaltermuster in Anführungszeichen.

Auch Muster, die für die frühere CLI mit / geschrieben wurden, funktionieren weiterhin. Ein Muster, das / enthält, wird ausschließlich an / aufgeteilt. Jeder Name wird dabei als Ganzes behandelt: auth/login wählt dieselben Schlüssel aus wie auth.login, und common/error.message wählt den Schlüssel error.message unter common aus. Prozentkodierte Namen wie legal/Terms%20of%20use werden dekodiert. Ein Muster ohne / ist dagegen ein Pfad in Punktnotation und wird nicht dekodiert. Schreiben Sie einen einzelnen kodierten Namen daher als JSONPath, etwa $['Terms of use']. Da jedes Muster mit / auf diese Weise interpretiert wird, benötigen Schlüssel, deren Name / enthält, ebenfalls JSONPath, etwa $.routes['/about'].title. In dieser Form steht * für einen vollständigen Namen. Ein abschließendes *, wie in auth/*, wählt die Werte direkt unter auth aus, nicht jedoch die dort verschachtelten Objekte oder Arrays – genau wie in der früheren CLI. Ein abschließendes /** umfasst alles unter dem davorstehenden Namen: auth/** entspricht auth, und auth/*/** umfasst auch die Objekte und Arrays unter auth, die auth/* auslässt. Eine Zahl wie items/0 wählt je nach Dokument das Array-Element oder den Objektschlüssel "0" aus. Glob-Muster innerhalb eines Namens, ** vor dem Ende, Klammern und leere Namen wie a//b werden abgewiesen.

FormateSchlüsselauswahl
JSON/JSONC, PHP, TypeScript, Java-PropertiesGeneriert ausgewählte Zeichenfolgen neu, auch wenn die Quellwerte unverändert sind.
YAML/YAML mit StammschlüsselnWählt stabile Schlüssel aus; bei unveränderten ausgewählten Zeichenfolgen können vorhandene Übersetzungen jedoch wiederverwendet werden.
gettext, ARB, Apple strings, XCStrings, CSV, Android, XLIFFNicht unterstützt; --key bricht den Push mit einem Fehler ab.
Markdown, MDX, Markdoc, HTML, OpenAPI YAML, SubRip, Klartext, Apple stringsdictKeine stabilen Schlüssel; wird mit einer Meldung übersprungen.

Die Neugenerierung anhand von Schlüsseln setzt vorhandene Ziele voraus. Fehlende Sprachen und Formate ohne stabile Schlüssel werden mit entsprechenden Meldungen übersprungen, statt initial angelegt zu werden. Backfill ergänzt fehlende reguläre Dateien, aber keine Lücken innerhalb vorhandener Dateien. Die zusätzliche Angabe von --force ändert weder die schlüsselbasierte Planung noch verhindert sie die Wiederverwendung bei YAML.

Die Neugenerierung anhand von Schlüsseln lässt die Quellbasis für die gesamte Quelle unverändert – unabhängig davon, ob push --wait oder ein separater Pull die Ergebnisse abruft. Ausstehende reguläre Quelländerungen werden daher weiterhin beim nächsten einfachen Push verarbeitet.

Neugenerierung nach einer Änderung der Vorgaben #

Wenn Sie das Glossar oder die Regeln einer Lokalisierungs-Engine bearbeiten, bleiben die Bytes der Quelldateien unverändert. Ein einfacher Push kann deshalb ohne Wirkung bleiben. Wählen Sie bei JSON, JSONC, TypeScript und PHP die betroffenen stabilen Schlüssel aus. Bei YAML bearbeiten Sie das Ziel direkt, um eine gezielte Korrektur vorzunehmen. Alternativ sichern Sie die akzeptierten Ziele und verwenden --force mit eingegrenzter Auswahl ganzer Dateien und ohne --key, um sie neu zu generieren. Sehen Sie sich die gesamte Ergebnisdatei an, da diese Ersetzung auch benachbarte Texte verändern kann. Schlüsselsteuerungen bestimmen, welche Quell- oder Zielwerte bei der Rekonstruktion erhalten bleiben; sie legen nicht fest, welche Inhalte verarbeitet werden.

Wählen Sie bei einer umfangreichen Änderung einen Bereich, der klein genug ist, um ihn durchzusehen und wiederherzustellen. Lassen Sie dann vor dem Absenden eine Schätzung erstellen. Dabei werden alle erforderlichen Dateien hochgeladen und die Verarbeitung geplant, ohne einen Übersetzungsauftrag zu erstellen.

Eine einzelne Sprache neu übersetzen #

Bei einem Projekt mit einer separaten Datei pro Sprache entfernen Sie die Zieldateien der gewünschten Sprache und ergänzen die fehlenden Dateien mit Backfill. Schließen Sie zuerst ausstehende Quellaktualisierungen ab und sichern Sie die akzeptierten Übersetzungen. Die gefilterte Bereinigung erhält die Quellbasen und Lockfile-Einträge für andere Sprachen.

Für eine konfigurierte Quelle unter locales/en.json lassen Sie sich zunächst eine Vorschau der Löschung der französischen Zieldatei anzeigen:

sh
lingo purge --locale fr --file locales/en.json

Sehen Sie sich die gemeldeten Pfade an. Handelt es sich um die gewünschten Zieldateien, bestätigen Sie die Löschung und erstellen Sie die fehlenden Übersetzungen:

sh
lingo purge --locale fr --file locales/en.json --yes
lingo push --backfill-missing --wait

Verwendet Ihre Konfiguration Glob-Muster wie locales/en/*.json, geben Sie in beiden Bereinigungsbefehlen konkrete Quellpfade an, indem Sie die Option --file mehrfach verwenden. Die Bereinigung löst Glob-Muster nicht selbst auf. Beziehen Sie jede Quelle ein, deren französische Zieldatei Sie neu generieren möchten. Stellen Sie vor Backfill außerdem sicher, dass keine anderen Zieldateien fehlen: Backfill erstellt alle fehlenden konfigurierten Zieldateien.

Sehen Sie sich nach Abschluss die französische Ausgabe an und erstellen Sie einen Commit dafür zusammen mit dem aktualisierten Lockfile. Vorhandene Zieldateien für andere Sprachen bleiben unverändert. Die Auswahlregeln finden Sie unter Bereinigung. Dieses Vorgehen gilt nicht für XCStrings-Kataloge, bei denen sich die Quelle und alle Zielsprachen eine Datei teilen.