Translation keys: naming conventions and organizing

You already know that translating your app is important, and you’re familiar with the general localization process. But as the saying goes, “the devil is in the details”—and one crucial detail that often gets overlooked is how you manage translation keys. Organizing and naming these keys effectively is essential to keeping the localization process smooth, especially as your app grows and evolves.

In this article, we’ll cover ten best practices for naming and organizing translation keys. These aren’t rigid rules but practical tips that can make a big difference. By following them, you can avoid common issues like key duplication, inconsistent naming, and disorganized translation files—problems that can slow down translators and complicate your localization workflow.

Think of this guide as a roadmap to make localization simpler—not only for the current version of your app but also for future updates and additional languages as your app expands.

10 best practices for translation keys

1. Develop a proper naming scheme

A solid naming scheme is import for keeping your translation keys organized. Without one, you could end up with inconsistent key structures across your team, making localization more difficult. Here’s how to ensure consistency and avoid chaos.

Important decisions to make:

• Naming convention: Choose between CamelCase or snake_case for key names. Consistency is key to avoid confusion.
• Handling similar keys: Plan how to differentiate similar keys used in various contexts. Options include:
  • Prefixes/Postfixes: Add context to keys (e.g., login_button, signup_button).
  • Namespaces: Group related keys under categories (e.g., forms.buttons.login).
• Addressing duplicates: Decide how to handle potential key duplication early. Key duplication can lead to translation conflicts or errors.
• Descriptive naming: Keep key names simple and meaningful. Avoid vague or overly complex names like btn1 or msg, which don’t provide context for developers or translators.

Example of a good naming scheme:

For example, consider the following naming scheme for buttons:

• forms.buttons.login_button – for a login button
• forms.buttons.signup_button – for a signup button
• errors.email_invalid – for an invalid email address error

These names are clear, descriptive, and grouped logically to avoid confusion.

To summarize:

• Do: Create consistent naming conventions (e.g., CamelCase or snake_case).
• Do: Use prefixes/postfixes or namespaces for similar keys in different contexts.
• Don’t: Use overly generic names like btn1, label2, or option.
• Don’t: Allow key duplication to go unchecked.

2. Give translation keys meaningful names

When naming translation keys, it’s essential to use descriptive, purposeful names. A well-named key provides clarity for both developers and translators by clearly describing its function. Poorly named keys can lead to confusion, making it harder to understand the content or context of the translation.

Important considerations for meaningful names:

• Descriptive naming: The key name should clearly describe its purpose, similar to how you’d name a variable in your code. It should be clear and meaningful at a glance.
  • Good examples: welcoming_message, choose_locale
  • Bad examples: heading, dropdown (too vague and generic)
• Avoid overly specific names: Key names shouldn’t be tied to the exact translation value. Focus on describing the purpose of the key, not the precise wording of the translation itself.
• Avoid using translation values as key names: In most cases, the translation text itself should not be used as the key name. For example, avoid naming a key "Confirm" for a button labeled “Confirm.” If the button text changes later (e.g., from “Confirm” to “OK”), you would need to update the key across the entire codebase, which could lead to errors.
  • Note on Gettext: Some localization systems, like Gettext, use the actual text as the key (known as “message IDs”). While this works for certain projects, it may not offer the flexibility needed for apps with rapidly changing content. For systems that support custom key names, it’s better to use descriptive names rather than the text itself.

Tip:

When multiple developers are working on a project, establish clear guidelines for naming conventions to ensure consistency across the team. Tools like Lokalise offer a collaborative environment where developers can manage and comment on translation keys through a web interface. This helps prevent miscommunication and ensures that everyone stays aligned on the purpose of each key.

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: Make key names descriptive and purposeful (e.g., welcoming_message, choose_locale).
• Do: Keep key names consistent, even if the translation value changes later.
• Don’t: Use vague key names that fail to describe the content (e.g., heading, dropdown).
• Don’t: Use the actual translation value as the key name—unless using a system like Gettext, which supports this approach.

3. Group translation keys into namespaces

If your technology supports it, grouping translation keys into namespaces can greatly improve the organization of your localization files. Namespaces can be based on different pages of your site, sections of your app, or logical groupings, making the management of translations easier as your app 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 reduces the risk of keys getting lost in long, unorganized lists, making your localization more manageable as your app scales.

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, ensure there’s a consistent structure across your 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 consistency prevents confusion and ensures uniformity in larger projects.

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.
• Don’t: Over-nest translation keys—it will make maintenance harder over time.
• Do: Establish a consistent naming structure for namespaces across your project.

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. Rather than creating separate keys for each instance, grouping these common keys under a global namespace (or general namespace) helps maintain consistency, reduces key duplication, and keeps your translation 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 minimizing 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:

Here’s an example of how a global namespace might look:

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

