CLI v0 key controls and manual edits

Keep source-owned values, human-owned translations, and ordinary corrections distinct in legacy catalogs.

An ordinary manual correction and a preserved key have different lifetimes. V0 normally retains a present target while its source is unchanged. A preserved key reserves the value for human maintenance even when source text changes.

Correct an ordinary translation #

Edit the target value directly and commit the accepted wording. With unchanged source, the ordinary delta can retain it. A changed source checksum makes that key eligible for translation again, and force can replace it without a source change.

Use this for a correction whose meaning should be reconsidered when the source changes. For content that must remain human-owned, choose preservation and a process for reviewing source changes.

Assign ownership explicitly #

ControlLegacy output behavior
lockedKeysCopy the source value; this can overwrite a target edit.
ignoredKeysExclude selected content from translation and output.
preservedKeysSeed a missing value from source, then retain the target for human maintenance.
json
{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name"],
      "ignoredKeys": ["internal/*"],
      "preservedKeys": ["legal/terms"]
    }
  }
}

Here the brand name stays identical, internal entries disappear, and legal terms remain human-owned. A newly preserved source-language placeholder still needs translation before release. If the application expects an ignored key, provide a fallback or change that expectation.

Inspect overlapping control patterns rather than assuming an undocumented precedence. This v0 behavior differs from current target-preservation controls.

Address nested and literal keys #

Legacy paths use slash traversal. brand/name selects name inside brand; modules/ai.translation selects a literal dotted key within modules. Wildcards follow the legacy matcher and should be tested at the intended depth. Current dot/bracket syntax is not interchangeable.

Rename reuse #

The old delta can match a new key's source-value hash with a removed key's previous hash in the same processed path context. If text stays identical, an existing target can move to the renamed key without a new translation.

Changing both key and source creates new work. Moving between independent paths or using repeated identical strings needs inspection; the match is not unrestricted translation memory. Current JSON identities are path-based and do not inherit this behavior.

Use Retranslation for deliberate replacement and Translator notes for contextual guidance. Neither is a substitute for choosing who owns an output value.