Key Preserving
Deprecated
These docs cover the legacy CLI (v0). The current CLI is v1. See the current CLI docs
Preserved keys are initialized once with source values and then protected from automatic updates. The CLI never overwrites them - they serve as placeholders for content that requires manual translation, such as legal text, compliance copy, or marketing taglines.
Configuration#
Add preservedKeys to a bucket in i18n.json:
json
{
"buckets": {
"json": {
"include": ["locales/[locale].json"],
"preservedKeys": ["legal/privacy", "legal/terms"]
}
}
}How it works#
Given this source file:
json
{
"welcome": "Welcome to our platform",
"legal": {
"privacy": "We respect your privacy and protect your data.",
"terms": "By using this service, you agree to our terms."
}
}On the first run, the CLI copies preserved keys as-is while translating everything else:
json
// locales/es.json (first run)
{
"welcome": "Bienvenido a nuestra plataforma",
"legal": {
"privacy": "We respect your privacy and protect your data.",
"terms": "By using this service, you agree to our terms."
}
}After you manually translate the legal section, subsequent CLI runs leave your translations intact.
Key Preserving vs. Key Locking#
| Key Preserving | Key Locking | |
|---|---|---|
| Initial value | Source value as placeholder | Source value (always) |
| Manual edits | Preserved permanently | Overwritten with source on each run |
| Use case | Legal, compliance, manual translation | Brand names, technical IDs |
Key path notation#
Use forward slash (/) for nested keys and asterisk (*) for wildcards:
json
{ "preservedKeys": ["legal/*", "marketing/tagline"] }