Android will run on many different devices in many different regions, and used by speakers of many different languages. To reach the most users in the most effective way, developers will want to localize their applications to the native languages spoken by the users they wish to reach.  This document explains how to localize an Android application.

What You Should Know Already

This is not an introduction to how to build Android applications; for that information, you can begin here: http://code.google.com/android/intro/index.html  This document assumes that you are generally familiar with Android resource loading, declarative UI building via Android’s XML system, and general Android development considerations such as Activity lifecycle.

Introduction to the L10nDemo App

To illustrate the concepts discussed in this document, we’ve created the L10nDemo application.  This application is very simple, and specifically constructed to illustrate the key moving parts of Android’s localization framework.

The application consists of a simple UI that displays 3 TextViews, and a button with a background image.  The 3 TextViews display text that is localized appropriately for the system’s current locale, and the button shows an image of the national flag for the system’s current locale. When clicked, the button displays a Dialog containing additional text.  The UI is implemented with two variants: one used for portrait orientations, and one for landscape. The contents of each variant are the same, but are visually arranged in a slightly different way.

Here is a screenshot of the L10nDemo application, running in English in the 1.0_r2 SDK emulator.

To download the source code, you can click here.

Android Localization: Theory of Operation

Before we dive in to the details of of the L10nDemo, let’s begin with an overview of how Android implements localization.

Android provides a framework that allows developers to separate their UI from their application logic. Generally, Android breaks down an application’s UI into 3 general concepts:

1. The layout of a UI — which buttons go where, where labels and data go, and so on. Android allows developers to specify these UIs declaratively via XML files.
2. Assets used to implement or “fill in” a UI, such as sounds and images.
3. Application code (written in Java) that drives the various behaviors of the UI and mutates the screen contents in response to user input.

Developers are not required to make use of these resources; for instance, developers could simply put all their images into the ‘raw/’ directory in a project, and build up user interfaces programmatically directly from Java source code.  However, this design approach is generally considered to be poorly “internationalized” (meaning that it is difficult to localize to multiple languages.)  The framework used by Android is specifically designed to be easy to localize, and so we strongly encourage developers to make use of this framework.

As you know, Android loads resources such as declarative layout XML files and media assets from the project’s ‘res/’ directory. However, there’s a bit more to it than just that: Android can actually selectively load resources from different directories, based on the current device configuration and locale.  For instance, your application code might wish to refer to a string value named ‘R.string.title’. Android will choose the correct value for that string at runtime by loading the appropriate strings.xml file from a matching ‘res/values’ directory.  For instance, if the current locale is ‘en-US’, then Android will look for a value for R.string.title by looking in the following files, in this order: ‘res/values-en-rUS/strings.xml’, ‘res/values-en/strings.xml’, ‘res/values/strings.xml’.  Android chooses the first value it finds — that is, the value most specific to the current locale, eventually falling back on the default.  (Note that you use whatever language you like for the default file in ‘res/values/strings.xml’; many developers choose English, but it doesn’t need to be.)

Besides locale, Android will also perform similar resource resolution for device configurations or states, such as whether the screen is currently portrait or landscape.  For instance, on a T-Mobile G1 with the screen open and keyboard exposed, Android will look for a layout file matching ‘R.layout.main’ in this order:  ‘res/layout-land/main.xml’, ‘res/layout/main.xml’.  You can also mix-and-match these permutations.  For instance, ‘res/values-fr-rCA-land/strings.xml’ would be used to supply values for strings whenever a French-Canadian device is in landscape mode.  This particular example is somewhat contrived since it’s unlikely you’d have special needs for that specific combination, but if you have a particularly busy UI it might be useful for providing field labels of varying lengths for different screen modes.

For the full details on how Android resolves resources, see:  http://code.google.com/android/devel/resources-i18n.html#AlternateResources  As you’ll see, the resource-resolution framework is fairly sophisticaed and can be used for more than just localization.  The remainder of this document, however, focuses on showing how to use this framework to localize an app.

L10nDemo Resources

Below is a list of all the resource directories present in the L10nDemo project, and an explanation of when they are used.

• Layouts:
  res/layout-land — used when the device is in landscape mode.
  res/layout — the default, used when a more specific layout mode is not matched (i.e. when device is in portrait mode)
• Strings
  res/values-fr — application strings localized to French (for use in Canada and France)
  res/values-de — application strings localized to German (for use in Germany and Austria)
  res/values-en-rUS — application strings used for US English
  res/values — application strings used when no more specific locale is matched. In this case, the default strings are in British English.
• Drawables (i.e. national flag images):
  res/drawable-de-rDE — used when the current locale is Germany
  res/drawable-fr-rCA — used when the current locale is French-Canadian (fr-CA)
  res/drawable-fr-rFR — used when the current locale is France (fr-FR)
  res/drawable-en-rCA — used when the current locale is English Canadian (en-CA)
  res/drawable-en-rAU — used when the current locale is Australia
  res/drawable-en-rUS — used when the current locale is the United States
  res/drawable — used when no other more specific locale is matched. In this case, the default content is in English, and consists of the UK flag.

Finally, here is a table specifying exactly which resources are loaded for while locales:

• [1] – Because this demo has no need to load different layouts based on language, the same layout file will be used for all languages. It will change only when the device orientation changes.  However, if your application is localized to a language with a different alphabet, such as to Japanese or Chinese, it may make sense to have a different layout entirely for those languages.  In such cases you could use something like ‘res/layout-jp’, ‘res/layout-land-jp’, and ‘res/layout-port-jp’.
• [2] – Because the project does not have a flag specifically for Austria, the system will fall back on the default, which is the US flag defined in ‘res/drawable’. In a real-world app this would be inappropriate and considered a mistake, but is included here as an illustrative example. If you were to change ‘res/drawable-de-rDE’ to ‘res/drawable-de’, then it becomes more generic (less specific) and would be used for all German-speaking locales — in this case, Austria and Germany. This would still be incorrect for Austria, but it might be better than the default of the UK flag.
• [3] – Canada, Australia, and the United Kingdom all share strings. Since there are 3 such nations, it is reasonable to use the default/fallback strings file for this case, and use a more specific match for US-English strings (since US English has different spellings for some words.)  However, a real-world developer might consider the more explicit res/values-en/strings.xml to be “better style”.

Localization Techniques in Java Code

In some cases, you cannot avoid needing to access resources from code.  The most common example is filling in a template string with values computed at runtime.  Fortunately, the Android localization framework is also used when resolving resources from code.  For example, the snippet of code below from the L10nDemo uses the standard Java MessageFormat functionality in conjunction with Android’s localization framework to transparently select the correct template string for the current locale and fill it in with values derived from code:

In some cases, developers may wish to look up specific resources manually.  For example, a project being ported from a different platform that doesn’t have a localization framework might have lots of resources simply placed into a shared directory, such as ‘raw/’.  In such cases we recommend that developers convert over to use Android’s framework, but those who choose not to may wish to look up the current locale to select resources manually.  That can be accomplished via the standard Java API, or by using the Android Context.  For instance, the two lines below are equivalent: