Soluling home   Document home

Android Localization and Internationalization

Android (Wikipedia) is a very popular platform for mobile phones and tablets. Soluling does not only let you localize the strings but also layouts, images, audio, and everything else you put in the res directory. Both Soluling Desktop and Soluling Cloud support Android.

• Localization process
• Plurals
• Language IDs
• Bidirectional languages
• Comments
• Signing applications
• Testing localized applications
• Samples
• Configuring Android localization
• Other documentation

The end of the document contains links to get the full source code of the samples. After reading this document, we recommend reading a tutorial about how to use Soluling.

Localization process

Android applications are written in Kotlin or Java and compiled to Android application package files (.apk) or Android App Bundles (.aab). An application contains both compiled code and resource data. When you write an Android application, you place resource files into the res directory of your project. The files are either XML based files that define actual resource items such as strings and layouts, media files such as images, or data files such as XML or JSON. Soluling can localize them all. Soluling lets you localize Android applications in two ways. The first is to localize value resource files. This is called resource file localization. The second is to localize the application project. This is called project file localization.

• Resource file localization
• Project file localization
• Comparing methods
• Multilingual application

Resource file localization

This localization method localizes the resource file(s). A resource file is the most important resource type. It can contain strings or other types such as colors and numbers used by the application. The resource file is in the res\values directory. By default, the file name for strings is strings.xml, but the name can be something else, and there may be more than one resource file. When Soluling localizes a resource file, it reads the original resource file (e.g., res\values\strings.xml) and creates localized versions of that file. For example, if you localize into German, Soluling will create res\values-de\strings.xml. Finally, when you rebuild your Android application, the localized resource files get compiled along with the original, resulting in a multilingual Android application.

This method lets you localize only resources that exist in the values directory. If you want to localize other resources, such as images or layouts, use project file localization.

You can localize a resource file either in Soluling Cloud or in Soluling Desktop. Project file localization needs Soluling Desktop.

Cloud process

With Soluling Cloud, you localize the resource file in your browser: upload the file, translate it in Translate, and download the localized files. You need a Soluling account. See the available Cloud plans.

Create a project

1. Sign in at www.soluling.com and open Cloud > Dashboard for Projects, Users and Terminology.
2. Click Add a new project, then Select files and pick res\values\strings.xml, or drag and drop the file onto the page. Click Create.
3. On the next page, check the project's Name. It defaults to the file's name.
4. Set the Original language to the language of your resource file, for example, English.
5. Under Target languages, check the languages you want to translate to, for example, Finnish, German, and Japanese.
6. Under Source type, select Android resource file (.xml). An Android resource file is also a valid XML file, so make sure you pick the Android parser: it understands string arrays, plurals, and the translatable attribute.
7. Click Create. The project appears on the dashboard, and its status changes to Ready once the file has been processed.

Translate the project

Click the project's green Translate button on the dashboard. Translate opens the project, and you can type the translations into the grid. Machine translation suggestions, translation memory, and spell checking are available there. You do not have to finish every language before moving on to the next step.

Get the localized files

1. In Translate's top bar, click the project's name. It opens the project's Manage page, the same page that the project's Manage button on the dashboard opens.
2. If you have translated something since the localized files were last built, the page says Localized files need to be built. Click Build localized files and wait until it finishes.
3. The Files section lists strings.xml with a download button for each target language. Save each localized file to the values directory of its language, for example, the German file to res\values-de\strings.xml. See Android language IDs.

Finally, rebuild your application. The localized resource files get compiled along with the original, resulting in a multilingual application.

Update the project

When you add or change strings in your application, upload the new strings.xml, translate what is new or changed, and download the localized files again. On the dashboard, click the project's Update file button (the upload arrow), select the new strings.xml or drop it onto the page, and click Update. Existing translations are kept, so you only translate the strings that were added or changed.

The dashboard is one of four ways to use Soluling Cloud. You can also use the SoluCLI command-line tool, Soluling Desktop, or SoluMake, which can run the update and build steps in your build pipeline. See the Cloud tutorial for all of them.

Desktop process

In resource file localization, the Soluling project contains a string resource file.

1. Start Soluling.
2. Drag res\values\strings.xml on Soluling or click the New from File or Files button and select the file.
3. If Soluling asks what kind of file it is, select Android resource file and click OK.
4. Project Wizard appears. Select the original language and the target languages, for example, Finnish, German, and Japanese, and complete the wizard.
5. The new project gets created. Translate the project and finally build the project by choosing Home | Build All ribbon menu. Soluling creates the localized resource files into the language specific values directories, for example, res\values-de\strings.xml.
6. Rebuild your application.

Project file localization

This method is like resource file localization, but instead of selecting a single resource file (e.g., res\values\strings.xml) you select your Android Studio project file (e.g., Sample.iml). Soluling scans all resources, including strings, layouts, menus, images, etc. When building, Soluling creates localized versions of those resources.

