18

We're developing a large application, consisting of many small packages. Each package has its own set of resource files for localization.

What's the best approach to organizing and naming the localization strings?

Here are my thoughts so far:

Handling duplicates

The same text (say, "Zip code") may occur multiple times within a given package. Programming instinct (DRY) tells me to create a single string resource shared by all occurrences.

Then again, a translator may want to choose a long translation ("Postleitzahl") in some places and a shorter one ("PLZ") in places with less space. Or we may decide to append a colon to some occurrences ("Zip code:"), but not to others. Or we may require a different capitalization ("zip code") in some places. All these arguments point to creating one resource per usage, even if their contents are identical.

Naming

If we aim to eliminate duplicates, it makes sense to name resources by content, maybe hinting at the kind of usage via prefix. So we may have labelOK = "OK", messageFileTooLarge = "The file exceeds the maximum file size.", and labelZipCode = "Zip code".

Naming by content has the advantage of handling format arguments naturally: The resource messageFileHas_0_MBWhileMaximumIs_1_MB clearly takes two formatting arguments, the actual file size and the maximum file size.

If we allow duplicates, however, naming by content alone doesn't make sense. In order to get unique resource names, we must somehow include the place of usage in the resource name. That works for graphical controls, although the identifiers tend to get a bit long: fileSelectionConfirmationButtonText = "OK", customerDetailsTableColumnZipCode = "Zip Code". However, for non-visual code files, it gets harder. How do you name a specific usage of a string if you don't know where it will eventually be displayed? By code file and function name? Seems rather clumsy and brittle to me.

All in all, I'm leaning toward allowing duplicates, but I'm struggling to find a consistent naming scheme that supports this.

Edit: This question has two aspects: How to organize resources (DRY vs. duplicates) and how to name them. So far, the answers have concentrated on the first aspect. I'd appreciate some feedback regarding naming conventions!

Improve this question
2
  • 1
    If you have small packages with loc sets each, then the question arises, whether you will see much duplicates. I'd go with the duplicates and wouldn't worry too much about the identifiers in code.
    – Martin Ba
    Commented Aug 2, 2016 at 9:23
  • "How do you name a specific usage of a string if you don't know where it will eventually be displayed?" Wouldn't this be a sign of a flaw with the design, where it mixes logic (deciding where to show it) and presentation (actually showing it). It would be very weird for you to construct some text with regional data but treating it like any other internal data object that you can move around.
    – Alpha
    Commented Aug 12, 2016 at 11:43

5 Answers 5

Reset to default
9

I would accept duplication whenever you cannot be absolutely sure the meaning is exactly the same in all cases a certain string is used.

Even if two labels always contain the same string in English (or your native tongue) they will not necessarily be the same in all languages. Accepting duplication may give you (or rather the translators) the flexibility needed to handle such situations.

As an example: Consider a label "Condition", which - depending on context - might get translated to "Zustand" or "Bedingung" in German (among lots of other possible translations).

Improve this answer
1
  • Yep. This.
    – zanlok
    Commented Mar 16, 2018 at 23:23
3

Accept some duplicates.

You can avoid some multiple translations by creating extra controls. E.g. a CancelButton and an OKButton which already contain their text, and now Cancel/Abbrechen OK/OK need to be translated only once. But that's almost a special case.

Improve this answer
2

This is the way we handle it in my company:

Naming convention: We name labels by prefixing them with their class/section/form/etc. For instance loadFile_loadButton, loadFile_fileNameLabel, loadFile_cancel are all labels belonging to a Load File dialogue. Although this underscored naming convention is not the most common, we favor it over more standard conventions because it improves readability and "groupability": notice how easy it is to see which element the labels belong to, and what each label represents, compared to labels named loadFileLoadButton, loadFileNameLabel and loadFileCancel. You may think the difference is not that big, but when you have thousands of labels, the compound effect is worth it.

Header comments: Additional to prefixing label names, we also add "header" comments to the resource files to define clearly the label groupings. This way, somebody wanting to modify or add specific labels related to one particular class/section/form/etc can find all labels related to that particular element in just one place, under one header, and can easily proceed to add or modify labels easily knowing that they won't break translations for any other elements (IMHO, this is also a very strong point on why you need to allow duplication).

