Symbian has the capability of supporting resources in multiple languages, and letting the user decide which language to use at installation time. This article shows how to support this in your code.

This article is applies to all Symbian SDK that I know. I have tested it both in Series 60 (6.1, 7.0s), and UIQ, and with several European languages, as well as Chinese. However, I haven't tested it with RTL (Right-to-Left) languages.

The key to doing this is in the project's resource file. Basically, it gets compiled twice, once for each supported language, each time with different strings. Then at installation, when the user selects a language for the application, the device effectively copies the appropriate compiled resource file, which is then used as the application's resource file.

Any application can support this framework by following these steps.

Prepare the source code

First, you should make sure that you have no descriptors inside your code, and they're all in the your .RSS file. Strings that are part of a resource (such as prompts in a dialog line, and such), are in the RSS file anyway. For literals, the simplest way to export a literal is to a TBUF. For example, if you have something like this:

you should export the literal to the .RSS file:

and then use it in your code as follows:

Of course, if you use the string frequently, you may want to load it into a class member. You may also want to load the resource into a TBuf:

Export the strings to a seprate file

The second step is the simplest: You need to export all the strings in MyApp.RSS to a header file named by convention MyApp.LOC (or .RLS, it doesn't really matter), and then #include this file into your .RSS. The .loc file is a simple header file with #defines. This header file is commonly known as a localization file.

In the above example, we would replace the following line in MyApp.RSS RESOURCE TBUF r_my_line { buf = "Cheers, Mate";}

with

and add the following line to the .loc file #define string_my_line "Cheers, Mate"

Create localization files

Now your program is prepared for localization. You should now take your .loc file and translate it to the other language you wish to support. In this example, I will assume it is Chinese.

First, you should determine what is the code of the language you're translating to. You can easily determine this by examining the TLanguage enum in <e32std.h>. The code for PRC Chinese is 31.

Now make a copy of MyLoc.loc and name it using the appropriate code for your language, for example: MyLoc.L31. Now you should translate all the strings to Chinese, e.g. #define string_my_line "你好，朋友"

Now, since the file is not ASCII, you must write it in UTF-8 and put the following line in the beginning of the file: CHARACTER_SET UTF8

Note: If you're using MS Visual Studio, you'll find out that introduces a problem here, since it only supports ANSI. You can easily edit the file in Notepad, which, (in Win2K & XP) lets you save the file as UTF-8. Unfortunately, notepad has the side effect of prefixing the file with the three bytes 0xEF, 0xBB, 0xBF, which make the file unreadable by the compiler. You can fix this by opening the file in Visual studio and deleting these characters.

Integrate the localized strings into the project

Ok, now that you have exported and translate all the strings, comes the heart of the process: Integrating the strings into your project. This is actually very simple. In your .mmp file, locate the line beginning with “LANG”. If there isn't any such line create one, doesn't matter where.

This line contains the language codes for all the supported languages: LANG 31 SC where SC is the default language (usually UK English), and 31 is the language code. You may put as many codes as you wish.

Then, in the .RSS file replace #include "MyApp.loc"

with

If all works well, after the next compilation, you'll have two binary resource files: MyApp.RSC in English, and MyApp.R31, in Chinese.

What happens with this, is that the builder compiles the resource file once for each language code. On each compilation it defines a different preprocessor definition according of the following pattern: LANGUAGE_xx, where xx is the language code as specified in the .MMP file [1].

Use the localized resources in installation

Now that you have localized resource files, you need to modify your .pkg file so that it will let the user install your application in his desired language

Again, you have to add language indication to the file. In the .PKG it looks like this: &EN, ZH

EN and ZH are language codes for English and PRC Chinese. Here is the full list as it appears in the documentation under "Package file format .pkg". The list is identical for all the aforementioned SDKs.

Now, locate the line in code that controls the copying of the .rsc file: "\Symbian\UIQ_70\Epoc32\data\z\system\apps\MyApp\MyApp.rsc"-"!:\system\apps\MyApp\MyApp.rsc" and replace it with:

This format is used to specify a list of files, of which only one will be installed, depending on the language selected by the user during installation: If the user selects English, the first file will be copied; if he selects Chinese, the second file will be copied (and renamed MyApp.RSC). Again, you may put as many languages as you wish.

Unfortunately, the file format requires that you “translate” all the strings in your code to all the supported languages, i.e, all strings in the .pkg, must appear twice (or more, depending on the number of languages you support). This includes your application name: #{"MyApp","MyApp"},(0x06812345),0,40,0 but also strings like:

Install

That's it! If all went well, when you install the application you will be given a choice of languages, and only the language you chose will be installed.

Enjoy!

[1] You may have noticed that the language code used to identify the language during the compilation doesn't really matter. This is true. Symbian is not really aware of the destination language, at least not until the installation phase. When compiling it simply uses the given code for declaring the LANGUGAGE_xx's, and naming the resulting .RSC files; so you may use any two characters to identify the language. However, using the TLanguage enum for the language code is the recommended convention. I also make use of this convention in my next article, which will cover changing the application's language at run-time