CODEWITHSUNDEEP
internationalizationtranslation
Jurian Sluiman
Jurian Sluiman

Reputation: 13558

Best practice for key values in translation files

In general, translation methods take a key > value mapping and use the key to transform that into a value. Now I recognize two different methods to name your translation keys and within my team we do not come to consensus what seems to be the best method.

Method 1: Use full English words or sentences:

Name => Name
Please enter your email address => Please enter your email address

Method 2: Use keywords describing the situation:

NAME => Name
ENTER_EMAIL => Please enter your email address

I personally prefer method #1 because it directly shows the meaning of the message. If the translation is not present, you could fall back to the key and this doesn't cause any problems. However, the method is cumbersome when a translation changes frequently, because all the files need to be updated. Also for longer texts these keys become very large. This is solved by using keys like ENTER_EMAIL, but the phrasing is completely out of the context. The list of abstract translation keys would be huge, you need meta data for all the keys explaining their usage and collisions can occur much easier.

Is there a best of both worlds or a third method? How do you use translation keys in your application? In our case it is a php-based webapplication, but I think above problem is generic enough to talk about i18n in general.

Upvotes: 35

Views: 8701

Answers (2)

sven7
sven7

Reputation: 748

Why not use both worlds? I use method #1 for short strings, and method #2 for long strings that are full sentences. I am not afraid to mix both in the same file.

For example, in the following string the text may change if in a new app version the user experience is modified:

"screen description" = "Tap the plus button to add a new item. Tap an item for more options or to edit its details.";

So here it makes sense to apply method #2. However, for simple strings like in the following example, method #1 is more useful:

"Preferences" = "Preferences";

In general when people try to standardize things it often appears restrictive to me. Personally, I prefer a more "anarchistic" approach where several methods are valid (not only as in this method #1 vs method #2 thread, but also for example when a team of developers fight over coding style).

Upvotes: 4

Clafou
Clafou

Reputation: 15400

This is a question that is also faced by iOS/OSX developers. And for them there is even a standard tool called genstrings which assumes method 1. But of course Apple developers don't have to use this tool--I don't.

While the safety net that you get with method 1 is nice (i.e you can display the key if you somehow forgot to localize a string) it has the downside that it can lead to conflicting keys. Sometimes one identical piece of display text needs to be localized in two different ways, due to grammar rules or differences in context. For instance the French translation for "E-mail" would be "E-mail" if it's a dialog title and "Envoyer un e-mail" if it's a button (in French the word "E-mail" is only a noun and can't be used as a verb, unlike in English where it's both a noun and a verb). With method 2 you could have keys EMAIL_TITLE and EMAIL_BUTTON to solve this issue, and as a bonus this would give a hint to translators to help them translate correctly.

One more advantage of method 2 is that you can change the English text without having to worry about updating the key in English and in all your localizations.

So I recommend method 2!

Upvotes: 25

Related Questions