Localizing your resources

  • Written by  Clive

Keeping it local

Android localisation icon

Android apps can be installed on devices around the world. If you want to distribute your app to this large market, then you should provide alternative resources such as text, sound and images.

Android makes it easy to include alternative strings, sound files, layouts and images so that your app will work in any country and in any language.

Our tutorial app will show you how to include alternative text and image resources.

Providing different resources in your app

For a quick refresher on using resources in your apps, check out our tutorial, Using your application resources.

Your app uses resources such as strings, layouts, sound and images. If your app targets different countries and languages then you probably need to supply alternative resources for those languages and countries.

For example, if your app targets both English and German users, then you should provide text strings in both languages. You may also have to provide alternative image and sound resources.

The system will select the correct resources at run time, depending on the device’s locale setting.

You should always provide default resources

You should always provide default resources. These will be used if there are no alternatives.

Providing alternative resources

Create your app in the language of your choice. Make sure that you include all the necessary resources. These are your default resources.

If you’re going to market your app in other regions or languages then you need to include translations and alternative images, sounds, etc. that may be needed for your app to function correctly in those regions and languages. These are your alternative resources.

Put your alternative resources into a qualified resource folder. You don’t have to duplicate all your resources. Only those that are unique to the various locales that you are targeting.

Alternative qualified resource folders

Create alternative resource folders for each of your alternative languages and/or regions that you are targeting. Simply copy the existing default folders and append the suitable qualifiers to its name.

Put your alternative resources into these folders.

Here’s a list of qualifier names.

Here’s a list of the two character language code qualifiers, and here’s a list of two character region code’s that you should use.

You can have a number of qualifiers for a single resource folder. Just separate them with a dash (-) and make sure that they are in the order as laid out in the list of qualifier names.

At run time, the system selects the correct resource according to the order of precedence.

Alternative resource folders that you’re probably familiar with

  • drawable-mdpi
  • drawable-hdpi
  • drawable-xhdpi

You put your alternative image resources in these folders and the system chooses the correct one at run time.

You can also include other alternative resources by including an appropriately qualified resource folder, for example:

  • values-en-rGB – here we add the language qualifier, en, followed by the region qualifier, rGB. We can now include all our alternative values resources such as strings, styles and dimensions in this folder. These values resources will only be used when the device’s locale has been set to English (United Kingdom). You need only include the resources that are unique for this locale. The system will select the defaults for the rest

How does the system know which folder to use?

If there are a number of resource files matching a device’s configuration, then the system selects the resource according to a set of rules.

Locale takes precedence except for:

  • MCC – mobile country code
  • MNC – mobile network code

Have a look here to see how android finds the best matching resource.

We’ll show you how to provide alternative language text strings and alternative images in our tutorial app.

Our tutorial app

The tutorial app displays an image of a flag and a descriptive line of text below the flag.

Android localisation tutorial app screenshot

Here the device’s Language has been set to English (South Africa) and the appropriate flag and text string is displayed

Our tutorial app targets New Zealand.

We provide a default image of the New Zealand flag which we put in the default drawable folder. We also provide a default string for the text that appears below the flag. We place this default string in the default values folder.

We also expect to market our app in the United Kingdom, the Netherlands and South Africa. To make the app more user friendly in these regions, we provide alternative resources for these regions.

Here are the values resource folders:

Android localisation tutorial app values alternative Resources

Our alternative values resource folders containing only the alternative string resources

Note the following:

  • values – the default values resource folder. All our default strings are found here
  • values-en-rGB – the values resource folder for the English (United Kingdom) locale. It includes a language (en) and a region qualifier (rGB). We only put the alternative countryFlag text string in this folder. It will be used when the device’s locale is set to English (United Kingdom)
  • values-en-rZA – the values resource folder for English (South Africa) locale. It includes a language (en) and a region qualifier (rZA). We only put the alternative countryFlag text string in this folder. It will be used when the device’s local is set to English (South Africa)
  • values-nl – the values resource folder for the Dutch language. It includes a language qualifier (nl). We only put the alternative countryFlag text string in this folder. It will be used when the device’s local is set to Nederlands (either Belgie or Nederland). Note that there is no region qualifier

Here are the strings:

Android localisation tutorial app alternative Resources strings

The default string resources grouped at the top with the three alternative strings below. Note that the alternative string’s name is the same as the default’s name

Note the following:

  • The top four strings are the default strings and are in the default values folder. These will be used if the device’s locale is set to anything but:
    • English (South Africa)
    • English (United Kingdom)
    • Nederlands
  • The fifth string is in the values-en-rZA folder and will be used when the device’s locale is set to English (South Africa)
  • The sixth string is in the values-en-rGB folder and will be used when the device’s locale is set to English (United Kingdom)
  • The seventh string is in the values-nl folder and will be used when the device’s locale is set to Nederlands. Note that if the device’s locale is set to Nederlands (Belgie), the correct text string will be used because the values folder uses the language qualifier. However, the drawable folder includes a Nederlands region qualifier (rNL) so it’s drawable will not be used. In this case, the system falls back on the default drawable resource which is the New Zealand flag found in the default drawable folder

Here are the drawable resource folders:

Android localisation tutorial app alternative drawable Resources

Our alternative drawable resource folders containing the alternative flag images

Note the following:

We use the same name for the image file in all the drawable folders, namely flag.png.

  • drawable – the default drawable folder. It’s image, the New Zealand flag will be used for all locales except for:
    • South Africa
    • United Kingdom
    • Nederlands
  • drawable-en-rGB – the English (United Kingdom) locale drawable folder. It’s image, the British flag will be used when the device’s locale is set to English (United Kingdom)
  • drawable-en-rZA – the English (South Africa) locale drawable folder. It’s image, the South African flag will be used when the device’s locale is set to English (South Africa)
  • drawable-nl-rNL – the Nederlands (Nederland) locale drawable folder. It’s image, the Netherland’s flag will be used when the device’s locale is set to Nederlands (Nederland). This image will not be used if the locale is set to Nederlands (Belgie) because it does not match the Nederlands region qualifier (rNL). Instead, the default image will be used

Here are all the included resource folders:

Android localisation tutorial app Resources Folders

All our resource folders, including the alternative resource folders

Setting the locale

You can select your locale by opening up your device’s Settings. Choose Language & input, click on the Language setting and select your language from the drop-down list.

Android localisation tutorial app set device Locale

Select Language & input then click on Language and select your language from the pop-up list

Running the app displays the appropriate flag and accompanying text label.

Android localisation tutorial app screenshot flags

The different flags and text labels

We include a line of code in our activity which gets the current locale:

Android localisation tutorial app locale.getDisplayName()

Getting the current locale in code

We can then display the locale in a Toast message as well as in the LogCat:

Android localisation tutorial app locale.getDisplayName() logCat

The logCat showing the changes in the locale

I hope that you have found this tutorial helpful.

This project was created using Android Studio.

You can download the project files here Download icon

Are you using Eclipse or another IDE? Here's how you can use this project's Android Studio files.