1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-F35C5336-907C-5B2A-92C6-F8883D49996E" xml:lang="en"><title>How |
|
13 to localise resources</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section><title>Overview</title> <p>Symbian developers can localise a C++ |
|
15 application by simply changing the resource file text associated with each |
|
16 menu item, task bar or other control. Since changes to the text do not change |
|
17 the symbol information in the generated header file, it is not necessary to |
|
18 recompile the application to use the new file. Consequently, a resource file |
|
19 may be generated for each language supported, and the actual resource used |
|
20 is determined by the end-user at installation time. </p> <p>The examples quoted |
|
21 in this page are taken from the code example <filepath>Examples\ToolsAndUtilities\Localise</filepath>, |
|
22 which provides the Hello World application, localised for English and German. </p> </section> |
|
23 <section><title>Localisable strings</title> <p>Localisable strings should |
|
24 not be defined within a resource file, but in separate files with the extension <filepath>.rls</filepath>. |
|
25 An <filepath>.rls</filepath> file defines symbolic identifiers for strings, |
|
26 to which the resource file refers when it needs the associated string. </p> <p>An |
|
27 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 |
|
28 rls_string STRING_r_example_first_menu_name "Hello" |
|
29 rls_string STRING_r_example_item0 "Item 0"</codeblock> <p>The keyword <codeph>rls_string</codeph> appears |
|
30 before each string definition, followed by a symbolic identifier, and then |
|
31 the string itself in quotes. To localise the file for German, the same identifiers |
|
32 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 |
|
33 rls_string STRING_r_example_first_menu_name "Hallo" |
|
34 rls_string STRING_r_example_item0 "Eintrag 0"</codeblock> <p>The resource |
|
35 file itself would be the same, whatever the locale, as it would only refer |
|
36 to strings through their symbolic names, e.g. </p> <codeblock id="GUID-D427E092-1BA9-56A8-B449-DFDA182107AE" xml:space="preserve">MENU_TITLE |
|
37 { |
|
38 menu_pane=r_example_first_menu; |
|
39 txt=STRING_r_example_first_menu_name; |
|
40 }</codeblock> <p>defines a menu title resource, with a title string defined |
|
41 by <codeph>STRING_r_example_first_menu_name</codeph> (i.e. "Hello" in UK, |
|
42 "Hallo" in German). </p> </section> |
|
43 <section><title>Building localised resource files</title> <p>You can define |
|
44 in a project definition (<filepath>.mmp</filepath>) file the locales that |
|
45 the project supports. Given appropriate resource source and <filepath>.rls</filepath> files, |
|
46 the build process then builds a separate compiled resource file for each supported |
|
47 locale. </p> <p>The process in detail can be broken into three steps: </p> <ul> |
|
48 <li id="GUID-89FC1834-F661-5341-A03C-9F068CAC0655"><p>determine on a symbolic |
|
49 identifier for every supported locale </p> </li> |
|
50 <li id="GUID-CEBA3187-2758-5D17-9CE1-032D037BE9F9"><p>specify in the project |
|
51 definition file the supported locales </p> </li> |
|
52 <li id="GUID-48C74787-5367-5EE9-ACF9-8A67E87B3CA3"><p> <codeph>#include</codeph> the <filepath>.rls</filepath> files |
|
53 for the supported locales in the resource source file </p> </li> |
|
54 </ul> <p>These are discussed further below. </p> <p><b>Locale identifiers </b> </p> <p>You |
|
55 should decide on a symbolic identifier for every supported language. The symbol |
|
56 should be of the form: </p> <p> <codeph>LANGUAGE_</codeph> <varname>language-code</varname> </p> <p>where <codeph>language-code</codeph> should |
|
57 be two characters long, but otherwise can be anything you like, as long as |
|
58 each language in the resource file has a unique symbol. </p> <p>You are recommended |
|
59 to use a standard two-digit number as defined by Symbian in an enumeration <codeph>TLanguage</codeph> in <filepath>e32std.h</filepath>, |
|
60 which gives numeric values to the languages. For example, the value <codeph>ELangGerman</codeph> (German) |
|
61 in <codeph>TLanguage</codeph> has the value 3, so you could use <codeph>LANGUAGE_03</codeph> as |
|
62 the symbol for German. </p> <p>Alternatively, you can use logical letters |
|
63 for each language: e.g. US English might have the symbol <codeph>LANGUAGE_US</codeph>, |
|
64 while French might have the symbol <codeph>LANGUAGE_FR</codeph>. </p> <p><b>Project |
|
65 definition files </b> </p> <p>For projects with localised resources, you must |
|
66 use the <codeph>lang</codeph> statement in the <filepath>.mmp</filepath> file |
|
67 to set the languages codes used. So, for the above example, in which the language |
|
68 codes used are for German (03) and UK English (01), the <codeph>lang</codeph> statement |
|
69 should read: </p> <codeblock id="GUID-BE1AE938-89E7-5E9C-B71D-81F16A64748C" xml:space="preserve">lang 01 03</codeblock> <p>When |
|
70 the project is built, each resource file specified in the project file will |
|
71 be compiled multiple times, once for each language-code specified. The language |
|
72 codes are used to complete the extension of the built resource files: for |
|
73 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, |
|
74 with conditional compilation statements, to specify which string definitions |
|
75 should be compiled for each language. In the example code fragment below, |
|
76 the file <filepath>01-strings.rls</filepath> is assumed to have the strings |
|
77 localised for UK English, and the file <filepath>03-strings.rls</filepath> the |
|
78 strings localised for German. </p> <codeblock id="GUID-51F46C07-27F9-5A36-A2C2-374A61C5EBF7" xml:space="preserve">// Conditional compile, depending on locale |
|
79 #ifdef LANGUAGE_01 // if language code is for UK |
|
80 #include "01-strings.rls" |
|
81 #elif defined LANGUAGE_03 // if language code is for German |
|
82 #include "03-strings.rls" |
|
83 #endif |
|
84 // end conditional compile |
|
85 </codeblock> <ul> |
|
86 <li id="GUID-95464F59-9F66-5984-8B31-1A77D91EC033"><p>when built with the |
|
87 code 01, the UK English strings in <filepath>01-strings.rls</filepath> are |
|
88 compiled into the resource file </p> </li> |
|
89 <li id="GUID-48DE7451-D93E-51F0-8B43-2EA94A68E800"><p>when built with the |
|
90 code 03, the German strings in <filepath>03-strings.rls</filepath> are compiled |
|
91 into the resource file </p> </li> |
|
92 </ul> </section> |
|
93 <section><title>How programs load resource files </title> <p>The Uikon application |
|
94 framework attempts to load the project's resource file when the application |
|
95 starts up. If the resource file has the extension <filepath>.rsc</filepath>, |
|
96 then this is loaded. Alternatively, the framework attempts to load the correct |
|
97 resource file by comparing the system locale setting with the available resource |
|
98 files: for example, in a German locale, the resource file with extension <filepath>.r03</filepath> would |
|
99 be loaded. Resource files that are explicitly loaded by programs, rather than |
|
100 by the framework, can use the same stategy, by calling <codeph>BalfUtils::NearestLanguageFile()</codeph> to |
|
101 find a resource file with the correct language extension. </p> <p>More typically |
|
102 than installing all the resource files for all the available locales, you |
|
103 would only want to select a single resource file for installation, based on |
|
104 the system locale or user preference. The Symbian platform Installation System |
|
105 enables this, as described in <xref href="GUID-5D508751-C824-48E4-A6E3-0C5EA05DEC99.dita">PKG |
|
106 file format to support multilingual application installation</xref>. </p> </section> |
|
107 </conbody></concept> |
|