This structure helps you maintain consistency across screens and components without duplicating keys for common UI elements like buttons and labels.

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 can greatly simplify your translation files and make localization easier for translators. However, it’s important to strike the right balance between minimizing duplication and maintaining flexibility for different contexts.

Why reduce duplication?

• Simplified translations: Fewer keys mean less work for translators, leading to a more streamlined localization process.
• Ease of management: Managing a smaller number of keys makes it easier to update and maintain translations.

How to consolidate duplicate keys:

• Manual identification: You can manually search for and consolidate duplicate keys, replacing them with a single, shared key when they represent the same meaning.
• Use automation tools: Some localization tools provide scripts or automation to detect and remove duplicate keys. Introducing a global namespace (see above) allows shared keys to be reused across multiple parts of the software, reducing duplication.

Be careful with “god” keys:

While reducing duplication is important, avoid using a single “god” key across all contexts. This can lead to unintended issues. 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. Using one key for both can lead to awkward or inappropriate 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 different keys to form a new string—can lead to significant localization issues, especially when working with multiple languages. Although it might seem like a shortcut to avoid creating new keys, concatenation often results in 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 can result in grammatically incorrect or awkward sentences in other languages.
  • 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: In most cases, it’s better to create a new translation key for any unique text combination, even if it seems repetitive. This ensures that translations remain contextually accurate and sound natural in all languages.

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 linked translations don’t fit the context, you can easily remove the link and create a separate key when necessary.

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.
• 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, it’s essential to regularly audit and remove unused translation keys. These “orphan” keys, which no longer have references in your codebase, can clutter your translation files and make managing translations more challenging for both developers and translators.

Why remove unused keys?

• Prevents bloat: Unused keys add unnecessary bloat to your translation files (e.g., JSON, PO files), making them harder to navigate and manage.
• Reduces confusion: It’s more difficult to track which keys are in active use when unused keys remain. This can lead to confusion as your app grows in size and complexity.
• Improves efficiency: Keeping translation files tidy ensures easier maintenance and allows translators to focus on relevant keys, improving the overall localization process.

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 offer scripts or features to automatically detect and remove unused keys. This can streamline the cleanup process, especially for larger, more complex apps with extensive localization requirements.

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: Forget that unused keys can lead to bloated and unmanageable translation files.

8. Place translations into separate files and folders

As your app grows, managing translations can become more complex. Storing all translation keys for all supported languages in a single file is not scalable and can quickly become overwhelming. Organizing translations into separate files and folders based on language and scope is a more effective strategy.

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:
  • /translations/en/
  • /translations/fr/
  • /translations/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 translations
  • static_pages_de.json for static page translations

By organizing translations in this way, you reduce complexity and make localization easier to manage. It also enables you to scale more effectively as your app grows to support additional languages or new 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 sometimes eliminate the need to physically separate keys into different 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 is essential. Documenting your keys ensures that everyone understands the purpose and usage of each key, preventing confusion and mistranslations. This is particularly important when key names aren’t self-explanatory or when meaning depends on specific contexts, such as UI elements or user flows.

Why documentation matters:

• Clarity for developers and translators: Proper documentation helps avoid miscommunication, especially when key names don’t fully explain their intended purpose.
• Improved accuracy: Contextual information ensures that document translation is accurate and suitable for their usage, minimizing guesswork and potential errors.

How to document translation keys:

• Use comments or descriptions: Many translation formats, like PO files, allow you to add 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 allow you to add descriptions, comments, and even upload screenshots directly to individual keys. 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: Assume that key names alone are sufficient—context is crucial for accurate translations, especially for non-technical translators.

10. Regularly review and refactor translation keys

As your app evolves and new features are added, your translation keys may become outdated, redundant, or irrelevant. To maintain a clean and scalable localization system, it’s essential to regularly review and refactor your translation files.

Why regular reviews are important:

• Prevent clutter: Over time, unused or outdated translation keys can accumulate, cluttering your files and making them harder to manage and maintain.
• Ensure consistency: Regularly reviewing your keys allows you to spot inconsistencies, simplify namespaces, and consolidate similar keys, keeping your localization clean and organized.
• Improve translator experience: A well-structured set of keys makes it easier for translators to navigate the files, reducing the likelihood of errors and speeding up the translation process.

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: Ensure that key names are consistent with the current state of the app and relevant to the features you are supporting.

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 your translation files become cluttered with old, redundant, or obsolete keys.

Conclusion

In this article, we’ve explored ten practical recommendations for naming and organizing your translation keys. While it may not always be necessary to follow every suggestion exactly, keeping these best practices in mind will help you avoid common pitfalls and ensure your localization process runs smoothly. By adopting clear naming conventions, organizing translations efficiently, and regularly managing your keys, both developers and translators will benefit from a cleaner, more scalable workflow.

I hope these tips help you streamline your translation management and support the growth of your app. Thanks for reading, and good luck with your next localization project!