How to localise resources

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.

To localise a resource file, either:

• specify the text strings (as #defines) for each language in a separate file, and #include the file in the resource file that references these strings

  or,

• specify the text strings in each language that you want to support in the resource file itself, and specify in the project's .mmp file the supported languages. The build process builds a separate compiled resource file for each supported language.

These steps for this second option are explored in detail below.

You should decide on a symbolic identifier for every supported language. The symbol should be of the form LANGUAGE_language-code. 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 ELangFrench (French) in TLanguage has the value 2, so you could use LANGUAGE_02 as the symbol for French.

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.

The symbols can then used, with conditional compilation statements, to specify which resources should be compiled for each language. In the example code fragment below:

• when the resource file is built with the code 10 (American English), then the text “Localize” is compiled into the resource file

• when built with the code 01 (UK English), the UK English spelling “Localise” is compiled into the resource file

#ifdef LANGUAGE_10 // if language code is for US
 LBUF { txt="Localize" ; },
#elif defined LANGUAGE_01 // if code is for UK
 LBUF { txt="Localise" ; },
#endif // end condititional compile

Resource files are built when a project is built using abld build or through the MSVC++ IDE. To just build the resource files (plus the aif files and bitmaps), without other build steps such as compiling C++ files, you can use abld resource.

For projects with localised resource files, you must use the lang statement in the .mmp file to set the languages codes used in those resource files. So, for the above example, in which the language codes used are for the US and UK, the lang statement should read:

lang 10 01

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.r10 and project-name.r01.

The resource file automatically loaded by the Uikon framework must have the extension .rsc. If an application supports several different languages, and hence has resource files with different extensions, the installation process allows the user to choose the language they want, and renames the required resource file appropriately. Details of this are given in How to create an installation file for a multilingual application.

Other resource files can be explicitly loaded by programs, in which case their are no restrictions on the name of the resource file. Where resource files have been named using the Symbian two-digit language values, BalfUtils::NearestLanguageFile() can be used to try to find a resource file with the correct language extension for a given language code.