|
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. After reading this document, we recommend reading a tutorial about how to use Soluling.
Android applications are written in Java and compiled to Android application package files (.apk). A .apk file contains both compiled code and resource data. When you write an Android application, you place resource files into the 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 applications in three 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. The third is to localize the application file. This is called application file localization.
This localization method localizes the resource files(s). A resource file is the most important resource type. It can contain strings or other types such as color and numbers used by the application. The resource file exists on the res\values directory. By default, the file name for strings is strings.xml, but the name can be other, and there may be more than one resource file. 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 in a multilingual Android application file.
 |
If you want to use resource localization, add a string resource file into the Soluling project. Once Soluling has created the localized files, recompile your application. |
This method lets you localize only resources that exist in the values directory. In addition, this method produces only a 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 a localized application that supports only one language (for example, making application files smaller), you have to use the application 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), 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.
 |
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 but 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 some other development IDE but Android Studio, Eclipse or Visual Studio, you can not use project localization, but you have to use either resource file or application file localization.
This method localizes the compiled application package file, .apk. When Soluling localizes an Android application file, it reads the original application package file and creates localized versions of that file. The 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 contain the user interface design of the application. The string resource contains strings thate are used by the application. In addition to these two resource types, application files also contain image resources and may also contain animation, XML, or any custom resources. Soluling can localize them all.
 |
If you want to use application localization, add an Android application file into the Soluling project. Once Soluling has created the localized application files, they are ready to be deployed. |
The following table shows some pros and cons of each localization methods:
| Method | Pros | Cons |
|---|---|---|
| Resource |
|
|
| Project |
|
|
| Application |
|
|
In general, if we recommend using the resource or project localization unless you don't have the full source code of the application when you have to use the application localization.
Android applications can use several resource types.
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 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 value is "Hello World".
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="hello">Hello World</string>
</resources>
In addition of the plain strings, the string resource can also contain string arrays and plural patterns. Soluling localizes them too.
If you use Android Studio or Eclipse, you don't have to edit XML manually, but you can use Android Studio/Eclipses Android resource editor.
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="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 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 layout itself at the same time. Unfortunately, Android documentation recommends you to use 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.
<?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 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 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 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. 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 tablet, 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 a 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 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 string in place.
In addition to these two resource types, an application file also contains image resources and may also contain animation, XML, JSON, or any custom resources. Soluling can localize them all.
The above resource files are all source resource files. The compiled Android application file does not contain 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.
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 device's default locale. If the application contains resources 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 deployed. All customers install the same file. The disadvantage of the multilingual application is the larger file size compared to a monolingual application. Suppose only strings and layout resources are localized. In that case, 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 a 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 create both output types. The following picture contains a simplified structure of an original Android application file. It contains compiled Java code and resources. Some resources are language-neutral, and there is no need to localize them. Such resources may be the image and some 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.
Let's suppose that you have added the above file into a 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.
The above solution works fine but requires to have multiple application files in the 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 option 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 a 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. The multilingual application file is easy to deploy because you only install one file to the Android Market, and all customers get the same file. When the application is run on an Android device having English as an active language, the application will start in English. On German Android, it will start in German and so on.
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 contain 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 create the multilingual application file.
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 something 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.
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 is 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 resources using both the current ISO and deprecated ids. This option makes your application to work on all devices. |
Use Resource options sheet id Source dialog to configure language id settings.
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. In order to use the automatic RTL support, you have to target at least API version 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 interface will be automatically mirrored and bi-directional text correctly rendered.
See <data-dir>\Samples\Android\BiDi sample to see how to add RTL support.
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 can not use this because next time you use Eclipse's Android string resource editor, the comment attribute will be removed. When you 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]
| comment | Any comment that is passed to the project as the row comment of this string. |
| characters | The maximum length of the translation in characters. |
| pixels | The maximum length of the translation is 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>
Properties in the comment element can be in any order. The case of the property names is 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.
All Android applications must be signed. If an application is not signed, Android OS will not install it. In order to sign 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 kinds of keys in Android. The first one is the debug key. This is a temporal key that works only on the emulator. You can not deploy applications signed with a debug key. The password of the debug key is always the same, so there is no need to store passwords or ask for a password for them. If you use Android Studio or Eclipse, they automatically debug sign the application before installing it on the emulator.
Soluling can sign the application package files it creates. To do this, you have to have the 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 file 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.
Android applications run on Android OS. Windows can not directly run an Android application. Fortunately, you can connect your Android device to your PC using a USB cable or use the Android emulator that works on Windows. The emulator comes with the Android SDK. If you are an Android developer, you already have an Android emulator installed on your machine. If you do not have one, you can download the Android SDK from the Android web page and install it. Once a device is connected or an emulator exists, Soluling can use them. When you click Run Original or Run Localized menu, 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 test the localized application in a real environment.
No matter if you use a connected device or emulator, you need to first install Android SDK into your PC. Once installed, Soluling will automatically detect it and use it. Use Options | Platforms | Android | General to configure the 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 your output file is multilingual, there are several languages where to select from. The selection is made based on the active language of your emulator. To change the language:
Start your application again. If the application supports the language you just selected, then the application will appear in that language.
Android emulator is very, very slow to start. It is recommended that you use a real device. If you 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 improve the application load time. Well, it will still be very slow, but better than restarting the emulator again every time you want to run your localized application.
<data-dir>\Samples\Android contains the 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.
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.
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.
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.
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.
Android SDK online documentation contains several useful topics:
Copyright © 2010-2024 Soluling