Translation key naming conventions: 11 best practices for developers

Examples:

• Welcoming message: welcoming_message (descriptive and purpose-driven)
• Locale selection: choose_locale (clearly relates to choosing a language or locale)
• Vague options: heading or dropdown (too generic—lacking clarity and context)

To summarize:

• Do: Use descriptive, purpose-driven key names (e.g., welcoming_message, choose_locale).

• Do: Keep key names stable, even if the translation value changes later.

• Don’t: Use vague names that don’t describe the content (e.g., heading, dropdown).

• Don’t: Use the translation text itself as the key name—unless your system (like Gettext) is built for it.

Bad vs good translation key naming examples

3. Group translation keys into namespaces

Grouping translation keys into namespaces improves the organization of your localization files. Namespaces can reflect pages, features, or logical sections of your app, making translations easier to manage as the project grows.

Benefits of using namespaces:

• Avoid name clashes: Different sections of your app may use similar terms like save, but with different meanings. Without namespaces, you would need to add prefixes or suffixes (e.g., profile_save, order_save) to differentiate them. With namespaces, you can separate these keys cleanly—e.g., order.save and profile.save—avoiding conflicts.
• Improve organization: Nesting keys into logical groups helps maintain a clear structure in your translation files. This keeps keys easy to find and prevents them from getting lost in large translation files.

Example of namespaced key structure:

Here’s an example of a JSON translation file. It demonstrates how you could structure your translation keys using namespaces for different parts of the UI, such as orders, profiles, and forms:

{
  "order": {
    "checkout": "Proceed to checkout",
    "continue_shopping": "Return to the store and continue shopping",
    "discard": "Remove all items from the cart and discard the order",
    "save": "Save the order as draft"
  },
  "profile": {
    "save": "Save profile changes",
    "undo": "Undo all recent profile changes",
    "edit_password": "Edit your password"
  },
  "forms": {
    "buttons": {
      "login_button": "Log In",
      "signup_button": "Sign Up",
      "submit_button": "Submit"
    },
    "labels": {
      "email_address_label": "Email Address",
      "shipping_address_label": "Shipping Address",
      "password_label": "Password"
    }
  },
  "errors": {
    "email_invalid": "Please enter a valid email address",
    "password_required": "Password is required"
  }
}

In this example, the keys are grouped into namespaces like order, profile, forms, and errors, which helps keep translations organized and scalable.

Tips:

• Avoid excessive nesting: Limit the depth of your namespaces to 2-3 levels. Over-nesting can make it difficult to maintain and manage translations over time.
• Establish consistency: When using namespaces, keep the structure consistent across the project. Agree on how namespaces will be organized (e.g., by pages, features, or UI elements) so that all team members follow the same pattern. This prevents confusion and keeps large projects predictable and easier to maintain.

To summarize:

• Do: Use namespaces to avoid key name clashes (e.g., order.save vs. profile.save).
• Do: Limit nesting to 2-3 levels for simplicity.
• Do: Establish a consistent naming structure for namespaces across your project.
• Don’t: Over-nest translation keys—it will make maintenance harder over time.

4. Take advantage of a global namespace

In most apps, certain translation keys—like "Profile," "Save," "Next," "Option", and "Cancel"—are reused across multiple screens and components. Grouping these common keys under a global namespace (or general namespace) keeps translations consistent, reduces duplication, and keeps files clean.

Benefits of using a global namespace:

• Consistency across UI elements: Shared elements like buttons, form actions, and navigation labels maintain a consistent translation across your software. For example, using global.ok ensures every "Okay" button is uniform and easy to update if needed.
• Simplified management: By centralizing common translations, managing updates becomes more straightforward. Updating global.cancel changes "Cancel" throughout the app, reducing redundancy and inconsistencies.
• Cleaner translation files: Grouping frequently used terms into a global namespace prevents clutter and duplicate keys in your translation files.

Example of a global namespace:

The example below shows a simple global namespace:

{
  "global": {
    "ok": "Okay",
    "cancel": "Cancel",
    "next": "Next",
    "previous": "Previous"
  }
}

This structure keeps UI text consistent across screens without duplicating keys.

Tips:

