The 15th chapter applies Localization

Please refer to the textbook to fully understand and complete the section of this chapter ...

Copy the engineering Ch13 and rename the project catalog to ch14.

Localization is a process that provides the appropriate resources for an application based on device language settings. In this chapter we will localize the Hellomoon application and provide it with a Chinese version of the string resource. When the language of the device is set to Chinese, Android will automatically find and use the corresponding Chinese resources, as shown in 15-1.

Figure 15-1 Hello, moon 15.1 localization resources

Language settings are part of the device configuration. Android provides configuration modifiers for different languages. Localization is easy: first create a resource subdirectory with the target language configuration modifier, and then put the optional resources in it. The Android resource system will handle other follow-up work for us.

The language configuration modifier comes from the ISO 639-1 standard code. The modifier for Chinese is-zh. In the Hellomoon project, open the Res\raw directory and create a new subdirectory: Raw-zh; Open the Res\values directory and create a new subdirectory: Values-zh.

In the package, locate the files: Raw\one_small_step.wav and Values\strings.xml, and copy the files to the corresponding directory you just created. Finally, change the Values-zh\strings.xml to Chinese:

<stringname= "Hellomoon_play">Play</string><stringname= "Hellomoon_stop">Stop it</string><stringname= "Hellomoon_description">Neil Armstrong set foot on the moon</string>

This completes the task of providing localized resources for your app. To verify the results, open the Settings app , find the Language Settings option, and change the device language to Simplified Chinese. Although the Android system has a wide variety of versions, language setting options are typically labeled Language and input, Language and keyboard, or other similar names.

Run the Hellomoony app. Click the Play button to see Armstrong's famous speech. Default Resource

The configuration modifier for the Chinese language is-zh. When localizing processing, our first reaction might be to rename the original raw and values directories directly to Raw-zh and Values-zh.

That's not a good idea. These resources that do not have a configuration modifier are the default resources for Android. The provision of default resources is very important. If Android cannot find a resource that matches the device configuration and no default resource is available, the app crashes.

For example, if you have a Strings.xml file in the values-en/and values-zh/directories, and the values/ The String.xml file is not prepared under the directory, and the Hellomoon will crash when it runs on devices that are not in English or Chinese language settings. Therefore, even if a matching device configuration resource is not provided, the default resource can still guarantee the proper operation of the application.

Exceptions for screen display density

The Android Default Resource usage rule does not apply to screen display density. The project's drawable directory typically displays density requirements by screen, with three types of modifiers:-mdpi,-hdpi, and-xhdpi. However, Android determines which class of drawable resources to use does not simply match the screen display density of the device, nor does it use the default resource directly when there are no matching resources. 15.2 configuration modifier

So far, we've seen and used several configuration modifiers to provide optional resources, such as language (values-zh/), screen orientation (layout-land/), screen display density (drawable-mdpi/), and API level (VALUES-V11).

Table 15-1 lists some of the device configuration features that have configuration modifiers that the Android system uses to identify and locate resources through these configuration modifiers.

Table 15-1 device characteristics with configuration modifiers

1	Mobile country code, usually with mobile network code	10	UI mode
2	Language code, usually with area code	11	Night mode
3	Layout direction	12	Screen display density
4	Minimum width	13	Touch screen Type
5	Available widths	14	Availability of keyboard
6	Available height	15	Preferred Input Method
7	Screen size	16	Navigation key Availability
8	Screen aspect ratio	17	Non-text navigation methods
9	Screen orientation	18	API level

15.2.1 available Resource priority scheduling

Given that there are so many configuration modifiers for locating resources, there may be situations where the device configuration matches several optional resources. Assuming this happens, Android determines the use priority of the modifier based on the order shown in table 15-1.

To actually understand this prioritization, let's add an optional resource for the Hellomoon app, the string resource for horizontal mode app_name . The app_name resource is displayed as the activity title on the action Bar. When the device is in horizontal mode, more text can be displayed on the action bar. We can try to set up a conversation, not just the words "Hello, moon".

Create a Values-land directory, and then copy the default string resource file in.

In horizontal mode, you only need to change the app_name string resource. Delete other string resources that do not need to change, and then modify app_name the values against the code listing 15-1.

Code Listing 15-1 Creating a string resource for horizontal mode (values-land/strings.xml)

String alternative resources (including other values resources) are provided on a per-string basis, so the string resource does not have to be duplicated at the same time. Repeating string resources can only lead to future maintenance nightmares.

There are now three versions of the APP_NAME resource: The default version in the Values/strings.xml file, the Chinese alternative version in the Values-zh/strings.xml file, and the values-land/ The alternate version of the horizontal mode in the Strings.xml file.

Under the premise that the device language is set to Simplified Chinese, run the Hellomoon app, and then rotate the device to horizontal mode. Because the Chinese alternative version resource has the highest priority, we see a string resource from the Values-zh/strings.xml file, shown in 15-2.

Figure 15-2 Android scheduling language priority higher than screen orientation

You can also reset the language of the device to the English language, and then run the app again to confirm that the alternate string resource in horizontal mode appears as expected. 15.2.2 multiple configuration modifiers

You can use multiple configuration modifiers on the same resource directory. Create a resource directory named Values-zh-land, which prepares the Chinese string resource for the horizontal mode for the Hellomoon app.

Using multiple configuration modifiers on the same resource directory, each configuration modifier must be ordered in order of precedence. Therefore, Values-zh-land is a valid resource directory name, and the Values-land-zh directory name is invalid.

Note that the locale modifier, such as-es-res, looks like a multi-configuration modifier consisting of two different configuration modifiers, but in fact it is only a separate configuration modifier (the zone part itself cannot form a valid configuration modifier).

Copy the Values-land/strings.xml file to the values-zh-land/directory, and then modify the content in code listing 15-2.

