--- a/Symbian3/SDK/Source/GUID-F35C5336-907C-5B2A-92C6-F8883D49996E.dita Fri Jul 16 17:23:46 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,107 +0,0 @@
-<?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