1. Code
  2. Android SDK

Android SDK: Building a Localized Phrasebook

Read Time:12 minsLanguages:

In this tutorial, you will learn how to create and use alternative resource files with an Android application called One Minute Phrasebook. This application displays certain text and graphics based upon the Android system language/locale setting.

Before You Begin

The authors are assuming the reader has some basic knowledge of Android and has all of the necessary tools, such as Eclipse and the Android SDK, installed and working. The examples given here are engineered to show how Android project resources can be localized. Specifically, this tutorial will show you how to include resources for different languages and locales.

Note: The code for the OneMinutePhrasebook application is also available on Google Code.

Step 1: Create the OneMinutePhrasebook Application

Begin by creating a new Android project.

To do this within Eclipse, choose File->New Android Project to launch the Android project wizard.

Name the project: e.g. “Phrasebook”

Choose an appropriate Build Target, such as Android 2.1.

Name the application: e.g. “One Minute Phrasebook”

Name the package: e.g. com.mamlambo.article.phrasebook

Create a launch Activity: e.g. PhrasebookActivity

Creating the Android phrasebook project.Creating the Android phrasebook project.Creating the Android phrasebook project.

Step 2: Configure the Application for Debugging

You will be debugging this application, so you need to set the Debuggable attribute in the Android Manifest file to true.

Modifying the Android Manifest file.Modifying the Android Manifest file.Modifying the Android Manifest file.

Step 3: Create a Debug Configuration

You will want to be able to easily launch the application in the Android emulator and on the device from Eclipse, so you need to create a Debug Configuration.

To do this within Eclipse, choose Run->Debug Configurations....

Double click on the Android Project option.

Name your new configuration: “Phrasebook Test”

Select the project: Phrasebook

Selecting the android phrasebook project.Selecting the android phrasebook project.Selecting the android phrasebook project.

Step 4: Create Default String Resources

The One Minute Phrasebook displays the locale as well as several strings (“Hello”, “Goodbye”, “Please”, “Thank You” and “Help!”) on the screen. Therefore, you need to add a bunch of string resources to the /res/values/strings.xml file. Specifically, add one string for each phrase, as well as a label for each phrase. Also, add strings for the Flag (label), Map (label), and CIA World Factbook link (more on this in a moment).

For default strings, we use one of the most common languages understood around the world–English. (Certainly, you could choose another language for your default, if you like.)

The resulting strings.xml file should look something like this:

These are the default string resources that are used by this application. Many applications use only default resources.

Step 5: Create Other Resources

The One Minute Phrasebook application also requires several other types of resources. Specifically:

  • Some color resources for TextView text colors (/res/values/colors.xml)
  • Some dimension resources for TextView text size (/res/values/dimens.xml)
  • Two graphics files: one for the map and one for the flag (/res/drawable/flag.png and /res/drawable/map.png)

You can either add these resources now or as you build the layout. The flag and map images used in this tutorial were acquired from public domain images available on the CIA World Factbook website.

For the default cause, we will say the locale is “World-wide”, and display a graphic with a bunch of world maps, and a map of the planet.

Configuring Android ResourcesConfiguring Android ResourcesConfiguring Android Resources

Step 6: Design the One Minute Phrasebook User Interface

Next, turn your attention to designing the user interface of the application. The One Minute Phrasebook is a very simple application with just one screen. The screen displays some useful phrases, a flag and a map for the country, and a link to the CIA World Factbook website for the appropriate country.

Android Phrasebook Interface View.

Note: For this application, we use an Android Virtual Device (AVD) profile to closely match that of the Nexus One, with its 800x480 screen. Feel free to create an AVD to match whichever Android device you have on hand to test with.

Step 7: Implementing the User Interface

This application has just one screen, defined within the /res/layout/main.xml file. This is the file you need to edit.

In this case, we want nice, formatted columns, so consider using the TableLayout control to format the TextView and ImageView controls containing the phrase, flag, map and link to the CIA World Factbook.

The resulting main.xml layout file should look something like this:

Step 8: Running the Application

It’s time to run the application for the first time. To do so from Eclipse, choose Run->Debug Configurations. Select the Phrasebook Test configuration and click the Debug button.

Android Debugging Screen.Android Debugging Screen.Android Debugging Screen.

Step 9: Changing the Device or Emulator Locale

Now it’s time to explore the language settings of your emulator or device. To view and change the language/locale settings from the Home screen, click the Menu button and choose Settings->Language and Keyboard->Select Locale.

Try changing the locale to a foreign language you are familiar with.

Warning: Keep in mind that if you change the language and leave the Settings, you will need to be able to navigate back to the settings screen in that language. Memorizing, or writing down, the keystrokes to do this can simplify doing so.

Note how all the menus change to that language. Run the One Minute Phrasebook application in this locale. Note how the application does not appear any different than before you changed the locale—it still appears in English.

Now, change back to your favored locale. Mine is English (United States).

Android Phrasebook Locale Listing.

Note: The emulator has all locale options available in a given version of the Android SDK. However, specific devices may have a limited set of locales to choose from.

Step 10: Understanding How Android Manages Resources

Each time a screen is drawn within an Android application, the Android operating system attempts to match the best possible project resource for the job. In many cases, applications provide only one set of resources—the default resources.

When alternate resources are included with an application as part of their package, the Android operating system always attempts to load the most specific resources available.

