Introduction to localizing your Symbian

OS applications: part 2 - Symbian OS v9

Martin de Jode and Mark Shackman
Version 1.1

1 Introduction
In the previous article we outlined the measures required to localize your applications for versions of
Symbian OS prior to version 9. In this article we will complete the picture by looking at the changes
required for Symbian OS v9 and later.
The release of Symbian OS v9 marked a major watershed, with the introduction of an enhanced security
architecture. The constraints imposed by the new security model have necessitated some minor changes
in the structure of applications, and these necessarily result in some changes to the structure and location
of resource files involved in localization. For a detailed overview of platform security and migrating
applications to v9, the reader is referred to “Symbian OS Platform Security” by Craig Heath (Wiley 2006).
In this paper we will focus only on the changes relevant to the localization process. Fortunately these are
minor and the underlying principles outlined in the previous paper remain.

2 Localizing your application

First let us take a look at the (S60) .MMP file.
// HelloWorld.mmp

TARGET HelloWorld.exe
TARGETTYPE exe
UID 0x100039CE 0xE0000003

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

START RESOURCE HelloWorld.rss

HEADER
TARGETPATH \resource\apps
LANG 01 02
END

START RESOURCE HelloWorld_reg.rss

#ifdef WINSCW
TARGETPATH \private\10003a3f\apps
#else
TARGETPATH \private\10003a3f\import\apps
#endif
END

START RESOURCE HelloWorld_loc.rss

TARGETPATH \resource\apps
LANG 01 02
END

LIBRARY euser.lib, apparc.lib, cone.lib, avkon.lib, eikcore.lib

The major changes to the .MMP file for v9 and later relate to the RESOURCE syntax. For example
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) file to be created in the system
include folder …\epoc32\include. The TARGETPATH statement specifies the location of the compiled
resource file (.RSC). In Symbian OS v9 and later, data caging (part of the platform security architecture)
requires resources to be placed into the correct path, either \resource for resources that are public but
read-only, or \private\<secure_ID>, for resources that are private to the application with <secure_ID>
(where <secure_ID> is the application’s UID3, if not otherwise specified). The LANG keyword has the
same meaning as before. So in the example above the resource compiler will be invoked twice, for each
of the specified locales.

3 Localizing your application’s resources

Let’s take a look at the .RSS file for this version of the application, for the S60 user interface:
NAME HEWO

#include <eikon.rh>
#include <eikcore.rsg>
#include <appinfo.rh>
#include <avkon.rh>
#include <avkon.rsg>
#include "helloworld.hrh"
#ifdef LANGUAGE_01
#include "helloworld.l01"
#elif defined LANGUAGE_02
#include "helloworld.l02"
#endif
RESOURCE RSS_SIGNATURE { }

RESOURCE TBUF r_default_document_name

{
buf="HEWO";
}

RESOURCE EIK_APP_INFO
{
hotkeys=r_example_hotkeys;
menubar=r_example_menubar;
cba = R_AVKON_SOFTKEYS_OPTIONS_EXIT;
}

RESOURCE HOTKEYS r_example_hotkeys

{
control=
{
HOTKEY { command=EAknSoftkeyExit; 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; },

2
 MENU_ITEM { command=EExampleItem1; txt=STRING_r_example_item1; },
MENU_ITEM { command=EExampleItem2; txt=STRING_r_example_item2; },
MENU_ITEM { command=EAknSoftkeyExit; 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; }

This is identical in structure to the pre v9 version, using the same conditional include of the .RLS files we
saw in Part 1:
#ifdef LANGUAGE_01
#include "01-strings.rls"
#else if defined LANGUAGE_02
#include "02-strings.rls"
#endif

3.1 Localized resource strings

The localized strings are contained in files with the same name as the application but with a _lXX
extension, where XX is the locale number. These are loaded by the .RSS file using the statements:
#ifdef LANGUAGE_01
#include "helloworld.l01"
#elif defined LANGUAGE_02
#include "helloworld.l02"
#endif

The example below is the contents of helloworld.l02, which contains the resources for locale 02
(France).
// Strings localised for France
rls_string STRING_r_example_first_menu "Bonjour"
rls_string STRING_r_example_item0 "Élément 0"
rls_string STRING_r_example_item1 "Élément 1"
rls_string STRING_r_example_item2 "Élément 2"
rls_string STRING_r_example_close "Fin"
rls_string STRING_r_example_text_hello "Bonjour Monde!"

rls_string STRING_r_example_short_caption "B M"

rls_string STRING_r_example_caption "Bonjour tout le monde"

4 Application registration files

The other major change required for v9 is the introduction of the 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. Putting
the _reg file in a private directory prevents a malicious application replacing an existing application’s
_reg file with a spoof version. The application registration file is shown below.

3
#include <appinfo.rh>

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 <AppInfo.rh>

#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

5 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

#{"HelloWorld_v9_s60_EN","HelloWorld_v9_s60_FR"},(0xE0000003),1,0,1, TYPE=SA, NC

:"Symbian Software Ltd"

%{"Symbian Software","Symbian Logiciel."}

"E:\Symbian\S60_3rd\EPOC32\RELEASE\ARMV5\UREL\HelloWorld_S60.exe" -"!:\sys\bin\HelloWorld_S60.exe"
"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"

4
Note that where a single string or file name varies due to localization, the number of options within the
braces must match the number of locale variants specified in the .MMP file (in this case, we have just the
two).

6 Summary
In this second part of “How to localize your Symbian OS application” we have considered the changes
necessary to migrate your application to Symbian OS version 9 and later. The underlying principles
remain the same as for earlier versions, but the requirements of Platform Security necessitate some
syntactical changes to the MMP and associated resource files.

NOTE: As of the current issue of this document, there is a defect in CodeWarrior and Carbide.c++ that
prevents the code examples given in this paper from being correctly built. A workaround is available for
this defect and the updated file in question (ide_cw.pm) is included in recent builds of Symbian OS v9.2
and v9.3. The updated file is also supplied as an additional download with this paper and should
replace the existing file in \epoc32\tools.

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.