lingo push

Quelldateien an die Engine senden, auf den Durchlauf warten und die Ausgaben auf den Datenträger schreiben.

lingo push [patterns...] [--key <pattern>] [--force] [--backfill-missing] [--yes] [--wait] [--estimate]

Standardverhalten — Delta-Push#

Ohne Argumente läuft lingo push im reinen Delta-Modus:

1. Hash für jede Quelldatei berechnen, die auf die files-Patterns der Konfiguration passt
2. Jeden Hash mit der Lockfile abgleichen, um geänderte Quellen zu ermitteln
3. Geänderte Quellen als Durchlauf an die Engine hochladen
4. Warten, bis der Durchlauf abgeschlossen ist
5. Ausgabedateien auf den Datenträger schreiben
6. Die neuen Quell-Hashes in die Lockfile übernehmen

Wenn sich seit dem letzten erfolgreichen Push keine Quelle geändert hat, beendet sich der Befehl direkt mit ✓ Nothing to push. — ohne Server-Roundtrip und ohne Token-Verbrauch.

Argumente und Flags#

Positionsargument: patterns... — Scoped Push#

lingo push docs/en/about.md
lingo push 'docs/en/**/*.md' 'locales/en.json'

Beschränkt den Push auf bestimmte Dateien (müssen auf Patterns passen, die bereits in .lingo/config.json definiert sind). Schaltet den Befehl in den Scoped-Modus:

• Kein Abgleich mit vorherigen Quellen — jede passende Quelle gilt als im Scope, auch wenn sie unverändert ist.
• Serverseitiges No-op für Ziele, die bereits mit passenden Quell-Hashes existieren — die Engine überspringt sie und die CLI meldet sie als gecacht.

Nutze das, wenn du genau eine aktualisierte Datei übersetzen möchtest, ohne das gesamte Projekt neu zu hashen, oder wenn du eine einzelne Seite mit --force neu übersetzen willst.

--key <pattern>#

lingo push --key auth.login
lingo push --key auth.login --key billing.plan
lingo push --key "auth.*"

Nur die Schlüssel neu übersetzen, die ein Muster erfasst, sie mit der vorhandenen Übersetzung zusammenführen und alle anderen Schlüssel bytegenau unverändert lassen. Wiederholbar — ein --key pro Muster.

Ein Schlüsselbereich ignoriert den Diff der Quelle. Daher wird ein Schlüssel auch dann neu übersetzt, wenn sich sein Quelltext nie geändert hat. Genau darum geht es bei diesem Flag: Es ist der unterstützte Weg, nach einer Formulierungsänderung, einem Modellwechsel oder einer Glossar-Aktualisierung gezielt einige Strings neu zu übersetzen, ohne für den Rest der Datei zu zahlen.

--force fügt daneben nichts weiter hinzu und unterdrückt die Bestätigungsabfrage für die gesamte Datei.

Was mit jedem Schlüssel geschieht#

Die letzte Zeile unterscheidet einen Schlüsselbereich von einem normalen Push. Ein Schlüssel, der seit deinem letzten vollständigen Push in der Quelle hinzugekommen ist, wird nicht als Quelltext in die Übersetzung übernommen — er bleibt außen vor, und erst das nächste normale lingo push übersetzt ihn.

Wie ein Muster übereinstimmt#

