Logo Icon Logo
A Crowd-sourced Cookbook on Writing Great Android® Apps
GitHub logo Twitter logo OReilly Book Cover Art

Internationalizing Application Text

Author: Ian Darwin
Published? true -- FormatLanguage: W

Problem:

You want the text of your buttons, labels and so on to appear in the user's chosen language.

Solution:

Create a new strings.xml in the res/values-XX/ subdirectory of your application. Translate the string values to the given language.

Discussion:

Every Android Project created with the SDK has a file called strings.xml in the res/values directory. This is where you are recommended to place all your application's strings, from the application title through to the button text and even down to the contents of dialogs.

When you refer to a string by name, either by a reference like android:text="@string/hello" in a layout file or by a lookup like getString(R.string.hello), you look up the string's value from this file.

To make all of these strings available in a different language, you need to know the correct ISO-3166 language code; a few common ones are shown in the table.

Common Languages and Codes
Language Code
Chinese (traditional) cn-tw
Chinese (simplified) cn-zh
English en
French fr
German de
Italian it
Spanish es

With this information, you can create a new subdirectory res/values-XX/ (where XX is replaced by the ISO language code). In this directory you create a copy of strings.xml and in it, translate the individual string values. For example, a simple application might have the following strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="hello">Hello Android</string>
    <string name="app_name">MyAndroid</string>
</resources>

You might create res/values-es/strings.xml containing the following:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="hello">Hola Android</string>
    <string name="app_name">MiAndroid</string>
</resources>

And create the file create res/values-fr/strings.xml containing the following:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="hello">Bonjour Android</string>
    <string name="app_name">MonAndroid</string>
</resources>

Now when you look up the string "hello" using either of the methods described earlier, you will get the version based on the user's language choice. If the user selects a language that you don't have a L10N file for, the app will still work, but will get the value from the default file - the one in the values directory with no language code. For most of us, that will contain the English values, but it's up to the developer.

Similarly, if there is a string that's not defined in a language-specific file, the app will find the version of it from the default strings.xml file.

Is it really that simple?

Yes. Just package your application and deploy it (if you're using Eclipse, just Run As Android Application). Go into the Settings app of your emulator or device, choose Language, and select French or Spanish and the program title and window contents should reflect the change.

You just have to remember to keep the versions of strings.xml in sync.

Regional Variants

OK, so it's not quite that simple. There are also regional variations within a language. In English there are, for example, UK English (a.k.a. "the real thing" by some), US English, Canadian, Australian, and so on. These, fortunately, have tended to use the same vocabulary for technical terms, so using the regional variations is not as important for English. French and Spanish, to name just two, are languages where there is significant variation from in vocabulary from one region to another. Parisian French and French Canadian have used different vocabularies for many words coined since the 1500's when their exodus began. The many Spanish colonies were likewise largely isolated from hearing each others' speech for hundreds of years - from their founding until the age of radio - and they have diverged even more than French. So you may want to create 'variant' files for these languages, as for any other that has significant regional variation.

Android's practice here diverges slightly from Java's, in that Android uses a letter 'r' to denote regional variations, e.g., values-fr-rCA for French Canadian. Note that as in Java, language codes are in lower case and variations (which are usually the two-letter ISO country code) are written in capital letters (except for the leading 'r'). So we might wind up with the set of files listed in the table below.

L10N Directory Examples
Directory!Contains
values English; default.
values-es Spanish ("Castilian", generic)
values-es-rCU Spanish - Cuban
values-es-rCL Spanish - Chilean

See Also:

There is a bit more detail at the official Android Localization documentation.

barral 2013-03-06 07:54:07.933 Here is a tool you can use to localize Android apps in over 200 languages: http://poeditor.com/. It's really useful.