From 32e428e78e68a7270ba34d3051e53ec46170208d Mon Sep 17 00:00:00 2001 From: Eric Schmidt Date: Fri, 22 Jul 2016 10:34:54 -0700 Subject: [PATCH] docs: Migrating multilingual-support to permanent home. Bug: 30224032 Change-Id: I14ddb924bdf6c17719520b7883ab601281c548c2 --- docs/html/_redirects.yaml | 3 + docs/html/guide/_book.yaml | 2 + .../topics/resources}/multilingual-support.jd | 101 +++++++++++---------- 3 files changed, 60 insertions(+), 46 deletions(-) rename docs/html/{preview/features => guide/topics/resources}/multilingual-support.jd (62%) diff --git a/docs/html/_redirects.yaml b/docs/html/_redirects.yaml index 1e6f2169f122..850712857ad9 100644 --- a/docs/html/_redirects.yaml +++ b/docs/html/_redirects.yaml @@ -1218,3 +1218,6 @@ redirects: to: /training/articles/scoped-directory-access.html - from: /preview/features/notification-updates.html to: /guide/topics/ui/notifiers/notifications.html +- from: /preview/features/multilingual-support.html + to: /guide/topics/resources/multilingual-support.html + diff --git a/docs/html/guide/_book.yaml b/docs/html/guide/_book.yaml index b788c3840633..0f3db799b8f6 100644 --- a/docs/html/guide/_book.yaml +++ b/docs/html/guide/_book.yaml @@ -72,6 +72,8 @@ toc: section: - title: ICU4J Android Framework APIs path: /guide/topics/resources/icu4j-framework.html + - title: Language and Locale + path: /guide/topics/resources/multilingual-support.html - title: Resource Types path: /guide/topics/resources/available-resources.html section: diff --git a/docs/html/preview/features/multilingual-support.jd b/docs/html/guide/topics/resources/multilingual-support.jd similarity index 62% rename from docs/html/preview/features/multilingual-support.jd rename to docs/html/guide/topics/resources/multilingual-support.jd index ff21b52d5a8b..8d8484b262e9 100644 --- a/docs/html/preview/features/multilingual-support.jd +++ b/docs/html/guide/topics/resources/multilingual-support.jd @@ -18,25 +18,21 @@ page.image=images/cards/card-nyc_2x.jpg -

Android N provides enhanced support for multilingual users, -allowing them to select multiple locales in settings. Android N +

Starting in Android 7.0 (API level 24), +Android provides enhanced support for multilingual users, +allowing them to select multiple locales in settings. Android provides this capability by greatly expanding the number of locales supported -and changing the way the system resolves resources. The new method of resolving -resources is more robust and designed to be compatible with existing APKs, but -you should take extra care to spot any unexpected behavior. For example, you -should test to make sure that your app defaults to the expected language. Also, -if your app supports multiple languages, you should ensure that this support works as -intended. Finally, you should try to ensure that your app gracefully handles -languages that you didn't explicitly design it to support.

- -

This document starts by explaining the resource resolution strategy prior to -Android N. Next, it describes Android N's improved -resource-resolution strategy. Last, it explains how to take advantage of +and changing the way the system resolves resources.

+ +

This document starts by explaining the resource resolution strategy in +versions of Android lower than 7.0 (API level 24). Next, it describes +the improved resource-resolution strategy in Android 7.0. +Last, it explains how to take advantage of the expanded number of locales to support more multilingual users.

Challenges in Resolving Language Resources

-

Prior to Android N, Android could not always successfully +

Prior to Android 7.0, Android could not always successfully match app and system locales.

For example, assume that you have the following situation:

@@ -88,15 +84,17 @@ Use default (en)

In this example, the system displays English strings without knowing whether the user can understand English. This behavior is pretty common -today. Android N should substantially reduce the frequency -of outcomes like this one.

+today.

Improvements to Resource-Resolution Strategy

-

Android N brings more robust resource resolution, and -finds better fallbacks automatically. However, to speed up resolution and improve +

