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 #
| Control | Legacy output behavior |
|---|---|
lockedKeys | Copy the source value; this can overwrite a target edit. |
ignoredKeys | Exclude selected content from translation and output. |
preservedKeys | Seed a missing value from source, then retain the target for human maintenance. |
{
"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.