Home » Tutorials » ICanLocalize – Android Localization Tutorial

ICanLocalize – Android Localization Tutorial

In this tutorial we show how to write multilingual Android apps.

To build multilingual Android apps you need to collect the texts into resource files and translate them.

Once you provide the translation, Android OS will choose the resources that match user’s locale. If your application is available in several languages, Android will select the language that the device uses.

In this tutorial, we’ll cover:

  1. Application localization process
  2. Translating strings
  3. Localizing images
  4. Running and testing the localized application
  5. Localization checklist
  6. Sample multilingual Android app for download

Need Translation for Your Android App?

ICanLocalize provides professional translation for Android apps.

Upload your resource file and get a final quote, right now.

Android XML resource file:

From language:

To language:

1. Application Localization Process

Android loads text and media resources from the project’s ‘res’ directory. Additionally, Android can select and load resources from different directories, based on the current device configuration and locale.

For example, if the code loads a string called ‘R.string.title’, Android will choose the correct value for that string at runtime by loading the appropriate strings.xml file from a matching ‘res/values’ directory.

In order to have a multilingual Android app you need to provide Android with the localized resource files.

If the locale is ‘en-US’, Android will look for a value of “R.string.title” by searching the files in the following order:

  1. ‘res/values-en-rUS/strings.xml’
  2. ‘res/values-en/strings.xml’
  3. ‘res/values/strings.xml’

When it manages to find the string in the resource file, it uses that value and stops searching. This means that the default language acts as a fall-back option and when translation exists, it’s used instead. It also means that you should either localize everything or nothing, as seeing half translated applications is usually worse than apps that are not translated at all.

Let’s go over a sample application to better understand the localization process. This is a very simple single-language application which displays a country’s image and a text view according to the language set in the device. The structure of the project will be as shown in the figure 1.

Figure 1: Structure of the sample project

The application doesn’t check the user’s locale and always executes the same, for any locale setting. A screen-shot of the sample application is shown in figure 2. Note that the background image refers to an image of the United States and the text is in English (default locale setting).

Figure 2: Snapshot of the sample single-language application.

Our first step towards localizing this app is to plan the way an it should display differently for different locales. We’ll add locale-specific information for Italy, France, Canada, and Russia. Table 1 details the different display options for different locales.

Table 1: Display options for different locales

Table 2: Location of “strings.xml” and background images for different locales

Table 2 shows the paths to the different resource files and which ones are used for which locale.

As shown in Table 1, we’ll have six background images (5 locales specific and one default). We’ll also have three sets of string translations (Italian, Russian and French).

Translations go under folders named values-<language>.

The language part of the folder name contains the language ISO code and an optional region code, preceded by lowercase r.

For example:

  • Without region code: fr
  • With region code: fr-rFR or fr-rCA

The application selects the resource files to load at run-time, based on the phone’s locale. If no locale-specific resources are available, it falls back on the defaults. For example, if we’re in Switzerland, and the phone’s language is set to French, Android will first look for a folder called fr-rCH. If it can’t find it, it looks for fr and if that’s not found too, it loads the resource files for the default language.

It does that for each resource type, so we can have French strings with the default graphics, or any other combination of translated resources.

2. Translating Strings

The application requires four strings.xml files, one for each in English, Italian, French, and Russian.

The procedure for creating strings.xml files is as follows:

  1. Translate the strings.xml file to each language.
  2. Create three new folders under resvalues-it, values-fr and values-ru (The original values folder already exists).
  3. Place the translated strings.xml files in the respective folders.

For fast and efficient and affordable translation, you’re welcome to try our professional Android localization service. Our system parses your resource files, extracts all the texts and then builds the translated resource files, ready to be used in Android.

3. Localizing Images

Our application also needs six more drawable folders, each containing a variant of the background image.

Place background image that has to appear for a respective language in corresponding folders under the project workspace of the sample application as specified in Table 3.

If your images contain texts, we recommend creating copies of the texts in your strings.xml file. This way, translators can translate just the texts, and you can rebuild the localized images.

Background image Destination folder in project workspace
Italian drawable-it-rIT/background.png
French drawable-fr-rFR/background.png
French (Canada) drawable-fr-rCA/background.png
English (Canada) drawable-en-rCA/background.png
Russian drawable-ru-rRU/background.png
US English drawable-en-rUS/background.png
Default (Earth image) drawable/background.png

