1afc028071494d1c8acf4405f2ff2f606fc44375cDirk Doughertypage.title=Localizing with Resources 2f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott Mainparent.title=Application Resources 3afc028071494d1c8acf4405f2ff2f606fc44375cDirk Doughertypage.tags="localizing","localization","resources", "formats", "l10n" 420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtparent.link=index.html 520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt@jd:body 620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<div id="qv-wrapper"> 820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <div id="qv"> 920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 10afc028071494d1c8acf4405f2ff2f606fc44375cDirk Dougherty<h2>Quickview</h2> 1120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 1220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<ul> 13afc028071494d1c8acf4405f2ff2f606fc44375cDirk Dougherty <li>Use resource sets to create a localized app.</li> 14afc028071494d1c8acf4405f2ff2f606fc44375cDirk Dougherty <li>Android loads the correct resource set for the user's language and locale.</li> 15afc028071494d1c8acf4405f2ff2f606fc44375cDirk Dougherty <li>If localized resources are not available, Android loads your default resources.</li> 1620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</ul> 1720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 1820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h2>In this document</h2> 1920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<ol> 20afc028071494d1c8acf4405f2ff2f606fc44375cDirk Dougherty <li><a href="#resource-switching">Overview: Resource-Switching in Android</a></li> 21afc028071494d1c8acf4405f2ff2f606fc44375cDirk Dougherty<li><a href="#using-framework">Using Resources for Localization</a></li> 22d296e25a329b7251c89c85dec836878f4c03a4ecDirk Dougherty<li><a href="#strategies">Localization Tips</a></li> 2320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<li><a href="#testing">Testing Localized Applications</a></li> 2420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</ol> 2520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 2620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h2>See also</h2> 2720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <ol> 283506ac87c09c0748d92ef594c94365a5d7b07262Dirk Dougherty <li><a href="{@docRoot}distribute/tools/localization-checklist.html">Localization Checklist</a></li> 29f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott Main <li><a href="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a></li> 3050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Layouts</a></li> 3120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li><a href="{@docRoot}reference/android/app/Activity.html#ActivityLifecycle">Activity Lifecycle</a></li> 3220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</ol> 3320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</div> 3420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</div> 3520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 3620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>Android will run on many devices in many regions. To reach the most users, 3720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtyour application should handle text, audio files, numbers, currency, and 3820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtgraphics in ways appropriate to the locales where your application will be used. 3920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</p> 4020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 4120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>This document describes best practices for localizing Android 4220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtapplications. The principles apply whether you are developing your application 4320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtusing ADT with Eclipse, Ant-based tools, or any other IDE. </p> 4420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 4520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>You should already have a working knowledge of Java and be familiar with 4620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina StenstedtAndroid resource loading, the declaration of user interface elements in XML, 4720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtdevelopment considerations such as Activity lifecycle, and general principles of 4820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtinternationalization and localization. </p> 4920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 5020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>It is good practice to use the Android resource framework to separate the 5120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtlocalized aspects of your application as much as possible from the core Java 5220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtfunctionality:</p> 5320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 5420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<ul> 5520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>You can put most or all of the <em>contents</em> of your application's 5620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtuser interface into resource files, as described in this document and in <a 57f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott Mainhref="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a>.</li> 5820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>The <em>behavior</em> of the user interface, on the other hand, is driven 5920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtby your Java code. 6020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt For example, if users input data that needs to be formatted or sorted 6120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtdifferently depending on locale, then you would use Java to handle the data 6220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtprogrammatically. This document does not cover how to localize your Java code. 6320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</li> 6420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</ul> 6520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 6612a5475205243bc2d069a87d2c7d4982b5f4d11dScott Main<p>For a short guide to localizing strings in your app, see the training lesson, <a 6712a5475205243bc2d069a87d2c7d4982b5f4d11dScott Mainhref="{@docRoot}training/basics/supporting-devices/languages.html">Supporting Different Languages</a>. </p> 6820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 6920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 7020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h2 id="resource-switching">Overview: Resource-Switching in Android</h2> 7120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 7220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>Resources are text strings, layouts, sounds, graphics, and any other static 7320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtdata that your Android application needs. An application can include multiple 7420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtsets of resources, each customized for a different device configuration. When a 7520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtuser runs the application, Android automatically selects and loads the 7620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtresources that best match the device.</p> 7720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 7820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>(This document focuses on localization and locale. For a complete description 7920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtof resource-switching and all the types of configurations that you can 8020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtspecify — screen orientation, touchscreen type, and so on — see <a 81f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott Mainhref="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Providing 82f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott MainAlternative Resources</a>.)</p> 8320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 8420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<table border="0" cellspacing="0" cellpadding="0"> 8520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <tr border="0"> 8620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <td width="180" style="border: 0pt none ;"><p class="special-note"> 8720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <strong>When you write your application:</strong> 8820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <br><br> 89f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott Main You create a set of default resources, plus alternatives to be used in 9020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt different locales.</p></td> 9120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <td style="border: 0pt none; padding:0"> 9220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <p style="border:0; padding:0"><img src="../../../images/resources/right-arrow.png" alt="right-arrow" 9320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt width="51" height="17"></p></td> 9420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <td width="180" style="border: 0pt none ;"><p class="special-note"> 9520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <strong>When a user runs your application:</strong> 9620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <br><br>The Android system selects which resources to load, based on the 9720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt device's locale.</p></td> 9820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt </tr> 9920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</table> 10020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 101f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott Main<p>When you write your application, you create default and alternative resources 10220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtfor your application to use. To create resources, you place files within 10320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtspecially named subdirectories of the project's <code>res/</code> directory. 10420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</p> 10520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 10620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 10720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 10820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h3 id="defaults-r-important">Why Default Resources Are Important</h3> 10920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 11020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>Whenever the application runs in a locale for which you have not provided 11120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtlocale-specific text, Android will load the default strings from 11220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<code>res/values/strings.xml</code>. If this default file is absent, or if it 11320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtis missing a string that your application needs, then your application will not run 11420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtand will show an error. 11520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina StenstedtThe example below illustrates what can happen when the default text file is incomplete. </p> 11620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 11720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p><em>Example:</em> 11820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>An application's Java code refers to just two strings, <code>text_a</code> and 11920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code>text_b</code>. This application includes a localized resource file 12020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt (<code>res/values-en/strings.xml</code>) that defines <code>text_a</code> and 12120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code>text_b</code> in English. This application also includes a default 12220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt resource file (<code>res/values/strings.xml</code>) that includes a 12320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtdefinition for <code>text_a</code>, but not for <code>text_b</code>: 12420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<ul> 12520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>This application might compile without a problem. An IDE such as Eclipse 12620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt will not highlight any errors if a resource is missing.</li> 12720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>When this application is launched on a device with locale set to English, 12820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt the application might run without a problem, because 12920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code>res/values-en/strings.xml</code> contains both of the needed text 13020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt strings.</li> 13120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>However, <strong>the user will see an error message and a Force Close 13220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt button</strong> when this application is launched on a device set to a 13320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt language other than English. The application will not load.</li> 13420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</ul> 13520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 13620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 13720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>To prevent this situation, make sure that a <code>res/values/strings.xml</code> 13820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt file exists and that it defines every needed string. The situation applies to 13920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt all types of resources, not just strings: You 14020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt need to create a set of default resource files containing all 14120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt the resources that your application calls upon — layouts, drawables, 14220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt animations, etc. For information about testing, see <a href="#test-for-default"> 14320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt Testing for Default Resources</a>.</p> 14420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 14520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h2 id="using-framework">Using Resources for Localization</h2> 14620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 14720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h3 id="creating-defaults">How to Create Default Resources</h3> 14820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 14920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>Put the application's default text in 15020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedta file with the following location and name:</p> 15120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p><code> res/values/strings.xml</code> (required directory)</p> 15220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 15320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>The text strings in <code>res/values/strings.xml</code> should use the 15420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtdefault language, which is the language that you expect most of your application's users to 15520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtspeak. </p> 15620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 15720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>The default resource set must also include any default drawables and layouts, 15820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt and can include other types of resources such as animations. 15920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<br> 16020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code> res/drawable/</code>(required directory holding at least 1614d7bc65538c7cd9fbb1fbbcf22d1da47fcee1219Dirk Dougherty one graphic file, for the application's icon on Google Play)<br> 16220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code> res/layout/</code> (required directory holding an XML 16320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt file that defines the default layout)<br> 16420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code> res/anim/</code> (required if you have any 16520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code>res/anim-<em><qualifiers></em></code> folders)<br> 16620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code> res/xml/</code> (required if you have any 16720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code>res/xml-<em><qualifiers></em></code> folders)<br> 16820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code> res/raw/</code> (required if you have any 16920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code>res/raw-<em><qualifiers></em></code> folders) 17020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</p> 17120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 17220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p class="note"><strong>Tip:</strong> In your code, examine each reference to 17320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt an Android resource. Make sure that a default resource is defined for each 17420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt one. Also make sure that the default string file is complete: A <em> 17520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt localized</em> string file can contain a subset of the strings, but the 17620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <em>default</em> string file must contain them all. 17720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</p> 17820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 179f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott Main<h3 id="creating-alternatives">How to Create Alternative Resources</h3> 18020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 181f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott Main<p>A large part of localizing an application is providing alternative text for 182f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott Maindifferent languages. In some cases you will also provide alternative graphics, 18320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtsounds, layouts, and other locale-specific resources. </p> 18420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 18520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>An application can specify many <code>res/<em><qualifiers></em>/</code> 186f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott Maindirectories, each with different qualifiers. To create an alternative resource for 18720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedta different locale, you use a qualifier that specifies a language or a 18820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtlanguage-region combination. (The name of a resource directory must conform 18920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtto the naming scheme described in 190f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott Main<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Providing 191f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott MainAlternative Resources</a>, 19220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtor else it will not compile.)</p> 19320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 19420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p><em>Example:</em></p> 19520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 19620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>Suppose that your application's default language is English. Suppose also 19720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtthat you want to localize all the text in your application to French, and most 19820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtof the text in your application (everything except the application's title) to 199f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott MainJapanese. In this case, you could create three alternative <code>strings.xml</code> 20020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtfiles, each stored in a locale-specific resource directory:</p> 20120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 20220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<ol> 20320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li><code>res/values/strings.xml</code><br> 20420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt Contains English text for all the strings that the application uses, 20520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtincluding text for a string named <code>title</code>.</li> 20620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li><code>res/values-fr/strings.xml</code><br> 20720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt Contain French text for all the strings, including <code>title</code>.</li> 20820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li><code>res/values-ja/strings.xml</code><br> 20920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt Contain Japanese text for all the strings <em>except</em> 21020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<code>title</code>.<br> 21120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code></code></li> 21220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</ol> 21320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 21420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>If your Java code refers to <code>R.string.title</code>, here is what will 21520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedthappen at runtime:</p> 21620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 21720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<ul> 21820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>If the device is set to any language other than French, Android will load 21920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<code>title</code> from the <code>res/values/strings.xml</code> file.</li> 22020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>If the device is set to French, Android will load <code>title</code> from 22120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtthe <code>res/values-fr/strings.xml</code> file.</li> 22220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</ul> 22320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 22420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>Notice that if the device is set to Japanese, Android will look for 22520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<code>title</code> in the <code>res/values-ja/strings.xml</code> file. But 22620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtbecause no such string is included in that file, Android will fall back to the 22720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtdefault, and will load <code>title</code> in English from the 22820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<code>res/values/strings.xml</code> file. </p> 22920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 23020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h3 id="resource-precedence">Which Resources Take Precedence?</h3> 23120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 23220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p> If multiple resource files match a device's configuration, Android follows a 23320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtset of rules in deciding which file to use. Among the qualifiers that can be 23420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtspecified in a resource directory name, <strong>locale almost always takes 23520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtprecedence</strong>. </p> 23620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p><em>Example:</em></p> 23720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 23820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>Assume that an application includes a default set of graphics and two other 23920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtsets of graphics, each optimized for a different device setup:</p> 24020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 24120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<ul> 24220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li><code>res/drawable/</code><br> 24320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt Contains 24420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt default graphics.</li> 24520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li><code>res/drawable-small-land-stylus/</code><br> 24620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt Contains graphics optimized for use with a device that expects input from a 24720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt stylus and has a QVGA low-density screen in landscape orientation.</li> 24820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li><code>res/drawable-ja/</code> <br> 24920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt Contains graphics optimized for use with Japanese.</li> 25020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</ul> 25120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 25220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>If the application runs on a device that is configured to use Japanese, 25320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina StenstedtAndroid will load graphics from <code>res/drawable-ja/</code>, even if the 25420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtdevice happens to be one that expects input from a stylus and has a QVGA 25520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtlow-density screen in landscape orientation.</p> 25620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 25720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p class="note"><strong>Exception:</strong> The only qualifiers that take 25820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtprecedence over locale in the selection process are MCC and MNC (mobile country 25920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtcode and mobile network code). </p> 26020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 26120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p><em>Example:</em></p> 26220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 26320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>Assume that you have the following situation:</p> 26420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 26520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<ul> 26620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>The application code calls for <code>R.string.text_a</code></li> 26720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>Two relevant resource files are available: 26820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <ul> 26920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li><code>res/values-mcc404/strings.xml</code>, which includes 27020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<code>text_a</code> in the application's default language, in this case 27120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina StenstedtEnglish.</li> 27220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li><code>res/values-hi/strings.xml</code>, which includes 27320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<code>text_a</code> in Hindi.</li> 27420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt </ul> 27520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt </li> 27620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>The application is running on a device that has the following 27720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtconfiguration: 27820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <ul> 27920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>The SIM card is connected to a mobile network in India (MCC 404).</li> 28020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>The language is set to Hindi (<code>hi</code>).</li> 28120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt </ul> 28220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt </li> 28320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</ul> 28420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 28520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>Android will load <code>text_a</code> from 28620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<code>res/values-mcc404/strings.xml</code> (in English), even if the device is 28720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtconfigured for Hindi. That is because in the resource-selection process, Android 28820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtwill prefer an MCC match over a language match. </p> 28920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 29020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>The selection process is not always as straightforward as these examples 291f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott Mainsuggest. Please read <a 2925dd0fd5c89099f194b9ec2323bb6413fa48e7db8Scott Mainhref="{@docRoot}guide/topics/resources/providing-resources.html#BestMatch">How Android Finds 293f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott Mainthe Best-matching Resource</a> for a more nuanced description of the 29420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtprocess. All the qualifiers are described and listed in order of 295f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott Mainprecedence in <a 2965dd0fd5c89099f194b9ec2323bb6413fa48e7db8Scott Mainhref="{@docRoot}guide/topics/resources/providing-resources.html#table2">Table 2 of Providing 297f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott MainAlternative Resources</a>.</p> 29820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 29920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h3 id="referring-to-resources">Referring to Resources in Java</h3> 30020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 30120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>In your application's Java code, you refer to resources using the syntax 30220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<code>R.<em>resource_type</em>.<em>resource_name</em></code> or 30320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<code>android.R.<em>resource_type</em>.<em>resource_name</em></code><em>.</em> 304f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott MainFor more about this, see <a 3055dd0fd5c89099f194b9ec2323bb6413fa48e7db8Scott Mainhref="{@docRoot}guide/topics/resources/accessing-resources.html">Accessing Resources</a>.</p> 30620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 307d296e25a329b7251c89c85dec836878f4c03a4ecDirk Dougherty<h2 id="checklist">Localization Checklist</h2> 308d296e25a329b7251c89c85dec836878f4c03a4ecDirk Dougherty 309d296e25a329b7251c89c85dec836878f4c03a4ecDirk Dougherty<p>For a complete overview of the process of localizing and distributing an Android application, 3103506ac87c09c0748d92ef594c94365a5d7b07262Dirk Doughertysee the <a href="{@docRoot}distribute/tools/localization-checklist.html">Localization 311d296e25a329b7251c89c85dec836878f4c03a4ecDirk DoughertyChecklist</a> document.</p> 312d296e25a329b7251c89c85dec836878f4c03a4ecDirk Dougherty 313d296e25a329b7251c89c85dec836878f4c03a4ecDirk Dougherty<h2 id="strategies">Localization Tips</h2> 31420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 31520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h4 id="failing2">Design your application to work in any locale</h4> 31620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 31720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>You cannot assume anything about the device on which a user will 31820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtrun your application. The device might have hardware that you were not 31920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtanticipating, or it might be set to a locale that you did not plan for or that 32020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtyou cannot test. Design your application so that it will function normally or fail gracefully no 32120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtmatter what device it runs on.</p> 32220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 32320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p class="note"><strong>Important:</strong> Make sure that your application 32420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtincludes a full set of default resources.</p> <p>Make sure to include 32520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<code>res/drawable/</code> and a <code>res/values/</code> folders (without any 32620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtadditional modifiers in the folder names) that contain all the images and text 32720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtthat your application will need. </p> 32820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 32920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>If an application is missing even one default resource, it will not run on a 33020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt device that is set to an unsupported locale. For example, the 33120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code>res/values/strings.xml</code> default file might lack one string that 33220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt the application needs: When the application runs in an unsupported locale and 33320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt attempts to load <code>res/values/strings.xml</code>, the user will see an 33420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt error message and a Force Close button. An IDE such as Eclipse will not 33520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt highlight this kind of error, and you will not see the problem when you 33620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt test the application on a device or emulator that is set to a supported locale.</p> 33720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 33820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>For more information, see <a href="#test-for-default">Testing for Default Resources</a>.</p> 33920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 34020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h4>Design a flexible layout</h4> 34120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 34220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p> If you need to rearrange your layout to fit a certain language (for example 343f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott MainGerman with its long words), you can create an alternative layout for that 34420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtlanguage (for example <code>res/layout-de/main.xml</code>). However, doing this 34520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtcan make your application harder to maintain. It is better to create a single 34620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtlayout that is more flexible.</p> 34720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 34820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>Another typical situation is a language that requires something different in 34920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtits layout. For example, you might have a contact form that should include two 35020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtname fields when the application runs in Japanese, but three name fields when 35120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtthe application runs in some other language. You could handle this in either of 35220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedttwo ways:</p> 35320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 35420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<ul> 35520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>Create one layout with a field that you can programmatically enable or 35620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtdisable, based on the language, or</li> 35720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>Have the main layout include another layout that includes the changeable 35820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtfield. The second layout can have different configurations for different 35920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtlanguages.</li> 36020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</ul> 36120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 36220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h4>Avoid creating more resource files and text strings than you need</h4> 36320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 36420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>You probably do not need to create a locale-specific 36520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtalternative for every resource in your application. For example, the layout 36620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtdefined in the <code>res/layout/main.xml</code> file might work in any locale, 367f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott Mainin which case there would be no need to create any alternative layout files. 36820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</p> 36920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 370f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott Main<p>Also, you might not need to create alternative text for every 37120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtstring. For example, assume the following:</p> 37220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 37320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<ul> 37420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>Your application's default language is American 37520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina StenstedtEnglish. Every string that the application uses is defined, using American 37620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina StenstedtEnglish spellings, in <code>res/values/strings.xml</code>. </li> 37720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 37820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>For a few important phrases, you want to provide 379f940a1f316ddbed760f6f3ab9a3e4f2112909381Scott MainBritish English spelling. You want these alternative strings to be used when your 38020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtapplication runs on a device in the United Kingdom. </li> 38120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</ul> 38220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 38320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>To do this, you could create a small file called 38420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<code>res/values-en-rGB/strings.xml</code> that includes only the strings that 38520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtshould be different when the application runs in the U.K. For all the rest of 38620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtthe strings, the application will fall back to the defaults and use what is 38720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtdefined in <code>res/values/strings.xml</code>.</p> 38820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 38920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h4>Use the Android Context object for manual locale lookup</h4> 39020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 39120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>You can look up the locale using the {@link android.content.Context} object 39220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtthat Android makes available:</p> 39320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 39420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<pre>String locale = context.getResources().getConfiguration().locale.getDisplayName();</pre> 39520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 39620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h2 id="testing">Testing Localized Applications</h2> 39720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 39820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h3 id="device">Testing on a Device</h3> 39920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>Keep in mind that the device you are testing may be significantly different from 40020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt the devices available to consumers in other geographies. The locales available 40120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt on your device may differ from those available on other devices. Also, the 40220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt resolution and density of the device screen may differ, which could affect 40320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt the display of strings and drawables in your UI.</p> 40420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 40572c80d308a88d59347f13dd813f2885bc4f45accScott Rowe<p>To change the locale or language on a device, use the Settings application.</p> 40620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 40720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h3 id="emulator">Testing on an Emulator</h3> 40820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 40920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>For details about using the emulator, see See <a 41050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainhref="{@docRoot}tools/help/emulator.html">Android Emulator</a>.</p> 41120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h4>Creating and using a custom locale</h4> 41220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 4139519eab313fdb0f74a05e85cffe25b61aa76a5ddDirk Dougherty<p>A "custom" locale is a language/region combination that the Android 4149519eab313fdb0f74a05e85cffe25b61aa76a5ddDirk Doughertysystem image does not explicitly support. (For a list of supported locales in 4159519eab313fdb0f74a05e85cffe25b61aa76a5ddDirk DoughertyAndroid platforms see the Version Notes in the <a 4169519eab313fdb0f74a05e85cffe25b61aa76a5ddDirk Doughertyhref="{@docRoot}sdk/index.html">SDK</a> tab). You can test 4179519eab313fdb0f74a05e85cffe25b61aa76a5ddDirk Doughertyhow your application will run in a custom locale by creating a custom locale in 4189519eab313fdb0f74a05e85cffe25b61aa76a5ddDirk Doughertythe emulator. There are two ways to do this:</p> 41920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 42020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<ul> 42120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>Use the Custom Locale application, which is accessible from the 42220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina StenstedtApplication tab. (After you create a custom locale, switch to it by 42320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtpressing and holding the locale name.)</li> 42420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>Change to a custom locale from the adb shell, as described below.</li> 42520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</ul> 42620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 42720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>When you set the emulator to a locale that is not available in the Android 42820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtsystem image, the system itself will display in its default language. Your 42920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtapplication, however, should localize properly.</p> 43020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 43120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h4>Changing the emulator locale from the adb shell</h4> 43220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 43320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>To change the locale in the emulator by using the adb shell. </p> 43420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 43520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<ol> 43620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>Pick the locale you want to test and determine its language and region codes, for 43720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtexample <code>fr</code> for French and <code>CA</code> for Canada.<br> 43820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt </li> 43920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>Launch an emulator.</li> 44020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>From a command-line shell on the host computer, run the following 44120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtcommand:<br> 44220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code>adb shell</code><br> 44320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt or if you have a device attached, specify that you want the emulator by adding 44420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtthe <code>-e</code> option:<br> 44520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code>adb -e shell</code></li> 44620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>At the adb shell prompt (<code>#</code>), run this command: <br> 44720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code>setprop persist.sys.language [<em>language code</em>];setprop 44820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtpersist.sys.country [<em>country code</em>];stop;sleep 5;start <br> 44920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt </code>Replace bracketed sections with the appropriate codes from Step 45020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt1.</li> 45120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</ol> 45220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 45320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>For instance, to test in Canadian French:</p> 45420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 45520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p><code>setprop persist.sys.language fr;setprop persist.sys.country 45620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina StenstedtCA;stop;sleep 5;start </code></p> 45720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 45820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>This will cause the emulator to restart. (It will look like a full reboot, 45920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtbut it is not.) Once the Home screen appears again, re-launch your application (for 46020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtexample, click the Run icon in Eclipse), and the application will launch with 46120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedtthe new locale. </p> 46220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 46320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<h3 id="test-for-default">Testing for Default Resources</h3> 46420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>Here's how to test whether an application includes every string resource that it needs: </p> 46520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<ol><li>Set the emulator or device to a language that your application does not 46620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt support. For example, if the application has French strings in 46720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code>res/values-fr/</code> but does not have any Spanish strings in 46820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code>res/values-es/</code>, then set the emulator's locale to Spanish. 46920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt (You can use the Custom Locale application to set the emulator to an 47020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt unsupported locale.)</li> 47120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <li>Run the application.</li> 47220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<li>If the application shows an error message and a Force Close button, it might 47320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt be looking for a string that is not available. Make sure that your 47420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code>res/values/strings.xml</code> file includes a definition for 47520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt every string that the application uses.</li> 47620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</ol> 47720972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt</p> 47820972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 47920972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt<p>If the test is successful, repeat it for other types of 48020972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt configurations. For example, if the application has a layout file called 48120972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code>res/layout-land/main.xml</code> but does not contain a file called 48220972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt <code>res/layout-port/main.xml</code>, then set the emulator or device to 48320972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt portrait orientation and see if the application will run. 48420972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 48520972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 48620972da079adb6e53fe5f8758aa473d9d46a1b54Katarina Stenstedt 487