<?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>
</conbody></concept>