Table 3: Background image and the respective destination folders.

After you save the strings.xml and background image files in their target folders, the project workspace looks like this:

Figure 3: Structure of the sample multi-lingual Android app

4. Running and Testing the Localized Application

Once the localized string and image resources are added to the project workspace, the application is ready for testing. To test it, we can set different locales via Home > Menu > Settings > Locale & text > Select locale.

Depending on configuration of the device, some devices may offer only a few locales or may not offer any alternate locales via the settings application. However, the Android emulator will offer a selection of all the locales that are available in Android OS. To set the emulator to a locale that is not available in the system image, you can use Custom Locale, available in the Application tab.

Figure 4 shows some of the expected results that we should see after setting the region and language in the phone.

Italian

French (France)

French (Canada)

English (US)

Default locale

Figure 4: Expected results after localization.

5. Localization Checklist

Now that we understand how to use the Android development framework for multilingual apps, let’s go over a short checklist which reminds us the steps we need to take.

  1. Never hard-code strings or string constants; Instead use the R.string and strings.xml files.
  2. Similarly, don’t hard-code images or layouts; use R.drawable and R.layout
  3. Translate the strings.xml files and localize your images.
  4. Place your localized resources in the appropriate directories under ‘res/’.

Sample Multilingual Android App

Throughout this tutorial we’ve used a sample application, written especially to explain how to create multilingual Android apps.

Feel free to download it and experiment yourself:

ICL-LocalizationExample.zip (4MB)

Do you need help translating your Android app?

We offer efficient, accurate and timely translation for Android applications.

Expert translators, writing in their native languages will translate your application, helping you get more sales from around the world.

If you’re thinking about translating and republishing this tutorial, please contact us first. Tell us where you want to publish it and a few words about yourself.

12 responses to “ICanLocalize – Android Localization Tutorial”

  1. Bachi

    Thanks for the great tutorial. You might want to add that the Eclipse ADT tool offers a very useful helper function to externalize text strings to xml files: “Refactor > Android > Extract Android String”.

    - Bachi

  2. ICanLocalize Offers Translation Dashboard For iPhone & Android Apps cool | Mobile Stuff

    [...] VEGAS, NV – December 20, 2010 – Android Localization and the iPhone Applications Localization [...]

  3. Jason Kichline

    This is good information and all, but is it possible to create localized drawables in various DPIs? For instance, I need drawable-hdpi-fr which doesn’t seem possible.

  4. Ivan Milosavljević

    Thank you for excellent tutorial!!!

  5. venky

    great job thx for giving tutorial

  6. gg00xiv

    What is : Home > Menu > Settings > Locale & text > Select locale please ? There is not menu named “Home”, nether “Settings” in my Eclipse IDE…

    Thank you

  7. hukum

    @gg00xiv………Here author is talking about android home screen. for your ease go to your android phone home screen and then press menu button of your phone there you will find setting option press it then u will find language and input option click it and change your mobile language.

  8. PhilA

    @gg00xiv,
    I know it’s a few months later, but when referring to “Home > Menu > Settings”, it’s actually referring to the Android device or AVD… the option there is to change the language of Android to test it, not change it in Eclipse…

  9. Mahesh

    Thanks a lot for the tutorial. Even the official site confused me, you came to my rescue..

  10. DS

    Good post here.

    Now, how do I change my device’s *COUNTRY* setting to test localizations?

    In iOS for example, this is the “Region Format” setting, which is completely distinct from the “Language” setting.

    The use case is I have a product that is known by one brand in one English-speaking country and by another brand in another English-speaking country, so I show different logos to them and need to test that the code is behaving properly.

  11. NDK

    Thank you for the tutorial. You explained everything very clearly. However, I have I want to allow users to select the language when they enter the app using a Spinner. How can I set the language in the code without going to Settings -> Locale & Text?

    Thank you,

    1. Philip Arnold

      @NDK, this is actually quite simple:
      Locale locale = new Locale(“ar”);
      Locale.setDefault(locale);
      Configuration config = new Configuration();
      config.locale = locale;
      getBaseContext().getResources().updateConfiguration(config,
      getBaseContext().getResources().getDisplayMetrics());

      where “ar” is the relevant code for the locale, either short or long version

      The way I’d suggest doing it is to use the device default, unless it’s over-ridden by the language spinner

      Hope this helps,
      Phil

Leave a Reply