Symbian Localization

This blog contains parts of document i created.
1 Description
This document describes the localization support as available in vault and secure code. The document covers the topic in a generic manner, for both sym9 and others. The document describes the localization support for applications prior to symbian 9 in the first section and for symbian 9 in the second section.
2 Assumptions
The document assumes that the reader has enough experience (3-4 years) in working with symbian applications and understands the application development cycle thoroughly.
The document doesn’t assume that the reader is familiar with vault or secure code.
The document assumes that the reader is familiar with the symbian installation terminologies and sis file creation.

3 Localization before symbian 9
This section describes the procedures required to localize applications prior to the introduction of enhanced Platform Security in Symbian OS v9. The section also covers how to localize the resources and the application caption.
The localization when needed is added in three files. The mmp file, the rss file and the pkg file.
3.1 Localization in mmp file
Mmp file contains crucial information about the localization support available with the application. This is done by the LANG key word.
The syntax is LANG
CODE is the language code to be used and is two digit number defined as TLanguage enum in e32std.h header file.

A sample mmp file for English and French locals is as shown below.

TARGET HelloWorld.app
TARGETTYPE app
UID 0x100039CE 0x10000008
TARGETPATH \system\apps\HelloWorld
SOURCEPATH.
SOURCE HelloWorld_Main.cpp
SOURCE HelloWorld_Application.cpp
SOURCE HelloWorld_Document.cpp
SOURCE HelloWorld_AppUi.cpp
SOURCE HelloWorld_AppView.cpp
USERINCLUDE .
SYSTEMINCLUDE \epoc32\include
LANG 01 02
RESOURCE HelloWorld.rss
LIBRARY euser.lib apparc.lib cone.lib eikcore.lib avkon.lib
AIF helloworld.aif .\ helloworldAIF.res c8 helloworld.bmp helloworldm.bmp

3.2 localization in rss file
Resource file is the main file supporting localization in terms of application building. The resource files are also listed in the mmp file as part of the project. The rss file should selectively compile for all available locals.
The sample rss file given below makes the concept clear.

NAME HEWO
#include
#include
#include "helloworld.hrh"
#ifdef LANGUAGE_01
#include "01-strings.rls"
#else if defined LANGUAGE_02
#include "02-strings.rls"
#endif
RESOURCE RSS_SIGNATURE { }
RESOURCE TBUF { buf=""; }
RESOURCE EIK_APP_INFO
{
hotkeys=r_example_hotkeys;
menubar=r_example_menubar;
}

A key feature of this file is the conditional inclusion listed below

#ifdef LANGUAGE_01
#include "01-strings.rls"
#else if defined LANGUAGE_02
#include "02-strings.rls"
#endif



For each language code specified in the .mmp file, you need to provide a file with extension .rls of the localized strings. The .rls files for our minimal example application are listed below.

// 01-strings.rls
// Strings localized for UK English
rls_string STRING_first_menu "Hello"
rls_string STRING_item0 "Item 0"
rls_string STRING_item1 "Item 1"
rls_string STRING_item2 "Item 2"
rls_string STRING_close "Close"
rls_string STRING_hello "Hello World!"
// 02-strings.rls
// Strings localized for French
rls_string STRING_first_menu "Bonjour"
rls_string STRING_item0 "Élément 0"
rls_string STRING_item1 "Élément 1"
rls_string STRING_item2 "Élément 2"
rls_string STRING_close "Fin"
rls_string STRING_hello "Bonjour Monde!"


At build time the .mmp file is parsed and for each LANG value (01, 02 etc) the resource compiler compiles the .rss file with the appropriate language switch (LANGUAGE_01, LANGUAGE_02 etc.). The key point is that the resource compiler with be called as many times as there are language variants specified in your .mmp file. The resulting output will be multiple versions of the compiled resource file, one for each LANG value specified in your .mmp file (with file extension .r01, .r02 etc). It is worth noting in passing that in the absence of the LANG statement in the .mmp file, the resource compiler is called just once on the .rss file and the resulting compiled resource file has the extension .rsc, indicating the default locale.

In a similar way the application caption can be localized too. The resource file used for this is aif resource file. AIF files has information about the application caption and also the icon. This is built along with the application via the AIF statement in mmp file as shown below.

AIF helloworld.aif .\ helloworldAIF.res c8 helloworld.bmp helloworldm.bmp

The aif resource file for the above sample will be as shown below. The details are self explanatory.

#include
RESOURCE AIF_DATA
{
caption_list=
{
CAPTION { code=01; caption="Hello"; },
CAPTION { code=02; caption="Bonjour"; }
};
app_uid=0x10000008;
num_icons=1;
hidden=KAppNotHidden;
}
Note:
One can also use the aif builder tool, details of which are available elsewhere.

3.3 localization in pkg file


The final stage involved in localizing an application is to create the installation (.sis) file. The installation can be internationalized so that the appropriate localized variant is installed according to the locale setting of the phone. In this section we will show this can be achieved. The package file for our internationalized Hello World application is shown below:

