Key controls
Choose whether a value comes from source content, an existing target, translation, or locale metadata.
Some catalog values should remain identical across languages. Others belong to a human-maintained target. Key controls make those choices explicit when a supporting file handler reconstructs output.
These are file-entry options in .lingo/config.json. They do not choose files or request a key refresh; translation scopes do that.
| Control | Output behavior |
|---|---|
lockedKeys | Copy the source value without translating it. |
preservedKeys | Keep the existing target value when available. |
ignoredKeys | Remove selected content from a supporting format's output. |
injectLocale | Write the target locale at a selected location. |
Give each value an owner #
{
"pattern": "locales/en.json",
"lockedKeys": ["product.id"],
"preservedKeys": ["legal.notice"],
"ignoredKeys": ["internal.note"],
"injectLocale": { "enabled": true, "key": "meta.locale" }
}Here the product ID comes from the source, an existing legal notice remains from the target, and the internal note is omitted. Locale injection writes the target locale to meta.locale, creating missing object containers when needed. For array locations, provide an existing array and select an existing element or the position immediately after its end; paths that create gaps or cross incompatible values fail.
Preservation cannot create a human translation where none exists. Ordinary incremental work already uses existing target content to keep unchanged-key edits; preservedKeys adds deliberate protection beyond that behavior. A changed source or renamed JSON key can still require new work.
Paths and overlapping controls #
JSON/JSONC controls use dot names and bracket indices, such as checkout.submit or items[0].title. A protected path can cover descendants. Use a quoted JSONPath property, such as $['checkout.submit'], when a literal key contains a dot. lingo push also reads lists written for the earlier CLI with /: each name between / is taken whole, so checkout/submit equals checkout.submit and common/error.message names the key error.message under common. Percent-encoded names such as legal/Terms%20of%20use are decoded; a pattern without / is a dot path and is not decoded, so write a single encoded name as JSONPath, such as $['Terms of use']. Because every pattern with / is read this way, a key whose name contains / needs JSONPath, such as $.routes['/about'].title. A trailing *, as in internal/*, covers the values directly under internal but not objects or arrays nested there, as in the earlier CLI. The earlier CLI also matched keys that continue with - or ., so legal/terms covered legal/terms-short. That prefix match is gone; list such keys separately. The GitHub App does not accept the slash form: when the App reads the same configuration, write these lists with dots or as JSONPath. Scopes describes this form.
At the same location, an ignored rule removes the value, including an injected locale value. Locale injection takes precedence over locking and preservation. A lock takes precedence over preservation, so a key in both lists uses its source value. An ignored ancestor also removes its descendants. Give each value one owner where possible, and inspect the output when rules overlap across an object or array.
Whole-file force clears the current-target artifact sent to the server. A preserved rule cannot retain earlier human wording when that target context is absent. Keep a recoverable copy before forced replacement.
Handler boundaries #
JSON and JSONC support all four controls. TypeScript, PHP, YAML, and locale-root YAML support locking, preservation, and ignoring; stringsdict supports locking and preservation. Java properties supports locking, preservation, ignoring, and key scope, matching each pattern against the whole key as the previous CLI did. CSV supports none of the three key rules: the CLI and the GitHub App reject a CSV entry that sets lockedKeys, preservedKeys or ignoredKeys. Read the chosen format reference for its output behavior.
The short path form supports whole-segment *, numeric indices, and empty brackets. It rejects partial wildcards. With lingo push, the three key-rule lists also accept the slash form; the GitHub App and the injection location do not. Use quoted JSONPath properties for literal names containing punctuation; explicit $ queries pass through. Injection requires one location, with language as the enabled default key.