<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-F35C5336-907C-5B2A-92C6-F8883D49996E" xml:lang="en"><title>How

to localise resources</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Overview</title> <p>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. </p> <p>The examples quoted

in this page are taken from the code example <filepath>Examples\ToolsAndUtilities\Localise</filepath>,

which provides the Hello World application, localised for English and German. </p> </section>

<section><title>Localisable strings</title> <p>Localisable strings should

not be defined within a resource file, but in separate files with the extension <filepath>.rls</filepath>.

An <filepath>.rls</filepath> file defines symbolic identifiers for strings,

to which the resource file refers when it needs the associated string. </p> <p>An

example from an <filepath>.rls</filepath> file is shown below: </p> <codeblock id="GUID-FA54B424-D6C1-5A80-821D-3B25A720873D" xml:space="preserve">// Strings localised for UK

rls_string STRING_r_example_first_menu_name "Hello"

rls_string STRING_r_example_item0 "Item 0"</codeblock> <p>The keyword <codeph>rls_string</codeph> 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. </p> <codeblock id="GUID-722A8D45-5747-5FE8-A3C6-FE9AD2C43542" xml:space="preserve">// Strings localised for German

rls_string STRING_r_example_first_menu_name "Hallo"

rls_string STRING_r_example_item0 "Eintrag 0"</codeblock> <p>The resource

file itself would be the same, whatever the locale, as it would only refer

to strings through their symbolic names, e.g. </p> <codeblock id="GUID-D427E092-1BA9-56A8-B449-DFDA182107AE" xml:space="preserve">MENU_TITLE

    {

    menu_pane=r_example_first_menu;

    txt=STRING_r_example_first_menu_name;

    }</codeblock> <p>defines a menu title resource, with a title string defined

by <codeph>STRING_r_example_first_menu_name</codeph> (i.e. "Hello" in UK,

"Hallo" in German). </p> </section>

<section><title>Building localised resource files</title> <p>You can define

in a project definition (<filepath>.mmp</filepath>) file the locales that

the project supports. Given appropriate resource source and <filepath>.rls</filepath> files,

the build process then builds a separate compiled resource file for each supported

locale. </p> <p>The process in detail can be broken into three steps: </p> <ul>

<li id="GUID-89FC1834-F661-5341-A03C-9F068CAC0655"><p>determine on a symbolic

identifier for every supported locale </p> </li>

<li id="GUID-CEBA3187-2758-5D17-9CE1-032D037BE9F9"><p>specify in the project

definition file the supported locales </p> </li>

<li id="GUID-48C74787-5367-5EE9-ACF9-8A67E87B3CA3"><p> <codeph>#include</codeph> the <filepath>.rls</filepath> files

for the supported locales in the resource source file </p> </li>

</ul> <p>These are discussed further below. </p> <p><b>Locale identifiers </b> </p> <p>You

should decide on a symbolic identifier for every supported language. The symbol

should be of the form: </p> <p> <codeph>LANGUAGE_</codeph> <varname>language-code</varname>  </p> <p>where <codeph>language-code</codeph> 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. </p> <p>You are recommended

to use a standard two-digit number as defined by Symbian in an enumeration <codeph>TLanguage</codeph> in <filepath>e32std.h</filepath>,

which gives numeric values to the languages. For example, the value <codeph>ELangGerman</codeph> (German)

in <codeph>TLanguage</codeph> has the value 3, so you could use <codeph>LANGUAGE_03</codeph> as

the symbol for German. </p> <p>Alternatively, you can use logical letters

for each language: e.g. US English might have the symbol <codeph>LANGUAGE_US</codeph>,

while French might have the symbol <codeph>LANGUAGE_FR</codeph>. </p> <p><b>Project

definition files </b> </p> <p>For projects with localised resources, you must

use the <codeph>lang</codeph> statement in the <filepath>.mmp</filepath> 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 <codeph>lang</codeph> statement

should read: </p> <codeblock id="GUID-BE1AE938-89E7-5E9C-B71D-81F16A64748C" xml:space="preserve">lang 01 03</codeblock> <p>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: <varname>project-name</varname> <filepath>.r01</filepath> and <varname>project-name</varname> <filepath>.r03</filepath>. </p> <p><b>Resource source files </b> </p> <p>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 <filepath>01-strings.rls</filepath> is assumed to have the strings

localised for UK English, and the file <filepath>03-strings.rls</filepath> the

strings localised for German. </p> <codeblock id="GUID-51F46C07-27F9-5A36-A2C2-374A61C5EBF7" xml:space="preserve">// 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

</codeblock> <ul>

<li id="GUID-95464F59-9F66-5984-8B31-1A77D91EC033"><p>when built with the

code 01, the UK English strings in <filepath>01-strings.rls</filepath> are

compiled into the resource file </p> </li>

<li id="GUID-48DE7451-D93E-51F0-8B43-2EA94A68E800"><p>when built with the

code 03, the German strings in <filepath>03-strings.rls</filepath> are compiled

into the resource file </p> </li>

</ul> </section>

<section><title>How programs load resource files </title> <p>The Uikon application

framework attempts to load the project's resource file when the application

starts up. If the resource file has the extension <filepath>.rsc</filepath>,

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 <filepath>.r03</filepath> would

be loaded. Resource files that are explicitly loaded by programs, rather than

by the framework, can use the same stategy, by calling <codeph>BalfUtils::NearestLanguageFile()</codeph> to

find a resource file with the correct language extension. </p> <p>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 <xref href="GUID-5D508751-C824-48E4-A6E3-0C5EA05DEC99.dita">PKG

file format to support multilingual application installation</xref>. </p> </section>