1 page.title=Localizing with Resources
\r
2 parent.title=Application Resources
\r
3 page.tags="localizing","localization","resources", "formats", "l10n"
\r
4 parent.link=index.html
\r
7 <div id="qv-wrapper">
\r
13 <li>Use resource sets to create a localized app.</li>
\r
14 <li>Android loads the correct resource set for the user's language and locale.</li>
\r
15 <li>If localized resources are not available, Android loads your default resources.</li>
\r
18 <h2>In this document</h2>
\r
20 <li><a href="#resource-switching">Overview: Resource-Switching in Android</a></li>
\r
21 <li><a href="#using-framework">Using Resources for Localization</a></li>
\r
22 <li><a href="#strategies">Localization Tips</a></li>
\r
23 <li><a href="#testing">Testing Localized Applications</a></li>
\r
28 <li><a href="{@docRoot}distribute/googleplay/publish/localizing.html">Localization Checklist</a></li>
\r
29 <li><a href="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a></li>
\r
30 <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Layouts</a></li>
\r
31 <li><a href="{@docRoot}reference/android/app/Activity.html#ActivityLifecycle">Activity Lifecycle</a></li>
\r
36 <p>Android will run on many devices in many regions. To reach the most users,
\r
37 your application should handle text, audio files, numbers, currency, and
\r
38 graphics in ways appropriate to the locales where your application will be used.
\r
41 <p>This document describes best practices for localizing Android
\r
42 applications. The principles apply whether you are developing your application
\r
43 using ADT with Eclipse, Ant-based tools, or any other IDE. </p>
\r
45 <p>You should already have a working knowledge of Java and be familiar with
\r
46 Android resource loading, the declaration of user interface elements in XML,
\r
47 development considerations such as Activity lifecycle, and general principles of
\r
48 internationalization and localization. </p>
\r
50 <p>It is good practice to use the Android resource framework to separate the
\r
51 localized aspects of your application as much as possible from the core Java
\r
55 <li>You can put most or all of the <em>contents</em> of your application's
\r
56 user interface into resource files, as described in this document and in <a
\r
57 href="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a>.</li>
\r
58 <li>The <em>behavior</em> of the user interface, on the other hand, is driven
\r
60 For example, if users input data that needs to be formatted or sorted
\r
61 differently depending on locale, then you would use Java to handle the data
\r
62 programmatically. This document does not cover how to localize your Java code.
\r
66 <p>For a short guide to localizing strings in your app, see the training lesson, <a
\r
67 href="{@docRoot}training/basics/supporting-devices/languages.html">Supporting Different Languages</a>. </p>
\r
70 <h2 id="resource-switching">Overview: Resource-Switching in Android</h2>
\r
72 <p>Resources are text strings, layouts, sounds, graphics, and any other static
\r
73 data that your Android application needs. An application can include multiple
\r
74 sets of resources, each customized for a different device configuration. When a
\r
75 user runs the application, Android automatically selects and loads the
\r
76 resources that best match the device.</p>
\r
78 <p>(This document focuses on localization and locale. For a complete description
\r
79 of resource-switching and all the types of configurations that you can
\r
80 specify — screen orientation, touchscreen type, and so on — see <a
\r
81 href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Providing
\r
82 Alternative Resources</a>.)</p>
\r
84 <table border="0" cellspacing="0" cellpadding="0">
\r
86 <td width="180" style="border: 0pt none ;"><p class="special-note">
\r
87 <strong>When you write your application:</strong>
\r
89 You create a set of default resources, plus alternatives to be used in
\r
90 different locales.</p></td>
\r
91 <td style="border: 0pt none; padding:0">
\r
92 <p style="border:0; padding:0"><img src="../../../images/resources/right-arrow.png" alt="right-arrow"
\r
93 width="51" height="17"></p></td>
\r
94 <td width="180" style="border: 0pt none ;"><p class="special-note">
\r
95 <strong>When a user runs your application:</strong>
\r
96 <br><br>The Android system selects which resources to load, based on the
\r
97 device's locale.</p></td>
\r
101 <p>When you write your application, you create default and alternative resources
\r
102 for your application to use. To create resources, you place files within
\r
103 specially named subdirectories of the project's <code>res/</code> directory.
\r
108 <h3 id="defaults-r-important">Why Default Resources Are Important</h3>
\r
110 <p>Whenever the application runs in a locale for which you have not provided
\r
111 locale-specific text, Android will load the default strings from
\r
112 <code>res/values/strings.xml</code>. If this default file is absent, or if it
\r
113 is missing a string that your application needs, then your application will not run
\r
114 and will show an error.
\r
115 The example below illustrates what can happen when the default text file is incomplete. </p>
\r
117 <p><em>Example:</em>
\r
118 <p>An application's Java code refers to just two strings, <code>text_a</code> and
\r
119 <code>text_b</code>. This application includes a localized resource file
\r
120 (<code>res/values-en/strings.xml</code>) that defines <code>text_a</code> and
\r
121 <code>text_b</code> in English. This application also includes a default
\r
122 resource file (<code>res/values/strings.xml</code>) that includes a
\r
123 definition for <code>text_a</code>, but not for <code>text_b</code>:
\r
125 <li>This application might compile without a problem. An IDE such as Eclipse
\r
126 will not highlight any errors if a resource is missing.</li>
\r
127 <li>When this application is launched on a device with locale set to English,
\r
128 the application might run without a problem, because
\r
129 <code>res/values-en/strings.xml</code> contains both of the needed text
\r
131 <li>However, <strong>the user will see an error message and a Force Close
\r
132 button</strong> when this application is launched on a device set to a
\r
133 language other than English. The application will not load.</li>
\r
137 <p>To prevent this situation, make sure that a <code>res/values/strings.xml</code>
\r
138 file exists and that it defines every needed string. The situation applies to
\r
139 all types of resources, not just strings: You
\r
140 need to create a set of default resource files containing all
\r
141 the resources that your application calls upon — layouts, drawables,
\r
142 animations, etc. For information about testing, see <a href="#test-for-default">
\r
143 Testing for Default Resources</a>.</p>
\r
145 <h2 id="using-framework">Using Resources for Localization</h2>
\r
147 <h3 id="creating-defaults">How to Create Default Resources</h3>
\r
149 <p>Put the application's default text in
\r
150 a file with the following location and name:</p>
\r
151 <p><code> res/values/strings.xml</code> (required directory)</p>
\r
153 <p>The text strings in <code>res/values/strings.xml</code> should use the
\r
154 default language, which is the language that you expect most of your application's users to
\r
157 <p>The default resource set must also include any default drawables and layouts,
\r
158 and can include other types of resources such as animations.
\r
160 <code> res/drawable/</code>(required directory holding at least
\r
161 one graphic file, for the application's icon on Google Play)<br>
\r
162 <code> res/layout/</code> (required directory holding an XML
\r
163 file that defines the default layout)<br>
\r
164 <code> res/anim/</code> (required if you have any
\r
165 <code>res/anim-<em><qualifiers></em></code> folders)<br>
\r
166 <code> res/xml/</code> (required if you have any
\r
167 <code>res/xml-<em><qualifiers></em></code> folders)<br>
\r
168 <code> res/raw/</code> (required if you have any
\r
169 <code>res/raw-<em><qualifiers></em></code> folders)
\r
172 <p class="note"><strong>Tip:</strong> In your code, examine each reference to
\r
173 an Android resource. Make sure that a default resource is defined for each
\r
174 one. Also make sure that the default string file is complete: A <em>
\r
175 localized</em> string file can contain a subset of the strings, but the
\r
176 <em>default</em> string file must contain them all.
\r
179 <h3 id="creating-alternatives">How to Create Alternative Resources</h3>
\r
181 <p>A large part of localizing an application is providing alternative text for
\r
182 different languages. In some cases you will also provide alternative graphics,
\r
183 sounds, layouts, and other locale-specific resources. </p>
\r
185 <p>An application can specify many <code>res/<em><qualifiers></em>/</code>
\r
186 directories, each with different qualifiers. To create an alternative resource for
\r
187 a different locale, you use a qualifier that specifies a language or a
\r
188 language-region combination. (The name of a resource directory must conform
\r
189 to the naming scheme described in
\r
190 <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Providing
\r
191 Alternative Resources</a>,
\r
192 or else it will not compile.)</p>
\r
194 <p><em>Example:</em></p>
\r
196 <p>Suppose that your application's default language is English. Suppose also
\r
197 that you want to localize all the text in your application to French, and most
\r
198 of the text in your application (everything except the application's title) to
\r
199 Japanese. In this case, you could create three alternative <code>strings.xml</code>
\r
200 files, each stored in a locale-specific resource directory:</p>
\r
203 <li><code>res/values/strings.xml</code><br>
\r
204 Contains English text for all the strings that the application uses,
\r
205 including text for a string named <code>title</code>.</li>
\r
206 <li><code>res/values-fr/strings.xml</code><br>
\r
207 Contain French text for all the strings, including <code>title</code>.</li>
\r
208 <li><code>res/values-ja/strings.xml</code><br>
\r
209 Contain Japanese text for all the strings <em>except</em>
\r
210 <code>title</code>.<br>
\r
214 <p>If your Java code refers to <code>R.string.title</code>, here is what will
\r
215 happen at runtime:</p>
\r
218 <li>If the device is set to any language other than French, Android will load
\r
219 <code>title</code> from the <code>res/values/strings.xml</code> file.</li>
\r
220 <li>If the device is set to French, Android will load <code>title</code> from
\r
221 the <code>res/values-fr/strings.xml</code> file.</li>
\r
224 <p>Notice that if the device is set to Japanese, Android will look for
\r
225 <code>title</code> in the <code>res/values-ja/strings.xml</code> file. But
\r
226 because no such string is included in that file, Android will fall back to the
\r
227 default, and will load <code>title</code> in English from the
\r
228 <code>res/values/strings.xml</code> file. </p>
\r
230 <h3 id="resource-precedence">Which Resources Take Precedence?</h3>
\r
232 <p> If multiple resource files match a device's configuration, Android follows a
\r
233 set of rules in deciding which file to use. Among the qualifiers that can be
\r
234 specified in a resource directory name, <strong>locale almost always takes
\r
235 precedence</strong>. </p>
\r
236 <p><em>Example:</em></p>
\r
238 <p>Assume that an application includes a default set of graphics and two other
\r
239 sets of graphics, each optimized for a different device setup:</p>
\r
242 <li><code>res/drawable/</code><br>
\r
244 default graphics.</li>
\r
245 <li><code>res/drawable-small-land-stylus/</code><br>
\r
246 Contains graphics optimized for use with a device that expects input from a
\r
247 stylus and has a QVGA low-density screen in landscape orientation.</li>
\r
248 <li><code>res/drawable-ja/</code> <br>
\r
249 Contains graphics optimized for use with Japanese.</li>
\r
252 <p>If the application runs on a device that is configured to use Japanese,
\r
253 Android will load graphics from <code>res/drawable-ja/</code>, even if the
\r
254 device happens to be one that expects input from a stylus and has a QVGA
\r
255 low-density screen in landscape orientation.</p>
\r
257 <p class="note"><strong>Exception:</strong> The only qualifiers that take
\r
258 precedence over locale in the selection process are MCC and MNC (mobile country
\r
259 code and mobile network code). </p>
\r
261 <p><em>Example:</em></p>
\r
263 <p>Assume that you have the following situation:</p>
\r
266 <li>The application code calls for <code>R.string.text_a</code></li>
\r
267 <li>Two relevant resource files are available:
\r
269 <li><code>res/values-mcc404/strings.xml</code>, which includes
\r
270 <code>text_a</code> in the application's default language, in this case
\r
272 <li><code>res/values-hi/strings.xml</code>, which includes
\r
273 <code>text_a</code> in Hindi.</li>
\r
276 <li>The application is running on a device that has the following
\r
279 <li>The SIM card is connected to a mobile network in India (MCC 404).</li>
\r
280 <li>The language is set to Hindi (<code>hi</code>).</li>
\r
285 <p>Android will load <code>text_a</code> from
\r
286 <code>res/values-mcc404/strings.xml</code> (in English), even if the device is
\r
287 configured for Hindi. That is because in the resource-selection process, Android
\r
288 will prefer an MCC match over a language match. </p>
\r
290 <p>The selection process is not always as straightforward as these examples
\r
291 suggest. Please read <a
\r
292 href="{@docRoot}guide/topics/resources/providing-resources.html#BestMatch">How Android Finds
\r
293 the Best-matching Resource</a> for a more nuanced description of the
\r
294 process. All the qualifiers are described and listed in order of
\r
296 href="{@docRoot}guide/topics/resources/providing-resources.html#table2">Table 2 of Providing
\r
297 Alternative Resources</a>.</p>
\r
299 <h3 id="referring-to-resources">Referring to Resources in Java</h3>
\r
301 <p>In your application's Java code, you refer to resources using the syntax
\r
302 <code>R.<em>resource_type</em>.<em>resource_name</em></code> or
\r
303 <code>android.R.<em>resource_type</em>.<em>resource_name</em></code><em>.</em>
\r
304 For more about this, see <a
\r
305 href="{@docRoot}guide/topics/resources/accessing-resources.html">Accessing Resources</a>.</p>
\r
307 <h2 id="checklist">Localization Checklist</h2>
\r
309 <p>For a complete overview of the process of localizing and distributing an Android application,
\r
310 see the <a href="{@docRoot}distribute/googleplay/publish/localizing.html">Localization
\r
311 Checklist</a> document.</p>
\r
313 <h2 id="strategies">Localization Tips</h2>
\r
315 <h4 id="failing2">Design your application to work in any locale</h4>
\r
317 <p>You cannot assume anything about the device on which a user will
\r
318 run your application. The device might have hardware that you were not
\r
319 anticipating, or it might be set to a locale that you did not plan for or that
\r
320 you cannot test. Design your application so that it will function normally or fail gracefully no
\r
321 matter what device it runs on.</p>
\r
323 <p class="note"><strong>Important:</strong> Make sure that your application
\r
324 includes a full set of default resources.</p> <p>Make sure to include
\r
325 <code>res/drawable/</code> and a <code>res/values/</code> folders (without any
\r
326 additional modifiers in the folder names) that contain all the images and text
\r
327 that your application will need. </p>
\r
329 <p>If an application is missing even one default resource, it will not run on a
\r
330 device that is set to an unsupported locale. For example, the
\r
331 <code>res/values/strings.xml</code> default file might lack one string that
\r
332 the application needs: When the application runs in an unsupported locale and
\r
333 attempts to load <code>res/values/strings.xml</code>, the user will see an
\r
334 error message and a Force Close button. An IDE such as Eclipse will not
\r
335 highlight this kind of error, and you will not see the problem when you
\r
336 test the application on a device or emulator that is set to a supported locale.</p>
\r
338 <p>For more information, see <a href="#test-for-default">Testing for Default Resources</a>.</p>
\r
340 <h4>Design a flexible layout</h4>
\r
342 <p> If you need to rearrange your layout to fit a certain language (for example
\r
343 German with its long words), you can create an alternative layout for that
\r
344 language (for example <code>res/layout-de/main.xml</code>). However, doing this
\r
345 can make your application harder to maintain. It is better to create a single
\r
346 layout that is more flexible.</p>
\r
348 <p>Another typical situation is a language that requires something different in
\r
349 its layout. For example, you might have a contact form that should include two
\r
350 name fields when the application runs in Japanese, but three name fields when
\r
351 the application runs in some other language. You could handle this in either of
\r
355 <li>Create one layout with a field that you can programmatically enable or
\r
356 disable, based on the language, or</li>
\r
357 <li>Have the main layout include another layout that includes the changeable
\r
358 field. The second layout can have different configurations for different
\r
362 <h4>Avoid creating more resource files and text strings than you need</h4>
\r
364 <p>You probably do not need to create a locale-specific
\r
365 alternative for every resource in your application. For example, the layout
\r
366 defined in the <code>res/layout/main.xml</code> file might work in any locale,
\r
367 in which case there would be no need to create any alternative layout files.
\r
370 <p>Also, you might not need to create alternative text for every
\r
371 string. For example, assume the following:</p>
\r
374 <li>Your application's default language is American
\r
375 English. Every string that the application uses is defined, using American
\r
376 English spellings, in <code>res/values/strings.xml</code>. </li>
\r
378 <li>For a few important phrases, you want to provide
\r
379 British English spelling. You want these alternative strings to be used when your
\r
380 application runs on a device in the United Kingdom. </li>
\r
383 <p>To do this, you could create a small file called
\r
384 <code>res/values-en-rGB/strings.xml</code> that includes only the strings that
\r
385 should be different when the application runs in the U.K. For all the rest of
\r
386 the strings, the application will fall back to the defaults and use what is
\r
387 defined in <code>res/values/strings.xml</code>.</p>
\r
389 <h4>Use the Android Context object for manual locale lookup</h4>
\r
391 <p>You can look up the locale using the {@link android.content.Context} object
\r
392 that Android makes available:</p>
\r
394 <pre>String locale = context.getResources().getConfiguration().locale.getDisplayName();</pre>
\r
396 <h2 id="testing">Testing Localized Applications</h2>
\r
398 <h3 id="device">Testing on a Device</h3>
\r
399 <p>Keep in mind that the device you are testing may be significantly different from
\r
400 the devices available to consumers in other geographies. The locales available
\r
401 on your device may differ from those available on other devices. Also, the
\r
402 resolution and density of the device screen may differ, which could affect
\r
403 the display of strings and drawables in your UI.</p>
\r
405 <p>To change the locale on a device, use the Settings application (Home >
\r
406 Menu > Settings > Locale & text > Select locale). </p>
\r
408 <h3 id="emulator">Testing on an Emulator</h3>
\r
410 <p>For details about using the emulator, see See <a
\r
411 href="{@docRoot}tools/help/emulator.html">Android Emulator</a>.</p>
\r
412 <h4>Creating and using a custom locale</h4>
\r
414 <p>A "custom" locale is a language/region combination that the Android
\r
415 system image does not explicitly support. (For a list of supported locales in
\r
416 Android platforms see the Version Notes in the <a
\r
417 href="{@docRoot}sdk/index.html">SDK</a> tab). You can test
\r
418 how your application will run in a custom locale by creating a custom locale in
\r
419 the emulator. There are two ways to do this:</p>
\r
422 <li>Use the Custom Locale application, which is accessible from the
\r
423 Application tab. (After you create a custom locale, switch to it by
\r
424 pressing and holding the locale name.)</li>
\r
425 <li>Change to a custom locale from the adb shell, as described below.</li>
\r
428 <p>When you set the emulator to a locale that is not available in the Android
\r
429 system image, the system itself will display in its default language. Your
\r
430 application, however, should localize properly.</p>
\r
432 <h4>Changing the emulator locale from the adb shell</h4>
\r
434 <p>To change the locale in the emulator by using the adb shell. </p>
\r
437 <li>Pick the locale you want to test and determine its language and region codes, for
\r
438 example <code>fr</code> for French and <code>CA</code> for Canada.<br>
\r
440 <li>Launch an emulator.</li>
\r
441 <li>From a command-line shell on the host computer, run the following
\r
443 <code>adb shell</code><br>
\r
444 or if you have a device attached, specify that you want the emulator by adding
\r
445 the <code>-e</code> option:<br>
\r
446 <code>adb -e shell</code></li>
\r
447 <li>At the adb shell prompt (<code>#</code>), run this command: <br>
\r
448 <code>setprop persist.sys.language [<em>language code</em>];setprop
\r
449 persist.sys.country [<em>country code</em>];stop;sleep 5;start <br>
\r
450 </code>Replace bracketed sections with the appropriate codes from Step
\r
454 <p>For instance, to test in Canadian French:</p>
\r
456 <p><code>setprop persist.sys.language fr;setprop persist.sys.country
\r
457 CA;stop;sleep 5;start </code></p>
\r
459 <p>This will cause the emulator to restart. (It will look like a full reboot,
\r
460 but it is not.) Once the Home screen appears again, re-launch your application (for
\r
461 example, click the Run icon in Eclipse), and the application will launch with
\r
462 the new locale. </p>
\r
464 <h3 id="test-for-default">Testing for Default Resources</h3>
\r
465 <p>Here's how to test whether an application includes every string resource that it needs: </p>
\r
466 <ol><li>Set the emulator or device to a language that your application does not
\r
467 support. For example, if the application has French strings in
\r
468 <code>res/values-fr/</code> but does not have any Spanish strings in
\r
469 <code>res/values-es/</code>, then set the emulator's locale to Spanish.
\r
470 (You can use the Custom Locale application to set the emulator to an
\r
471 unsupported locale.)</li>
\r
472 <li>Run the application.</li>
\r
473 <li>If the application shows an error message and a Force Close button, it might
\r
474 be looking for a string that is not available. Make sure that your
\r
475 <code>res/values/strings.xml</code> file includes a definition for
\r
476 every string that the application uses.</li>
\r
480 <p>If the test is successful, repeat it for other types of
\r
481 configurations. For example, if the application has a layout file called
\r
482 <code>res/layout-land/main.xml</code> but does not contain a file called
\r
483 <code>res/layout-port/main.xml</code>, then set the emulator or device to
\r
484 portrait orientation and see if the application will run.
\r