How to Internationalize Software With Placeholders

Presenting software in the language of the country in which it’s used is a good way to improve its usability. Localization is the process of translating software into a local language. Most of the time, localizing software involves a straightforward translation of the words, phrases and sentences in one language to the corresponding words, phrases and sentences in another language. However, localizing phrases and sentences into which variable values must be inserted is not so straightforward.

For example, the following message contains the variable value 23:

Your search returned 23 results

This message is simple to code in JavaScript, for example:

var resultsCount = 23;
var message = "Your search returned " + resultsCount + " results";

Internationalization is the process of preparing software for localization. In most cases, internationalization involves replacing the text in the software with a call to a function that returns the text in the user’s language. For example, we can rewrite the JavaScript example above using a getLanguageResource function:

var resultsCount = 23;
var message = getLanguageResource("SEARCH-RESULTS-MESSAGE-LEFT") +
                resultsCount + getLanguageResource("SEARCH-RESULTS-MESSAGE-RIGHT");

getLanguageResource is an example function that returns the translation of the string parameter in the user’s language, such as English, French or German.

The SEARCH-RESULTS-MESSAGE-LEFT and SEARCH-RESULTS-MESSAGE-RIGHT keys would be defined in a language-resource data structure, such as:

Key Value
SEARCH-RESULTS-MESSAGE-LEFT Your search returned
SEARCH-RESULTS-MESSAGE-RIGHT results

The software would have one language-resource data structure for each supported language.

Joining strings and variables works well for English, but not all languages have the same word order as English. For example, some languages might place the variable value at the beginning of the sentence; other languages might place the variable value at the end. To deal with these differences, we need to code language-specific information into the software, which is obviously counter-productive for our internationalization efforts.

Placeholders are the solution to this problem. A placeholder is a marker in the text that specifies where a variable value should be inserted. Placeholders are a general solution that work for any language because the translator rather than the programmer positions the placeholder in the sentence.

To internationalize the example search-results message with a placeholder, we create a message template with a placeholder symbol (%V) located where we want to insert the variable value:

Your search returned %V results

(I’m using %V as the placeholder, but you can use any sequence of characters that won’t appear in the translated text.)

To insert the variable value, we call a string replace function, which is available in most languages. For example, we can rewrite the JavaScript code above as follows:

var resultsCount = 23;
var messageTemplate = "Your search returned %V results";
var message = messageTemplate.replace("%V", resultsCount);

To internationalize this code, we retrieve the message template with a call to getLanguageResource:

var resultsCount = 23;
var messageTemplate = getLanguageResource("SEARCH-RESULTS-MESSAGE");
var message = messageTemplate.replace("%V", resultsCount);

Each language-resource data structure now has a single entry for the search-results message:

Key Value
SEARCH-RESULTS-MESSAGE Your search returned %V results
blog comments powered by Disqus