Translation keys: Best practices for naming them

Translation keys are identifiers used in internationalization (i18n) and localization (l10n) processes to reference specific strings or messages in a software application. These keys act as a link between the original source text in a base language and its translated versions in other languages.

By using translation keys, developers can easily manage and update translations without altering the source code, among other benefits. This separation allows for efficient collaboration between developers and translators and makes it simpler to maintain multilingual applications.

We’ve put together this list of best practices when it comes to naming translation keys to help developers create translation keys that are easy for translators to understand and use. This will help to produce high-quality translations and streamline the localization process.

How to name translation keys

We know that naming translation keys can be a challenge, but choosing good translation keys is crucial for maintaining a clear and organized codebase. Incorrectly named localization keys can lead to a range of issues, including misinterpretation, difficulty in maintenance, inconsistencies, increased risk of bugs, collaboration challenges, impact on user experience, search and debugging difficulties, reduced scalability, and integration problems. To mitigate these issues, it makes sense to establish and follow a standardized naming convention for localization keys, ensuring clarity and consistency throughout the development and localization process.

Here are some guidelines on how to name translation keys:

Be descriptive

Choose keys that clearly describe the content or purpose of the translation. For example, instead of using generic names like key1 or text123, use something like homepage.title or login.button.

Use a hierarchy

Structure keys hierarchically to mirror the organization of your application. This makes management and categorization more intuitive. For instance, you could use section.subsection.item for a clear hierarchy.

Include Variable Information

When dealing with dynamic content or placeholders, include variables within the keys to represent these changing elements. Like using greeting.user where {user} is a variable.

Be consistent

Stick to a consistent naming convention throughout your project. Choose either CamelCase (homePageTitle) or underscores (home_page_title) and use it uniformly.

Avoid spaces and special characters

Use alphanumeric characters and underscores to ensure compatibility and ease of use across different systems or platforms. For example, use home_page_title instead of home page title.

Consider plurals and gender

If your application supports different forms for plurals or gender-specific languages, plan your keys accordingly. For instance, use message.singular and message.plural for different forms.

Include context

If a term might have multiple meanings, include context in the key. Like using address.user and address.shipping for different contexts.

Careful with the abbreviations

While brevity can be helpful, avoid excessively cryptic abbreviations. The goal is to maintain clarity for everyone involved in the project. For instance, go for user instead of usr.

Maintain documentation

Maintain documentation for your keys, explaining their purpose and usage. This helps maintain consistency across teams, offering clarity to all stakeholders. You could include comments or a README file with key documentation.

How to use translation keys with POEditor

POEditor is a translation management system that allows you to manage your translation projects in one place. You can use the platform to create and manage translation keys, as well as to collaborate with translators to translate your content into multiple languages.

Simply create a project in the POEditor TMS and add the languages you want to support in your application. In your source code, replace the actual text to be translated with unique keys. Next, upload the source language file containing the keys and their corresponding text in POEditor. Translators can then view the keys and provide translations for each language.

Once translations are complete, you can export them from POEditor in the the desired localization file format and use them in your application. By following these steps, you create a seamless workflow where developers define and manage translation keys within their code, while translators collaborate on the translations using the platform.