Document home

Android

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 layout, comments, images, audio and everything you put in the res directory. Soluling localization tool and service support Android.

The end of the document contains links to get the full source code of the samples.

Localization process

Android applications are written in Java and compiled to Android application package files (.apk). An .apk file contains both compiled code and resource data. When you write an Android application you place resource files into res directory in 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 application in three ways. First is to localize value resource files. This is called resource file localization. Second is to localize the application project. This is called project file localization. Third is to localize the application file. This is called application file localization.

Resource file localization

This localization method localizes the string resource files(s). String resource file is the most important resource type. It contains strings used by the application. The resource file exists on res\values directory. By default the file name is strings.xml but the name can be other and there may be more than one resource files. When Soluling localizes a resource file it read 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 the original resulting a multilingual Android application file.

Resource project If you want to use resource localization add a string resource file into Soluling project. Once Soluling has created the localized files recompile your application.

This method lets you to localize only resources that exist on the values directory. In addition this method produces only multilingual application. If you want to localize some other resources such as images or layouts, you have to use either project file or application file localization. If you want to create localized application that support only one language (for example to make application files smaller) you have to use the application localization.

Project file localization

This method is similar to 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), Eclipse project file (e.g. .project), or Xamarin project file (e.g. .csproj). Soluling scans all resources including strings, layout, menus, images, etc. When building Soluling creates localized versions of those resources.

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

This methods has several advantages over resource file localization. First of all it allows you to localize other resource types but strings. Second it requires only one file to be added into 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 some other development IDE but Android Studio or Eclipse you can not use project localization but you have to use either resource file or application file localization.

Application file localization

When Soluling localizes an Android application it reads the original application package file and creates localized versions of that file. Application package file contains all the resources that need to be localized. There are several resource types. Most important for localization are the string and layout resources. Layout resources contains the user interface design of the application. String resource contains strings are are used by the application. In addition of these two resource types application files contain also image resource and may also contain animation, XML or any custom resources. Soluling can localize them all.

Binary project If you want to use application localization add an Android application file into Soluling project. Once Soluling has created the localized application files they are ready to be deployed.

Comparing methods

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

Method Pros Cons
Resource
  • Simple to use
  • Only strings resources can be localized
  • You need to recompile and sign your application each time you build localized files
  • Cannot (easily) create localized single language applications
Project
  • Can localize all resources
  • You will get the localized resource source files
  • Can read comment values from string resources
  • You need to recompile and sign your application after each time you build localized files
  • Cannot (easily) create localized single language applications
Application
  • Can localize all resources
  • In addition of multilingual applications can also create localized single language applications
  • No recompilation need but you can deploy the localized .apk right away
  • You will not get the localized resource source files (e.g. res\values-*\strings.xml) but only localized or multilingual application files (.apk)
  • Cannot read comment values from string resources

In general if we recommend using the project localization unless you don't have full source code of the application when you have to use the application localization.

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 uses 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 contains one or more items. The following resource file, res\values\strings.xml, contains one string resource. The name of the resource is "hello" and value is "Hello World".

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

If you use Eclipse you don't have to edit XML manually but you can use Eclipses Android resource editor.

Layout resources

The user interface of 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="fill_parent" android:layout_height="fill_parent" >
  <TextView android:layout_width="fill_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 easy and strait forward way to enter the strings of the user interface. The strings are on the logical places and you can edit the strings and layout itself at the same time. Unfortunately Android documentation recommend you to use 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 the string in the layout file. The following code contains the modified sample.

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

<?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 contain 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 as 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 belong. If you use the approach recommend by Android SDK you not only make your life more difficulty you also make translation work more difficult by not providing 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 can not 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 form landscape layout. Using string links you only have to write the string once in the string file. Soluling on the other hand can localized all Android resources. 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 if you have only one version of the layout. You might have multiple versions one for portrait, one for table, etc. If this is the case it is better to store the string into the string resource and refer 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 layout file. However even portrait and landscape should have the same string it may be that there is some space issues in portrait and a shorter string or translation should be used. If you use reference there is no way the translator can use different translation on portrait. There are many other advantages storing strings inplace. Most obvious is that it is easier: you only have to enter and maintain string in the same location as the rest of UI design. Also using inplace strings makes your code much easier to read. This is way we recommend storing layout string inplace.

