The Lingo.dev CLI detects when you rename translation keys and preserves existing translations automatically. If the key name changes but the source content stays the same, the CLI applies the existing translation to the new key - no retranslation occurs.
How it works#
The CLI compares content fingerprints, not key names. When a fingerprint match is found under a different key, the CLI recognizes it as a rename.
// locales/en.json (before refactoring)
{
"welcome_msg": "Welcome to our platform",
"btn_save": "Save"
}
// locales/es.json (existing translations)
{
"welcome_msg": "Bienvenido a nuestra plataforma",
"btn_save": "Guardar"
}After renaming keys in the source file:
// locales/en.json (after refactoring)
{
"homepage.welcome": "Welcome to our platform",
"button.save": "Save"
}Running npx lingo.dev@latest run preserves the translations:
// locales/es.json (translations carried forward)
{
"homepage.welcome": "Bienvenido a nuestra plataforma",
"button.save": "Guardar"
}Detection rules#
Key rename is detected when:
- The key name changes
- The source content remains identical
- The key exists in the same bucket
Key rename is not detected when:
- Both key and content change simultaneously (treated as a new key)
- Only the content changes (treated as a content update, triggers retranslation)
Mass refactoring#
Rename detection works at any scale. You can reorganize your entire key structure - from flat keys to nested namespaces - and the CLI carries all matching translations forward in a single run.