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.
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:
- You can put most or all of the contents of your application's user interface into resource files, as described in this document and inProviding Resources.
- The behavior of the user interface, on the other hand, is driven by your Java code. For example, if users input data that needs to be formatted or sorted differently depending on locale, then you would use Java to handle the data programmatically. This document does not cover how to localize your Java code.
For a short guide to localizing strings in your app, see the training lesson, Supporting Different Languages.
Overview: Resource-Switching in Android
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.
Why Default Resources Are Important
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 fortext_b:
- When this application is launched on a device with locale set to English, the application might run without a problem, because
res/values-en/strings.xmlcontains both of the needed text strings. - However, the user will see an error message and a Force Close button when this application is launched on a device set to a language other than English. The application will not load.
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.
Using Resources for Localization
How to Create 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.
How to Create Alternative Resources
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.xml
Contains English text for all the strings that the application uses, including text for a string namedtitle.res/values-fr/strings.xml
Contain French text for all the strings, includingtitle.res/values-ja/strings.xml
Contain Japanese text for all the strings excepttitle.
If your Java code refers to R.string.title, here is what will happen at runtime:
- If the device is set to any language other than French, Android will load
titlefrom theres/values/strings.xmlfile. - If the device is set to French, Android will load
titlefrom theres/values-fr/strings.xmlfile.
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.
Which Resources Take Precedence?
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/
Contains default graphics.res/drawable-small-land-stylus/
Contains graphics optimized for use with a device that expects input from a stylus and has a QVGA low-density screen in landscape orientation.res/drawable-ja/
Contains graphics optimized for use with Japanese.
If the application runs on a device that is configured to use Japanese, Android will load graphics fromres/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:
- The application code calls for
R.string.text_a - Two relevant resource files are available:
res/values-mcc404/strings.xml, which includestext_ain the application's default language, in this case English.res/values-hi/strings.xml, which includestext_ain Hindi.
- The application is running on a device that has the following configuration:
- The SIM card is connected to a mobile network in India (MCC 404).
- The language is set to 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.
Referring to Resources in Java
In your application's Java code, you refer to resources using the syntax R.resource_type.resource_name orandroid.R.resource_type.resource_name. For more about this, see Accessing Resources.
Localization Checklist
For a complete overview of the process of localizing and distributing an Android application, see the Localization Checklist document.
Localization Tips
Design your application to work in any locale
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.
For more information, see Testing for Default Resources.
Design a flexible layout
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:
- Create one layout with a field that you can programmatically enable or disable, based on the language, or
- Have the main layout include another layout that includes the changeable field. The second layout can have different configurations for different languages.
Avoid creating more resource files and text strings than you need
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:
- Your application's default language is American English. Every string that the application uses is defined, using American English spellings, in
res/values/strings.xml. - For a few important phrases, you want to provide British English spelling. You want these alternative strings to be used when your application runs on a device in the United Kingdom.
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.
Use the Android Context object for manual locale lookup
You can look up the locale using the Context object that Android makes available:
String locale = context.getResources().getConfiguration().locale.getDisplayName();
Testing Localized Applications
Testing on a Device
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.
Testing on an Emulator
For details about using the emulator, see See Android Emulator.
Creating and using a custom locale
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:
- Use the Custom Locale application, which is accessible from the Application tab. (After you create a custom locale, switch to it by pressing and holding the locale name.)
- Change to a custom locale from the adb shell, as described below.
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.
Changing the emulator locale from the adb shell
To change the locale in the emulator by using the adb shell.
- Pick the locale you want to test and determine its BCP-47 language tag, for example, Canadian French would be
fr-CA.
- Launch an emulator.
- From a command-line shell on the host computer, run the following command:
adb shell
or if you have a device attached, specify that you want the emulator by adding the-eoption:
adb -e shell - At the adb shell prompt (
#), run this command:
setprop persist.sys.locale [BCP-47 language tag];stop;sleep 5;startReplace 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, and the application launches with the new locale.
Testing for Default Resources
Here's how to test whether an application includes every string resource that it needs:
- Set the emulator or device to a language that your application does not support. For example, if the application has French strings in
res/values-fr/but does not have any Spanish strings inres/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.) - Run the application.
- If the application shows an error message and a Force Close button, it might be looking for a string that is not available. Make sure that your
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.
Android将在许多地区的许多设备上运行。为了达到最多的用户，您的应用程序应该处理文本，音频文件，数字，货币和图形以适合您的应用程序将要使用的语言环境的方式。
本文档描述了本地化Android应用程序的最佳实践。
你应该已经有一个Java的工作知识，熟悉与Android资源加载，用户界面元素的XML声明，发展的考虑，例如活动的生命周期，以及国际化和本地化的一般原则。
这是使用Android资源框架到应用程序的本地化方面，从核心Java功能，尽可能分开好的做法：
- 你可以把大部分或全部内容，应用程序的用户界面到资源文件，如本文档中，并在描述 提供了资源。
- 该行为在用户界面的，另一方面，是由Java代码来驱动。例如，如果不同，具体取决于语言环境需要格式化或排序用户输入数据，那么你会使用Java编程处理数据。本文不包括如何定位你的Java代码。
对于短指南在你的应用本地化的字符串，看到训练课， 支持不同的语言。
概述：资源切换Android中
资源是文本字符串，布局，声音，图形和其他任何静态数据，你的Android应用程序的需求。一个应用程序可以包括多组资源，每个定制用于不同设备配置。当用户运行该应用程序，Android的自动选择，并加载最佳匹配设备的资源。
（本文侧重于本地化和区域设置的资源交换的完整描述和所有类型的配置，你可以指定-屏幕方向，触摸屏类型，等等-见 提供替代资源。）
| 当你写你的应用程序： | | 当用户运行应用程序： |
当你写你的应用程序，您可以创建默认和替代资源，为您的应用程序使用。要创建资源，您将项目的特别命名的子目录中的文件RES /目录。
为什么默认资源是重要的
每当应用程序在你没有提供具体的语言环境的文本语言环境中运行，Android将加载从默认的字符串 RES /价值/ strings.xml中。如果这个默认的文件不存在，或者如果它丢失了自己的应用需要一个字符串，那么你的应用程序将无法运行，并会显示一个错误。下面的例子说明，当默认文本文件不完整会发生什么。
例：
一个应用程序的Java代码指的只是两个字符串，text_a和 text_b。此应用程序包括一个本地化的资源文件（RES /值-EN / strings.xml中定义）text_a和 text_b英文。本申请还包括一个默认的资源文件（RES /值/ strings.xml中，其包括用于定义）text_a，但不适用于text_b：
- 当该应用程序在设备上启动与区域设置为英语，应用程序可能没有问题运行，因为
RES /值-EN / strings.xml中包含所需的文本字符串。 - 但是，用户会看到一个错误信息并强制一个关闭按钮时，这个应用程序设置为英语之外的其他语言的设备上启动。该应用程序将不会加载。
为了防止这种情况发生，确保一个RES /价值/ strings.xml中 的文件是否存在，以及它定义每一个需要的字符串。这种情况适用于所有类型的资源，不只是字符串：您需要创建一套包含所有你的应用程序吁请资源默认的资源文件-版式，图形，动画等有关测试的信息，请参阅 测试为默认资源。
使用资源本地化
如何创建默认资源
把应用程序的默认文本具有以下位置和名称的文件：
RES /价值/ strings.xml中（必需的目录）
在文本字符串RES /价值/ strings.xml中应该使用默认的语言，这是你最期待您的应用程序的用户讲的语言。
默认的资源集还必须包括任何默认可绘制和布局，并且可能包括其它类型的资源，例如动画。 RES /绘制/（必需的目录保持至少一个图形文件，应用程序对谷歌图标播放） RES /布局/（必需的目录拿着定义默认布局的XML文件） RES /动画/（所需如果您有任何 RES / anim- <预选赛>文件夹） RES / XML /（必填，如果您有任何 RES / XML的<预选赛>文件夹） RES /生/（如果您有任何需要 RES / raw- <预选赛>文件夹）
提示：在您的代码，检查每个引用一个Android资源。确保一个默认资源为每个一项所定义。另外，还要确保该默认字符串文件是完整的：一个 本地化的字符串文件可以包含字符串的一个子集，但是 默认字符串文件必须包含所有。
如何创建替代资源
本地化应用程序的很大一部分是提供不同的语言替代文本。在某些情况下，你也将提供替代的图形，声音，布局，以及其他特定的语言环境资源。
应用程序可以指定多个RES / <预选赛> / 目录中，各有不同的预选赛。要创建一个不同的区域设置的替代资源，您可以使用限定符指定语言或语言区域的组合。（资源目录的名称必须符合所描述的命名方案 提供替代资源，否则将无法编译。）
例：
假设您的应用程序的默认语言是英语。还假设您要本地化应用程序中的法国所有的文字，而大部分的文本在您的应用程序（除了应用程序的标题一切）日本。在这种情况下，你可以创建三个替代的strings.xml 文件，每个文件存储在一个特定地区的资源目录：
RES /价值/ strings.xml中
包含应用程序使用的所有字符串，包括文本字符串命名英文文本标题。RES /值-FR / strings.xml中
包含的所有字符串，包括法国的文字标题。RES /值-JA / strings.xml中
包含的所有字符串日语文本除了标题。
如果你的Java代码是指R.string.title，这里是在运行时会发生什么：
- 如果设备被设置为法文以外的任何语言，Android将加载
标题从RES /价值/ strings.xml中的文件。 - 如果设备设置为法语，Android将加载
标题从RES /值-FR / strings.xml中的文件。
请注意，如果设备设置为日语，Android将查找 标题中的RES /值-JA / strings.xml中的文件。但因为没有这样的字符串包含在该文件中，Android将回落到默认值，将加载 标题从英文 RES /价值/ strings.xml中的文件。
它的资源优先？
如果有多个资源文件相匹配的设备的配置，Android的遵循一套规则，决定使用哪种文件。其中，可以在资源目录名中指定的预选赛中，现场几乎总是优先。
例：
假设一个应用程序包含图形的默认设置和其他两组图形，分别用于不同设备的设置进行了优化：
RES /绘制/
包含默认的图形。RES /绘制小土地手写笔/
包含图形与从触笔输入期望并具有横向QVGA一个低密度屏幕的设备进行了优化。RES /绘制-JA /
包含图形与日本进行了优化。
如果该应用程序被配置为使用日语的设备上运行，机器人将加载从图形 水库/抽拉-JA /，即使设备恰好是一个从触笔期望的输入和具有风景的QVGA低密度屏方向。
例外：即优先于区域设置在选择过程中唯一的限定词是MCC和MNC（移动国家代码和移动网络代码）。
例：
假设你有以下情况：
- 应用程序代码呼吁
R.string.text_a - 两个相关资源文件可用：
水库/值-mcc404 / strings.xml中，其中包括text_a在应用程序的默认语言，在这种情况下，英语。RES /值喜/ strings.xml中，其中包括text_a在印地文。
- 应用程序，具有以下结构的设备上运行的：
- SIM卡被连接到在印度一个移动网络（MCC 404）。
- 该语言设置为印地文（
喜）。
Android将加载text_a从 RES /价值观mcc404 / strings.xml中（英文），即使设备配置为印地文。这是因为在资源选择过程中，Android将会更喜欢MCC比赛过的语言匹配。
选择过程并不总是那么简单，因为这些事例表明。请阅读 Android如何寻找最佳匹配资源的过程的更细致入微的描写。所有的预选赛中被描述并列出优先顺序提供替代资源的表2。
谈到资源的Java
在应用程序的Java代码，你参考，使用语法资源 R. RESOURCE_TYPE。RESOURCE_NAME或android.R。RESOURCE_TYPE。RESOURCE_NAME。 想了解更多，请访问资源。
本地化清单
本地化和分发Android应用程序的过程的完整概述，请参阅本地化清单文件。
本地化提示
在设计应用程序中的任何区域工作
你不能假设有关其用户将运行应用程序设备什么。该设备可能有你没有期待的硬件，也可能被设置为你没有的，或者你无法测试计划区域设置。设计应用程序，使其正常运行或不能正常不管它运行在什么设备。
重要提示：请确保您的应用程序包括一套完整的默认资源。
确保包括 RES /绘制/和RES /价值/文件夹（无文件夹名称的任何附加修饰），包含所有的图片和您的应用程序将需要的文本。
如果应用程序丢失甚至一个默认的资源，它不会被设置为不支持的语言环境的设备上运行。例如， RES /价值/ strings.xml中默认的文件可能缺乏应用程序需要一根弦：当应用程序在不支持的语言环境中运行，并尝试加载RES /价值/ strings.xml中，用户会看到一个错误信息，并一个强制关闭按钮。
欲了解更多信息，请参见测试对于默认资源。
设计一个灵活的布局
如果您需要重新安排布局，以适应某种语言（例如德国以其悠久的话），你可以创建该语言（例如替代布局RES /布局-DE / main.xml中）。但是，这样做可以使你的应用程序难以维护。这是更好地建立一个单一的布局更为灵活。
另一种典型的情况是，需要东西它的布局不同的语言。例如，你可能有一个接触的形式，应该包括两个名称字段，当应用程序在日本运行，但三个名称字段，当应用程序在其他一些语言运行。可以在以下两种方式之一处理这个问题：
- 创建一个字段中的一个的布局，您可以通过编程启用或禁用，基于语言，或
- 有主要布局包括另一个布局，包括多变的领域。第二布局可以有不同的语言不同的配置。
避免创造更多的资源文件和文本字符串比你需要
你也许并不需要为应用程序中每个资源的特定语言环境的替代品。例如，在定义的布局RES /布局/ main.xml中文件可能在任何区域工作，在这种情况下，就没有必要创建任何替代布局文件。
此外，您可能不需要创建为每个字符串替代文本。例如，假定：
- 您的应用程序的默认语言是美国英语。该应用程序使用的每个字符串的定义，使用美国英语拼写，在
RES /价值/ strings.xml中。 - 对于一些重要的短语，你要提供英式英语拼写。您希望在应用程序在英国的设备上运行，使用这些替代字符串。
要做到这一点，你可以创建一个所谓的小文件 RES /值-EN-RGB / strings.xml中，包括只有当应用程序在英国运行对于字符串的所有其余的应该是不同的字符串，该应用程序将下降回默认值，并使用被定义RES /价值/ strings.xml中。
使用Android Context对象手动查找区域
您可以使用查找区域上下文对象的Android使得可供选择：
字符串的语言环境= 环境。getResources （）。getConfiguration （）。语言环境。getDisplayName （）;
测试本地化的应用软件
测试在设备上
请记住，您正在测试的设备可以是提供给消费者在其他地区的设备显著不同。您的设备上可用的语言环境可能与在其他设备上可用的不同。此外，该设备屏幕的分辨率和密度可能会有所不同，这可能会影响你的UI字符串和绘图的显示。
要更改区域设置或语言的设备上，使用设置应用程序。
测试在一个仿真器
有关使用模拟器的详细信息，请参阅见Android模拟器。
创建和使用自定义的语言环境
“自定义”区域是一门语言/区域组合了Android系统映像没有明确支持。（对于Android的平台所支持的语言环境的列表，请参阅该版本注释SDK选项卡）。你可以测试一下你的申请将在自定义区域创建在模拟器中的自定义语言环境中运行。有两种方法可以做到这一点：
- 使用自定义区域设置的应用程序，这是从应用程序选项卡访问。（您创建一个自定义区域后，按住设置名称切换到它。）
- 更改为从亚行外壳定制的语言环境，如下所述。
当在模拟器设置为一个区域，是不是在Android系统中可用的图像，系统本身会在其默认语言显示。您的应用程序，但是，要正确定位。
从亚行Shell改变模拟器的区域设置
要使用亚行外壳更改仿真器的语言环境。
- 选择您要测试并确定其BCP-47语言标记，例如语言环境，加拿大法语是
FR-CA。
- 启动仿真器。
- 从主机计算机上的命令行shell，运行以下命令：
亚行的shell，或者如果你有一个附加设备，指定通过添加所需的模拟器-e选项：ADB -e壳
- 在亚行的shell提示符（
＃），运行这个命令：setprop persist.sys.locale [BCP-47语言标记];停止;睡眠5;开始从步骤1更换用适当的代码括号部分。
例如，在加拿大法语测试：
setprop persist.sys.locale FR-CA;停止;睡眠5;启动
这将导致仿真器重新启动。（它看起来像一个完整的重新启动，但事实并非如此。）一旦在主屏幕上再次出现，重新启动您的应用程序，该应用程序使用新的语言环境启动。
测试的默认资源
以下是如何测试应用程序是否包括它需要每一个字符串资源：
- 设置仿真器或设备，你的应用程序不支持的语言。例如，如果应用程序中有法国串
RES /值-FR /但没有任何西班牙语字符串RES /值-ES /，然后设置模拟器的区域设置为西班牙语。（您可以使用自定义区域设置应用到模拟器设置为不受支持的语言环境。） - 运行该应用程序。
- 如果应用程序显示错误消息和强制关闭按钮，它可能会寻找一个字符串，它是不可用。请确保您的
RES /价值/的strings.xml文件包含应用程序使用的每个字符串的定义。
如果测试成功，重复它对于其他类型的配置。例如，如果应用程序有一个布局文件名 为 RES /布局土地/ main.xml中，但不包含一个名为 RES /布局端口/ main.xml中，然后设置仿真器或设备为纵向，看看应用程序将运行。
416
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
