1page.title=Language and Locale 2page.tags=androidn 3page.image=images/cards/card-nyc_2x.jpg 4 5@jd:body 6 7<div id="qv-wrapper"> 8<div id="qv"> 9<h2>In this document:</h2> 10<ol> 11 <li><a href="#preN">Challenges in Resolving Language Resources</a></li> 12 <li><a href="#postN">Improvements to Resource-Resolution Strategy</a></li> 13 <li><a href="#design">Designing your App to Support Additional 14 Locales</a></li> 15 16</ol> 17 18</div> 19</div> 20 21<p>Android N provides enhanced support for multilingual users, 22allowing them to select multiple locales in settings. Android N 23provides this capability by greatly expanding the number of locales supported 24and changing the way the system resolves resources. The new method of resolving 25resources is more robust and designed to be compatible with existing APKs, but 26you should take extra care to spot any unexpected behavior. For example, you 27should test to make sure that your app defaults to the expected language. Also, 28if your app supports multiple languages, you should ensure that this support works as 29intended. Finally, you should try to ensure that your app gracefully handles 30languages that you didn't explicitly design it to support.</p> 31 32<p>This document starts by explaining the resource resolution strategy prior to 33Android N. Next, it describes Android N's improved 34resource-resolution strategy. Last, it explains how to take advantage of 35the expanded number of locales to support more multilingual users.</p> 36 37<h2 id="preN">Challenges in Resolving Language Resources</h2> 38 39<p>Prior to Android N, Android could not always successfully 40 match app and system locales.</p> 41 42 <p>For example, assume that you have the following situation:</p> 43 <ul> 44 <li>Your app's default language is {@code en_US} (US English), and it also has 45 Spanish strings localized in {@code es_ES} 46 resource files.</li> 47 <li> A device is set to {@code es_MX} </li> 48 49<p>When your Java code refers to strings, the system would load 50strings from the default ({@code en_US}) resource file, even if the app has 51Spanish resources localized under {@code es_ES}. This is because when the system 52 cannot find an exact match, it continues to look for resources by stripping the 53 country code off the locale. Finally, if no match is found, the system falls 54 back to the default, which is {@code en_US}. </p> 55 56 57<p>The system would also default to {@code en_US} if the user chose a language that 58the app didn't support at all, like French. For example:</p> 59 60<p class="table-caption" id="t-resource-res"> 61<strong>Table 1.</strong> Resource resolution without an exact locale match. 62</p> 63<table> 64<tbody> 65<tr> 66<th>User Settings</th> 67<th>App Resources</th> 68<th>Resource Resolution</th> 69</tr> 70<tr> 71<td>fr_CH</td> 72<td> 73default (en)<br> 74de_DE<br> 75es_ES<br> 76fr_FR<br> 77it_IT<br> 78</td> 79 <td> 80Try fr_CH => Fail<br> 81Try fr => Fail<br> 82Use default (en) 83</td> 84 </tr> 85 </tbody> 86</table> 87 88 89<p>In this example, the system displays English strings without 90knowing whether the user can understand English. This behavior is pretty common 91today. Android N should substantially reduce the frequency 92of outcomes like this one.</p> 93 94<h2 id="postN">Improvements to Resource-Resolution Strategy</h2> 95<p>Android N brings more robust resource resolution, and 96finds better fallbacks automatically. However, to speed up resolution and improve 97 maintainability, you should store resources in the most common parent dialect. 98 For example, if you were storing Spanish resources in the {@code es-US} directory 99 before, move them into the {@code es-419} directory, which contains Latin American Spanish. 100 Similarly, if you have resource strings in a folder named {@code en-GB}, rename 101 the folder to {@code en-001} (international English), because the most common 102 parent for <code>en-GB</code> strings is {@code en-001}. 103 The following examples explain why these practices improve performance and 104reliability of resource resolution.</p> 105 106<h3>Resource resolution examples</h3> 107 108<p>With Android N, the case described in <strong>Table 1</strong> is resolved 109differently:</p> 110 111<p class="table-caption" id="t-improved-res"> 112<strong>Table 2.</strong> An improved resolution strategy for when there is no 113exact locale match.</p> 114<table> 115<tr> 116<th>User Settings</th> 117<th>App Resources</th> 118<th>Resource Resolution</th> 119</tr> 120<tr> 121<td><ol> 122<li> fr_CH</li> 123</ol> 124</td> 125<td> 126default (en)<br> 127de_DE<br> 128es_ES<br> 129fr_FR<br> 130it_IT<br> 131</td> 132<td> 133Try fr_CH => Fail<br> 134Try fr => Fail<br> 135Try children of fr => fr_FR<br> 136Use fr_FR 137</td> 138</tr> 139 140</table> 141 142 143<p>Now the user gets French resources instead of English. This example also shows 144 why you should store French strings in {@code fr} rather than {@code fr_FR} 145 for Android N. Here the course of action is to match the closest parent dialect, 146 making resolution faster and more predictable.</p> 147 148<p>In addition to this improved resolution logic, Android now offers more 149 user languages to choose from. Let’s try the above example again with Italian 150 specified as an additional user language, but without app support for French. </p> 151 152<p class="table-caption" id="t-2d-choice"> 153<strong>Table 3.</strong> Resource resolution when the app only matches the 154user's second-preferred locale setting.</p> 155<table> 156<tr> 157<th>User Settings</th> 158<th>App Resources</th> 159<th>Resource Resolution</th> 160 161</tr> 162<tr> 163<td><ol> 164<li> fr_CH</li> 165<li> it_CH</li> 166</ol> 167</td> 168<td> 169default (en)<br> 170de_DE<br> 171es_ES<br> 172it_IT<br> 173</td> 174<td> 175Try fr_CH => Fail<br> 176Try fr => Fail<br> 177Try children of fr => Fail<br> 178Try it_CH => Fail<br> 179Try it => Fail<br> 180Try children of it => it_IT<br> 181Use it_IT 182</td> 183 184</tr> 185 186</table> 187<p>The user still gets a language they understand, even though the app doesn’t 188support French.</p> 189 190 191<h2 id="design">Designing your App to Support Additional Locales</h2> 192<h3>LocaleList API</h3> 193 194<p>Android N adds a new API {@code LocaleList.getDefault()} 195that lets apps directly query the list of languages a user has specified. This API 196allows you to create more sophisticated 197 app behavior and better-optimized display of content. For example, Search 198 can show results in multiple languages based on user’s settings. Browser apps 199 can avoid offering to translate pages in a language the user already knows, 200 and keyboard apps can auto-enable all appropriate layouts. </p> 201 202<h3>Formatters</h3> 203 204<p>Up through Android 6.0 (API level 23), Android supported only one or two locales 205 for many common languages 206(en, es, ar, fr, ru). Because there were only a few variants of each language, 207apps could get away with storing some numbers and dates as hard coded strings 208in resource files. However, with Android's broadened set of supported locales, 209there can be 210significant differences in formats for dates, times, currencies, and similar 211information even within a single locale. Hard-coding your formats can produce a 212confusing experience for end users. Therefore, when developing for Android N 213make sure to use formatters instead of hard coding numbers and date strings.</p> 214 215<p>A prime example is Arabic, whose support Android N expands from 216one {@code ar_EG} to 27 Arabic locales. These locales can share most resources, 217but some prefer ASCII digits, while others prefer native digits. For example, 218when you want to create a sentence with a digit variable, such as 219"Choose a 4 digit pin", use formatters as shown below:</p> 220 221<pre> format(locale, "Choose a %d-digit PIN", 4)</pre> 222
