Retranslate selected CLI v0 content

Refresh legacy translations after source or guidance changes while controlling scope and protecting accepted edits.

Use an ordinary run when source content changes. Use force when the source stays the same but the translation needs to reflect new instructions or replace an unsatisfactory value. Both can replace ordinary manual edits.

Let source changes select ordinary work #

sh
lingo run
Source/target stateOrdinary v0 result
Source value has changed from its previous checksumTranslate the changed value.
A source key is absent from the targetTranslate the missing content.
A source key was removedRemove its managed target entry.
A new key matches a removed key's source-value checksumReuse the translation within that processed context.
Present target and unchanged sourceRetain the target value.

An ordinary manual correction survives unchanged source, not every future update. Preserved keys reserve a separate human-owned value.

Refresh one affected translation #

After changing a model, prompt, glossary, or rule, begin with the affected locale and key:

sh
lingo run --force --target-locale es --key welcome/title

Here welcome/title addresses title inside welcome. In 0.138.10, run accepts exact keys, boundary-aware prefixes, and globs. Quote --key 'welcome/**' to select descendants without shell expansion.

Inspect the translated result beside its source, then load it through the application. Locale- or key-scoped work does not refresh an existing shared baseline. Follow the lockfile settlement rules so a later ordinary run does not unexpectedly revisit the same source change.

Select manageable work in a large project #

--target-locale, --bucket, --file, and --key are repeatable selectors. --source-locale changes the source used for the run. Start from the configured bucket/path inventory, then restrict it rather than naming an arbitrary unconfigured file.

sh
lingo run --target-locale es --bucket json --file 'apps/web/**'

Run's file matcher accepts substring or minimatch matching against discovered configured paths. Purge's file matcher is substring-only; its key matcher also differs. Do not transfer selectors between the two commands without checking the selected entries.

For a broader deliberate refresh:

sh
lingo run --force --bucket json --target-locale es

That can regenerate all selected Spanish JSON work. Bare lingo run --force covers the configured project. Preserve accepted output before widening scope and estimate the same forced scope when using the Lingo.dev backend.

For large changes, separate file/locale scopes make diffs easier to review. Keep successful chunk output after a failure and retry the relevant scope before forcing everything. Parallel processing controls throughput, not selection or rollback.

Keep UI catalogs and documents in their own format buckets, with generated and draft content excluded. Separate package configurations when targets or localization engines differ. In CI, lingo run --frozen checks a trusted baseline without translating; investigate failure rather than rebuilding checksums to suppress it. The current runner recipe uses a different package and configuration, so migrate before adopting it.

Use purge only when deletion is intended #

The historical purge-then-run technique makes target keys missing so ordinary gap filling processes them. It deletes output before regeneration succeeds and is not an established performance improvement. Use the purge reference to verify its distinct selectors and source-locale risk; retain a recoverable copy until regeneration and review succeed.