Cascading Through Locale and Language Resource Files

Localized resources are placed in folders whose qualifiers reflect the language and possibly the locale of the localization. The folder name format is values-<language> or values-<language-region code>.

“Language” in this instance is the language ISO code, such as “fr” for French.

“Region code” is the optional region code, preceded by “r” (lowercase r), for example: fr-rFR for French used in France or fr-rCA for Canadian French.

Android selects the resource files required by the application when it is launched based on the device’s locale. If there are no locale-specific resources, the next level of resources will be checked, and finally the default resources used, if not other suitable resources exist.

For example, suppose the locale is Swiss French, but no “fr-rCH” folder or resources (no res/values-fr-rCH/strings.xml, etc.) exist. Android will then check the “fr” folder (res/values-fr/strings.xml, etc.), and finally the default folder if required (res/values/strings.xml) to obtain a version of the resources for display.

Avoid Hardcoding of Text or Other Resources

Placing text resources in your default strings.xml file from the beginning avoids the difficulties associated with hard coding them in your app. Use of the strings.xml file greatly facilitates modification, updating, and app localization. It also means that translated versions (from appropriate subdirectories) can be used without having to recompile your app’s code. Text used in the generation of images should be placed in the strings.xml file for the same reason. Localized images will then be generated correctly in the same way.

Making Strings.xml Understandable to Translators

Remember that translators producing localized texts may only see your strings.xml file without knowing as much about your app and its purpose as you do. Therefore, think ahead and include information on the context of each string in the strings.xml file. This is especially important for short texts used for buttons, for instance, where one word like “clear” in English could correspond to two completely different words in another language (“clear” as in “transparent,” or as in “delete”). Contextual information can even help you be more efficient in managing your text strings when you come back to them later after working on other projects.

Indicating Content That Is Not to Be Translated

Strings may also contain text that should not be translated, such as code, value placeholders, special symbols, or proper nouns. These texts must be indicated to translators, so that they are not changed. To do this, mark such text using an <xliff:g> tag, as the following example shows. Note the use of the id attribute to explain to readers the purpose of the placeholder and the example attribute to show how the string using the placeholder will be displayed.

Using Java and Formatters

If your app uses dates, times, numbers, currencies or other locale-dependent parameters, use the Android system to provide correct locale-specific formats. Like text strings, any attempts to hardcode the use of these entities will necessarily make an assumption about the locale, rapidly leading to problems when users change their Android devices to other locales. Even small flaws in versions for other locales can leave users with a poor impression of your app, depressing sales and adoption rates. For example, where the English format for numbers uses a period (.) as a decimal separator, French format uses a comma (,), but the difference is immediately obvious to native users when the wrong separator is displayed.

Android offers several utilities to help you format correctly across locales, such as:

DateUtils and DateFormat for dates.

String.format() or DecimalFormat for numbers and currency.

PhoneNumberUtils for phone numbers.

Android Assistance In Localizing Plurals

Locale-specific use of plurals can be complex too. Consider the basic rule in English, which is to use the singular with a quantity of one (“1 product”) and the plural with other quantities (“n products”, including “0 products”.) Other languages define more cases and have more rules. For example, Russian has specific plural formats for not just “one” and “other” as in English, but also for “few” and “many”, giving a total of four different formats. The full set of plural formats supported by Android is zero, one, two, few, many, and other. The Android method “getQuantityString()” cuts through the complexity to select the plural format to be used for a given language/locale and a given quantity.

Handling Screen Layouts

In general, the fewer layouts you have to handle, the better. A single, responsive design that adapts automatically to different devices makes life simpler. However, there may be cases where a user interface cannot properly display text for your Android app localization. A simple example would be a short label or menu item with the word “Now” in a default version using English, where the equivalent word in French would be “Maintenant” (more than three times as long.) One option is to create an alternative layout for that special case and store it in the location with the corresponding resource qualifier. On the other hand, this is an additional resource to manage, check, and update as appropriate for future versions of your app.

