Multilingual Application Development

Developing a multilingual application is rather simple with Symbian OS and this tutorial will show you to achieve this. Of course, it is always tempting to hardcode your strings. But with only a little effort you can have your application working in English and your native language - sorry for the Brits which do not need this ;-). A couple of web friends will probably help you adding extra translations in a second step.

Introduction

In our example, let's consider we will write an application that supports three languages:
  English
  French
  German

The application is amazingly called MyApp. It might be running on any GUI environment, a few figures here and there are specific to UIQ but are not directly related to our discussion.

This tutorial mostly introduce the changes you have to make to this application to turn it into a true multilingual one. There are 5 steps:
  identify all your strings and put them into specific language file
  update your resources
  update your source code so that it handle variable strings instead of hardcoded ones
  update your MMP file to tell the resource compiler which language are supported
  localize the name of the application
  package the whole.

Step 1: Put your strings in a localisation file

The first step is to create three localised files, named MyApp.l01, MyApp.l02 and MyApp.l03, which will respectively describe my english, french and german strings. The 01, 02 and 03 figures are Symbian OS convention to identify a language. All the possible values are defined by the TLanguage enum found in e32std.h:

Then create a localisation file that will gather the three files above:

The purpose of this .loc file is only to ease the inclusion of the proper language file in your .rss, so it is a pure convention to use and define it.

As far as I am concerned, I generally put all these files with my RSS file, in a dedicated directory called rsc. This is definitely not a mandatory requirement. Just think that these files are included so their path should be accessible from the MMP file. But this is another story we will discuss in step 4.

Step 2: Use localised strings in your menus and dialogs

Now that we have our localised strings, let's integrate them in our resource files so they can be taken into account. First, we have to include the .loc file at the beginning of our resource definitions:

Once this is done, we change the hardcoded strings in our objects by indirections to the localised ones. Ex:

instead of:

That wasn't a big deal! This is enough if you only need to localise your menu. But if you intend to use localised strings in your code as well, then you also have to define a resource buffer to hold them. Simply add a TBUF resource declaration for each string you need to access from your code at the end of your .rss file:

Step 3: Use localised strings in your code

You should now be able to delete most of the _LIT() definitions in your code. Ex, no more:

myDes.Format(_L("You have %d apples"),num);

Use instead a format string read from the resource file. This is slightly more complex but CCoeEnv::AllocReadResourceLC() will do most of the job for you:

This code allocates a HBufC descriptor and copy the R_STRING_APPLE strings into it. The descriptor is then used as a format template to include a numerical value. Depending on the language settings of your phone (and the num value!), the myDes descriptor contain "You have 3 apples.", "Vous avez 3 pommes." or "Sie haben 3 Apfels" (Note: I must apologize for this real dummy text but I only speak and write very limited German!).

Step 4: Update your MMP file

That's all as far the code is concerned. However, a small update is necessary in the MMP file to tell the resource compiler which language shall be used. Add a LANG statement with the code corresponding to each of the language you currently support:

Remember to include your .rss file in the compilation (with the RESOURCE statement) and to include the path to your localisation files as well (the second USERINCLUDE primitive).

Step 5: Localize the name of your application

The name of the application is by default the name of the .app file which cannot be localised. However,by creating an .aif file, you can specify localised name for your application. First, create or update the definition file as specified:

The caption_list associates one different name to each language configuration. Now add the corresponding statement at the end of your .mmp if it is not already present:

This also customizes the logo that appears on the Launcher Menu to represent your application.

Step 6: Update your PKG file

Still reading ? Good, and you are now close to the end. But now is the time to ask you a question reagarding the packaging and the installation of the languages files. Do you want to:
  install all the languages silently on the phone (this may waste some space for complex/big applications but do not bother the user with a language popup)
  ask the user which language he wants to install ? (this uses less space on the disk but adds a step in the installation process)

Let's take the first option first. As we don't want to bother the user with the language popup dialog, then we will install a resource file corresponding to each language we support and we rely on the operating system for the language selection. By default, these resource files have the extension .rXX where XX is the language code and they are located in the

\epoc32\data\z\system\apps\MyApp\

directory. We have to list all them in our .pkg and install them in our application directory:

You may notice that, despite the fact we are writing a multilingual application, we do not specify any language in this .pkg. This is why the user won't be asked. And the magic there is that your application will appear in English for a English user, in French for a French user and in German for a German user. User of other countries will see what Symbian OS think is the most appropriate language according to their locale settings (which is generally English). And if you switch your phone language, the application will automatically switc has well! One of the issue with this method is that ou cannot completely localize the name of the application as it will be displayed by the installer.

The other alternative is to display a language popup at install time, and only install the requested language. No change is required in your code, just tweak a few lines in your .pkg:

This .pkg generates a .sis file that will behave slightly differently at installation:
  the application has the name that is localised even in the installer (here "MyApp", "MonApp" or "MeinApp".
  a popup will be shown and the user will be asked to select a language
  only one of the three .rXX file will be installed on the phone and it will be renamed as .rsc.
  after installation, the application will always appear in this language, no matter of the phone language settings.

Related Links

If you are interested in localizong your own application, the following links may be of interest for you:
  The Nokia language example in the directory Series60Ex\Language of your Series 60 SDK
  Localization by Ariel of Giant Steps, Ltd
  How to make a multilingual application installerby SavaaZ
  The Localisation example on Sendo Developer site (requires a registration).