Translation scopes
Select files and stable keys while keeping incremental updates, target coverage, and deliberate refresh separate.
A localization change can affect a file, a language, or a set of messages. The CLI selects those dimensions differently: project configuration selects files and target locales; positional patterns narrow files and change planning; --key selects messages by stable key.
File scope changes the plan #
lingo push 'locales/en.json' --waitThe pattern narrows the configured source files. For a separate-file format, this command creates missing targets and leaves existing targets unchanged, even when the source has changed. If it leaves configured locales out of the job, it retains an existing source baseline so a later plain push can still process those edits. It can initialize the baseline when none exists.
For routine source edits, use plain lingo push --wait. For deliberate whole-file replacement in separate-file formats, supply positional scope with --force, knowing that force discards existing target context. XCStrings catalogs can still reuse embedded translations; see catalog updates. Targets always come from targetLocales; push has no --locale or --target-locale flag.
Stable-key refresh #
lingo push 'locales/en.json' --key 'checkout.title' --key 'checkout.submit' --waitRepeat --key for multiple selections. A key is a dot/bracket path such as checkout.title or items[0].title, and selecting an object includes every string beneath it. Thus auth.login includes auth.login.title without selecting auth.login_url. * stands for one whole segment and [] for every array item; partial wildcards such as auth.log* are rejected. A pattern starting with $. or $[ passes through as a JSONPath query. Quote wildcard patterns.
Patterns written for the earlier CLI with / also work. A pattern that contains / is split on / only, and each name is taken whole: auth/login selects the same keys as auth.login, and common/error.message selects the key error.message under common. Percent-encoded names such as legal/Terms%20of%20use are decoded; a pattern without / is a dot path and is not decoded, so write a single encoded name as JSONPath, such as $['Terms of use']. Because every pattern with / is read this way, a key whose name contains / needs JSONPath, such as $.routes['/about'].title. In this form * stands for one whole name, and a trailing *, as in auth/*, selects the values directly under auth but not objects or arrays nested there, as the earlier CLI did. A trailing /** covers everything under the name before it: auth/** is the same as auth, and auth/*/** also covers the objects and arrays under auth that auth/* leaves out. A number such as items/0 selects the array item or the object key "0", whichever the document has. Globs inside a name, ** before the end, brackets, and empty names such as a//b are rejected.
| Formats | Key scope |
|---|---|
| JSON/JSONC, PHP, TypeScript, Java properties | Regenerates selected strings, including unchanged source values. |
| YAML/root-key YAML | Selects stable keys, but unchanged selected strings can reuse existing translations. |
| gettext, ARB, Apple strings, XCStrings, CSV, Android, XLIFF | Not supported; --key stops the push with an error. |
| Markdown, MDX, Markdoc, HTML, OpenAPI YAML, SubRip, plain text, Apple stringsdict | No stable keys; skipped with a message. |
Key refresh requires existing targets. Missing locales and formats without stable keys are skipped with messages rather than bootstrapped. Backfill fills missing ordinary files, not holes inside existing ones. Adding --force does not change key-scoped planning or prevent YAML reuse.
Key refresh leaves the whole-source baseline unchanged, whether push --wait or a separate pull collects it. Pending ordinary source edits therefore still reach the next plain push.
Refresh after changing guidance #
Editing a localization engine's glossary or rules does not change source-file bytes. Plain push can therefore do nothing. For JSON, JSONC, TypeScript, and PHP, select the affected stable keys. For YAML, edit the target directly for a precise correction, or save accepted targets and use a scoped whole-file --force without --key to regenerate them. Inspect the whole resulting file because that replacement can change neighboring messages too. Key controls determine which source or target values survive reconstruction; they do not select the work.
For a large change, choose a scope small enough to inspect and recover, then estimate it before submission. Estimation uploads any required files and plans the work without creating a translation job.
Retranslate a single locale #
For a project with a separate file for each language, remove that language's targets and backfill the missing files. Finish pending source updates and save accepted translations first. The filtered purge keeps source baselines and lockfile entries for other languages.
For a configured source at locales/en.json, preview the French target deletion:
lingo purge --locale fr --file locales/en.jsonInspect the reported paths. If they are the intended targets, confirm deletion and create the missing translations:
lingo purge --locale fr --file locales/en.json --yes
lingo push --backfill-missing --waitFor a configuration that uses globs, such as locales/en/*.json, pass concrete source paths with repeated --file options in both purge commands. Purge does not expand the globs itself. Include every source whose French target you want to regenerate, and verify that no other target files are missing before backfill: backfill creates all missing configured targets.
After completion, inspect the French output and commit it with the updated lockfile. Existing target files for other languages remain unchanged. See Purge for selection rules. This recipe does not apply to XCStrings catalogs, where source and all target locales share one file.