lingo push

Submit source changes, fill missing target files, or deliberately refresh selected translations.

After the first-file setup, use lingo push --wait for ordinary source edits. The CLI compares source bytes with its baseline, requests the changed work, and downloads completed targets. Byte-identical sources are skipped.

Other modes serve different tasks. Choose them by what should change, rather than treating every push as a full translation.

Choose the work #

InvocationBehavior
Plain push without a valid baselineStores source bytes; does not request an initial translation automatically.
Plain push with a baselineTranslates source changes incrementally.
lingo push 'locales/en.json'Uses scoped planning without the ordinary previous-source diff; existing targets can be adopted.
lingo push --backfill-missingCreates missing target files across configured sources.
Scoped push with --forceRegenerates selected separate-file targets without keeping existing target context.
Push with --keySelects stable-key units in existing targets; unchanged-value reuse depends on the format.

Backfill does not add new or changed keys to an ordinary target file that already exists. It warns about source changes since the baseline; finish those routine updates with plain push before backfill to keep existing languages current. A document covering fewer configured locales retains an existing source baseline, so a later ordinary push can still process pending edits for the others. Shared XCStrings catalogs use per-locale planning. Positional patterns intersect configuration rather than admitting arbitrary files.

Options #

OptionEffect
Positional patternsSelect configured files; quote shell wildcards.
--force, -fReplace whole-file translations; use explicit file patterns or backfill.
--backfill-missingBootstrap missing target files.
--key <pattern>Repeatable stable-unit selection.
--yes, -ySkip force confirmation.
--wait, -wWait and download instead of returning after submission.
--estimatePlan and price work without translating or creating a job.
--with <stage>Run a stage for this push only; repeatable.
--without <stage>Skip a stage for this push only; repeatable.
--review-*, --content-lengthAdjust stage settings for this push only.

Boolean flags default to false. Targets come from config; push has no locale flag. Whole-file force prompts unless yes, key scope, or estimate suppresses it. Without positional patterns, --force selects every configured source file and target locale. Use explicit file patterns and inspect the scope with --estimate before a broad replacement. Force can replace manual target edits because it clears current-target context for separate-file formats. XCStrings catalogs and CSV tables can still reuse translations embedded in the shared source file.

Refresh selected keys #

Use a key refresh when saved guidance changed but source text did not, or when a known subset needs retranslation:

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

Keys are dot/bracket paths, and selecting an object includes every string beneath it: auth.login includes auth.login.title, but not auth.login_url. * stands for one whole segment. The earlier CLI's slash form, such as auth/login, also works. JSON, JSONC, TypeScript, and PHP regenerate selected strings even when their source is unchanged. YAML and root-key YAML accept key selection but can reuse current target values when their source matches the saved baseline. For a YAML wording correction, edit the target directly; for broader regeneration after guidance changes, save accepted targets and use whole-file --force without --key.

Missing target locales and formats without stable keys are skipped with messages; other formats stop the push with an error. Bootstrap missing targets separately. Adding --force to --key does not change key-scoped planning or prevent YAML reuse.

A key-scoped push leaves the whole-source baseline unchanged, whether push --wait or a later pull collects it, so pending ordinary source edits still reach the next plain push. Scopes covers the format matrix and key grammar.

Estimate before a broad replacement #

sh
lingo push 'locales/en.json' --force --estimate

Estimate plans the exact delta without translating or creating a job. It uploads the files the server lacks for that plan, so it is a product call, not an offline dry run. It does not replace the saved pull pointer or completed baseline. A first push only stores sources, so its estimate reports nothing to estimate and points to lingo push --estimate --backfill-missing.

The output reports planned cost, the translations to produce and reuse, output tokens, and per-locale rows. Conditional cost for follow-up corrections and spend billed by your own AI provider appear on separate lines and are excluded from the planned total; warnings then name what the estimate excludes. Amounts marked ~ are approximate. They describe the plan, not measured usage or a quote. A push too large to estimate fails with the server's reason; pass file patterns to estimate part of it.

Change stages for one push #

bash
lingo push 'locales/en.json' --force --wait --with human-review --review-level strict --review-timeout 12 --without pre-edit

Stage flags change the engine's pipeline for this push only, so you can try a configuration without editing or recreating the engine. Every setting a flag does not name comes from the engine, including its human review pools.

--with and --without take pre-edit, rephrase, human-review, post-edit, content-length or back-translation. Translation always runs. --without also skips the stages that need the skipped one: --without human-review skips AI review and post-edit.

SettingValues
--review-leveleverything sends every unit to reviewers; strict, medium or lax sends only units AI review flags at that severity.
--review-pool <name>Reviews on this pool instead of the engine's pools.
--review-languages <locales>Comma-separated locales the --review-pool pool reviews; every locale by default.
--review-timeout <hours>Hours reviewers have.
--content-length <rule>source, match:<percent> or max:<columns>.

A setting adjusts a stage without turning it on, so the push fails when the stage does not run: add --with human-review or --with content-length. --with human-review on an engine with no review pools needs --review-pool. A stage you ask for that your plan does not include fails the push instead of being skipped. The push writes its results like any other push; add --force or --key so unchanged units are translated again, and --estimate to price the configuration first. A retry must repeat the same stage flags.

For a new language, first complete ordinary source updates for existing targets. Then add it to targetLocales, inspect lingo push --backfill-missing --estimate, and request backfill without changing the source revision. Add a language carries that sequence through application checks. Removing a locale stops future selection without deleting files. Do not use locale purge on shared XCStrings catalogs.

Collect and recover #

Without wait, keep the checkout and machine-local pointer until pull retrieves output. Another push can replace that pointer. With wait, inspect failed or partially failed results and the actual downloaded files. Wait stops once every unfinished target is waiting for human review; run pull after the reviewers finish. Do not edit targets during direct wait collection, which lacks pull's fresh local-edit comparison.

To retry failed work, correct the cause and follow the failed-run recovery procedure: repeat the appropriate push with state preserved, confirm the printed job ID, then inspect the resulting output. If the earlier push was never collected and the request is unchanged, push reuses that request instead of duplicating it: a running job is re-attached, a completed one is collected, and a failed one is replaced by a new job.