docs: Migrating multilingual-support to permanent home.
Bug: 30224032
Change-Id: I14ddb924bdf6c17719520b7883ab601281c548c2
diff --git a/docs/html/_redirects.yaml b/docs/html/_redirects.yaml
index 1e6f216..8507128 100644
--- a/docs/html/_redirects.yaml
+++ b/docs/html/_redirects.yaml
@@ -1218,3 +1218,6 @@
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 b788c38..0f3db79 100644
--- a/docs/html/guide/_book.yaml
+++ b/docs/html/guide/_book.yaml
@@ -72,6 +72,8 @@
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 ff21b52..8d8484b 100644
--- a/docs/html/preview/features/multilingual-support.jd
+++ b/docs/html/guide/topics/resources/multilingual-support.jd
@@ -18,25 +18,21 @@
</div>
</div>
-<p>Android N provides enhanced support for multilingual users,
-allowing them to select multiple locales in settings. Android N
+<p>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.</p>
+and changing the way the system resolves resources.</p>
-<p>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
+<p>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.</p>
<h2 id="preN">Challenges in Resolving Language Resources</h2>
-<p>Prior to Android N, Android could not always successfully
+<p>Prior to Android 7.0, Android could not always successfully
match app and system locales.</p>
<p>For example, assume that you have the following situation:</p>
@@ -88,15 +84,17 @@
<p>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.</p>
+today.</p>
<h2 id="postN">Improvements to Resource-Resolution Strategy</h2>
-<p>Android N brings more robust resource resolution, and
-finds better fallbacks automatically. However, to speed up resolution and improve
+<p>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 <code>en-GB</code> strings is {@code en-001}.
@@ -105,8 +103,8 @@
<h3>Resource resolution examples</h3>
-<p>With Android N, the case described in <strong>Table 1</strong> is resolved
-differently:</p>
+<p>With versions of Android greater than 7.0, the case described in
+ <strong>Table 1</strong> is resolved differently:</p>
<p class="table-caption" id="t-improved-res">
<strong>Table 2.</strong> An improved resolution strategy for when there is no
@@ -142,7 +140,8 @@
<p>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.</p>
<p>In addition to this improved resolution logic, Android now offers more
@@ -184,38 +183,48 @@
</tr>
</table>
-<p>The user still gets a language they understand, even though the app doesn’t
-support French.</p>
+<p>
+ The user still gets a language they understand, even though the app doesn’t
+ support French.
+</p>
<h2 id="design">Designing your App to Support Additional Locales</h2>
<h3>LocaleList API</h3>
-<p>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
+<p>
+ 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. </p>
+ and keyboard apps can auto-enable all appropriate layouts.
+</p>
<h3>Formatters</h3>
-<p>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.</p>
+<p>
+ 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.</p>
-<p>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:</p>
+<p>
+ 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:
+</p>
<pre> format(locale, "Choose a %d-digit PIN", 4)</pre>
