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:
- -For a short guide to localizing strings in your app, see the training lesson, Supporting Different Languages.
- - -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 res/ directory.
-
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.
Example: -
An application's Java code refers to just two strings, text_a and
- text_b. This application includes a localized resource file
- (res/values-en/strings.xml) that defines text_a and
- 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 text_b:
-
res/values-en/strings.xml contains 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 on Google Play)
- res/layout/ (required directory holding an XML
- file that defines the default layout)
- res/anim/ (required if you have any
- res/anim-<qualifiers> folders)
- res/xml/ (required if you have any
- res/xml-<qualifiers> folders)
- res/raw/ (required if you have any
- res/raw-<qualifiers> folders)
-
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.)
Example:
- -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:
res/values/strings.xmltitle.res/values-fr/strings.xmltitle.res/values-ja/strings.xmltitle.If your Java code refers to R.string.title, here is what will
-happen at runtime:
title from the res/values/strings.xml file.title from
-the res/values-fr/strings.xml file.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
-res/values/strings.xml file.
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.
-Example:
- -Assume that an application includes a default set of graphics and two other -sets of graphics, each optimized for a different device setup:
- -res/drawable/res/drawable-small-land-stylus/res/drawable-ja/ 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).
- -Example:
- -Assume that you have the following situation:
- -R.string.text_ares/values-mcc404/strings.xml, which includes
-text_a in the application's default language, in this case
-English.res/values-hi/strings.xml, which includes
-text_a in Hindi.hi).Android will load text_a from
-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
-R.resource_type.resource_name or
-android.R.resource_type.resource_name.
-For more about this, see Accessing Resources.
For a complete overview of the process of localizing and distributing an Android application, -see the Localization -Checklist document.
- -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:
- -res/values/strings.xml. 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 res/values/strings.xml.
You can look up the locale using the {@link android.content.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 or language on a device, use the Settings application.
- -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.
- -fr-CA.adb shell-e option:adb -e shell#), run this command: setprop persist.sys.locale [BCP-47 language tag];stop;sleep 5;start
- Replace bracketed sections with the appropriate codes from Step
-1.For instance, to test in Canadian French:
- -setprop persist.sys.locale fr-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.xml file 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.
-
-
-
+page.title=Localizing with Resources
+parent.title=Application Resources
+page.tags="localizing","localization","resources", "formats", "l10n"
+parent.link=index.html
+@jd:body
+
+
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:
+ +For a short guide to localizing strings in your app, see the training lesson, Supporting Different Languages.
+ + +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 res/ directory.
+
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.
Example: +
An application's Java code refers to just two strings, text_a and
+ text_b. This application includes a localized resource file
+ (res/values-en/strings.xml) that defines text_a and
+ 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 text_b:
+
res/values-en/strings.xml contains 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 on Google Play)
+ res/layout/ (required directory holding an XML
+ file that defines the default layout)
+ res/anim/ (required if you have any
+ res/anim-<qualifiers> folders)
+ res/xml/ (required if you have any
+ res/xml-<qualifiers> folders)
+ res/raw/ (required if you have any
+ res/raw-<qualifiers> folders)
+
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.)
Example:
+ +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:
res/values/strings.xmltitle.res/values-fr/strings.xmltitle.res/values-ja/strings.xmltitle.If your Java code refers to R.string.title, here is what will
+happen at runtime:
title from the res/values/strings.xml file.title from
+the res/values-fr/strings.xml file.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
+res/values/strings.xml file.
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.
+Example:
+ +Assume that an application includes a default set of graphics and two other +sets of graphics, each optimized for a different device setup:
+ +res/drawable/res/drawable-small-land-stylus/res/drawable-ja/ 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).
+ +Example:
+ +Assume that you have the following situation:
+ +R.string.text_ares/values-mcc404/strings.xml, which includes
+text_a in the application's default language, in this case
+English.res/values-hi/strings.xml, which includes
+text_a in Hindi.hi).Android will load text_a from
+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
+R.resource_type.resource_name or
+android.R.resource_type.resource_name.
+For more about this, see Accessing Resources.
For a complete overview of the process of localizing and distributing an Android application, +see the Localization +Checklist document.
+ +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:
+ +res/values/strings.xml. 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 res/values/strings.xml.
You can look up the locale using the {@link android.content.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 or language on a device, use the Settings application.
+ +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.
+ +fr-CA.adb shell-e option:adb -e shell#), run this command: setprop persist.sys.locale [BCP-47 language tag];stop;sleep 5;start
+ Replace bracketed sections with the appropriate codes from Step
+1.For instance, to test in Canadian French:
+ +setprop persist.sys.locale fr-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.xml file 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.
+
+
+
diff --git a/docs/overview-ext.html b/docs/overview-ext.html
index 57202452fc73e..f80d629633a03 100644
--- a/docs/overview-ext.html
+++ b/docs/overview-ext.html
@@ -1,8 +1,8 @@
-