Other resources

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

Binary resources

The above resource files are all source resources files. The compiled Android application file does not contains the XML based source resource files but compiled binary resource files. The binary files are optimized for size and speed. When Soluling localizes an Android application file it reads and writes the binary resource data that are embedded inside the application file.

Localized application vs. Multilingual application

When you write an Android application you can include resources in several languages. If you do that the compiled Android application file contains resources in several languages. Such an application is multilingual. When the application starts Android OS checks if the application contains resource data for the default locale of the device. If the application contains resource in that locale they will be used instead of the neutral resources. The advantage of the multilingual application is that you only have one file to be deploy. All customers install the same file. The disadvantage of the multilingual application is larger file size compared to a monolingual application. If only strings and layout resources are localized then the size difference is minimal but if you start localizing image or other media files the multilingual files gets a lot bigger than the monolingual one. In such case it is better to create many monolingual applications each support one language (e.g. English version, German version, etc).

Most applications are monolingual by default and in almost every case the language of the strings and UI is English. If you select a monolingual file into a Soluling project you have two choices about the output files. Soluling can either create localized application files (one for each language) or one multilingual application file that contains resources in all languages you have added into the Soluling project. You can even make Soluling to create both output types. The following picture contains simplified structure of an original Android application file. It contains compiled Java code and resources. Some resources are language neutral and there is not need to localize them. Such resources may be the image and layout resources. Some resources contain English text and must be localized. Such resources are the string and layout resources. Some resources are language neutral and do not require localization. Such resources are for example most images.

Original application file

Let's suppose that you have added the above file into Soluling project and have added German and French as target languages. Now Soluling has two output options. One is to make multiple monolingual but localized application files. The following picture contains German and French application files created by Soluling. They both are similar to the original file except the English resource has been replaced with German or French.

German application file

French application file

The above solution works fine but requires to have multiple application files in Android Market. The user has to choose the right version. An easier solution would be one multilingual file. This also is possible. The second output options is to create a multilingual application file. It contains the same code and resources as the original file but it also contains German and French resources. Each resource data can have a language id. This makes it possible to include the same source more than once if each resource has different language id. The following picture contains such a file. Original neutral resource and English resource have no language id. German resource is the same as English resource but instead of having no language id it has German language id. French resource has French language id. Multilingual application file is easy to deploy because you only install one file to Android Market and all customer get the same file. When the application is run on Android having English as active language, the application will start in English. On German Android it will start in German and so on.

Multilingual application file

If your original application file is multilingual the process is the same except Soluling automatically imports the existing translations from the original application file. The output file is either localized files that contains resources in one language or one multilingual file that contains resources of the original languages plus those languages you have added into the Soluling project. If you start a new Android project from scratch we recommend that your original application would be monolingual. If you want to make it multilingual let Soluling to create the multilingual application file.

Plurals in Android

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

