Preserve reviewed translations during updates

Keep the source and accepted target baselines together, choose the right update mode, and verify exactly what changed.

An accepted translation represents work worth preserving. When one source message changes, its neighbors may still be correct. Reuse can retain them when the workflow receives the right baselines and applies the intended merge behavior.

“Incremental” alone does not describe that protection. Keep the previous source and accepted target, choose the caller's update contract, and inspect the actual diff. For a known target correction, use one-key updates; for submitted work that stopped, start with recovery.

Record both what must change and what must survive #

Consider this illustrative source:

json
{
  "retention": "Reports remain available for 30 days.",
  "support": "Contact support",
  "productName": "ExampleApp"
}

The source owner changes the retention period to 60 days. Preserve the earlier source, new source, and reviewed target. The target's period must change; the accepted support wording should remain. Keeping productName identical to the source is a different requirement from preserving a reviewed target phrase.

Save the latest accepted target revision, including local edits made since download and their rationale. The server baseline and working-tree target may no longer be the same content.

Use normal delta planning for source changes #

The current CLI's ordinary lingo push --wait uses recorded source state and targets to plan changes. Keep configuration, source, accepted targets, and .lingo/lock.json in version control. Deleting the lockfile changes planning; it is not a neutral refresh.

--backfill-missing fills missing target files, not every missing or changed key inside existing files. Positional source patterns use scoped planning with different reuse behavior. --force regenerates selected separate-file targets and can replace accepted text; shared XCStrings catalogs can still reuse their embedded translations. Choose through the Push reference before requesting replacement.

Inspect the scope and, where useful, estimate before broad execution. After retrieval, compare the changed value and nearby accepted values. Establish preservation from the result, not the run label.

Distinguish source locking from target preservation #

A supported locked key copies source text into the target. A preserved key retains an existing target value. Locking a reviewed French message can therefore replace it with English; it does not protect the French wording.

Key controls are format-specific. Ignoring a key from output is different again. A value whose source facts changed should not be preserved unconditionally, because that could retain obsolete meaning.

Reconcile local corrections during retrieval #

Save existing corrections before submitting an update. The exact target captured by push is eligible for replacement as part of that update. To detect edits made after submission, omit --wait, then inspect lingo pull --dry-run. Pull compares local targets with the captured target and recorded hashes and can refuse to overwrite later edits; the direct download from push --wait does not make this fresh check.

For a conflict, compare the local correction, recorded target, and incoming result against the relevant source revisions. Preserve a correction that still applies through the normal review process. Use lingo pull --force only after saving local work and deliberately choosing replacement. Force bypasses protection; it does not choose correct language.

For shared Apple catalogs, preserve the whole file and check untouched locales. Do not purge a file containing source and several languages as if it were disposable target output.

Accept the new baseline after inspection #

For the example, verify 60 days in the new target, the preserved support value, and the intended productName behavior. Check variables and structure through the consuming runtime. The diff identifies changes; language review determines whether the new claim is correct.

Retain the accepted target with its source revision as the next baseline. If the correction should change future guidance, make that separate glossary or rule decision rather than assuming one accepted edit teaches the localization engine a new policy.