• Avoid overcomplicating the global namespace: Stick to common, frequently used elements. Don’t clutter the global namespace with unrelated keys, as this will bloat the file and make it harder to manage.
• Potential pitfall: While global namespaces are great for consistency, avoid using them for elements that need unique translations in different contexts. For instance, global.ok may work across most of your software, but in some cases, a more specific translation like "Confirm" or "Agree" may be needed. In those situations, create separate keys to ensure contextual accuracy.

To summarize:

• Do: Group frequently used keys (e.g., buttons, navigation labels) into a global namespace.
• Do: Ensure consistency by using the same key across different parts of the app (e.g., global.ok for all "Okay" buttons).
• Don’t: Create separate duplicate keys for common terms in different contexts.
• Don’t: Overcomplicate the global namespace by adding too many unrelated keys.

5. Avoid translation key duplication

Translation key duplication is a common issue in large projects, and reducing duplicate keys simplifies translation files and makes localization easier to manage. However, balance matters: reduce duplication without losing context flexibility.

Why reduce duplication?

• Simplified translations: Fewer keys reduce translator workload and speed up the localization process.
• Ease of management: Fewer keys are easier to maintain and update.

How to consolidate duplicate keys:

• Manual identification: Manually identify duplicate keys and replace them with a single shared key when they have the same meaning.
• Use automation tools:
  • Automation tools can detect and remove duplicate keys.
  • A global namespace (see above) enables reuse across the app and reduces duplication.
  • Translation memory tools store and suggest existing translations, improving consistency and reducing repeated work.
• Want to learn more? Discover benefits of translation memory to make the most of it.

Avoid "god" keys (one key for everything):

While reducing duplication is important, avoid using a single "god" key across all contexts. This breaks flexibility and creates problems when text needs to change in one place but not others. For example:

• A key like confirm might be used for all confirmation actions, but if your designer wants to change "Confirm" to "OK" on the registration page, you’ll need to create a new key (e.g., registration_confirm) to avoid impacting other parts of the app.

Context matters:

Words and phrases often change meaning based on context. For instance:

• A key like save might be used both on a settings page and in a shopping cart, but the tone or meaning could differ. Reusing one key across different contexts leads to incorrect or awkward translations. Create separate keys when necessary to preserve context.

Tips:

• Tip: Tools like Lokalise offer a duplicate finder feature, making it easier to detect and resolve duplicate keys. This is particularly helpful in large-scale projects with extensive localization needs.

To summarize:

• Do: Consolidate duplicate keys when they represent the same meaning or context.
• Do: Use tools or scripts to find and remove duplicated translation keys.
• Don’t: Use a single key for everything (e.g., confirm or save) across different contexts.
• Don’t: Overuse global keys, especially when slight differences in meaning or tone matter.

6. Avoid concatenating translations

Concatenating translations—combining multiple keys into a single string—creates localization issues, especially in multilingual apps. It may seem like a shortcut, but it often produces awkward or incorrect translations.

Why concatenation is problematic:

• Word order varies across languages: Not all languages follow the same word order as English. Simply combining words often produces grammatically incorrect or unnatural sentences.
  • Example: In English, “Agree and proceed” makes sense, but in Russian, concatenating “соглашаюсь” (agree) and “продолжить” (proceed) results in “соглашаюсь и продолжить,” which is grammatically incorrect.

The better approach:

• Create unique keys: Add a new translation key for each unique text combination, even if it seems repetitive. This ensures that translations remain contextually accurate and sound natural in all languages.
• Use structured message formats: The ICU Message Format lets developers embed plural and gender logic into a single key, removing the need for string concatenation in most cases. This keeps translations flexible and grammatically correct without splitting them into multiple pieces.

Tools for reusing translations:

• Tip: Some localization platforms, like Lokalise, allow you to link translation keys. This way, you can reuse translations from other keys without concatenation. If the reused translation doesn’t fit the context, remove the link and create a separate key.

To summarize:

• Do: Create a new translation key for each unique text, even if parts of it seem repetitive.
• Do: Use translation tools that support key linking when appropriate for your workflow. Many CAT tools offer this functionality, making it easier to manage related content and maintain consistency across your translations.
• Don’t: Concatenate multiple translation keys to create new strings.
• Don’t: Assume word order will be the same across all languages—it often isn’t.