If you want to use project localization, add an Android project file into the Soluling project. Once Soluling has created the localized files, recompile your application.

This method has several advantages over resource file localization. First of all, it allows you to localize other resource types than strings. Second, it requires only one file to be added to the Soluling project file. If you later add new resource files into your Android project, you do not have to add those files into your Soluling project file.

If you use an IDE other than Android Studio, you cannot use project localization. Use resource file localization instead.

Comparing methods

The following table shows some pros and cons of each localization method:

Use resource file localization if you only need to localize strings or want to use Soluling Cloud. Use project file localization if you also need to localize layouts, images, or other resources.

Resource types

Android applications can use several resource types.

String resources

The value resource is the most important Android resource type. It contains one or more string values. A value is most often a string but can also be a number, color, or boolean value. Your code or layout files use those values. If all strings of the application (from code and from layout files) are added into string resources, all you need to do to localize is to translate the string resources.

The string resource source files are XML files that contain one or more items. The following resource file, res\values\strings.xml, contains one string resource. The name of the resource is "hello", and the value is "Hello World".

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="hello">Hello World</string>
</resources>

In addition to plain strings, the string resource can also contain string arrays and plural patterns. Soluling localizes them too.

You don't have to edit the XML manually, but you can use the Translations Editor of Android Studio.

Layout resources

The user interface of the Android application is defined by writing layout files. These files contain the user interface layout, components, and properties. Here is a simple layout file:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:orientation="vertical" android:layout_width="match_parent" android:layout_height="match_parent" >
  <TextView android:layout_width="match_parent" android:layout_height="wrap_content" android:text="Hello World" />
</LinearLayout>

The file contains one text property that has "Hello World" as a value. The above way is an easy and straightforward way to enter the strings of the user interface. The strings are in logical places, and you can edit the strings and the layout itself at the same time. Unfortunately, Android documentation recommends a much harder way. Instead of writing the string into the layout file, the documentation tells you to add the string into a string resource file (strings.xml) and then refer to the string in the layout file. The following code contains the modified sample. First the layout file:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:orientation="vertical" android:layout_width="match_parent" android:layout_height="match_parent" >
  <TextView android:layout_width="match_parent" android:layout_height="wrap_content" android:text="@string/hello" />
</LinearLayout>

Then the string resource file:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="hello">Hello World</string>
</resources>

As you can see, the actual string is not in the layout file but in a separate string file. The layout file contains a link to the string file. What makes this more difficult to use is that you have to edit two files simultaneously. This is more difficult than editing only the layout file. If you look at the string file, you see that there is no real context of the string. There is only the name of the string. In user interface localization, it is very important to see the context where the string belongs. If you use the approach recommended by Android SDK, you make your life more difficult and make translation work more difficult by not providing the proper context for the translator.

So why does Android documentation recommend a method that is obviously worse? The reason is that the localization support provided by Android SDK is very limited. The tool can only localize string resources. It cannot localize other resources, such as layout resources. Another reason is that an Android application may contain multiple versions of the same layout. For example, one for portrait layout and another for landscape layout. Using string links, you only have to write the string once in the string file. Soluling, on the other hand, can localize all Android resources when you use project file localization. This is why you don't have to use this complex double resourcing method, but you can hard code strings into layout files.

Which method should I use? This depends on whether you have only one version of the layout. You might have multiple versions, one for portrait, one for tablet, etc. If this is the case, it is better to store the string into the string resource and refer to it from the layout files. However, if you have only one version of each layout file, then it may be better to store the string into a layout file. However, even if portrait and landscape should have the same string, there may be some space issues in portrait, and a shorter string or translation should be used. If you use a reference, there is no way the translator can use a different translation on a portrait layout. There are many other advantages to storing strings in place. The most obvious is that it is easier: you only have to enter and maintain strings in the same location as the rest of the UI design. Also, using in place strings makes your code much easier to read. This is why we recommend storing layout strings in place.

Other resources

In addition to these two resource types, an application also contains image resources and may also contain animation, XML, JSON, or any custom resources. Soluling can localize them all.

Multilingual application

Both localization methods create localized resource files that you compile into your application. The result is a multilingual application that contains resources in several languages. When the application starts, Android checks if the application contains resources for the device's language. If it does, they are used instead of the default resources. The advantage of a multilingual application is that you have only one file to deploy, and all customers install the same file. If you publish your application on Google Play as an Android App Bundle (.aab), Google Play installs only the languages that the device uses, so localizing does not make the download much bigger.

Plurals in Android

Android has a plural enabled format function. Use the Resources.getQuantityString function instead of Resources.getString whenever one parameter of the message is a numerical quantity. For example, if you have something like this

private void setMessageValue(int id, int count)
{
  TextView text = (TextView)findViewById(id);
  text.setText(res.getString(R.string.message, count));
}

change the above code to this