&01,02
#{ "Localized Hello World", "Bonjour Monde localisé"}, (0x10000008), 1,0,0, TYPE=SISAPP
"D:\Symbian\7.0s\Series60_v20\epoc32\data\z\system\apps\HelloWorld\helloworld.aif" - "!:\System\Apps\HelloWorld\HelloWorld.aif"
"D:\Symbian\7.0s\Series60_v20\epoc32\release\ARMI\UREL\HELLOWORLD.APP"-"!:\System\Apps\HelloWorld\HelloWorld.app"
{
"D:\Symbian\7.0s\Series60_v20\epoc32\data\z\system\apps\HelloWorld\HELLOWORLD.R01"
"D:\Symbian\7.0s\Series60_v20\epoc32\data\z\system\apps\HelloWorld\HELLOWORLD.R02"
} - "!:\System\Apps\HelloWorld\HelloWorld.rsc"
The first line in the package file, &01,02 indicates the supported locales. For each supported locale we have to provide an application description (as seen from the second line of the package file), the appropriate variant of which is displayed to the user at installation time, according to the locale setting of the phone. If the number of descriptions provided does not match the number of supported locales as indicated in the first line of the package file, the MakeSIS tool will generate an error, when attempting to create the .sis file.

In addition, for each supported locale (01, 02, etc.) we need to supply the respective compiled resource file (.r01, .r02, etc.). Again the number and file extension of the localized resource files specified in the package file must correspond to the supported locales specified in the first line otherwise the MakeSIS tool will generate an error. At the installation time of the application the installer detects the locale of the phone, and installs the appropriate compiled resource file for that locale.

If the user wants to install all the local data to phone for specific purposes, the user must change the pkg file such that the pkg file will install all the resource files.

4 Localization in symbian 9
With the introduction of platform security, symbian 9 had introduced some changes in the way localization is done, but the underlying principles remain same.
4.1 MMP file changes
The format of mmp file has changed. The main change is the way resource files are organized.

START RESOURCE HelloWorld.rss
HEADER
TARGETPATH \resource\apps
LANG 01 02
END
For each .RSS file a RESOURCE block is specified, commencing with START and terminating with END. The optional HEADER keyword causes a resource header (.RSG) files to be created in the system include folder …\epoc32\include. The TARGETPATH statement specifies the location of the compiled resource file (.RSC). The LANG keyword has the same meaning as before, and the resource compiler will be invoked for all the locals.
4.2 RESOURCE file changes
There are no syntactical changes in the resource files, but the locale files will have the same name as the application and will have the extension of –l. There is no change in the data which is available in these locale specific files.
But platform security changes have introduced another set of files, which are also compiled by the resource compiler. One of them is application registration file.

Since GUI applications are now .EXEs (rather than .APPs in pre-v9 versions) the application registration file is used to tell the application architecture that this particular .exe is a GUI application. Looking again at the MMP file we see the following structure (simplified):

START RESOURCE HelloWorld_reg.rss
TARGETPATH \private\10003a3f\apps
END

The Application Registration file by convention has the same filename as the application, but with a _reg suffix and replaces the Application Information File (AIF) file supported on earlier versions. The registration file must build into a private data caged directory belonging to the Application Architecture Server, since the application architecture is ultimately responsible for launching all applications. The file details could be as shown below.

#include
UID2 KUidAppRegistrationResourceFile
UID3 0xE0000003 // application UID
RESOURCE APP_REGISTRATION_INFO
{
app_file = "HelloWorld";
localisable_resource_file = "\\resource\\apps\\HelloWorld_loc";
}

The APP_REGISTRATION_INFO structure minimally needs to provide the name (but not extension) of the application binary (using the app_file statement). If a localisable icon/caption definition file is provided, as in this example, its full path and filename must be specified, excluding the drive letter and file extension. This file defines the application's captions and the name of the icon file. By convention it has the same filename as the application, but with a _loc suffix.

#include
#ifdef LANGUAGE_01
#include "helloworld.l01"
#elif defined LANGUAGE_02
#include "helloworld.l02"
#endif
RESOURCE LOCALISABLE_APP_INFO
{
short_caption = STRING_r_example_short_caption;
caption_and_icon =
{
CAPTION_AND_ICON_INFO
{
caption = STRING_r_example_caption;
number_of_icons = 1;
icon_file = "\\resource\\apps\\helloworld.mbm";
}
};
}

The HelloWorld_loc.rss file is a standard localisable Symbian resource file, so it is compiled by the resource compiler by including lines similar to the following in the application's .MMP file:

START RESOURCE HelloWorld_loc.rss
TARGETPATH \resource\apps
LANG 01 02
END

4.3 pkg file changes
There are no changes with respect to the underlying principle, but that the new files will also be part of the pkg file as shown below.

"E:\Symbian\S60_3rd\EPOC32\data\Z\private\10003a3f\apps\HelloWorld_reg.RSC" - "!:\private\10003a3f\import\apps\HelloWorld_reg.RSC"
{"E:\Symbian\S60_3rd\EPOC32\data\Z\resource\apps\HelloWorld.R01"
"E:\Symbian\S60_3rd\EPOC32\data\Z\resource\apps\HelloWorld.R02"
} -"!:\resource\apps\HelloWorld.RSC"
{"E:\Symbian\S60_3rd\EPOC32\data\Z\resource\apps\HelloWorld_loc.R01"
"E:\Symbian\S60_3rd\EPOC32\data\Z\resource\apps\HelloWorld_loc.R02"
} -"!:\resource\apps\HelloWorld_loc.RSC"
5 conclusion
It is evident that there is no change in the underlying principles for localizing an application from symbian 9 and other versions of symbian. Due to the introduction of platform security, there are changes in the mmp and rss file syntax for symbian 9 onwards.