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