private void setMessageValue(int id, int count)
{
  TextView text = (TextView)findViewById(id);
  text.setText(res.getQuantityString(R.plurals.message, count, count));
}

See GitHub or <data-dir>\Samples\Android\Plural sample to see how to use plural enabled messages.

Android language IDs

Some Android devices use deprecated language IDs for certain languages. The following list contains those languages:

If you use the current ISO 639-1 ID, some Android devices just don't load the localized resources. To make your application work on those devices, you must use the deprecated IDs. However, if you use the deprecated IDs, it may be that some devices do not load the resources. To solve this, Soluling has an option to choose what ID (current or deprecated or both) to use. The methods are:

Use the Resource options sheet in the Source dialog to configure language ID settings.

Bidirectional languages on Android

Starting from Android 4.2 (Jelly Bean, API 17), the operating system has full support for RTL languages. This includes both text rendering and right-to-left user interface layout. To use the automatic RTL support, add the following attribute to the application element of the manifest file, AndroidManifest.xml.

<application
  ...
  android:supportsRtl="true"
  ...>

Once this is included and the device runs at least API 17, the user interface will be automatically mirrored and bidirectional text correctly rendered. Use start and end instead of left and right in your layout attributes (for example, android:layout_marginStart) so that the layouts mirror correctly.

See <data-dir>\Samples\Android\Old\BiDi sample to see how to add RTL support.

Comments in Android value files

There is no standard way to attach comments for string resources in Android. The string resources are flat XML files that contain name and value:

<string name="hello">Hello World</string>

The name of the above string is "hello", and the value is "Hello World". In many cases, it would be good to have additional information for a translator. Soluling lets you do that by using XML attributes or comments. If you use Android Studio, you can just add a comment attribute to the string element.

<string name="hello" comment="This is a comment">Hello World</string>

If you use Eclipse, you cannot use this because next time you use Eclipse's Android string resource editor, the comment attribute will be removed. When you use Eclipse, you have to use XML comments. Here is the same resource item with XML comments.

<!-- This is a comment -->
<string name="hello">Hello World</string>

The comment element must be right before the value element.

The comment attribute or element can contain some other information in addition to the comment value. These are called parameters. The syntax is

comment [MaxChars=characters][MaxPixels=pixels]

The following sample contains a "Number one" comment and a maximum character length of 20.

<string name="one" comment="Number one MaxChars=20" >One</string>

Parameters in the comment can be in any order. Parameter names are case insensitive. The following is the same as above.

<!-- MaxChars=20 Number one -->
<string name="one">One</string>

See GitHub or <data-dir>\Samples\Android\Comments sample to see how to use comments.

Android signing

All Android applications must be signed. If an application is not signed, Android will not install it. To sign an application, you need a key. You can create the key yourself. There is no need to get it from a certified key provider. There are two kinds of keys in Android. The first one is the debug key. Android Studio automatically signs debug builds with it, so you can run them on a device or emulator, but you cannot publish an application signed with a debug key. The second one is the release key that you use to sign the application you publish.

Both resource and project file localization create localized resource files, not application files, so Soluling does not sign anything. Sign your application when you build it, as you would sign it without localization.

Learn more about signing from Android documentation.

Testing localized Android application

Test the localized application as you test any Android application: run it from Android Studio on a device that is connected to your PC with a USB cable, or on the Android emulator that comes with Android Studio.

A multilingual application starts in the language of the device. To change the language of the device or emulator:

1. Open Settings.
2. Choose System > Languages (on some devices System > Languages & input > Languages).
3. Add the language you want to test and move it to the top of the list.

Start your application again. If the application supports the language you just selected, the application will appear in that language. On Android 13 and later, you can also change the language of a single application in Settings > System > Languages > App languages, if the application declares its supported languages.

Samples

GitHub and <data-dir>\Samples\Android contain the following Android samples:

All samples have been written in Android Studio. The Old directory contains older samples, for example, BiDi that shows how to localize to bidirectional languages such as Arabic or Hebrew.

Configuring Android localization

Soluling can localize Android projects (.iml, .csproj, and .project) and Android string resource files (.xml). Read Localization process to figure out what is the right method for you.

Configuring Android Resource File Localization

You create a resource file localization project by adding the Android string resource file (e.g., D:\Sample\res\values\strings.xml) into your Soluling project. You can configure how to localize your Android string resource file by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.

• File
• Data types
• Output
• Resource options

Configuring Android Project File Localization

You create a project file localization project by adding the Android Studio project file (e.g., D:\StudioSample\Sample.iml), Xamarin project file (e.g., D:\XamarinSample\XamarinSample.csproj), or Eclipse project file (e.g., D:\EclipseSample\.project) into your Soluling project. You can configure how to localize your Android project file by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.

• File
• Resources
• Data types
• Android rules
• Resource options

Other documentation

Android online documentation contains several useful topics:

• Providing resources
• Localize your app
• Resource types