Key Renaming

Lingo.dev CLI automatically detects when you rename translation keys and preserves existing translations, avoiding unnecessary retranslation when only the key identifier changes.

When you refactor your code and rename keys for better organization, the CLI recognizes that the content is the same and applies existing translations to the new key names.

How Key Renaming Works

Lingo.dev CLI compares content fingerprints, not key names, to track translations. When you rename a key but keep the same content, the CLI detects this pattern and preserves your existing translations.

Example scenario:

// 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 refactoring key names:

// locales/en.json (after refactoring)
{
  "homepage.welcome": "Welcome to our platform",
  "button.save": "Save"
}

Running npx lingo.dev@latest i18n preserves the existing translations:

// locales/es.json (translations preserved)
{
  "homepage.welcome": "Bienvenido a nuestra plataforma",
  "button.save": "Guardar"
}

The CLI recognizes that the content is identical and applies existing translations to the new key structure.

When Key Renaming Is Detected

Lingo.dev CLI detects key renames when:

• The key name changes (welcome_msg → homepage.welcome)
• The source content remains identical ("Welcome to our platform")
• The key appears in the same bucket configuration

When Key Renaming Is Not Detected

The CLI treats these as new content requiring retranslation:

Content changes:

// Before
{
  "welcome": "Welcome to our app"
}

// After
{
  "welcome": "Welcome to our platform"
}

Both key and content change:

// Before
{
  "old_key": "Old content"
}

// After
{
  "new_key": "New content"
}

Mass Key Refactoring

Key rename detection works for large refactoring operations. You can reorganize your entire key structure and the CLI will preserve all matching translations.

Before refactoring:

{
  "welcome_text": "Welcome",
  "save_btn": "Save",
  "cancel_btn": "Cancel",
  "error_network": "Network error"
}

After refactoring to namespaces:

{
  "homepage.welcome": "Welcome",
  "buttons.save": "Save",
  "buttons.cancel": "Cancel",
  "errors.network": "Network error"
}

All translations are preserved because the content fingerprints match.

Forcing Retranslation

If you want to retranslate content despite having matching fingerprints, use the --force flag:

npx lingo.dev@latest i18n --force

This bypasses key rename detection and retranslates all content, useful when you want fresh translations after changing AI models or prompts.

For more information on retranslation, see Retranslation.