Code Listing 15-2 Creating a Chinese string resource in horizontal mode (values-zh-land/strings.xml)

Under the premise that the device language is set to Chinese Simplified, run the Hellomoon application to confirm that the new alternative resource appears as expected, as shown in 15-3.

Figure 15-3 Chinese string resource in horizontal mode 15.2.3 Looking for the most matching resource

Let's take a look at how Android determines app_name the resource version. First, remember that the current device has the following three versions of the app_name string alternative resources:

• Values-zh/strings.xml
• Values-land/strings.xml
• Values-zh-land/strings.xml

Second, in terms of device configuration, the current device configuration includes Simplified Chinese language and horizontal screen orientation.

Exclude Incompatible Directories

To find the most matching resource, the first thing Android does is to exclude the resource directory that is incompatible with the current device configuration.

In combination with alternative resources and device configurations, the three versions of alternative resources are compatible with the device's current configuration. If you rotate the device to vertical mode, the device configuration changes. At this point, the values-land/and values-zh-land/resource directories can be filtered out because they are incompatible with the current configuration.

Some configuration modifiers are not compatible with black-and-white exclusivity. For example, the API level is not a strictly matched modifier. Modifier-V11 is compatible with system version devices that run API level 11 and higher.

Some configuration modifiers are added to the newer API level. For example, the layout direction configuration modifier introduced in API level 17. There are two options for this configuration modifier:-ldltr (from left to right) and-ldrtl (from right to left). The configuration modifiers that are added late are generally accompanied by an implied API level modifier, so-ldltr can also be considered as-ldltr-v17. (These additional implicit configuration modifiers also explain, on the other hand, why you might want to prepare the default resources in a project.) ）

Android has taken a different approach to screen display density. Therefore, the usual configuration modifier is compatible with the device configuration to match the principle that it does not apply to it. Android chooses the resources it deems most appropriate to match the device configuration, which may or may not be the resource prepared under the configuration modifier directory for the corresponding device configuration.

Filter incompatible directories by priority table

After filtering out incompatible resource catalogs, Android starts with the highest-priority MCC and continues to filter the incompatible directories by Priority table (table 15-1). If any resource directory with the MCC configuration modifier exists, all resource directories without the MMC modifier will be excluded. If there is still more than one directory match, Android will continue to filter by secondary high priority, so repeatedly until it finds the only directory that meets the compatibility.

There are no directories in this example that contain MCC modifiers, so you cannot filter out any directories. Next, Android sees the second-highest-priority device language modifier. Three resource directories, the values-zh/and values-zh-land/directories contain language modifiers so that values-land/that do not contain language modifiers can be excluded.

Android continues to view the priority table, followed by the screen orientation. At this point, Android will find a modifier directory with screen orientation and a directory without screen orientation, so the values-zh/directory is also excluded. In this way, values-zh-land/becomes the only directory that satisfies the compatibility. Thus, Android eventually determines the use of resources under the values-zh-land/directory. 15.3 More resources use principle and control

Now we have a better understanding of the Android resource system. However, to prepare for the future development of your own applications, you should also be aware of the following resource usage requirements. 15.3.1 Resource Naming

The name of the resource can only be made up of lowercase letters and cannot contain spaces, some examples of proper naming are: One_small_step.wav, App_name, armstrong_on_moon.jpg.

The reference should not include the file's extension, whether it is referencing the resource in XML or in code. For example, the @drawable/armstrong_on_moon referenced in the layout file and the R.drawable.armstrong_on_moon referenced in the code. This also means that under the same subdirectory, you cannot differentiate between naming the same resource file by the file's extension. 15.3.2 Resource Directory Structure

All resources must be kept in subdirectories of the res/directory. Attempting to save a resource in the root directory of the res/directory will result in a compilation error.

The name of the RES subdirectory is directly bound to the Android compilation process and therefore cannot be changed at will. We have seen subdirectories with drawable/, layout/, menu/, raw/, and values/.

Android ignores other subdirectories in the res/directory. Creating a res/my_stuff may not cause an error to occur, but Android does not use any of the resources placed therein.

In addition, we cannot create multilevel subdirectories under the res/directory. This limitation can be a bit of a hassle for development. You know, there are often hundreds of drawable resources in a real-world development project. Therefore, it is natural to create a multilevel subdirectory to manage these resource files, but Android does not allow this. In this case, the only thing we can do is to consciously name the resource so that it can be sorted by file name, in order to find a particular file.

Android's naming convention for layout files is a typical example of sorting by file name. Layout files are usually prefixed with their defined view type names, such as activity_ , dialog_ ,, and list_item_ so on. For example, in the Criminalintent application's res/layout/directory, some layouts are named: activity_crime_pager ,, activity_fragment dialog_date ,, fragment_crime and list_item_crime . As you can see, the activity layout is sorted by name, so it's much easier to find an activity layout file. 15.4 Test Alternative Resources

When you apply development, the layout and testing of other resources are important. Layout testing allows us to know the number of alternative resources required in advance for different sizes of screen, screen orientation, and other device configurations. We can test on a virtual device, or on a physical device, or even with a graphical layout tool.

The graphical Layout tool provides a number of options for previewing how layouts are displayed under different configurations. These options are screen size, device type, API level, device language, and so on.

To view these options, you can open the Fragment_hello_moon.xml file in the Graphics Layout tool. Then refer to Figure 15-4 and try using various options to preview the layout.

Figure 15-4 previewing a resource using the image Layout tool

By setting the device language to a language that does not provide localized resources, you can ensure that the project already includes all the required default resources. Run the app to test, view all the view interfaces and rotate the device. If your app crashes, check the "Resource not found ..." error message in Logcat to confirm which default resources are missing.

The 15th chapter applies Localization