The Lingo.dev CLI provides four key-level controls that determine how individual translation keys behave during processing. Each serves a distinct purpose:
| Control | Config field | Behavior |
|---|---|---|
| Key Locking | lockedKeys | Copies source values to all targets without translation. Keys appear in target files with identical values. |
| Key Ignoring | ignoredKeys | Excludes keys from processing entirely. They do not appear in target files. |
| Key Preserving | preservedKeys | Initializes keys once from source, then protects them from automatic updates. Designed for content that requires manual translation. |
| Key Renaming | Automatic | Detects when keys are renamed and preserves existing translations. No configuration required. |
When to use what#
Lock a key when the value must remain identical across all languages - brand names, technical identifiers, configuration values:
{ "lockedKeys": ["brand/name", "config/apiUrl"] }Ignore a key when it should not exist in target files at all - debug strings, internal flags, test data:
{ "ignoredKeys": ["internal/debug", "dev/testData"] }Preserve a key when it needs manual translation - legal text, compliance content, marketing copy that requires human review:
{ "preservedKeys": ["legal/privacy", "legal/terms"] }Renaming is automatic - the CLI detects when a key changes but its content stays the same, and carries the existing translation forward without retranslation.
Key path notation#
All key arrays use forward slash (/) notation for nested paths and asterisk (*) for wildcards:
{
"lockedKeys": ["brand/name"],
"ignoredKeys": ["internal/*"],
"preservedKeys": ["legal/privacy/full"]
}Keys containing dots in their names are handled naturally - the forward slash separates hierarchy levels, so modules/ai.translation correctly targets the key "ai.translation" inside the "modules" object.