Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Added documentation for expanded multilingual support in N.

Browse Source 
Bug: 27048604
Change-Id: I85119d95e3dc8071bc76cf0fed801cef5a64b0f6
This commit is contained in:
sreevanis
2016-02-24 18:06:44 -08:00
committed by Andrew Solovay
parent e90d9993e9
commit f56220fa9d
1 changed files with 213 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

213
docs/html/preview/features/multilingual-support.jd Normal file
View File

@@ -0,0 +1,213 @@
page.title=Supporting Multilingual Users
@jd:body
<div id="tb-wrapper">
<div id="tb">
<h2>In this document:</h2>
<ol>
<li><a href="#preN">Challenges in Resolving Language Resources</a></li>
<li><a href="#postN">Improvements to Resource-Resolution Strategy</a></li>
<li><a href="#design">Designing your App to Support Additional
Locales</a></li>
</ol>
</div>
</div>
<p>Android N Developer Preview provides enhanced support for multilingual users,
allowing them to select multiple locales in settings. The N Developer Preview
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 it supports multiple languages, you should ensure that this support works as
intended. Last, 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
the N Developer Preview. Next, it describes the N Developer Preview's improved
resource-resolution strategy. 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 the Android N Developer Preview, Android could not always successfully
match app and system locales. For example, suppose that your app's default language
is US English, but that it also has Spanish strings localized in {@code es_ES}
resource files.</p>
<p>When your Java code referred to strings, it would resolve string languages as
follows:</p>
<ul>
<li>If a device were set to {@code es_MX} (Spanish-Mexico), Android would load
strings from {@code es_ES} resource files.</li>
<li>If the device were set to {@code en_AU}, Android would fall back on {@code
en_US}. The system would also default to {@code en_US} if the user chose a
language that the app didn't support at all, like French.</li>
</ul>
<p>These resolution problems arose because the system stripped the country code
off of the locale if it could not find an exact match. For example:</p>
<p class="table-caption" id="t-resource-res">
<strong>Table 1.</strong> Resource resolution without an exact locale match.
</p>
<table>
<tbody>
<tr>
<th>User Settings</th>
<th>App Resources</th>
<th>Resource Resolution</th>
</tr>
<tr>
<td>fr_CH</td>
<td>
default (en)<br>
de_DE <br>
es_ES <br>
fr_FR <br>
it_IT <br>
</td>
<td>
Try fr_CH =&gt; Fail <br>
Try fr =&gt; Fail <br>
Use default (en)
</td>
</tr>
</tbody>
</table>
<p>In this example, the system displays English strings without
knowing whether the user can understand English. This behavior is pretty common
today. The Android N Developer Preview should substantially reduce the frequency
of outcomes like this one.</p>
<h2 id="postN">Improvements to Resource-Resolution Strategy</h2>
<p>The Android N Developer Preview 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.
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}.
The following examples explain why these practices improve performance and
reliability of resource resolution.</p>
<h3>Resource resolution examples</h3>
<p>With the N Developer Preview, the case described in <a href="#t1">Table 1</a> 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
exact locale match.</p>
<table>
<tr>
<th>User Settings</th>
<th>App Resources</th>
<th>Resource Resolution</th>
</tr>
<tr>
<td><ol>
<li> fr_CH </li>
</ol>
</td>
<td>
default (en) <br>
de_DE <br>
es_ES <br>
fr_FR <br>
it_IT <br>
</td>
<td>
Try fr_CH =&gt; Fail <br>
Try fr =&gt; Fail <br>
Try children of fr =&gt; fr_FR <br>
Use fr_FR
</td>
</tr>
</table>
<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,
making resolution faster and more predictable.</p>
<p>In addition to this improved resolution logic, Android now offers more
user languages to choose from. Let’s try the above example again with Italian
specified as an additional user language, but without app support for French. </p>
<p class="table-caption" id="t-2d-choice">
<strong>Table 3.</strong> Resource resolution when the app only matches the
user's second-preferred locale setting.</p>
<table>
<tr>
<th>User Settings</th>
<th>App Resources</th>
<th>Resource Resolution</th>
</tr>
<tr>
<td><ol>
<li> fr_CH </li>
<li> it_CH </li>
</ol>
</td>
<td>
default (en) <br>
de_DE <br>
es_ES <br>
it_IT <br>
</td>
<td>
Try fr_CH =&gt; Fail <br>
Try fr =&gt; Fail <br>
Try children of fr =&gt; Fail <br>
Try it_CH =&gt; Fail <br>
Try it =&gt; Fail <br>
Try children of it =&gt; it_IT <br>
Use it_IT
</td>
</tr>
</table>
<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>The Android N Developer Preview 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
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>
<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>A prime example is Arabic, whose support the 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>
<pre> format(locale, "Choose a %d-digit PIN", 4)</pre>