Skip to content →

Android app localization tutorial

Introduction

You may be writing your first Android app or you may already have a few. Why are you writing them? Hopefully, you want your apps to grow and be used worldwide. But most of the world does not speak English. Sooner or later, you will need to support multiple languages.

Here is how to set up an Android app that can support any language, from scratch.

Prepare your application

Create a simple Android project from a template in Android Studio. It should look like this:

Note: We removed some stuff that we don’t need for now.

The”activity_main.xml” is where you put your text. For now, let’s put a simple “TextView” with a string “Hello world” in it:

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    android:padding="10dp"
    android:gravity="center_horizontal"
    tools:context="co.lokalise.localizationtutorial.MainActivity">

    <TextView
        android:id="@+id/test_text_view"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Hello world!"
        android:textSize="26dp" />
</LinearLayout>

Now run our application. It should look like this:

There’s a problem here. The string “Hello world!” is hard-coded in. You do not want “Hello world!” to be embedded into the source code. You want the text to change if your user changes to another language.

To localize your text, use Android Resource system. Open the “res/values” folder. Inside, look for the “strings.xml” file. We will save your default strings here:

<!-- English strings -->
<resources>
    <string name="app_name">Localization Tutorial</string>
    <string name="my_string_name">Hello world!</string>
</resources>

We named our sample text string resource (key) “my_string_name”. This is how we will refer to “Hello world!” string in the future. Make sure you come up with descriptive names for your keys, so you don’t forget what they denote, e.g. “settings_language_title”, “settings_language_description” etc.

Once you have your key, reference it in your layout:

...
<TextView
    android:id="@+id/test_text_view"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/my_string_name"
    android:textSize="26dp" />
...

If you need to dynamically change a string in a TextView, you can do it programmatically within our MainActivity.class:

package co.lokalise.localizationtutorial;

import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.widget.TextView;

public class MainActivity extends AppCompatActivity {

    private TextView mMyTextView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        mMyTextView = (TextView) findViewById(R.id.test_text_view);
        mMyTextView.setText(R.string.my_string_name);
    }
}

Now our app looks like this:

Yes, it looks the same. But it’s not. Now you can add versions of your string in different languages.

Add more languages

Let’s create a new resource folder for Russian language using Android Studio’s resource file wizard. Right click on the “res” folder and choose “New -> Android resource file”:

The wizard will let you choose from a list of available Resource qualifiers for your new folder. Qualifiers are used by the system to decide which resources to load based on the user’s device configuration such as selected language, screen size, country code etc. You can read more about Providing Resources here. Keep in mind that these qualifiers can be used for other types of resources as well such as images or layouts for example.

Select “Locale” from the list and add it to the chosen qualifiers:

You can now choose the language you want. We want “ru: Russian”, “Any Region”.

Click the OK button. A folder named “values-ru” should now be available to you.

Create a strings.xml file in “values-ru” folder. Your directory structure should now look like this:

Now let’s open our Russian strings.xml and add some translations:

<!-- Russian strings -->
<resources>
    <string name="app_name">Туториал по локализации</string>
    <string name="my_string_name">Привет мир!</string>
</resources>

Wait! We’re not done yet:

Change application Locale programmatically

By default, Android will try to load resources depending on the System language that is set on your user’s phone. So if your user wants to use the Russian version on a phone that is set to English, he will not be able to. If there are no resources available for current device configuration, Android will fall back to the default resources in your “values” folder without qualifiers.

There is a workaround. Here’s how to set the Locale of your application to override the Locale set in user’s system:

  1. Right-click on the directory with your sources.
  2. Select “New -> Java Class”. Let’s call it “MyApplication”.
  3. Add these contents:
package co.lokalise.localizationtutorial;

import android.app.Application;
import android.content.res.Configuration;

import java.util.Locale;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        // Create a new Locale object
        Locale locale = new Locale("ru");
        Locale.setDefault(locale);

        // Create a new configuration object
        Configuration config = new Configuration();
        // Set the locale of the new configuration
        config.locale = locale;

        // Update the configuration of the Accplication context
        getResources().updateConfiguration(
            config, 
            getResources().getDisplayMetrics()
        );
    }
}

4. Now reference your Application class in the AndroidManifest.xml. See the “android:name” attribute within the “application” element? You also have “app_name” string resource used as a label. Your user will see whatever is written here as your app’s name on his phone:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="co.lokalise.localizationtutorial">

    <application
        android:name=".MyApplication"
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