Alternate resources can be created for many different criteria, including, but not limited to, languages and regions, screen characteristics and device input methods. Some common alternative resources are those for languages, locales and screen orientation (layouts especially). Criteria are organized hierarchically and each type of criteria can be used as a suffix on the appropriate project resource directory name.

Alternate resources must use the same names as the default resources. Android resource resolution is best shown by example. In this tutorial, we focus only on creating alternate resources for specific languages and regions.

Step 11: Create Alternate String Resources for the French-Speaking Countries

Now let’s say you want to add support for French-speaking regions. You can easily do this by adding alternate resource strings to the project. For example, you might leave the phrase labels in English, but translate the actual phrases into the French language.

You can add language resources to any project by creating specially named project directories. Simply take the existing project directory name (such as /res/values) and tack on a dash followed by the two letter language code, as defined in ISO 639-2. So, for example, English is en, French is fr, Spanish is es, German is de, etc.

You can add a single set of French translated strings in the /res/values-fr/strings.xml file. These strings will be loaded whenever a French-speaking locale setting is enabled. Any other locale settings will continue to use the default strings.

Each of the alternate resource strings must have the same name as the default resource used (stored in /res/values/strings.xml). The Android operating system will choose the most specific resource available at runtime. You do not need to provide translations for all strings, just the ones you want altered when a French-speaking locale setting is chosen.

The resulting /res/values-fr/strings.xml file should look something like this:

Note that you may need to quote resource strings if they contain single quotes themselves (such as “S'il vous plaît”).

Step 12: Create Alternate String Resources for Specific Countries

Now that you’ve determined the French string resources (the phrases) that can be shared across all French-speaking locales and regions, you want to create some alternate string resources for specific countries: Belguim, Canada, France and Switzerland.

Each country will need:

  • A locale region string
  • A CIA World Factbook URL string

The Android platform supports language-specific alternative resources (such as those created in the previous step). However, you cannot create region-specific resources without the language. Instead, you must include the language and the country code in the resource directory name.

To create resources specific to a region, you must use its language (in this case “fr”), followed by a dash, followed by its region code in the form “rXX” where XX is the region code for the country as defined by ISO 3166-1-alpha-2 code.

For example, the language and region codes for the French-speaking countries supported in Android would be:

Belgium: fr-rBE
Canada: fr-rCA
France: fr-rFR
Switzerland: fr-rCH

So, for example, you can create a strings.xml file in the /res/values-fr-rBE project directory for string values specifically for the French (Belgium) locale setting.

/res/values-fr-rBE/strings.xml might look like this:

Step 13: Create Alternate Drawable Resources for Specific Countries

Alternate resources can be created for other types of data besides strings. You can create alternate resources for any type of resource, including strings, dimensions, colors, drawable resources and other types. You simply use the same project resource directory hierarchy rules.

So to add flag and map drawable resources for each country (Belguim, Canada, France, and Switzerland), you need to create four new directories under the project:

  • Store the Belgian flag.png and map.png graphics in the /res/drawable-fr-rBE/ directory.
  • Store the Canadian flag.png and map.png graphics in the /res/drawable-fr-rCA/ directory.
  • Store the Swiss flag.png and map.png graphics in the /res/drawable-fr-rCH/ directory.
  • Store the French flag.png and map.png graphics in the /res/drawable-fr-rFR/ directory.

Note that the drawable file names must match the default drawable file names (those stored in /res/drawable) exactly.

Your project should now be organized like this:

Android Project organization listing.

Step 14: Re-running with a French-speaking Locale

In your emulator or on your device, change the Locale to one of the French options (Français (France), Français (Canada), Français (Belguim), Français (Switzerland).)

Note: For those not versed in French, you can return to the locale settings menu from the Home screen by choosing: Menu->Paramètres->Langue et clavier->Langue et région.

Re-run the One Minute Phrasebook application and view the results. Note how the appropriate French strings are loaded for all French languages. Also note how the specific region dictates which country information is displayed within the application.

The figure shows what happens when you choose Français (France).

Android French screen content.

Step 15: Where to Go From Here

Internationalization forces design choices on the development team. For example, will you build one big project for all languages, or will you break the applications up by region? For some projects with light internationalization, you may be able to get away with one project with all internationalized resources. For deep internationalization, you may need to reorganize projects so that no application becomes too large or cumbersome for the user.

You may have noted that in all this internationalization work, we never once touched the java source files of the project. This is important to note, because it means that the work of internationalizing an application may fall not to a developer who knows how to use Eclipse and the Android tools well, but to someone else who will need some training on how Android internationalization works, how resources can be layered, and the drawbacks of over-internationalizing (resulting in very large package files with many graphics and such). On the plus side, this leaves developers free to do what they do best: developing code.

Lastly, you likely noted that the Android internationalization structure isn’t perfect—especially for countries with multiple official (and unofficial) languages. It makes little sense to have to include the same graphics (flag and map) in both an en-rCA and fr-rCA directories for English and French speaking Canadians. However, you can work around these limitations by programmatically determining the locale and loading the appropriate graphic files yourself. That, however, is for another tutorial.

You can find a more complete explanation of Android resource resolution in the Android SDK documentation here.


In this tutorial, you learned how to create and use alternative resource files with an Android application called One Minute Phrasebook. This application displays certain strings and graphics based upon the Android system language/locale setting. You learned about how the Android operating system resolves resources and chooses the most appropriate resource available at runtime. You also learned how to organize resources efficiently in order to provide your worldwide users with the best possible application experience.

We hope you enjoyed this tutorial and look forward to your feedback!

About the Authors




Looking for something to help kick start your next project?