Update one key or term safely

Retranslate a selected part, preserve its neighbors, and inspect both the intended correction and the content left unchanged.

A narrow correction succeeds in two ways: the selected content improves, and unrelated accepted content stays intact. Keep the existing target and its source revision so both can be checked.

Use this guide for a known key or term. For ordinary source changes, use preservation during updates. For work already submitted, inspect its recovery state before requesting more.

Include an accepted neighbor in the comparison #

An illustrative catalog might contain:

json
{
  "account": {
    "invitation": "Approval is required before access is granted.",
    "support": "Contact support"
  }
}

Suppose only the target wording of account.invitation needs correction. Save the target and source revision, including the accepted account.support wording you want to retain.

Choose how to correct the wording #

For an exact one-off correction, edit the target value directly, check it in the application, and commit the reviewed catalog. Ordinary source updates can retain that edit while the message's source remains unchanged.

For regeneration, first give translation the information it needs to produce a different result. Add an approved term to the engine's glossary, correct a recurring instruction in its rules, or clarify a message's JSONC context. Then refresh the affected keys. Regenerating with unchanged source and guidance can return the same wording.

Give term selection a semantic boundary #

Define the term's meaning before selecting messages. For example, a product's “workspace” can mean a shared project area, while another passage describes a physical workspace. Record the intended product sense and the team's approved target term in the glossary, then select only the messages using that sense. Term boundaries develops that decision.

Select an existing target key with the CLI #

In a configured project using that JSON source at locales/en/account.json:

bash
lingo push "locales/en/account.json" --key "account.invitation" --wait

For JSON, --key regenerates selected units even when source text is unchanged. It refreshes those keys in each configured locale that already has a target file, merging the new values into that target.

Save existing corrections before refreshing: the target captured by this push is eligible for replacement in the selected keys. To detect target edits made after submission, omit --wait and inspect lingo pull --dry-run before collecting. See Pull's local-edit classification for conflict handling.

A key refresh leaves the whole-source baseline unchanged, whether push --wait or a separate pull collects it. Pending ordinary source edits therefore still reach a later plain push.

Key patterns support exact keys, object prefixes, and whole-segment * wildcards. auth.login can include auth.login.title without matching auth.login_url. Quote wildcards and repeat --key for several intended patterns.

JSONC, TypeScript, and PHP have the same scoped refresh behavior. YAML and locale-root YAML can retain unchanged selected translations; edit the target directly for an exact correction, or save accepted targets before whole-file regeneration. CLI scopes lists format behavior and defines key spelling.

Find the keys or files affected by a term #

Find source messages that use the intended sense of the term and inspect their context. Select their supported keys with --key, using the command above. For formats that need whole-file regeneration, save the accepted targets and refresh the affected source files, for example:

sh
lingo push 'docs/en/workspaces.md' --force --wait

Use a source path already selected in your configuration. This replaces that file's translations for the configured target locales. Compare the whole rewritten message or file, including text around the term.

Verify change, preservation, and use #

Compare each changed target path with the saved version. In the example, the invitation must retain required approval before access, and the support message must match its accepted baseline. Missing neighbors or unexpected rewrites call for scope and baseline inspection before acceptance.

Check variables and key controls: a lock copies source text, preservation retains a target value, and ignoring removes content from a supporting format's output.

Load the output in the consuming runtime. For documents, inspect the changed passage, links, and components. Resolve pull conflicts before replacing local edits, then commit the accepted targets with their source revision and lockfile.