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"] }