Localization Tips, Part 1: It's Okay to Repeat Yourself

This is the first entry in a multi-part series about localization.

I recently worked on a mobile application that needed to support 27 different languages and numerous locales. My team was responsible for building the app's user interface and ensuring it was properly localized. We learned a lot throughout this process and I wanted to share some of it here.

Tip 1: It’s Okay To Repeat Yourself

Most platforms provide basic localization support by exposing an API to retrieve localized strings or "resources" that have been externalized into text files (key/value pair “properties” files, JSON, XML, etc). As software developers, we tend to follow the principle of "Do not Repeat Yourself" (DRY) and identify a single unambiguous place for each bit of logic or configuration. This principle doesn't always apply when dealing with translated text.

If the same string of text appears in several places in the UI there may be a temptation to define a single key for that word and utilize it in several places in the app. Unfortunately, different languages will sometimes have variations on the same word depending on the context in which it's used. For example, the word "search" when translated to Spanish will be "buscar" in some contexts and "búsqueda" in others. If the UI contains a main navigation element, page header and several buttons that all use the text "Search", define a separate value in the translation file for each instance rather than reusing a single value called "search."

Another subtle issue can arise when dealing with phrases that contain variable values such as numbers or formatted dates which are intermingled with translated text. For example, the UI may define a string that - in English - is represented as "$DATE at $TIME." It's commonplace for developers to define an entry for “at” in the resource file and then concatenate the values together in code. Some languages use a very different grammatical structure for certain phrases which may change the order of words and add certain punctuation elements not found in other languages. The best practice here is to define the entire phrase in the translation file as "$1 at $2" and use a string formatting utility provided by the language or localization API.

So here's a quick recap of Part 1's tips:

  • Define a value for each place in the user interface where a piece of text appears. It may appear duplicative and redundant but will offer a lot of flexibility as the UI is translated into additional languages.
  • Define phrases which contain variable values inside of the translation file using placeholder elements. Don't concatenate strings and variables in code.