Android 7.0 (API level 24) brings more robust resource resolution, and + finds better fallbacks automatically. However, to speed up resolution and + improve maintainability, you should store resources in the most common parent dialect. - For example, if you were storing Spanish resources in the {@code es-US} directory - before, move them into the {@code es-419} directory, which contains Latin American Spanish. + For example, if you were storing Spanish resources in the {@code es-US} + directory + before, move them into the {@code es-419} directory, which contains Latin + American Spanish. Similarly, if you have resource strings in a folder named {@code en-GB}, rename the folder to {@code en-001} (international English), because the most common parent for en-GB strings is {@code en-001}. @@ -105,8 +103,8 @@ reliability of resource resolution.

Resource resolution examples

-

With Android N, the case described in Table 1 is resolved -differently:

+

With versions of Android greater than 7.0, the case described in + Table 1 is resolved differently:

Table 2. An improved resolution strategy for when there is no @@ -142,7 +140,8 @@ Use fr_FR

Now the user gets French resources instead of English. This example also shows why you should store French strings in {@code fr} rather than {@code fr_FR} - for Android N. Here the course of action is to match the closest parent dialect, + for Android 7.0 or higher. Here the course of action is + to match the closest parent dialect, making resolution faster and more predictable.

In addition to this improved resolution logic, Android now offers more @@ -184,38 +183,48 @@ Use it_IT -

The user still gets a language they understand, even though the app doesn’t -support French.

+

+ The user still gets a language they understand, even though the app doesn’t + support French. +

Designing your App to Support Additional Locales

LocaleList API

-

Android N adds a new API {@code LocaleList.getDefault()} -that lets apps directly query the list of languages a user has specified. This API -allows you to create more sophisticated - app behavior and better-optimized display of content. For example, Search +

+ Starting with Android 7.0 (API level 24), Android exposes the + {@code LocaleList.getDefault()} API + that lets apps directly query the list of languages a user has specified. This API + allows you to create more sophisticated + app behavior and better-optimized display of content. For example, Search can show results in multiple languages based on user’s settings. Browser apps can avoid offering to translate pages in a language the user already knows, - and keyboard apps can auto-enable all appropriate layouts.

+ and keyboard apps can auto-enable all appropriate layouts. +

Formatters

-

Up through Android 6.0 (API level 23), Android supported only one or two locales - for many common languages -(en, es, ar, fr, ru). Because there were only a few variants of each language, -apps could get away with storing some numbers and dates as hard coded strings -in resource files. However, with Android's broadened set of supported locales, -there can be -significant differences in formats for dates, times, currencies, and similar -information even within a single locale. Hard-coding your formats can produce a -confusing experience for end users. Therefore, when developing for Android N -make sure to use formatters instead of hard coding numbers and date strings.

- -

A prime example is Arabic, whose support Android N expands from -one {@code ar_EG} to 27 Arabic locales. These locales can share most resources, -but some prefer ASCII digits, while others prefer native digits. For example, -when you want to create a sentence with a digit variable, such as -"Choose a 4 digit pin", use formatters as shown below:

+

+ Up through Android 6.0 (API level 23), Android supported only one or + two locales + for many common languages + (en, es, ar, fr, ru). Because there were only a few variants of each language, + apps could get away with storing some numbers and dates as hard coded strings + in resource files. However, with Android's broadened set of supported + locales, there can be + significant differences in formats for dates, times, currencies, and similar + information even within a single locale. Hard-coding your formats can produce + a confusing experience for end users. + Therefore, when developing for Android 7.0 or higher versions, + make sure to use formatters instead of hard coding numbers and date strings.

+ +

+ For example, Android 7.0 and higher includes support for + 27 Arabic locales. These locales can share most resources, + but some prefer ASCII digits, while others prefer native digits. For example, + when you want to create a sentence with a digit variable, such as + "Choose a 4 digit pin", use formatters as shown below: +

 format(locale, "Choose a %d-digit PIN", 4)
-- 2.11.0