How to Name Your Translation Keys?

Whenever I start a new multilingual project, there comes a moment of conundrum: How should I name my translation keys? Should I organize them per feature, or per page?

For quite some time, I skipped translation keys altogether — instead, I used the translation text itself as the key.

Translations as Keys

Here’s my default language file (English, lang/en.json):

{
    "Hello World!": "Hello World!"
}

And here’s the French version, lang/fr.json:

{
    "Hello World!": "Bonjour tout le monde !"
}

As you can see, each language uses the original text as its translation key. It’s straightforward: you don’t need to think about how to structure labels and texts — you just write, then translate.

This was my go-to approach for a while. I could quickly bootstrap i18n in a project and never think about it again.

Then I realized — this approach is far from perfect.

Imagine you have two data tables: one for users, another for projects.

Users:

Projects:

Both models have a name column. For a user, it means “Full name”; for a project, it means “Title”. But in English (and maybe French), “Name” works for both. In Slovak (or other languages), “name” may translate differently — e.g. “Meno” (personal name) vs. “Názov” (title / project name).

These collisions make it dangerous to treat the English text as the key. Using the full text as a key can easily lead to ambiguous or incorrect translations depending on context.

That realization prompted me to implement a naming convention in my latest i18n project.

Model-based Translation Keys

In a recent app (translated into English, French, Russian, Slovak, at least for now), I introduced a system that distinguishes between:

• common: strings used across multiple pages, modules or even database models

• unique: strings tied to a specific model or context

Common Keys

For example, the column currency exists in multiple tables: account, transaction. In all contexts, it means the same thing: a currency like EUR or USD. There is no ambiguity.

So in my translation files I name it simply: columns.currency.

Unique Keys

For strings that are specific to a model (or context), I use a structured naming scheme using dot-notation or colon-notation. For example:

{
    "user:columns.name": "Name" // English
}

{
    "user:columns.name": "Meno" // Slovak
}

Here is how the scheme is structured:

1. Model name in singular, lowercase, followed by a colon (:): user:, project:, account:

2. What the label represents: columns. (since “name” is a database column)

3. The actual label: name

This scheme is easy to extend:

{
    "user:notifications.created": "A new user was created",
    "user:form.create": "Add a New User",
    "home:welcome": "Welcome back, :name!"
}

I’m very happy with how this turned out. Even with more than 500 translation strings per language, I can quickly and easily add new ones without making a mess. Oh — and the files are sorted alphabetically. That matters!

Why This Approach Works

1. Clarity & Disambiguation. Meaning is always clear. There is no confusion whether “name” refers to user name or project name.

2. Scalability. As the project grows and languages multiply, structure keeps things manageable.

3. Consistency. The same scheme is applied everywhere, making it predictable and maintainable.

4. Maintenance-friendly. With alphabetical sorting and clear keys, adding/removing or updating translations is easier.

Final Thoughts

I believe that a well-thought naming convention is the backbone of a maintainable localization setup. Using structured keys rather than raw strings helps avoid ambiguity, supports context-aware translations, and keeps your translation files organized — even as the project grows big.

Whether you're working on a small side project or a large multilingual app, investing time up front into naming and organizing your translation keys pays off. Every single time.