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-141633B8-A3D4-5BBB-97C5-3D928746ECE7" xml:lang="en"><title>Resource |
|
13 localisable strings</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>Resource localisable strings (RLS) are defined in the resource files. Each |
|
15 RLS item definition is a new-line separated entry in the resource file, using |
|
16 literals to define a localisable string, number or character. </p> |
|
17 <p><b>Defining RLS items </b> </p> |
|
18 <p>The following literals can be used to define an RLS item: </p> |
|
19 <table id="GUID-F30AE1BF-B383-5A66-99C1-AD2110C41368"> |
|
20 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
21 <thead> |
|
22 <row> |
|
23 <entry>Name</entry> |
|
24 <entry>Description</entry> |
|
25 </row> |
|
26 </thead> |
|
27 <tbody> |
|
28 <row> |
|
29 <entry><p> <i>rls_string</i> </p> </entry> |
|
30 <entry><p>Use this literal to define a 16-bit Unicode string </p> </entry> |
|
31 </row> |
|
32 <row> |
|
33 <entry><p> <i>rls_string8</i> </p> </entry> |
|
34 <entry><p>Use this literal to define an 8-bit Unicode string </p> </entry> |
|
35 </row> |
|
36 <row> |
|
37 <entry><p> <i>rls_byte</i> </p> </entry> |
|
38 <entry><p>Use this literal to define an 8-bit number </p> </entry> |
|
39 </row> |
|
40 <row> |
|
41 <entry><p> <i>rls_word</i> </p> </entry> |
|
42 <entry><p>Use this literal to define a 16-bit number </p> </entry> |
|
43 </row> |
|
44 <row> |
|
45 <entry><p> <i>rls_long</i> </p> </entry> |
|
46 <entry><p>Use this literal to define a long number </p> </entry> |
|
47 </row> |
|
48 <row> |
|
49 <entry><p> <i>rls_double</i> </p> </entry> |
|
50 <entry><p>Use this literal to define a decimal number </p> </entry> |
|
51 </row> |
|
52 </tbody> |
|
53 </tgroup> |
|
54 </table> |
|
55 <p><b>BNF description </b> </p> |
|
56 <p><i><codeph><rls-file></codeph></i> |
|
57 </p> |
|
58 <p><b>rls-file ::=</b> |
|
59 </p> |
|
60 <p><i><codeph><rls-entry>* <rls-entry></codeph></i> |
|
61 </p> |
|
62 <p><b>rls-entry ::=</b> |
|
63 </p> |
|
64 <p> <i><codeph><rls-item> <rls-item></codeph></i> |
|
65 </p> |
|
66 <p><b>rls-item ::=</b> |
|
67 </p> |
|
68 <p><i><codeph><type>[<length> <cardinality>] <symbolic-identifier> |
|
69 <value> <type></codeph></i> |
|
70 </p> |
|
71 <p><b>type ::=</b> |
|
72 </p> |
|
73 <p><b><codeph> rls_string | rls_string8 | rls_byte | rls_word | rls_long | |
|
74 rls_double</codeph></b> <i><codeph><value></codeph></i> |
|
75 </p> |
|
76 <p><b>value ::=</b> |
|
77 </p> |
|
78 <p> <i><codeph><text> | <number></codeph></i></p> |
|
79 <p>where, </p> |
|
80 <table id="GUID-1B30B956-E495-5EE7-B5FA-33A336712087"> |
|
81 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
82 <tbody> |
|
83 <row> |
|
84 <entry><p> <varname>length</varname> </p> </entry> |
|
85 <entry><p>The optional maximum length of the <codeph>text</codeph> applicable |
|
86 to <codeph>rls_string</codeph> or <codeph>rls_string8</codeph> types only </p> </entry> |
|
87 </row> |
|
88 <row> |
|
89 <entry><p> <varname>cardinality</varname> </p> </entry> |
|
90 <entry><p>You can use the optional keyword qualifier "multi", which indicates |
|
91 that the localisable item may be used by more than one resource </p> </entry> |
|
92 </row> |
|
93 <row> |
|
94 <entry><p> <varname>symbolic-identifier</varname> </p> </entry> |
|
95 <entry><p>A unique ID for the localisable string or number </p> </entry> |
|
96 </row> |
|
97 <row> |
|
98 <entry><p> <varname>text</varname> </p> </entry> |
|
99 <entry><p>This is a string expression, which may include a string enclosed |
|
100 in double quotes (") and a character code enclosed in angle brackets (<>) </p> </entry> |
|
101 </row> |
|
102 <row> |
|
103 <entry><p> <varname>number</varname> </p> </entry> |
|
104 <entry><p>A numeric value for the literals <codeph>rls_byte</codeph>, <codeph>rls_word</codeph>, <codeph>rls_long</codeph> and <codeph>rls_double</codeph> </p> </entry> |
|
105 </row> |
|
106 </tbody> |
|
107 </tgroup> |
|
108 </table> |
|
109 <p>The following example shows how to define an RLS string and number: </p> |
|
110 <codeblock id="GUID-2B139C40-7B9C-502B-A709-ABEC93D3200E" xml:space="preserve">rls_string<32> STRING_1 "Example menu item"<0x2026> |
|
111 rls_byte multi NUMBER_1 17 |
|
112 </codeblock> |
|
113 <p>Characters are declared using the RLS type identifiers <codeph>rls_byte</codeph>, <codeph>rls_word</codeph> or <codeph>rls_long</codeph>. |
|
114 The type identifier to be used depends on the type of the structure member |
|
115 they will be included into. However, the value can be declared within single |
|
116 quotes. For example: </p> |
|
117 <codeblock id="GUID-A6595588-C05D-5883-B2A7-A7645270F657" xml:space="preserve"> |
|
118 rls_long hotkey_zoomin 'M'</codeblock> |
|
119 <p><b>Commenting RLS items </b> </p> |
|
120 <p>RLS items can be tagged with appropriate comments, which are placed just |
|
121 before each RLS item declaration. Optionally, if a <codeph>RESOURCE</codeph> declaration |
|
122 contains localisable data, a comment can precede the <codeph>RESOURCE</codeph> declaration. </p> |
|
123 <p>These comments save time and cost in localisation, and improve quality |
|
124 of localised text. If you supply more context information to the translators |
|
125 (maximum string length allowed, the details of the GUI in which their text |
|
126 will be displayed), the quality of the localised text is better. This will |
|
127 also reduce the need for re-translating the text. </p> |
|
128 <p>The localisation comments must be enclosed within the comment brackets |
|
129 /*&...*/. These comment brackets include a set of tags to provide more |
|
130 details about the RLS item. </p> |
|
131 <p>The resource compiler (<codeph>epocrc</codeph>) can warn if comments are |
|
132 missing. A Symbian platform licensee can configure the <codeph>epocrc</codeph> tool |
|
133 to emit warnings for missing comments through the <xref href="GUID-5FFBC0B0-FC6E-5D60-868B-064DBEB632E0.dita#GUID-5FFBC0B0-FC6E-5D60-868B-064DBEB632E0/GUID-014671B6-C19E-528A-984C-D8226375AC5A">epocrc configuration file</xref>. </p> |
|
134 <p>The following is a list of tags used within the comment brackets: </p> |
|
135 <ul> |
|
136 <li id="GUID-23B9063B-ED0F-538C-AAB2-6AAE1E2993E5"><p> <codeph>@localize</codeph>: |
|
137 This is an optional tag used to specify whether to allow the translator to |
|
138 change the string or not. The translator is allowed to change the RLS item, |
|
139 only if the tag is set to '<codeph>yes</codeph>'. To disallow any change to |
|
140 the RLS item, set it to '<codeph>no</codeph>'. By default, the translator |
|
141 is allowed to change an RLS item, if the corresponding localisation comment |
|
142 does not include this tag. </p> <p>For example: </p> <codeblock id="GUID-1FCD24E2-7F1A-59DA-BF72-6612D9ABF22A" xml:space="preserve">/*& |
|
143 @localize yes |
|
144 */ |
|
145 rls_string STRING_1 "Device locked" |
|
146 </codeblock> </li> |
|
147 <li id="GUID-C674C795-950D-5432-8908-89F20F85A891"><p> <codeph>@description</codeph>: |
|
148 This is mandatory tag used to provide a description about the RLS item. This |
|
149 tag is used to provide the following information to the translator: </p> <ul> |
|
150 <li id="GUID-D0519085-B8A6-5658-A7F5-D2891B033B89"><p>The context in which |
|
151 the string is used and the purpose of the dialog or views using the string. </p> </li> |
|
152 <li id="GUID-9591133E-65C3-5D7B-9B72-DE1D1B790FEE"><p>Its relationships with |
|
153 other strings. </p> </li> |
|
154 <li id="GUID-E8405E4E-A0AC-53B9-A6B5-630B276B7B7E"><p>If the localisable strings |
|
155 represent file names or URIs that must point to existing objects, describe |
|
156 those objects briefly. </p> </li> |
|
157 <li id="GUID-11F95E12-CECE-5311-8800-673FF4B3C059"><p>If the RLS items are |
|
158 tagged with <codeph>@restriction other</codeph>, describe the restriction. </p> </li> |
|
159 </ul> </li> |
|
160 <li id="GUID-A84221B4-5327-551A-8F92-ECC5B8D13F33"><p> <codeph>@restriction</codeph>: |
|
161 This is an optional tag used to specify the scope of the RLS item. The possible |
|
162 values for this tag are: </p> <ul> |
|
163 <li id="GUID-4C0C8F25-F6D0-550C-9A31-B96B483AD408"><p> <codeph>uri</codeph> to |
|
164 specify that the localisable item is an URI. If the URI changes, the resulting |
|
165 URI should be a valid URI pointing to the correct object. The description |
|
166 in the comment bracket can be used to give more details about the URI. </p> </li> |
|
167 <li id="GUID-F5FEC94D-DA1C-509E-A0BD-E35260F399E6"><p> <codeph>file</codeph> to |
|
168 specify that the localisable item is a file name. If the file changes, the |
|
169 ROM must be rebuilt to accommodate the change. If the full path of the file |
|
170 is not given, the description for the localisable item can be used to provide |
|
171 more details. </p> </li> |
|
172 <li id="GUID-1115504D-14E8-5997-9FF8-F79EC650943A"><p> <codeph>trademark</codeph> to |
|
173 specify that the localisable item is a trademark. The trademark differs from |
|
174 country to country, but any change to it must be subject to trademark owner's |
|
175 rules. The description for the localisable item can be used to provide more |
|
176 details. </p> </li> |
|
177 <li id="GUID-FF6ABAD0-2BC3-5445-842A-282CBEC7DBFE"><p> <codeph>other</codeph> to |
|
178 specify that the localisable item is none of the above. In such a case, the |
|
179 description should include the effects of changing the localisable item and |
|
180 the constraints. </p> </li> |
|
181 </ul> <p>For example: </p> <codeblock id="GUID-BD4F8548-23BD-5945-882E-54ABE0AF4468" xml:space="preserve">/*& @description Must point to the happy bugle wave file, used as a ring tone and displayed to the user in the ring-tone selection dialog. |
|
182 @localize yes |
|
183 @restriction file |
|
184 */ |
|
185 rls_string STRING_2 "happy bugle.wav" |
|
186 </codeblock> </li> |
|
187 <li id="GUID-E2630A48-BC17-51FD-B6F0-EA425DD64318"><p> <codeph>@uicontext</codeph>: |
|
188 This is a mandatory tag for RLS items defined using <codeph>rls_string</codeph> and <codeph>rls_string8</codeph>. |
|
189 It is used to specify the type of widget in which the localisable item is |
|
190 used. There is a list of UI contexts for Symbian developers, which are extended |
|
191 by the platform suppliers. The Symbian developers must use the values defined |
|
192 for the platforms on which they are developing. </p> <p>The possible values |
|
193 for this tag are: </p> <ul> |
|
194 <li id="GUID-E21387AA-B4DA-59CD-9C96-783DEA10529B"><p> <codeph>notvisible</codeph> to |
|
195 specify that the item does not appear in the UI. </p> </li> |
|
196 <li id="GUID-800536F2-9524-5A8F-8919-A57962346F91"><p> <codeph>pluginname</codeph> to |
|
197 specify that the string is the name of an ECOM (or other) plug-in. </p> </li> |
|
198 <li id="GUID-26670A96-7A7C-558F-8747-5D77F24EA2EE"><p> <codeph>system</codeph> to |
|
199 specify that the item may appear in the UI, but the component that supplies |
|
200 the UI does not mandate where. </p> </li> |
|
201 <li id="GUID-1E32422C-C7AE-59CE-9E55-956614395349"><p> <codeph>errortext</codeph> to |
|
202 specify that the string is used by the error resolver. </p> </li> |
|
203 <li id="GUID-C3AAA814-0117-5083-A272-81968E7399E9"><p> <codeph>fragment</codeph> to |
|
204 specify that the item is part of a string that appears in the UI. For example, |
|
205 a list separator. </p> </li> |
|
206 <li id="GUID-4A0EADED-7CB0-5105-AEBF-B0ACC10A1F21"><p> <codeph>appname</codeph> to |
|
207 specify the application name in the <codeph>APP_REGISTRATION_INFO</codeph> structure. </p> </li> |
|
208 <li id="GUID-7527BBBE-3AA6-5CCD-A124-4977316B5814"><p> <codeph>appgroup</codeph> to |
|
209 specify the application group in the <codeph>APP_REGISTRATION_INFO</codeph> structure. </p> </li> |
|
210 </ul> <p>For example: </p> <codeblock id="GUID-876F09BF-98DA-5CFD-8E8F-C5CB57A60A52" xml:space="preserve">/*& |
|
211 @uicontext pluginname |
|
212 */ |
|
213 rls_string STRING_1 "Device locked" |
|
214 </codeblock> </li> |
|
215 <li id="GUID-9E1F9CBA-14EC-52F1-8A8B-6AA3C6B07762"><p> <codeph>@group</codeph>: |
|
216 This is an optional tag used to group strings together. For example, you can |
|
217 group all strings that appear in the same view together. To group strings |
|
218 under a group, you have to define a group using the following syntax: </p> <codeblock id="GUID-05A63AFD-99A4-5C8E-9C62-8BB8F70D10DD" xml:space="preserve">@tagvalue group <your-group-name> [group-description]</codeblock> <p>Where, <varname>your-group-name</varname> is a name for the group, and <varname>group-description</varname> is an |
|
219 optional description about the group. </p> <p>For example, </p> <codeblock id="GUID-425EEBDF-432B-5D2E-A524-EBF0DB8A7187" xml:space="preserve">/*& |
|
220 @tagvalue group lock_dialog |
|
221 */ |
|
222 </codeblock> <p>You can use the group defined above as follows: </p> <codeblock id="GUID-1A81832F-679D-5DC0-A237-C4496A3610CA" xml:space="preserve">/*& |
|
223 @localize yes |
|
224 @group lock_dialog |
|
225 */ |
|
226 rls_string STRING_1 "Device locked" |
|
227 </codeblock> </li> |
|
228 <li id="GUID-A2E5B5EB-8EC1-5632-A576-DFBE1DD879C5"><p> <codeph>@uispec</codeph>: |
|
229 This is an optional tag used to specify where in the specifications document |
|
230 the RLS item appears. </p> <p>For example: </p> <codeblock id="GUID-E7E2A822-6840-5F69-A5F7-864882AABC4F" xml:space="preserve">/*& |
|
231 @uispec UIQ/ringtones-specification.doc/4.31 |
|
232 */ |
|
233 rls_string STRING_2 "happy bugle.wav" |
|
234 </codeblock> </li> |
|
235 </ul> |
|
236 <p><b>Creating new RLS comment tags </b> </p> |
|
237 <p>Apart from the pre-defined set of tags listed above, you can also declare |
|
238 a new tag and use it in the localisation comments. Tags are declared in resource |
|
239 header files (<filepath>.rh</filepath>). You can configure the <codeph>epocrc</codeph> tool |
|
240 to recognise the comment definitions from such files through the <filepath>epocrc.config</filepath> configuration |
|
241 file. For more information, refer to <xref href="GUID-5FFBC0B0-FC6E-5D60-868B-064DBEB632E0.dita#GUID-5FFBC0B0-FC6E-5D60-868B-064DBEB632E0/GUID-014671B6-C19E-528A-984C-D8226375AC5A">epocrc |
|
242 configuration file format</xref>. </p> |
|
243 <p>The following is the BNF description for declaring a new tag: </p> |
|
244 <p><i><codeph><tag-declaration></codeph></i> |
|
245 </p> |
|
246 <p><b>tag-declaration ::=</b> |
|
247 </p> |
|
248 <p><b><codeph>@declaretag </codeph></b><i><codeph><tag-type> <new-tag-name> |
|
249 [<description>] <tag-type></codeph></i> |
|
250 </p> |
|
251 <p><b>tag-type ::= |
|
252 </b> </p> |
|
253 <p><b><codeph>single | multiple | text | void</codeph></b></p> |
|
254 <p>Where, <varname>tag-type</varname> is used to specify the type value the |
|
255 tag can take. If you want the tag to take a single value, use "<codeph>single</codeph> " |
|
256 as the tag type. If you want the tag to take a single value from a set of |
|
257 values, use "<codeph>multiple</codeph> " as the tag type. For example, the <codeph>@uicontext</codeph> tag |
|
258 is of <codeph>multiple</codeph> type. If you want the tag not to take any |
|
259 value, use "<codeph>void</codeph> " as the tag type. If you want the tag to |
|
260 take free text, use "<codeph>text</codeph> " as the tag type. For example, |
|
261 the <codeph>@description</codeph> tag is of <codeph>text</codeph> type. </p> |
|
262 <p>For example, the following declares a tag called “visible” of type single: </p> |
|
263 <codeblock id="GUID-8C1F4921-CF51-57FA-8DDB-A9106B0AAF26" xml:space="preserve">@declaretag single visible</codeblock> |
|
264 <p>If you had declared the tag as <codeph>single</codeph> or <codeph>multiple</codeph>, |
|
265 you must declare its values. Value declaration is not required for other tag |
|
266 types. </p> |
|
267 <p>The following is the BNF description for declaring values for a tag: </p> |
|
268 <p><i><codeph><tag-value-declaration></codeph></i></p> |
|
269 <p> |
|
270 <b>tag-value-declaration ::=</b></p> |
|
271 <p> |
|
272 <b>@tagvalue</b> <i><codeph><tag-name> <list-of-values></codeph></i></p> |
|
273 <p>Where, <varname>tag-name</varname> is the name of the tag declared earlier. |
|
274 If the tag is of multiple type, the <varname>list-of-values</varname> lists |
|
275 a set of values for the tag, otherwise a single value must be specified. </p> |
|
276 <p>For example, the following declares that the permitted value for the visible |
|
277 tag is "yes": </p> |
|
278 <codeblock id="GUID-EE092FF4-FA7A-591B-9103-5875CE422224" xml:space="preserve">@tagvalue visible yes</codeblock> |
|
279 <p>After declaring the values for the tag, you must specify whether the tag |
|
280 is required or optional for an RLS item. The BNF description for this is as |
|
281 follows: </p> |
|
282 <p><i><codeph><tag-required-statement></codeph></i></p> |
|
283 <p><b> |
|
284 tag-required-statement ::=</b></p> |
|
285 <p> |
|
286 <b>@tagrequired</b><i><codeph> <tag-name> <rls-type-identifier> |
|
287 <tag-optional-statement></codeph></i> |
|
288 </p> |
|
289 <p><b>tag-optional-statement ::=</b></p> |
|
290 <p> |
|
291 <b>@tagoptional</b> <i><codeph><tag-name>=[<default-value>] <rls-type-identifier> |
|
292 <rls-type-identifier></codeph></i> |
|
293 </p> |
|
294 <p><b>rls-type-identifier ::=</b></p> |
|
295 <p> |
|
296 <b><codeph>rls_string | rls_string8 | rls_byte | rls_word | rls_long | |
|
297 rls_double</codeph></b></p> |
|
298 <p>Where, <varname>tag-name</varname> is the name of the declared tag, <varname>default-value</varname> is |
|
299 the default value used for optional tags. </p> |
|
300 <p>For example, the following declares that the visible tag is optional, and |
|
301 has a default value of “yes” for rls_string items: </p> |
|
302 <codeblock id="GUID-8793CE31-6D00-5607-AD69-77E7FC7B5D54" xml:space="preserve">@tagoptional visible=yes rls_string</codeblock> |
|
303 </conbody></concept> |
|