Avoiding i18n Key Duplication Across Translation Files

Avoiding i18n Key Duplication

Duplicate translation keys cause silent overwrites where one value replaces another without warning. In large projects with multiple contributors, duplicates are surprisingly common and can lead to incorrect translations appearing in production.

Types of Duplication

1. Exact Duplicate Keys

Two entries with the identical key in the same file:

{
  "buttons.submit": "Submit",
  "buttons.submit": "Send"
}

JSON parsers silently use the last value. The developer intended "Send" for a different context but accidentally reused the key.

2. Semantic Duplicates

Different keys with the same value:

{
  "auth.login.submit_button": "Submit",
  "settings.profile.save_button": "Submit",
  "checkout.payment.submit_button": "Submit"
}

While technically not errors, semantic duplicates waste translator effort (translating "Submit" three times) and create inconsistency risk if one instance is updated but others are not.

3. Cross-File Duplicates

The same key defined in multiple namespace files:

common.json:  { "buttons.save": "Save" }
settings.json: { "buttons.save": "Save Changes" }

Prevention Strategies

Shared Key Namespace

Create a common namespace for strings used in multiple places:

{
  "common": {
    "buttons": {
      "submit": "Submit",
      "cancel": "Cancel",
      "save": "Save",
      "delete": "Delete"
    }
  }
}

All components reference common.buttons.submit instead of defining their own.

Key Collision Detection

Use tools that detect collisions:

• The i18n Key Generator warns when two inputs generate the same key
• eslint-plugin-i18n-json validates JSON translation files for duplicates
• i18next-parser can detect when the same key is used with different default values

Code Review Checklist

During code review, check:

1. Is the new key truly unique?
2. Could an existing key from common be reused?
3. If the same text appears elsewhere, should it be consolidated?
4. Does the key follow the naming convention?

Automated Detection Script

A simple script to find duplicates in JSON:

# Find duplicate keys in translation JSON
jq -r 'paths(scalars) | join(".")' en.json | sort | uniq -d

When Duplication Is Acceptable

Sometimes the same English text should have different keys because:

• It may need different translations in other languages (context-dependent)
• The same word has different meanings in different contexts
• UI constraints require different lengths in different placements

In these cases, add a comment or context description to help translators understand why the duplicate exists.