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 OS Installation System enables this, as described in How to create an installation file for a multilingual application.

Resource building is performed by the epocrc tool. It is a three-stage process:

• pre-processing
• localised string merging
• compilation to binary format

The sections
Pre-processing
Resource files can use the familiar pre-processor directives. In particular, #include is used to include header files; #define is used to define macros such as numeric constants; and #if and related directives can be used to perform conditional compilation. Pre-processor arguments for include file paths and macro definitions can be passed to the pre-processor through epocrc.

The source file is pre-processed, using the cpp pre-processor, and an output file produced with an extension .rpp.

Merging localised strings
Strings that should be localised should not be defined in the resource file itself, but in separate files with an .rls extension. The .rpp files are processed by epocrc to merge in the localisable strings.

A flag can also be specified to epocrc that causes it to copy the .rpp files into a epoc32\localisation\ directory, from where they can form input into a localisation kit.

Compilation to binary format
The final stage is to convert the intermediary .rpp files into the final compiled format. This is done by the rcomp tool. The resource compiler also produces a header file that contains a symbolic identifier for each resource.

The names of the output files are specified as parameters to epocrc. Note though that:

resource files as built by the project build tools (abld) have the default extension .rsc. The additional naming conventions used when you need to supply multiple resource files, each for a different locale, are discussed in How to localise resources

by convention, the header file has an extension .rsg

The identifiers in the header file provide symbolic names for index positions in the resource file, so that your source code can be independent of the number and order of resources within the file. For a named resource such as:

RESOURCE TBUF r_eik_bafl_error_offset { buf="Wrong format resource file"; }
the generated header file will have a #define such as:

#define R_EIK_BAFL_ERROR_OFFSET 0xf3b045
where the number is a resource ID which encodes the resource index, and is suitable for passing to the C++ function RResourceFile::AllocReadLC().

In the course of project development, changes to the resource file may not always result in changes to the set of #define statements generated. If there is no change, the rsg file is not rebuilt, thereby avoiding unnecessary re-compilation and linking.

Much of the information that defines the appearance, behaviour and functionality of a Symbian OS application is stored externally to the main body of the program, in a resource file. This is unlike some other programming environments, in which a single executable contains all the code and information used by the application. Resource files can have the advantages that information is loaded only when needed, which can reduce RAM requirements, they can be compressed, and they can be localised without needing to recompile the main program.

Resource files are developed as text files written in a Symbian OS-specific resource language. These source files are then compiled into a binary file format that can be loaded and read by programs. The source files can be compiled on their own using the command-line resource builder tool (epocrc), or as part of the standard project building process either from the command-line or from within an IDE.

Purposes of resource files
Resource files are used for the following purposes:

to define the application user interface. The C++ application programming framework requires that some aspects of an application’s layout and behaviour, such as the menu bars and dialogs, are defined in a resource file

to define application properties that are used by the application launcher or system shell.

Until v9.0, (.aif) are used to define the application's icon and caption, and various properties, for instance whether the application is exposed to users or hidden, whether the application can be embedded, and the priority at which the application should be associated with MIME data types.

From v9.0, aif files are replaced by application registration information. The caption and icon are defined either in a special resource file called a localisable icon/caption definition file, or, if more convenient, in the application's UI resource file. The application's properties and some other information is defined in another type of resource file called a registration file.

Literal strings and other constant data: for example, dialog text and error messages. The resource tool chain provides support for localisation of these.

File types reference
The resource compilation process uses a number of file types:

rss
resource source file

rls
defines localisable strings, for inclusion in the resource source file

h
header file, for inclusion in C++ file

rh
resource header, for inclusion in the resource source file

hrh
common C++ or resource header, for inclusion in either type of source file

rsg
resource header file output from the resource compiler

rsc
compiled resource file from the resource compiler