7. Remove unused translation keys

To maintain a clean and efficient localization process, regularly audit and remove unused translation keys to keep the localization process clean and efficient. These "orphan" keys no longer exist in the codebase and clutter translation files, making them harder to manage.

Why remove unused keys?

• Prevents bloat: Unused keys bloat translation files (e.g., JSON, PO), making them harder to navigate and maintain.
• Reduces confusion: Unused keys make it harder to track which translations are actually in use. This creates confusion as the app grows in size and complexity.
• Improves efficiency: Clean translation files are easier to maintain and help translators focus on relevant keys.

How to manage unused keys:

• Manual audits: Regularly review your translation files to identify and remove orphaned keys that are no longer in use.
• Automation tools: Many localization tools include features to detect and remove unused keys automatically. This streamlines cleanup, especially in large and complex apps.

To summarize:

• Do: Regularly audit and remove unused (orphan) translation keys from your files.
• Do: Use scripts or tools to automate the detection of unused keys.
• Don’t: Leave unused keys in your translation files—they add clutter and confusion.
• Don’t let unused keys accumulate—they quickly make translation files hard to manage.

8. Place translations into separate files and folders

As your app grows, managing translations becomes more complex. A single file for all languages does not scale and quickly becomes hard to manage. Storing each language in a separate file (e.g., en.json, fr.json) reduces translation file complexity and makes exports predictable.

Depending on your platform, this might also include formats like .strings (iOS), strings.xml (Android), or .xliff in enterprise workflows. For example, Lokalise supports 30+ file formats, so teams can work across different technologies without changing their structure.

How to manage translations effectively:

• Separate by language: Store translations for each language in its own file to keep things organized. For example:
  • en.json for English
  • fr.json for French
  • de.json for German
• Organize by folder: Store language files in respective folders for better structure. For example:
  • /translation/en/
  • /translation/fr/
  • /translation/de/
• Divide by scope: For larger apps, you can further divide translation files based on features or sections of the app. For instance:
  • blog_en.json for blog-related translations
  • forum_fr.json for forum-related translation
  • static_pages_de.json for static page translations

This structure reduces complexity and makes localization easier to manage. It also scales well as your app grows and supports new languages or features.

Tips:

• Tip: Platforms like Lokalise allow you to assign translation keys to different files. When exporting translations, you can select the specific keys, languages, and file structures you want. Lokalise’s flexible approach—allowing you to filter and tag keys—can remove the need to physically separate keys into multiple files.

To summarize:

• Do: Store translations for each language in separate files (e.g., en.json, fr.json).
• Do: Organize translations by folder for easier management.
• Do: Consider dividing translation files by scope (e.g., blog, forum, static pages).
• Don’t: Store all translations for every language in a single, massive file.
• Don’t: Overcomplicate your folder structure—keep it simple but scalable.

9. Document translation keys for developers and translators

In large projects with multiple developers and translators, providing context for translation keys prevents confusion and mistranslations. Documenting your keys ensures that everyone understands the purpose and usage of each key, preventing confusion and mistranslations. This matters most when key names aren’t self-explanatory or when meaning depends on UI context or user flows.

Why documentation matters:

• Clarity for developers and translators: Documentation prevents miscommunication between developers and translators.
• Improved accuracy: Contextual information ensures translations are accurate and match their intended usage, minimizing guesswork and potential errors.

How to document translation keys:

• Use comments or descriptions: Formats like PO files support comments that provide critical context for translators. Here’s an example:

# This message is shown on the login button
msgid "login_button"
msgstr "Log In"

# Context: Error message displayed when a user's password is incorrect
msgid "invalid_password"
msgstr "The password you entered is incorrect."

# Translators: Please note this is used for confirmation pop-ups
msgid "confirm_action"
msgstr "Confirm"

In this example, comments help translators understand the context and purpose of each key, especially when the key name alone doesn’t provide enough information.

Tips:

