Best practices for creating translation keys

Translation key naming might seem like a small decision, but it has a big impact as your project grows.

With only 50 keys, inconsistent naming is manageable. But with 5,000 keys, multiple developers, and several target languages, poor naming conventions become a real problem: they lead to duplicates, confuse translators, break automation, and make updates costly. On the other hand, solid conventions make translations easier to understand, find, and maintain.

This guide covers naming conventions that scale, and it's part of a larger technical guide to internationalization and software localization.

What is a translation key?

A translation key is a stable identifier used in source code to reference a localized string. The key stays constant across languages; the translation value changes.

{
  "settings.save_changes": "Save changes"
}

{
  "settings.save_changes": "Guardar cambios"
}

The key settings.save_changes is the same in every language file. The value is what translators provide. This separation is what makes scalable multilingual systems possible.

For a deeper look at how keys relate to strings and how they're counted, see Translation keys vs Strings and What is a translation key?.

Best practices

Below are some best practices and tips for creating translation keys that are simple, comprehensive, and effective in the software localization process.

Be descriptive

Keys should give enough context that a translator can produce an accurate translation without needing to see the UI. Abbreviations save a few characters and cost understanding.

For example, instead of using an abbreviated version like btn.next, opt for a more descriptive version such as button.next_step.

// Too terse
btn_nxt
 
// Better
button.next_step

Descriptive keys also reduce the need for inline comments or screenshots in your TMS. The key itself carries the context.

Maintain consistency

Pick one naming convention and apply it everywhere. Mixing styles within a project creates confusion and makes tooling harder to build.

// Inconsistent, avoid this
log_in
logOut
LOG_REGISTER
 
// Consistent
log_in
log_out
log_register

Agree on separator style (dots, underscores, camelCase), casing, and how component names are represented. Write it down. Enforce it in review.

Organize hierarchically

Structure keys to reflect your application's component or feature hierarchy. This makes it immediately clear where a string appears and what it's for.

login.label_username
login.placeholder_email
login.button_submit
settings.billing.label_plan
settings.billing.button_upgrade

The prefix (login, settings.billing) acts as a namespace, making keys scannable and groupable. When you need to load only part of your translations, for performance, or because a feature is lazy-loaded, hierarchical keys map cleanly to namespaces in software localization.

Avoid embedding variables in key names

Placeholders and dynamic values belong inside the translation string, not in the key itself.

// Don't do this (the key breaks when the username changes)
welcome_message_{username}
 
// Do this instead
welcome_message
// with translation: "Welcome back, {username}"

Keys with embedded variables are difficult to maintain, hard to search, and impossible to manage in a TMS. The value can accommodate the dynamic part; the key should stay stable and static.

Choose meaningful names

Keys should be readable at a glance. Opaque identifiers make the file harder to work with every time someone touches it.

// Unreadable
xyz123
t_004_b
 
// Readable
error.invalid_email
dashboard.empty_state_title

If you can't tell what a key refers to without opening the UI, the name needs work.

Optimize for readability

Use separators that make keys easy to scan: dots for hierarchy, underscores within a level. Keep total key length reasonable; very long keys are as hard to parse as very short ones.

// Hard to read
errormessageinvalidemail
 
// Easy to read
error.message_invalid_email

Design for stability, not for current copy

This is the practice most teams skip early and regret later. Keys should describe the purpose of a string, not mirror its current text.

// Mirrors current copy (breaks if the label changes)
welcome.search.enter-your-name-or-booking-id-here
 
// Describes purpose (survives copy changes)
welcome.search.input_label

When product decides to change "Enter your name or booking ID here" to "Search reservations", the key welcome.search.input_label stays valid. The copy-mirroring key becomes wrong the moment it's updated, and anyone reading the code or translation file has to reconcile the mismatch.

Keys built for stability are particularly important in long-lived projects where copy evolves frequently but the underlying UI structure stays the same.

Managing keys at scale

Good naming conventions solve many issues. But as your product grows, you also need a routine to keep translation keys clean.

Keys pile up over time. Features are removed, copy is updated, and components are renamed. If you do not clean up regularly, locale files end up full of keys that are no longer used in code. These unused translation keys make files larger, confuse translators, and add unnecessary translation cost.

Shared components across features or products create another challenge: managing common translation keys across different contexts without creating duplicates or inconsistent wording. If your team maintains multiple apps with the same design system or component library, sharing translation keys across projects needs clear structure from the start.

Keeping translation keys in order, with the same sorting and structure in every locale file, is more important than it looks. Unsorted files create noisy diffs, increase merge conflicts, and slow down reviews.

As projects get bigger, adding new keys by hand becomes less realistic. Automatic message extraction with AI can scan your codebase and create keys in your TMS automatically, which helps keep translations aligned with development.

Conclusions

Translation key conventions are a long-term decision. Set them early and keep them consistent. Changing them later means renaming large numbers of keys, updating code references, and fixing mismatches in translation memory.

The core rules are simple: use clear names, stay consistent, organize keys by structure, keep names stable, and clean up regularly. If you apply these rules from the start, translation, review, QA, and expansion to new languages all become easier.

For a full technical view of how keys fit into an i18n setup, including file formats, framework integration, CI/CD, and performance, see the complete technical guide to internationalization and software localization.