--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-F35C5336-907C-5B2A-92C6-F8883D49996E.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,107 @@
+<?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>
\ No newline at end of file