Other situations affecting screen layouts include forms for user input with a different number of name fields, depending on the user’s language. Instead of defining a completely new layout, one option might be to include a field to be displayed or not by the code, according to the language being used. Another could be to have the main layout include a secondary layout with the language-dependent field.

Keep Resource Files to a Reasonable Minimum

For reasons of effort required and manageability, it makes sense to minimize the amount of resource files being used. The condition is, of course, that this does not degrade the user experience. In the example above of the form for user input, it may not be necessary to create a completely new layout. In other cases, just one layout defined in the res/layout/main.xml file may suffice for any locale.

Similar remarks apply to text strings. While a user should always see a completely localized version, it is possible that some regional variations overlap to a great extent. For example, American and British English have some differences, but in many other cases, they are identical. An app could use American English as its default language, with American English vocabulary in the res/values/strings.xml file. For certain phrases for which British English vocabulary is important for British app users, a smaller file can be created (res/values-en-rGB/strings.xml), containing only those strings that differ. For any other strings, the application will default back to the res/values/strings.xml file and (identical) American English equivalents.

Getting Files Translated

You determine the quality of your strings.xml file, including its accuracy, its organization, and any necessary explanations for translators. Automated translation software is unlikely to give sufficiently good results, because your explanations cannot be understood (remember our example above about the different possibilities for translating the word “clear”.) However, for human translators, explanations can help avoid many queries or misunderstandings. It may be a good idea to add a terminology list to the translator’s package to explain specific terms or jargon used in your app so that translators do not have to guess.

App Store Keywords

Remember to have your app description translated for app stores like Google Play. On the other hand, keywords for helping users to find your app and for promoting its use or sales are another matter. Keywords are not only language dependent, but also market dependent. It may make more sense to work with an SEO professional for the country or the market concerned, who will find the most effective keywords in that context. These may be different from translated versions of the keywords used in the default language version (however good the translations are.)

Checking Translations

When the localized files are returned to you, check the translations to make sure that all relevant content has been translated, and that any other content (not to be translated) has been left intact. If the files pass this preliminary check, move the localized directories and files back into the resource structure for your app, using the right language and locale qualifiers to ensure proper loading afterward, according to the locale selected.

Now test your application for each locale to be supported, checking for the correct management of the following items among others:

Formatting of dynamic text, such as numbers and dates.

Handling of word breaks, punctuation, and alphabetical sorting.

Fallbacks to default resources.

Display in landscape and portrait modes.

Where possible, and highly recommended in any case, have a native speaker for the locale review the application thoroughly and give feedback.

Pseudolocalization as a Further Check

Use pseudolocalization to check layouts and displays, for example by generating a version of strings.xml with text for resources that is deliberately nonsensical and/or that is twice as long as the default text. These pseudolocalization techniques make it easier to see if any strings have been missed in the app localization (these are the strings that are still displayed normally.) They can also help to see if any localized texts are likely to run out of space in constrained areas like buttons, titles, and labels.

App Store Considerations

When all necessary checks have been successfully made, it is time to sign your app, make your final build, and then make your localized app available to users. In Google Play for instance:

Select the languages for your localized app.

Upload your .apk file.

Add translations for the Store Listing page and AdWords campaigns. If a user’s language preference matches a language you have selected, the user will then see the translated version of your app. Add localized versions of any promotional graphics and videos too. If necessary, you can create different versions for different locales, linking to the relevant localized video for each language supported by the app.

Afterward, Rinse and Repeat for New Localizations

The big benefit of correctly internationalizing an app is that each app localization is then relatively simple to do. You get the resource files translated for the new language or locale, check them, and include them in the app in an appropriately named folder (and update the app listing information in the app store.) Internationalization and localization techniques can also go further. One example is greater sophistication in the way Android selects the best resource folder for a locale that has not yet been handled as part of the app localization. Nonetheless, this guide already gives you the basic information you should know concerning internationalization and localization of Android apps. With the growing international market for Android solutions, we wish you success in satisfying users in the markets of your choice.