docs: Migrating multilingual-support to permanent home. am: 32e428e7

  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

    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:

</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>

<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

and changing the way the system resolves resources.</p>

<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>

<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}.

<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

<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

</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()}

<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

<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

  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

  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,

<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>

  "Choose a 4 digit pin", use formatters as shown below:

</p>

<pre> format(locale, "Choose a %d-digit PIN", 4)</pre>