Ein Muster passt entweder exakt auf einen Schlüssel, als Präfix mit Abschluss an einer .-, /-, -- oder [-Grenze oder als Glob. Array-Mitglieder sind über die eckige Klammer erreichbar, daher erfasst nav.items nav.items[0].title.

Globs in Anführungszeichen setzen. Deine Shell erweitert sie zuerst: In zsh bricht ein unquotiertes --key auth.* entweder mit no matches found ab oder wird — wenn zufällig eine Datei wie auth.json im Verzeichnis liegt — stillschweigend zu diesem Dateinamen. Ein kommagetrennter Wert ist keine Liste: --key "a,b" ist ein einzelnes wörtliches Muster, das auf nichts passt. Wiederhole stattdessen das Flag.

Was abgelehnt wird#

Ein Schlüsselbereich meldet und überspringt Fälle, statt stillschweigend mehr zu tun, als du angefordert hast:

• Eine Sprache ohne vorhandene Übersetzung. Es gibt nichts, womit zusammengeführt werden könnte. Daher wird die Sprache genannt und übersprungen — übersetze sie einmal mit --backfill-missing und verwende danach --key.
• Formate, bei denen kein Schlüssel fehlen darf — Dokumentformate, deren Schlüssel sich verschieben, sobald das Dokument bearbeitet wird, sowie xcode-stringsdict, deren Pluralkategorien die Datei braucht, damit sie gültig bleibt. Formate enthält die vollständige Liste. Diese Dateien werden mit einer Warnung ausgeschlossen, sodass ein Push sie trotzdem mit Schlüssel-Wert-Dateien mischen kann. Pushen Sie sie ohne --key.
• Ein Bereich, der nichts erfasst hat, weist ausdrücklich darauf hin, statt den Durchlauf als bereits aktuell zu melden.

Positionsbezogene Elemente behalten ihren Quelltext auch innerhalb eines Bereichs — Array-Elemente, Android-<string-array>-Einträge, <plurals>-Mengen — denn das Entfernen eines Elements würde alle übrigen neu nummerieren.

Die Lockfile wird nicht aktualisiert#

Ein schlüsselbezogener Durchlauf übersetzt nur einen Teil einer Datei und lässt den Quell-Hash in der Lockfile daher absichtlich unverändert. Alles andere, was sich in dieser Datei geändert hat, bleibt weiter ausstehend, und das nächste normale lingo push nimmt es mit.

--force / -f#

lingo push docs/en/about.md --force

Alle passenden Ziele neu übersetzen, vorhandene Übersetzungen ignorieren und den serverseitigen Cache umgehen. Begrenze den Umfang — mit positionsbezogenen Mustern oder --backfill-missing — außer du meinst wirklich das gesamte Projekt: Ein unqualifiziertes lingo push --force übersetzt jedes konfigurierte Muster neu, und nur die Bestätigung unten steht noch dazwischen.

Bei einem Projekt, das noch nie übersetzt wurde, gibt es nichts zu überschreiben – --force bringt dort also keinen Mehrwert. Greifen Sie stattdessen zu --backfill-missing. Das ist generell die sicherere Wahl: Es füllt ausschließlich Lücken und fordert nie zu etwas auf.

Standardmäßig fragt --force vor dem Ausführen nach einer Bestätigung:

! --force will retranslate every target for pattern(s): docs/en/about.md and
  overwrite existing translations. Continue? (Yes, retranslate / Cancel)

Übergib --yes / -y, um die Abfrage zu überspringen (CI-freundlich).

Wenn du nur ein paar Strings statt ganzer Dateien neu übersetzen willst, greif zu --key — berechnet werden nur die Schlüssel, die du angibst.

--backfill-missing#

lingo push --backfill-missing

Alle Ziele übersetzen, die über alle konfigurierten Patterns hinweg noch nicht existieren. Entspricht einem Scoped Push über alle Konfigurations-Patterns, erzeugt aber nur Dateien, wenn sie fehlen. Nutze das nach dem Hinzufügen einer neuen Sprache zu targetLocales oder beim ersten Push eines neuen Projekts.

Mit --force kombinieren, um alles von Grund auf neu zu übersetzen:

lingo push --backfill-missing --force --yes

--yes / -y#

Überspringt die Bestätigungsabfrage für --force. Ohne --force hat das keine Wirkung, und zusammen mit --key ebenfalls nicht — ein Schlüsselbereich fragt nie nach, weil er nur die Schlüssel anfasst, die du angegeben hast.

--estimate#

lingo push --estimate
lingo push 'docs/en/**/*.md' --estimate

Die voraussichtlichen Kosten dieses Push-Vorgangs ausgeben und ohne zu übersetzen beenden. Die CLI durchläuft die komplette Push-Pipeline – Hashing, Delta und Upload der Quell-Bytes –, damit der Server das exakte Delta berechnen kann, und lässt anschließend die Engine den Durchlauf bepreisen, statt ihn zu starten. Es wird nichts übersetzt, geschrieben oder abgerechnet; die Sperrdatei und Ihre Zieldateien bleiben unberührt.

Die Werte sind Schätzungen, keine verbindlichen Angebote. --estimate lässt sich mit Bereichen sowie mit --key / --force / --backfill-missing kombinieren, sodass du genau den Push kalkulieren kannst, den du gleich ausführen willst.

Wenn sich an den Quelldateien nichts geändert hat, bricht --estimate mit ✓ Nothing to push. vorzeitig ab – genau wie ein regulärer Push.

Wenn für dieselben Quellen bereits ein Durchlauf läuft, schlägt --estimate fehl, statt einen nur halb gestarteten Durchlauf zu bepreisen:

Error: Cannot estimate: existing group run_a8c... is already in 'running' state. Change a source file or wait for the run to finish.

Ausgabe#

Bei Erfolg:

Pushing source files to localization engine…
✓ Run run_a8c...: localized 12 target file(s), 4 already up-to-date, uploaded 1 new artifact(s).

Die Zusammenfassung gliedert sich wie folgt:

• N Zieldatei(en) lokalisiert — die Engine hat neue Übersetzungen erzeugt und die CLI hat sie geschrieben.
• N bereits aktuell — serverseitige Cache-Treffer (Quelle stimmte überein, Ziel wurde wiederverwendet).
• N neue Artefakt(e) hochgeladen — Quellen, die der Engine bisher noch nicht bekannt waren (binäre/große Inhalte werden einmal gespeichert und danach referenziert).
• N Ziel(e) übersprungen (lokale Bearbeitungen) — lokale Ziel-Hashes weichen von der Lockfile ab. Mit --force erneut ausführen, um sie zu überschreiben.

Bei einem Fehler pro Ziel gibt die CLI den Fehler für jedes fehlgeschlagene Ziel aus und beendet sich mit einem Exit-Code ungleich null — nützlich für CI:

✓ Run run_a8c...: localized 10 target file(s).
  2 target(s) failed:
    locales/de.json: rate limit on engine; retry later
    locales/fr.json: timeout

Mit --estimate:

Estimating push cost…
› Estimated cost: ~$1.87 (12 target(s), ~48,000 output tokens — estimate, not a quote)
  de: ~$0.9350 (6 target(s), ~24,000 tokens)
  fr: ~$0.9350 (6 target(s), ~24,000 tokens)
  4 target(s) already up-to-date — no cost.
✓ Estimate complete — nothing was translated. Run `lingo push` to start the translation.

Retry-Semantik#

Die Lockfile wird erst nach einem vollständig erfolgreichen Durchlauf aktualisiert. Ein teilweiser Fehler (z. B. ein Timeout für eine Sprache) lässt die Quell-Hashes in der Lockfile unverändert, sodass das nächste lingo push denselben Diff erneut versucht — ganz ohne manuelles Zurücksetzen.

Wenn die Engine einen Fehler meldet, bevor überhaupt eine Übersetzung stattfindet (Authentifizierung, Validierung), wird nichts geschrieben und die Lockfile bleibt unverändert.

Häufige Patterns#

CI: Übersetzen beim Merge#

- run: lingo push --backfill-missing --yes
- run: git add . && git commit -m "chore: refresh translations" && git push

--backfill-missing ist die sichere Standardeinstellung: überschreibt nichts und füllt nur Lücken.

Ein paar Strings neu übersetzen#

lingo push --key auth.login --key billing.plan --wait

Genau diese Schlüssel nach einer Formulierungsänderung neu übersetzen und alle anderen Schlüssel in der Datei unangetastet lassen.

Einzeldatei-Iteration#

lingo push docs/en/onboarding.md -f -y

Nur eine Quelle nach einer größeren Textänderung neu übersetzen. Für schnelle Iterationen die Abfrage überspringen.

Neue Sprache hinzufügen#

Nach dem Erhöhen von targetLocales in .lingo/config.json:

lingo push --backfill-missing

Übersetzt den gesamten Bestand in die neue Sprache, ohne vorhandene Übersetzungen neu zu erzeugen.