lingo push

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

text

lingo push [patterns...] [--force] [--backfill-missing] [--yes] [--wait] [--estimate]

Standardverhalten — Delta-Push#

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

Hash für jede Quelldatei berechnen, die auf die files-Patterns der Konfiguration passt
Jeden Hash mit der Lockfile abgleichen, um geänderte Quellen zu ermitteln
Geänderte Quellen als Durchlauf an die Engine hochladen
Warten, bis der Durchlauf abgeschlossen ist
Ausgabedateien auf den Datenträger schreiben
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#

bash

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.

`--force` / `-f`#

bash

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

Jedes passende Ziel neu übersetzen, vorhandene Übersetzungen ignorieren und den serverseitigen Cache umgehen. Erfordert einen Scope — entweder Positions-Patterns oder --backfill-missing. Ein einzelnes lingo push --force wird abgelehnt, weil es das gesamte Projekt neu übersetzen würde.

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

text

! --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).

`--backfill-missing`#

bash

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:

bash

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

`--yes` / `-y`#

Überspringt die Bestätigungsabfrage von --force. Hat ohne --force keine Wirkung.

`--estimate`#

bash

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 Preisangaben. --estimate lässt sich mit dem Geltungsbereich sowie mit --force / --backfill-missing kombinieren, sodass Sie genau den Push bepreisen können, den Sie als Nächstes ausführen.

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:

text

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:

text

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:

text

✓ 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:

text

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#

yaml

- 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.

Einzeldatei-Iteration#

bash

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:

bash

lingo push --backfill-missing

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

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

text

lingo push [patterns...] [--force] [--backfill-missing] [--yes] [--wait] [--estimate]

Standardverhalten — Delta-Push#

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

Hash für jede Quelldatei berechnen, die auf die files-Patterns der Konfiguration passt
Jeden Hash mit der Lockfile abgleichen, um geänderte Quellen zu ermitteln
Geänderte Quellen als Durchlauf an die Engine hochladen
Warten, bis der Durchlauf abgeschlossen ist
Ausgabedateien auf den Datenträger schreiben
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#

bash

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.

`--force` / `-f`#

bash

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

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

text

! --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).

`--backfill-missing`#

bash

lingo push --backfill-missing

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

bash

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

`--yes` / `-y`#

Überspringt die Bestätigungsabfrage von --force. Hat ohne --force keine Wirkung.

`--estimate`#

bash

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

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:

text

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:

text

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:

text

✓ 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:

text

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.

- 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.

Einzeldatei-Iteration#

bash

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:

bash

lingo push --backfill-missing

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