Now, your app will be displayed in Russian, even if your phone’s System language is set to English:

How to set plurals in Android app texts

Sometimes you need your text to change when it appears next to different numbers. You don’t want your game to say “you have 3 cat” instead of “3 cats”. Use Android’s pluralisation support for this:

  1.  Add two more TextViews to your “activity_main.xml”:
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    android:padding="10dp"
    android:gravity="center_horizontal"
    tools:context="co.lokalise.localizationtutorial.MainActivity">

    <TextView
        android:id="@+id/test_text_view"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/my_string_name"
        android:textSize="26dp" />

    <TextView
        android:id="@+id/plural_view_1"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:textSize="26dp" />
    <TextView
        android:id="@+id/plural_view_2"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:textSize="26dp" />
</LinearLayout>

2. Do not specify the “android:text” attribute. Plurals can only be set programmatically anyway.

3. Now create your plurals for both languages:

<!-- English strings -->
<resources>
    <string name="app_name">Localization Tutorial</string>
    <string name="my_string_name">Hello world!</string>

    <plurals name="my_cats">
        <item quantity="one">I have %s cat</item>
        <item quantity="other">I have %s cats</item>
    </plurals>
</resources>
<!-- Russian strings -->
<resources>
    <string name="app_name">Туториал по локализации</string>
    <string name="my_string_name">Привет мир!</string>

    <plurals name="my_cats">
        <item quantity="one">У меня %s кот</item>
        <item quantity="few">У меня %s кота</item>
        <item quantity="many">У меня %s котов</item>
    </plurals>
</resources>

As you see, different languages have a different number of plural forms. English only has two, Russian has three, Arabic goes up to six!  Android supports all of them – zero, one, two, few, many and other.

Read more about plural rules for different languages here and more about plurals in Android here.

4. Now modify your MainActivity class to include the plurals:

package co.lokalise.localizationtutorial;

import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.widget.TextView;

public class MainActivity extends AppCompatActivity {

    private TextView mMyTextView;
    private TextView mPluralView1;
    private TextView mPluralView2;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        mMyTextView = (TextView) findViewById(R.id.test_text_view);
        mMyTextView.setText(R.string.my_string_name);

        Resources res = getResources();
        mPluralView1 = (TextView) findViewById(R.id.plural_view_1);
        String p1 = res.getQuantityString(R.plurals.my_cats, 1, 1);
        mPluralView1.setText(p1);

        mPluralView2 = (TextView) findViewById(R.id.plural_view_2);
        String p2 = res.getQuantityString(R.plurals.my_cats, 5, 5);
        mPluralView2.setText(p2);
    }
}

Look at the highlighted lines above. Numbers 1 and 5 are repeated twice for a reason. The first number is only used to calculate the required plural form. The second number is used for display purposes: it replaces the “%s” in our display text.

The result should look like this:

How to manage many text strings in different languages in Android

Easy to manage a couple of strings in two languages? Sure. But as you add more features and expand to more markets, your app will grow to thousands of strings in a dozen of languages. Here’s how to automate your text string localization:

Create an account or login to Lokalise. Then, create your localization project:

Upload your translation files. Yes, the ones you created at the beginning of this tutorial.

1. Click the “Upload files” button.

2. Drag and drop string.xml files to upload:

Once your files are in Lokalise, they will look like this:

Lokalise editor is the most feature-rich and includes cross-platform keys, multi-lingual view, cross-key referencing, proofreading, automatic translation suggestions, translation memory and much more.

How to edit your translations

  1. Edit any other text that you need to change. Let’s say you are a dog person. Click on the “cat” and replace it with “dog” in the popup.
  2. Then click the “Download” button to download your new translations:

  1. Choose the “Android Resources” file format from the list;
  2. Press the “Build and download” button to obtain the .zip archive with your new translations;
  3. Replace the old files in your project with the new ones.

 

Lokalise automatically generates the requested translation files with all your project languages for the specified platform. 

The next step in your Android localization is to integrate the Lokalise Android SDK with your apps. It provides for instant updates of text strings without submitting new app versions to the Google Play.

Was this tutorial helpful? If you still have questions about localization on Android, talk to us in the live support chat. Otherwise just sign up or sign in to start localizing your app!