Android Localization: Getting Started

When building apps, it’s important to think about your users. After all, they’re the ones who’ll be using your apps!

You should consider if your app would benefit from multi-lingual support to appeal to the widest range of users. You might also find that different images or layouts work better for different locales.

In this tutorial you’ll learn how to:

• Support multiple languages.
• Test your layouts for different languages, including Right-to-Left languages.
• Add resources for different locales.

Getting Started

Start by downloading the starter project using the Download Materials button at the top or bottom of this tutorial.

Open the project in Android Studio and get familiar with the files. Then build the project and run it on a device to see how the app looks.

The app is a simple avatar generator. The user can customize their avatar by selecting hair, clothes and shoe options from four Spinners. The Share button brings up a Share Sheet so the user can share a text description of their customized avatar through an app of their choice.

This starter project was built to appeal to an American audience. It displays options which make sense to those familiar with American English. There’s also a fun illustration which is very America-centric which displays the American flag.

In its current state, this app is fine for an American audience. But suppose you wanted to put this app in front of a British audience. The pants option takes on quite a more risque meaning!

You should add locale support for these users before making the app available to them. This tutorial will show you how to do that.

Localization

Before you dive in, keep the following things in mind. Your life will be much easier if you decide to localize later on.

This means all your strings are easy to find. You’ll see how that makes adding translations straightforward in a minute.

This file should be kept in the values directory in the resources section of your project. It’ll be your default strings file.

• Keep your strings in a strings.xml file: Instead of using hardcoded strings, which are added directly where needed in the code, define each string as a key value pair in a separate resource file called strings.xml. Here you assign an id to each string which can be referenced wherever you want to use that text in your project.
• Try to avoid images containing text: If you decide to localize, you’ll need to add a new image asset for each language, increasing the size of your APK. It’s better to keep all text as strings where possible.

Once you’ve developed your app with all your strings in the strings.xml file, adding localization support is quite straightforward. The Android system does much of work for you.

How the System Knows What to Display

When a user opens your app, the system uses the device locale to determine in which directory it can find the resources to display. Directories contain qualifiers in their names. The system uses these qualifiers to select the correct directory for each locale.

It’s important to provide a default resource file for each kind of resource, such as strings and drawables. If the system can’t find a directory to match the configuration of the device, then it’ll fall back to the default file. For example, if the user’s primary device locale is Spanish but there is no values-es directory present in the project, it’ll use the default.

If the system can’t find a default value to map a resource id to, then your app will crash. So, make sure to always define a default for all of your resources. The default file will live in a resource directory without any qualifiers in the name.

For each new language you wish to support, you’ll need to put a new strings.xml file containing your translations inside a new resource directory with a locale qualifier. The new file should contain translated strings paired with the same id used in the default file, as this id is the one which will be referred to in the code.

Don’t worry if this is a bit confusing at the moment. You’ll go through this step-by-step in the next section when you add British English translations to the sample app.

The following table, taken from the developer.android.com documentation, shows an example of the resolution strategy Android uses for versions greater than Android 7.

Here, the user has their device’s primary language set to fr_CH, but the app hasn’t explicitly supported this language. Failing to find an explicit match, the system looks for directories supporting other regions of the language. In this case, it found and displayed fr_FR.

If this directory hadn’t been present, it would’ve fallen back to the default. The default locale for Android devices is usually en-rUS.

For more explanation and examples of system resource resolution, consult the official Android documentation.

That seems like quite a lot to take in at once, but in practice it’s a fairly straightforward process. Time to get started localizing your app!

Adding Strings Files for Other Languages

In the sample project, open strings.xml. Most of the strings make sense on both sides of the pond. But, there are some which you should translate for a British audience:

<string name="top_sweater">Sweater</string>
<string name="bottom_pants">Pants</string>
<string name="shoes_sneakers">Sneakers</string>

Creating a New Resource Directory

Before moving on, make sure you have Android Studio set to the Project view, and not Android. This will let you see all directories as they appear on disk. That’ll come in handy when when you add new resource files later.

Create a new resource directory to store the GB translations. In Android Studio, navigate in the Project panel to the res folder. Right click on it, then choose New ▸ Android Resource Directory.

This opens the New Resource Directory window. From there, you can select the resource type and qualifiers you want to create. For localization of strings, add a new directory with a values resource type and a Locale qualifier.

Select Locale from the list of qualifiers and move it into the Chosen qualifiers section by pressing the >> button in the middle of the window. This will open new panels showing all the available options for your chosen qualifier. Select en: English as the language and GB: United Kingdom as the specific region.

Notice the directory name has been pre-filled with the resource type and qualifiers you selected. Don’t change the directory name because this format is required by the system to find your resources.

Press OK to confirm and close the window. You’ll see a new values directory appear in the Project panel named values-en-rGB. Put the strings file that contains all the translations for British users in this directory.