• Translation management systems (TMS) like Lokalise support descriptions, comments, and even uploading screenshots for each key. Screenshots provide additional visual context, ensuring that translators understand how the translation is used in the app, especially for UI elements.

To summarize:

• Do: Provide documentation or comments for complex or less obvious translation keys.
• Do: Include context to guide translators, especially when the key’s purpose isn’t immediately obvious.
• Don’t rely on key names alone—context is required for accurate translations.

10. Regularly review and refactor translation keys

As your app evolves, translation keys become outdated, redundant, or irrelevant. Regular reviews and refactoring keep your localization system clean and scalable as your app evolves.

Why regular reviews are important:

• Prevent clutter: Unused or outdated keys accumulate over time, cluttering files and making them harder to manage.
• Ensure consistency: Regular reviews reveal inconsistencies, simplify namespaces, and consolidate similar keys.
• Improve translator experience: A well-structured key system helps translators navigate files faster and reduces errors.

How to conduct regular reviews:

• Audit: Periodically audit your translation files to identify outdated or unnecessary keys.
• Refactor: Simplify and refactor your translation structure by consolidating similar keys and eliminating redundancies.
• Maintain consistency: Keep key names consistent with the current state of the app and its features.

To summarize:

• Do: Regularly audit your translation files to find outdated or unnecessary keys.
• Do: Refactor translation keys to simplify your localization structure where possible.
• Do: Ensure that key names remain consistent and relevant to the current state of the app.
• Don’t let outdated or redundant keys accumulate—they quickly make files hard to manage.

11. Lock and protect source strings to prevent accidental changes

As your localization workflow scales, protecting source strings becomes critical. Uncontrolled changes to source text or key structure can break translations, create inconsistencies, and introduce unnecessary rework for translators.

Why protection matters:

• Prevent accidental changes: Source strings define the reference for all translations. Changing them without control can invalidate existing translations and create confusion.

• Maintain consistency: Stable keys and source text ensure predictable behavior across the app and reduce unexpected issues during updates.

• Reduce errors: Limiting who can edit keys or source language values lowers the risk of breaking translations.

How to protect translation keys:

• Restrict access by role: Use role-based permissions to control who can modify keys, source strings, or translations. For example, translators may only edit target languages, while developers or managers control source content.

• Protect source language: Limit edits to the source language to a small group of authorized users. This prevents unintended changes that could affect all translations.

• Control key structure: Restrict who can rename or delete keys to avoid breaking references in the codebase.

• Use platform controls: Most TMS platforms provide governance features such as permissions, audit logs, and change tracking to manage updates safely.

• Use branching workflows: Some platforms support branching, allowing teams to isolate changes to translation keys in separate environments (e.g., feature branches). This protects the main set of keys from accidental edits and ensures updates are reviewed before being merged.

To summarize:

• Do: Restrict access to source strings and key structure using roles and permissions.

• Do: Keep source language edits limited to trusted contributors.

• Don’t: Allow unrestricted edits to keys or source text—it leads to broken translations and inconsistencies.

• Don’t: Assume all contributors should have the same level of access—separate responsibilities clearly.

Quick reference checklist for translation key naming

Use this checklist to quickly review your localization setup and spot issues:

• Use a consistent naming convention (camelCase or snake_case)

• Make key names descriptive and purpose-driven

• Group keys into namespaces by feature or context

• Use a global namespace for shared UI elements (e.g., global.save)

• Avoid duplicate keys—reuse only when context is identical

• Don’t concatenate translations—use full phrases or structured formats

• Remove unused (or orphaned) keys regularly

• Store translations in separate files by language and structure

• Add comments, descriptions, or screenshots for context

• Review and refactor keys as your app evolves

• Restrict access to source strings and protect key structure

A clean and consistent key structure improves developer experience, reduces translation errors, and makes your localization workflow easier to scale.

Conclusion

This guide covered eleven practical recommendations for naming, organizing, and managing translation keys. Clear structure and consistent naming reduce errors, prevent duplication, and make localization easier to scale as your app grows.

Translation key management is just one part of a broader localization strategy. Learn more about the full process in our guide to software localization.

By applying these practices, teams keep translation files clean, workflows predictable, and collaboration between developers and translators efficient.