lingo push

Push source files to the engine, wait for the run, and write outputs to disk.

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

Default behavior — delta push#

With no arguments, lingo push runs the delta-only mode:

1. Hash every source file matched by the config's files patterns
2. Diff each hash against the lockfile to find sources that changed
3. Upload changed sources as a run on the engine
4. Wait for the run to complete
5. Write outputs to disk
6. Commit the new source hashes to the lockfile

If no source has changed since the last successful push, the command short-circuits with ✓ Nothing to push. — no server round-trip, no token spend.

Arguments and flags#

Positional: patterns... — scoped push#

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

Restricts the push to specific files (must match patterns already in .lingo/config.json). Switches the command into scoped mode:

• No previous-source diff — every matching source is treated as in-scope, even if unchanged.
• Server-side noop for targets that already exist with matching source hashes — the engine skips them and the CLI reports them as cached.

Use when you want to translate exactly one updated file without rehashing the entire project, or when you want to retranslate a single page with --force.

--force / -f#

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

Retranslate every matching target, ignoring any existing translations and bypassing server-side caching. Requires a scope — either positional patterns or --backfill-missing. Bare lingo push --force is rejected because it'd retranslate the entire project.

By default --force prompts before running:

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

Pass --yes / -y to skip the prompt (CI-friendly).

--backfill-missing#

lingo push --backfill-missing

Translate every target that doesn't exist yet across every configured pattern. Equivalent to a scoped push over all config patterns, but only producing files where they're absent. Use after adding a new locale to targetLocales, or on the first push of a new project.

Combine with --force to retranslate everything from scratch:

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

--yes / -y#

Skips the --force confirmation prompt. No effect without --force.

Output#

On success:

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

The summary breaks down into:

• Localized N target file(s) — the engine produced new translations and the CLI wrote them.
• N already up-to-date — server-side cache hits (source matched, target reused).
• Uploaded N new artifact(s) — sources that the engine hadn't seen before (binary/large content stored once, referenced thereafter).
• N target(s) skipped (local edits) — local target hashes diverge from the lockfile. Rerun with --force to overwrite.

On per-target failure the CLI prints each failed target's error and exits non-zero — useful for 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

Retry semantics#

The lockfile is updated only after a fully successful run. A partial failure (e.g. one locale times out) leaves source hashes unchanged in the lockfile, so the next lingo push retries the same diff — no manual reset.

If the engine errors out before any translation happens (auth, validation), nothing is written and the lockfile is unchanged.

Common patterns#

CI: translate-on-merge#

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

--backfill-missing is the safe default: doesn't overwrite anything, only fills gaps.

Single-file iteration#

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

Retranslate just one source after a major copy change. Skip the prompt for fast iteration.

Adding a new locale#

After bumping targetLocales in .lingo/config.json:

lingo push --backfill-missing

Translates the entire corpus into the new locale without retranslating existing ones.