"Justified" duplicates are desirable: As mentioned above, these practices will definitively lead to duplicate labels, but we see no problem with that (more on how to handle this in Tools of the trade).

As others have pointed out, one label in one language can be translated in two or more different ways in other languages depending on the contexts they are presented. If you "unify" labels, the translator will have a really hard time coming up with a single label that accomodates to all the contexts where it is found. So, as we see it, allowing "justified" duplicates helps improve the quality of the localization, as long as they don't refer to the same thing under the same context (this is the meaning of "justified").

Tools of the trade: In order to be as effective as possible when doing your translations, you can build your own tool which looks for similar labels that exist in your bundles, and offer their translations as default values for new labels, or you can even use existing services like this one, which provide tools like the one I just mentioned, making translation of new labels a breeze (even more so if they are repeated several times, since the tool will offer you several translation options by default for the new labels).

Summing it up: Justified duplication and having labels grouped in a contextual way really helps translators do their work. Big time. Just think about it: having context goes a long way in aiding the translator to select the proper translation. And allowing "justified" duplicates eliminates the conflict of having to select one translation that fits poorly some contexts (but is the best overall fit anyway).

I hope this helps!

Improve this answer
1

When I've done this in the past we went down the route of the resource file containing full sentences. If the exact same sentence was used repeatedly great, but if it was only individual words from within a sentence those words would be duplicated.

We were tied to a framework where the resource file just contained a list of English phrases followed by the translation (with some indexing data at the end for fast lookup).

For small data prompts or buttons, such as a field name of "ZIP Code" or a button of "OK" it would store the string "ZIP Code" followed by the translation and would use that wherever that full string was required. But (unless we manually broke up a string) would not use it for "ZIP Code" appearing in a sentence.

Using your ZIP Code example, if you try and translate that on it's own and replace it in all sentences that use it you will get a very very bad translation.

For example, "ZIP Code must be entered" might need to translate the literal equivalent of "Entered ZIP Code must be" in another language. If you chop up a sentence you don't get that reversal of words required in another language.

That's why some badly done translations to English look so ridiculous, the person doing it just translated the individual words, not the whole sentence.

We always found it best to translate sentences as a whole, without breaking them up. We had place holders for data that needed inserting (e.g. "Part Number @1 is redundant") and the translator could move the place holder to the position they wanted it for a good translation.

However we found that allowing places that used exactly the same sentence, or the same data prompt or the same button label etc, were fine to share translations. That never came up as an issue and saved time/cost for the translator.

Improve this answer
4
  • Exactly. We also do this. Never try to break up labels/sentences in translation.
    – Martin Ba
    Commented Aug 2, 2016 at 9:38
  • 1
    I'm afraid that doesn't really address my question. I absolutely agree that sentences should never be broken up. However, most resources aren't sentences but simple labels (button texts, table headers, form labels etc.).
    – Daniel Wolf
    Commented Aug 2, 2016 at 10:37
  • In which case I would store it once and reuse. A consideration perhaps outside the scope of what you are directly doing is the cost of a translator. We actually got our re-sellers around the world to fund that for themselves and also test the translation within the application. They most definitely wanted duplicates avoided.
    – RosieC
    Commented Aug 2, 2016 at 11:12
  • I have worked translating several big applications from and to Spanish, and I can tell you that if you have the right translation tools, duplicates are not an issue (they are even desirable). See my answer for how to handle this effectively.
    – carlossierra
    Commented Aug 11, 2016 at 3:43
0

Your thinking on naming is good.

Objectives

  • Define a common label (i.e. variable name) for localized text.
  • The label should be "mind sized". That is... as short practical while being unambiguous.
  • Labels should follow a consistent format so as to maximize predictability and recall.

Implementation

  • Reduce cognitive load with consistent use of well known abbreviations (i.e., msg=message, lbl=label, btn=button, ...)
  • Tools present variables/labels in alphabetical lists, so human lookup is best when related labels group together. Make names hierarchical from most general to most specific. (i.e. msgFileMissing, msgFileSaved, msgFileDeleted).
  • English is a verb-noun ordered language. Many(most?) Other languages are noun-verb. Noun-verb works best for hierarchical grouping.
Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.