Namespace collision

In localization, strings are organized into namespaces, which are separate files or logical groups containing related translation keys. A collision happens when the same key name appears in the same namespace with different intended meanings. Because most i18n systems cannot distinguish between them, the last loaded value wins and quietly replaces the earlier one. No error gets thrown, and the wrong string gets served to users with no obvious indication of why.

A common example: two features both define a key called submit. In English both read “Submit,” but in other languages they may need different phrasing depending on context. If both files load into the same namespace, one translation overwrites the other at runtime.

💥 Where collisions come from #️⃣

The problem is most common when translation files from multiple sources get merged together. Multiple teams building features in parallel often reach for the same generic key names like save, cancel, title, or name without knowing others have done the same. The collision only surfaces when the files are combined.

Other common sources include third-party libraries or plugins that ship their own translation files with common key names, microservices whose translations get merged into a monolithic app, and white-label or vendor-provided translation packages. Case sensitivity adds another layer of risk: some file systems or frameworks treat Name and name as different keys that later collide when processed by a case-insensitive system.

🔑 Key points about namespace collisions #️⃣

• The last loaded translation silently overwrites earlier ones. Most i18n systems do not throw an error when this happens.
• Short, generic keys like title, save, cancel, and submit are the most frequent sources of collisions.
• Feature parallelization is a leading cause: teams working independently naturally reach for the same common key names.
• Third-party libraries and vendor translation packages are a less obvious but equally common source of conflicts.
• Duplicate keys within a single file are usually caught by JSON parsers, but some file formats allow them and will silently drop one.

Common solutions #️⃣

1. Use namespaces or prefixes — organize translations by feature or module and access them by specifying both namespace and key, for example common:save vs checkout:save. This is the most reliable structural fix.
2. Establish naming conventions — include context in key names from the start. button_checkout_save and form_profile_save make collisions obvious during code review before they become runtime problems.
3. Use hierarchical key structures — nested JSON objects or dot notation create natural separation within files. checkout.buttons.save and profile.buttons.save are far less likely to collide than a flat save.
4. Automate conflict detection — add CI/CD validation that scans for duplicate keys across all translation files and flags conflicts before they reach production.
5. Use a TMS with merge conflict resolution — platforms that detect key collisions on file import and provide a resolution workflow, where translators choose which translation to keep or create namespace-specific versions, prevent silent overwrites at the source.

How Localazy helps #️⃣

Localazy detects duplicate keys within a project during upload and surfaces them before they affect translators or reach production. Organizing strings into separate files per feature or platform also maps naturally to Localazy’s project structure, making namespace separation straightforward to maintain.

See also: managing duplicate strings in Localazy.