You are on page 1of 6

Introduction to localizing your Symbian OS

applications: part 1 pre-Symbian OS v9


Author: Martin de Jode
Date: November 2005
Version: 1.0
Status: Released

1. Introduction
In this paper we will look at the steps involved in internationalizing your Symbian OS application, and
producing and installing localized variants.

Prerequisites for understanding this article are a familiarity with the Symbian OS build tool chain and
some familiarity with the standard Symbian OS application framework and application installation
system.

This paper will concentrate on the procedures required to localize applications prior to the introduction of
enhanced Platform Security in Symbian OS v9. Due to requirements of so-called ‘data caging’,
localization has changed in the Platform Security world and will be the topic for a later paper.

In the following sections we will consider producing localized variants of your application, localizing the
application’s icon caption, and finally how to package the application so that the appropriate localized
variant is correctly installed according to the phone’s current locale setting.

2. Localizing your application


Let us first look at the .mmp file for an internationalized, sample HelloWorld application.

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
The first thing to notice is the LANG statement in the project .mmp file specifying the supported locales.
The language codes are two digit numbers defined in an enumeration TLanguage in e32std.h which can
be found in the \epoc32\include\ directory of your SDK. The first ten enumerations are listed below:
ELangTest = 0,
ELangEnglish = 1,
ELangFrench = 2,
ELangGerman = 3,
ELangSpansh = 4,
ELangItalian = 5,
ELangSwedish = 6,
ELangDanish = 7,
ELangNorwegian = 8,
ELangFinnish = 9

So our sample .mmp file is localized to English (01) and French (02).

The principle data structure involved in internationalizing an application is the Resource Source file
(.rss). The resource file(s) is (are) listed in the .mmp file using the RESOURCE statement (see the
above example). The key point is to avoid hard coding any strings in the .rss file. So for our sample
application the .rss file might look like this.
NAME HEWO
#include <eikon.rh>
#include <eikcore.rsg>
#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;
}

RESOURCE HOTKEYS r_example_hotkeys


{
control=
{
HOTKEY { command=EEikCmdExit; key='e'; }
};
}

RESOURCE MENU_BAR r_example_menubar


{
titles=
{
MENU_TITLE { menu_pane=r_example_first_menu; txt=STRING_r_example_first_menu; }
};
}

RESOURCE MENU_PANE r_example_first_menu


{
items=
{
MENU_ITEM { command=EExampleItem0; txt=STRING_r_example_item0; },
MENU_ITEM { command=EExampleItem1; txt=STRING_r_example_item1; },
MENU_ITEM { command=EExampleItem2; txt=STRING_r_example_item2; },
MENU_ITEM { command=EEikCmdExit; txt=STRING_r_example_close; }
};
}

RESOURCE TBUF r_example_text_Hello { buf=STRING_r_example_text_hello; }


RESOURCE TBUF r_example_text_Item0 { buf=STRING_r_example_item0; }
RESOURCE TBUF r_example_text_Item1 { buf=STRING_r_example_item1; }
RESOURCE TBUF r_example_text_Item2 { buf=STRING_r_example_item2; }
RESOURCE TBUF r_example_text_close { buf=STRING_r_example_close; }

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.
3. Localizing your application’s caption
Every Symbian OS application has a caption and icon (even if these are the defaults), that are displayed
on the main application launcher view. Generally for a production quality application the developer will
supply a custom icon and caption information.

The caption and icon are built into the application information file (AIF). Construction of the .aif file can
be done as part of the build process via the AIF statement in the .mmp file. In our sample .mmp file the
AIF statement looks like this:

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

The statements following AIF are respectively the name of the .aif file to be created, the directory
containing the resources required for the .aif file, a text file containing the AIF_DATA structure, the color
depth of the icon bitmaps and the icon bitmaps (image and mask) themselves. The contents of the
helloworldAIF.res (the name and file extension is arbitrary) file is shown below.

#include <aiftool.rh>
RESOURCE AIF_DATA
{

caption_list=
{
CAPTION { code=01; caption="Hello"; },
CAPTION { code=02; caption="Bonjour"; }
};

app_uid=0x10000008;
num_icons=1;
hidden=KAppNotHidden;

The crucial localization information is contained in the caption_list structure.

An alternative to creating the .aif file during the build process is to use the AIFBuilder tool. The
AIFBuilder tool provides facilities for creating the icon and mask bitmaps as well as localizing the
caption, and then generating the complete .aif file.
4. Localizing your application’s installation
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.

It’s worth noting in passing here that if you internationalize an existing application, you may need to
tweak other areas of your .pkg file too in order to ensure there are localized versions of every potentially
user-visible string. A classic example is the product ID required in SIS files targeting Symbian OS v7.0
and later products, where you must include a product ID string for each supported language (see FAQ-
0853 for example: http://www.symbian.com/developer/techlib/faq.html ).

5. Summary
In this paper we have looked at the simple steps required to localize Symbian OS C++ applications for
Symbian OS releases prior to the introduction of enhanced Platform Security in Version 9. Localizing
applications for platform releases based on Symbian OS v9 and later will be covered in a later article.

Back to Developer Library

Want to be kept informed of new articles being made available on the Symbian Developer Network?
Subscribe to the Symbian Community Newsletter.
The Symbian Community Newsletter brings you, every month, the latest news and resources for
Symbian OS.