private void setMessageValue(int id, int count)
{
  TextView text = (TextView)findViewById(id);
  text.setText(res.getString(R.plurals.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 <data-dir>\Samples\Android\Plural sample to see how to use plural enabled messages.

Android language ids

Some Android devices used deprecated language id for certain languages. The following list contains those languages:

Language Current ISO 639-1 id Deprecated id
Hebrew he iw
Indonesian id in
Yiddish yi ji

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

Method Description
ISO 639-1 id The standard ISO 639-1 (Wikipedia) language id are used. This is the default method.
Android id Deprecated language ids are used.
Both ISO 639-1 and Android ids Both language ids are used. Soluling creates resource using both the current ISO and deprecated ids. This options makes you application to work on all devices.

Use Resource options sheet id Source dialog to configure language id settings.

Bi-directional languages on Android

Starting from Android 4.2 (Jelly Bean, API 17) the operating system has a full support for RTL languages. This includes both text rendering and right-to-left user interface layout. In order to use the automatic RTL support you have to target at least to API verison 17. Make sure your manifest file, AndroidManifest.xml, specifies at least SDk version 17.

<uses-sdk android:targetSdkVersion="17" />

You have to add the following attribute to the manifest file.

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

Once these are included and the running system is at least API 17, the user inferface will be automatically mirrored and bi-direcitonal text correctly rendered.

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

Comments in Android value files

There is no standard way to attach comment for string resource 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 value is "Hello World". In many case it would be good to have additional information for translator. Soluling lets you do that by using XML attributes or comments. If you use Android Studio you can just add comment attribute to the string element.

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

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

<!-- 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 of the comment value. These are called parameters. The syntax is

comment [MaxChars=characters][MaxPixels=pixels]
comment

Any comment that is passed to project as the row comment of this string.

characters

Maximum length of the translation in characters.

pixels

Maximum length of the translation is pixels.

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

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

Properties in the comment element can be at any order. The case of the property names are case insensitive. The following is the same as above.

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

See <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 OS will not install it. In order to sing an application you need to have a key. You can do your key yourself. There is no need to get it from a certified key provided. There are two kind of keys in Android. The first one is the debug key. This is a temporal key that works only on emulator. You can not deploy applications signed with debug key. The password of the debug key is always the same so there is no need to store password or ask password them. If you use Android Studio or Eclipse they automatically debug sign the application before installing in to the emulator.

Soluling can sign the application package files it creates. To do this you have to have Android SDK installed on your computer. Use the Signing sheet of the Android application source dialog to configure sign settings. If you use project or resource files localization there is no need to sign localized files because they are localized resource files, not application files.

Learn more about signing from Android documentation.

Testing localized Android application

Android applications run on Android OS. Windows can not directly run an Android application. Fortunately you can connect your Android device into your PC using USB cable or use the Android emulator that works on Windows. The emulator comes with Android SDK. If you are an Android developer you already have Android emulator installed on your machine. If you do not have you can download Android SDK from Android web page and install it. Once a device is connected or an emulator exists Soluling can use tem. When you click Run Original or Run Localized Soluling uses the device or starts the emulator (if not already running), uploads the application package file into the device or emulator, and finally starts the application. This lets you to test the localized application in a real environment.

No matter if you use a connected device or emulator you need to fist install Android SDK into your PC. Once installed Soluling will automatically detect it and use it. Use Options | Platforms | Android | General to configure SDK path.

If your output files are monolingual localized files they will always start in the language of the application. No configuration is needed in the emulator. However if you output file is multilingual there are several languages where to select from. The selection is done based on the active language of your emulator. To change the language:

  1. Start Settings from the main menu of Android.
  2. Click Language & keyboard
  3. Click Select language and in list that appears click the language that you want to select.

Start your application again. If the application supports the language you just selected then the application will appears in that language.

Android emulator is very very slow to start. It is recommended that you use a real device. If do not have a real device it is recommended that you do not close the emulator but keep it running all the time. This will improved the application load time. Well it will still be very slow but better than restarting emulator again every time you want to run your localized application.

Samples

<data-dir>\Samples\Android contains following Android samples:

Directory Description Notes
Driving A sample that shows how to localize an Android application. Try this first!
BiDi A sample that shows how to make a localize to bidirectional languages such as Arabic or Hebrew.  
Comments A sample that shows how to use comments in the string resources.  
Multilingual A sample that shows how to make a multilingual Android application.  
Plural A sample that shows how to use plural messages.  

All samples have been written in Android Studio. If you use Eclipse you have to create a new project and insert .java and resource files into the project.

Configuring Android localization

Soluling can localize Android application files (.apk), Android Studio projects (.iml), Eclipse projects (.project), Xamarin projects (.csproj) and Android strings resource files (.xml). Read the process page to figure out what is the right method for you.

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), Eclipse project file (e.g. D:\EclipseSample\.project), or Xamarin project file (e.g. D:\XamarinSample\XamarinSample.csproj) 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.

Configuring Android Application File Localization

You create a binary file localization project by adding the Android application file (e.g. D:\Sample\bin\Sample.apk) into your Soluling project. You can configure how to localize your Android application 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.

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.

Other documentation

Android SDK online documentation contains several useful topics: