Android will run on many devices in many regions. To reach the most users, your application should handle text, audio files, numbers, currency, and graphics in ways appropriate to the locales where your application will be used.
This document describes best practices for localizing Android applications. The principles apply whether you are developing your application using ADT with Eclipse, Ant-based tools, or any other IDE.
You should already have a working knowledge of Java and be familiar with Android resource loading, the declaration of user interface elements in XML, development considerations such as Activity lifecycle, and general principles of internationalization and localization.
It is good practice to use the Android resource framework to separate the localized aspects of your application as much as possible from the core Java functionality:
The Hello, L10N tutorial takes you through the steps of creating a simple localized application that uses locale-specific resources in the way described in this document.
Resources are text strings, layouts, sounds, graphics, and any other static data that your Android application needs. An application can include multiple sets of resources, each customized for a different device configuration. When a user runs the application, Android automatically selects and loads the resources that best match the device.
(This document focuses on localization and locale. For a complete description of resource-switching and all the types of configurations that you can specify — screen orientation, touchscreen type, and so on — see Providing Alternative Resources.)
When you write your application:
When a user runs your application:
When you write your application, you create default and alternative resources for your application to use. To create resources, you place files within specially named subdirectories of the project's
Whenever the application runs in a locale for which you have not provided locale-specific text, Android will load the default strings from
res/values/strings.xml. If this default file is absent, or if it is missing a string that your application needs, then your application will not run and will show an error. The example below illustrates what can happen when the default text file is incomplete.
An application's Java code refers to just two strings,
text_b. This application includes a localized resource file (
res/values-en/strings.xml) that defines
text_b in English. This application also includes a default resource file (
res/values/strings.xml) that includes a definition for
text_a, but not for
res/values-en/strings.xmlcontains both of the needed text strings.
To prevent this situation, make sure that a
res/values/strings.xml file exists and that it defines every needed string. The situation applies to all types of resources, not just strings: You need to create a set of default resource files containing all the resources that your application calls upon — layouts, drawables, animations, etc. For information about testing, see Testing for Default Resources.
Put the application's default text in a file with the following location and name:
res/values/strings.xml (required directory)
The text strings in
res/values/strings.xml should use the default language, which is the language that you expect most of your application's users to speak.
The default resource set must also include any default drawables and layouts, and can include other types of resources such as animations.
res/drawable/(required directory holding at least one graphic file, for the application's icon in the Market)
res/layout/ (required directory holding an XML file that defines the default layout)
res/anim/ (required if you have any
res/xml/ (required if you have any
res/raw/ (required if you have any
Tip: In your code, examine each reference to an Android resource. Make sure that a default resource is defined for each one. Also make sure that the default string file is complete: A localized string file can contain a subset of the strings, but the default string file must contain them all.
A large part of localizing an application is providing alternative text for different languages. In some cases you will also provide alternative graphics, sounds, layouts, and other locale-specific resources.
An application can specify many
res/<qualifiers>/ directories, each with different qualifiers. To create an alternative resource for a different locale, you use a qualifier that specifies a language or a language-region combination. (The name of a resource directory must conform to the naming scheme described in Providing Alternative Resources, or else it will not compile.)
Suppose that your application's default language is English. Suppose also that you want to localize all the text in your application to French, and most of the text in your application (everything except the application's title) to Japanese. In this case, you could create three alternative
strings.xml files, each stored in a locale-specific resource directory:
If your Java code refers to
R.string.title, here is what will happen at runtime:
Notice that if the device is set to Japanese, Android will look for
title in the
res/values-ja/strings.xml file. But because no such string is included in that file, Android will fall back to the default, and will load
title in English from the
If multiple resource files match a device's configuration, Android follows a set of rules in deciding which file to use. Among the qualifiers that can be specified in a resource directory name, locale almost always takes precedence.
Assume that an application includes a default set of graphics and two other sets of graphics, each optimized for a different device setup:
If the application runs on a device that is configured to use Japanese, Android will load graphics from
res/drawable-ja/, even if the device happens to be one that expects input from a stylus and has a QVGA low-density screen in landscape orientation.
Exception: The only qualifiers that take precedence over locale in the selection process are MCC and MNC (mobile country code and mobile network code).
Assume that you have the following situation:
res/values-mcc404/strings.xml, which includes
text_ain the application's default language, in this case English.
res/values-hi/strings.xml, which includes
Android will load
res/values-mcc404/strings.xml (in English), even if the device is configured for Hindi. That is because in the resource-selection process, Android will prefer an MCC match over a language match.
The selection process is not always as straightforward as these examples suggest. Please read How Android Finds the Best-matching Resource for a more nuanced description of the process. All the qualifiers are described and listed in order of precedence in Table 2 of Providing Alternative Resources.
In your application's Java code, you refer to resources using the syntax
android.R.resource_type.resource_name. For more about this, see Accessing Resources.
You cannot assume anything about the device on which a user will run your application. The device might have hardware that you were not anticipating, or it might be set to a locale that you did not plan for or that you cannot test. Design your application so that it will function normally or fail gracefully no matter what device it runs on.
Important: Make sure that your application includes a full set of default resources.
Make sure to include
res/drawable/ and a
res/values/ folders (without any additional modifiers in the folder names) that contain all the images and text that your application will need.
If an application is missing even one default resource, it will not run on a device that is set to an unsupported locale. For example, the
res/values/strings.xml default file might lack one string that the application needs: When the application runs in an unsupported locale and attempts to load
res/values/strings.xml, the user will see an error message and a Force Close button. An IDE such as Eclipse will not highlight this kind of error, and you will not see the problem when you test the application on a device or emulator that is set to a supported locale.
For more information, see Testing for Default Resources.
If you need to rearrange your layout to fit a certain language (for example German with its long words), you can create an alternative layout for that language (for example
res/layout-de/main.xml). However, doing this can make your application harder to maintain. It is better to create a single layout that is more flexible.
Another typical situation is a language that requires something different in its layout. For example, you might have a contact form that should include two name fields when the application runs in Japanese, but three name fields when the application runs in some other language. You could handle this in either of two ways:
You probably do not need to create a locale-specific alternative for every resource in your application. For example, the layout defined in the
res/layout/main.xml file might work in any locale, in which case there would be no need to create any alternative layout files.
Also, you might not need to create alternative text for every string. For example, assume the following:
To do this, you could create a small file called
res/values-en-rGB/strings.xml that includes only the strings that should be different when the application runs in the U.K. For all the rest of the strings, the application will fall back to the defaults and use what is defined in
You can look up the locale using the
Context object that Android makes available:
String locale = context.getResources().getConfiguration().locale.getDisplayName();
Keep in mind that the device you are testing may be significantly different from the devices available to consumers in other geographies. The locales available on your device may differ from those available on other devices. Also, the resolution and density of the device screen may differ, which could affect the display of strings and drawables in your UI.
To change the locale on a device, use the Settings application (Home > Menu > Settings > Locale & text > Select locale).
For details about using the emulator, see See Android Emulator.
A "custom" locale is a language/region combination that the Android system image does not explicitly support. (For a list of supported locales in Android platforms see the Version Notes in the SDK tab). You can test how your application will run in a custom locale by creating a custom locale in the emulator. There are two ways to do this:
When you set the emulator to a locale that is not available in the Android system image, the system itself will display in its default language. Your application, however, should localize properly.
To change the locale in the emulator by using the adb shell.
frfor French and
adb -e shell
#), run this command:
setprop persist.sys.language [language code];setprop persist.sys.country [country code];stop;sleep 5;startReplace bracketed sections with the appropriate codes from Step 1.
For instance, to test in Canadian French:
setprop persist.sys.language fr;setprop persist.sys.country CA;stop;sleep 5;start
This will cause the emulator to restart. (It will look like a full reboot, but it is not.) Once the Home screen appears again, re-launch your application (for example, click the Run icon in Eclipse), and the application will launch with the new locale.
Here's how to test whether an application includes every string resource that it needs:
res/values-fr/but does not have any Spanish strings in
res/values-es/, then set the emulator's locale to Spanish. (You can use the Custom Locale application to set the emulator to an unsupported locale.)
res/values/strings.xmlfile includes a definition for every string that the application uses.
If the test is successful, repeat it for other types of configurations. For example, if the application has a layout file called
res/layout-land/main.xml but does not contain a file called
res/layout-port/main.xml, then set the emulator or device to portrait orientation and see if the application will run.
The Android Market is the main application distribution system for Android devices. To publish a localized application, you need to sign your application, version it, and go through all the other steps described in Preparing to Publish.
If you split your application in several .apk files, each targeted to a different locale, follow these guidelines:
These checklists summarize the process of localizing an Android application. Not everything on these lists will apply to every application.
|Choose a localization strategy. Which countries and which languages will your application support? What is your application's default country and language? How will your application behave when it does not have specific resources available for a given locale?|
Identify everything in your application that will need to be localized:
Design your Java code to externalize resources wherever possible:
|Create a full set of default resources in
|Obtain reliable translations of the static text, including menu text, button names, error messages, and help text. Place the translated strings in
|Make sure that your application correctly formats dynamic text (for example numbers and dates) for each supported locale. Make sure that your application handles word breaks, punctuation, and alphabetical sorting correctly for each supported language.|
|If necessary, create locale-specific versions of your graphics and layout, and place them in
|Create any other localized content that your application requires; for example, create recordings of sound files for each language, as needed.|
|Test your application for each supported locale. If possible, have a person who is native to each locale test your application and give you feedback.|
|Test the default resources by loading a locale that is not available on the device or emulator. For instructions, see Testing for Default Resources.|
|Test the localized strings in both landscape and portrait display modes.|
|Sign your application and create your final build or builds.|
|Upload your .apk file or files to Market, selecting the appropriate languages as you upload. (For more details, see Publishing Your Applications.)|