How +to localise resources

Overview

Symbian developers can localise a C++ +application by simply changing the resource file text associated with each +menu item, task bar or other control. Since changes to the text do not change +the symbol information in the generated header file, it is not necessary to +recompile the application to use the new file. Consequently, a resource file +may be generated for each language supported, and the actual resource used +is determined by the end-user at installation time.

The examples quoted +in this page are taken from the code example Examples\ToolsAndUtilities\Localise, +which provides the Hello World application, localised for English and German.

Localisable strings

Localisable strings should +not be defined within a resource file, but in separate files with the extension .rls. +An .rls file defines symbolic identifiers for strings, +to which the resource file refers when it needs the associated string.

An +example from an .rls file is shown below:

// Strings localised for UK +rls_string STRING_r_example_first_menu_name "Hello" +rls_string STRING_r_example_item0 "Item 0"

The keyword rls_string appears +before each string definition, followed by a symbolic identifier, and then +the string itself in quotes. To localise the file for German, the same identifiers +would be used, but the strings would be translated, i.e.

// Strings localised for German +rls_string STRING_r_example_first_menu_name "Hallo" +rls_string STRING_r_example_item0 "Eintrag 0"

The resource +file itself would be the same, whatever the locale, as it would only refer +to strings through their symbolic names, e.g.

MENU_TITLE + { + menu_pane=r_example_first_menu; + txt=STRING_r_example_first_menu_name; + }

defines a menu title resource, with a title string defined +by STRING_r_example_first_menu_name (i.e. "Hello" in UK, +"Hallo" in German).

Building localised resource files

You can define +in a project definition (.mmp) file the locales that +the project supports. Given appropriate resource source and .rls files, +the build process then builds a separate compiled resource file for each supported +locale.

The process in detail can be broken into three steps:

determine on a symbolic +identifier for every supported locale
specify in the project +definition file the supported locales
#include the .rls files +for the supported locales in the resource source file

These are discussed further below.

Locale identifiers

You +should decide on a symbolic identifier for every supported language. The symbol +should be of the form:

LANGUAGE_ language-code

where language-code should +be two characters long, but otherwise can be anything you like, as long as +each language in the resource file has a unique symbol.

You are recommended +to use a standard two-digit number as defined by Symbian in an enumeration TLanguage in e32std.h, +which gives numeric values to the languages. For example, the value ELangGerman (German) +in TLanguage has the value 3, so you could use LANGUAGE_03 as +the symbol for German.

Alternatively, you can use logical letters +for each language: e.g. US English might have the symbol LANGUAGE_US, +while French might have the symbol LANGUAGE_FR.

Project +definition files

For projects with localised resources, you must +use the lang statement in the .mmp file +to set the languages codes used. So, for the above example, in which the language +codes used are for German (03) and UK English (01), the lang statement +should read:

lang 01 03

When +the project is built, each resource file specified in the project file will +be compiled multiple times, once for each language-code specified. The language +codes are used to complete the extension of the built resource files: for +our example, two files would be built: project-name .r01 and project-name .r03.

Resource source files

The symbols can then used, +with conditional compilation statements, to specify which string definitions +should be compiled for each language. In the example code fragment below, +the file 01-strings.rls is assumed to have the strings +localised for UK English, and the file 03-strings.rls the +strings localised for German.

// Conditional compile, depending on locale +#ifdef LANGUAGE_01 // if language code is for UK + #include "01-strings.rls" +#elif defined LANGUAGE_03 // if language code is for German + #include "03-strings.rls" +#endif +// end conditional compile +

when built with the +code 01, the UK English strings in 01-strings.rls are +compiled into the resource file
when built with the +code 03, the German strings in 03-strings.rls are compiled +into the resource file

How programs load resource files

The Uikon application +framework attempts to load the project's resource file when the application +starts up. If the resource file has the extension .rsc, +then this is loaded. Alternatively, the framework attempts to load the correct +resource file by comparing the system locale setting with the available resource +files: for example, in a German locale, the resource file with extension .r03 would +be loaded. Resource files that are explicitly loaded by programs, rather than +by the framework, can use the same stategy, by calling BalfUtils::NearestLanguageFile() to +find a resource file with the correct language extension.

More typically +than installing all the resource files for all the available locales, you +would only want to select a single resource file for installation, based on +the system locale or user preference. The Symbian platform Installation System +enables this, as described in PKG +file format to support multilingual application installation.