--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-141633B8-A3D4-5BBB-97C5-3D928746ECE7.dita Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,303 @@
+<?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-141633B8-A3D4-5BBB-97C5-3D928746ECE7" xml:lang="en"><title>Resource
+localisable strings</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>Resource localisable strings (RLS) are defined in the resource files. Each
+RLS item definition is a new-line separated entry in the resource file, using
+literals to define a localisable string, number or character. </p>
+<p><b>Defining RLS items </b> </p>
+<p>The following literals can be used to define an RLS item: </p>
+<table id="GUID-F30AE1BF-B383-5A66-99C1-AD2110C41368">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<thead>
+<row>
+<entry>Name</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p> <i>rls_string</i> </p> </entry>
+<entry><p>Use this literal to define a 16-bit Unicode string </p> </entry>
+</row>
+<row>
+<entry><p> <i>rls_string8</i> </p> </entry>
+<entry><p>Use this literal to define an 8-bit Unicode string </p> </entry>
+</row>
+<row>
+<entry><p> <i>rls_byte</i> </p> </entry>
+<entry><p>Use this literal to define an 8-bit number </p> </entry>
+</row>
+<row>
+<entry><p> <i>rls_word</i> </p> </entry>
+<entry><p>Use this literal to define a 16-bit number </p> </entry>
+</row>
+<row>
+<entry><p> <i>rls_long</i> </p> </entry>
+<entry><p>Use this literal to define a long number </p> </entry>
+</row>
+<row>
+<entry><p> <i>rls_double</i> </p> </entry>
+<entry><p>Use this literal to define a decimal number </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+<p><b>BNF description </b> </p>
+<p><i><codeph><rls-file></codeph></i>
+</p>
+<p><b>rls-file ::=</b>
+ </p>
+<p><i><codeph><rls-entry>* <rls-entry></codeph></i>
+</p>
+<p><b>rls-entry ::=</b>
+ </p>
+<p> <i><codeph><rls-item> <rls-item></codeph></i>
+</p>
+<p><b>rls-item ::=</b>
+ </p>
+<p><i><codeph><type>[<length> <cardinality>] <symbolic-identifier>
+<value> <type></codeph></i>
+</p>
+<p><b>type ::=</b>
+ </p>
+<p><b><codeph> rls_string | rls_string8 | rls_byte | rls_word | rls_long |
+rls_double</codeph></b> <i><codeph><value></codeph></i>
+</p>
+<p><b>value ::=</b>
+ </p>
+<p> <i><codeph><text> | <number></codeph></i></p>
+<p>where, </p>
+<table id="GUID-1B30B956-E495-5EE7-B5FA-33A336712087">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<tbody>
+<row>
+<entry><p> <varname>length</varname> </p> </entry>
+<entry><p>The optional maximum length of the <codeph>text</codeph> applicable
+to <codeph>rls_string</codeph> or <codeph>rls_string8</codeph> types only </p> </entry>
+</row>
+<row>
+<entry><p> <varname>cardinality</varname> </p> </entry>
+<entry><p>You can use the optional keyword qualifier "multi", which indicates
+that the localisable item may be used by more than one resource </p> </entry>
+</row>
+<row>
+<entry><p> <varname>symbolic-identifier</varname> </p> </entry>
+<entry><p>A unique ID for the localisable string or number </p> </entry>
+</row>
+<row>
+<entry><p> <varname>text</varname> </p> </entry>
+<entry><p>This is a string expression, which may include a string enclosed
+in double quotes (") and a character code enclosed in angle brackets (<>) </p> </entry>
+</row>
+<row>
+<entry><p> <varname>number</varname> </p> </entry>
+<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>
+</row>
+</tbody>
+</tgroup>
+</table>
+<p>The following example shows how to define an RLS string and number: </p>
+<codeblock id="GUID-2B139C40-7B9C-502B-A709-ABEC93D3200E" xml:space="preserve">rls_string<32> STRING_1 "Example menu item"<0x2026>
+rls_byte multi NUMBER_1 17
+</codeblock>
+<p>Characters are declared using the RLS type identifiers <codeph>rls_byte</codeph>, <codeph>rls_word</codeph> or <codeph>rls_long</codeph>.
+The type identifier to be used depends on the type of the structure member
+they will be included into. However, the value can be declared within single
+quotes. For example: </p>
+<codeblock id="GUID-A6595588-C05D-5883-B2A7-A7645270F657" xml:space="preserve">
+ rls_long hotkey_zoomin 'M'</codeblock>
+<p><b>Commenting RLS items </b> </p>
+<p>RLS items can be tagged with appropriate comments, which are placed just
+before each RLS item declaration. Optionally, if a <codeph>RESOURCE</codeph> declaration
+contains localisable data, a comment can precede the <codeph>RESOURCE</codeph> declaration. </p>
+<p>These comments save time and cost in localisation, and improve quality
+of localised text. If you supply more context information to the translators
+(maximum string length allowed, the details of the GUI in which their text
+will be displayed), the quality of the localised text is better. This will
+also reduce the need for re-translating the text. </p>
+<p>The localisation comments must be enclosed within the comment brackets
+/*&...*/. These comment brackets include a set of tags to provide more
+details about the RLS item. </p>
+<p>The resource compiler (<codeph>epocrc</codeph>) can warn if comments are
+missing. A Symbian platform licensee can configure the <codeph>epocrc</codeph> tool
+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>
+<p>The following is a list of tags used within the comment brackets: </p>
+<ul>
+<li id="GUID-23B9063B-ED0F-538C-AAB2-6AAE1E2993E5"><p> <codeph>@localize</codeph>:
+This is an optional tag used to specify whether to allow the translator to
+change the string or not. The translator is allowed to change the RLS item,
+only if the tag is set to '<codeph>yes</codeph>'. To disallow any change to
+the RLS item, set it to '<codeph>no</codeph>'. By default, the translator
+is allowed to change an RLS item, if the corresponding localisation comment
+does not include this tag. </p> <p>For example: </p> <codeblock id="GUID-1FCD24E2-7F1A-59DA-BF72-6612D9ABF22A" xml:space="preserve">/*&
+@localize yes
+*/
+rls_string STRING_1 "Device locked"
+</codeblock> </li>
+<li id="GUID-C674C795-950D-5432-8908-89F20F85A891"><p> <codeph>@description</codeph>:
+This is mandatory tag used to provide a description about the RLS item. This
+tag is used to provide the following information to the translator: </p> <ul>
+<li id="GUID-D0519085-B8A6-5658-A7F5-D2891B033B89"><p>The context in which
+the string is used and the purpose of the dialog or views using the string. </p> </li>
+<li id="GUID-9591133E-65C3-5D7B-9B72-DE1D1B790FEE"><p>Its relationships with
+other strings. </p> </li>
+<li id="GUID-E8405E4E-A0AC-53B9-A6B5-630B276B7B7E"><p>If the localisable strings
+represent file names or URIs that must point to existing objects, describe
+those objects briefly. </p> </li>
+<li id="GUID-11F95E12-CECE-5311-8800-673FF4B3C059"><p>If the RLS items are
+tagged with <codeph>@restriction other</codeph>, describe the restriction. </p> </li>
+</ul> </li>
+<li id="GUID-A84221B4-5327-551A-8F92-ECC5B8D13F33"><p> <codeph>@restriction</codeph>:
+This is an optional tag used to specify the scope of the RLS item. The possible
+values for this tag are: </p> <ul>
+<li id="GUID-4C0C8F25-F6D0-550C-9A31-B96B483AD408"><p> <codeph>uri</codeph> to
+specify that the localisable item is an URI. If the URI changes, the resulting
+URI should be a valid URI pointing to the correct object. The description
+in the comment bracket can be used to give more details about the URI. </p> </li>
+<li id="GUID-F5FEC94D-DA1C-509E-A0BD-E35260F399E6"><p> <codeph>file</codeph> to
+specify that the localisable item is a file name. If the file changes, the
+ROM must be rebuilt to accommodate the change. If the full path of the file
+is not given, the description for the localisable item can be used to provide
+more details. </p> </li>
+<li id="GUID-1115504D-14E8-5997-9FF8-F79EC650943A"><p> <codeph>trademark</codeph> to
+specify that the localisable item is a trademark. The trademark differs from
+country to country, but any change to it must be subject to trademark owner's
+rules. The description for the localisable item can be used to provide more
+details. </p> </li>
+<li id="GUID-FF6ABAD0-2BC3-5445-842A-282CBEC7DBFE"><p> <codeph>other</codeph> to
+specify that the localisable item is none of the above. In such a case, the
+description should include the effects of changing the localisable item and
+the constraints. </p> </li>
+</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.
+@localize yes
+@restriction file
+*/
+rls_string STRING_2 "happy bugle.wav"
+</codeblock> </li>
+<li id="GUID-E2630A48-BC17-51FD-B6F0-EA425DD64318"><p> <codeph>@uicontext</codeph>:
+This is a mandatory tag for RLS items defined using <codeph>rls_string</codeph> and <codeph>rls_string8</codeph>.
+It is used to specify the type of widget in which the localisable item is
+used. There is a list of UI contexts for Symbian developers, which are extended
+by the platform suppliers. The Symbian developers must use the values defined
+for the platforms on which they are developing. </p> <p>The possible values
+for this tag are: </p> <ul>
+<li id="GUID-E21387AA-B4DA-59CD-9C96-783DEA10529B"><p> <codeph>notvisible</codeph> to
+specify that the item does not appear in the UI. </p> </li>
+<li id="GUID-800536F2-9524-5A8F-8919-A57962346F91"><p> <codeph>pluginname</codeph> to
+specify that the string is the name of an ECOM (or other) plug-in. </p> </li>
+<li id="GUID-26670A96-7A7C-558F-8747-5D77F24EA2EE"><p> <codeph>system</codeph> to
+specify that the item may appear in the UI, but the component that supplies
+the UI does not mandate where. </p> </li>
+<li id="GUID-1E32422C-C7AE-59CE-9E55-956614395349"><p> <codeph>errortext</codeph> to
+specify that the string is used by the error resolver. </p> </li>
+<li id="GUID-C3AAA814-0117-5083-A272-81968E7399E9"><p> <codeph>fragment</codeph> to
+specify that the item is part of a string that appears in the UI. For example,
+a list separator. </p> </li>
+<li id="GUID-4A0EADED-7CB0-5105-AEBF-B0ACC10A1F21"><p> <codeph>appname</codeph> to
+specify the application name in the <codeph>APP_REGISTRATION_INFO</codeph> structure. </p> </li>
+<li id="GUID-7527BBBE-3AA6-5CCD-A124-4977316B5814"><p> <codeph>appgroup</codeph> to
+specify the application group in the <codeph>APP_REGISTRATION_INFO</codeph> structure. </p> </li>
+</ul> <p>For example: </p> <codeblock id="GUID-876F09BF-98DA-5CFD-8E8F-C5CB57A60A52" xml:space="preserve">/*&
+@uicontext pluginname
+*/
+rls_string STRING_1 "Device locked"
+</codeblock> </li>
+<li id="GUID-9E1F9CBA-14EC-52F1-8A8B-6AA3C6B07762"><p> <codeph>@group</codeph>:
+This is an optional tag used to group strings together. For example, you can
+group all strings that appear in the same view together. To group strings
+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
+optional description about the group. </p> <p>For example, </p> <codeblock id="GUID-425EEBDF-432B-5D2E-A524-EBF0DB8A7187" xml:space="preserve">/*&
+@tagvalue group lock_dialog
+*/
+</codeblock> <p>You can use the group defined above as follows: </p> <codeblock id="GUID-1A81832F-679D-5DC0-A237-C4496A3610CA" xml:space="preserve">/*&
+@localize yes
+@group lock_dialog
+*/
+rls_string STRING_1 "Device locked"
+</codeblock> </li>
+<li id="GUID-A2E5B5EB-8EC1-5632-A576-DFBE1DD879C5"><p> <codeph>@uispec</codeph>:
+This is an optional tag used to specify where in the specifications document
+the RLS item appears. </p> <p>For example: </p> <codeblock id="GUID-E7E2A822-6840-5F69-A5F7-864882AABC4F" xml:space="preserve">/*&
+@uispec UIQ/ringtones-specification.doc/4.31
+*/
+rls_string STRING_2 "happy bugle.wav"
+</codeblock> </li>
+</ul>
+<p><b>Creating new RLS comment tags </b> </p>
+<p>Apart from the pre-defined set of tags listed above, you can also declare
+a new tag and use it in the localisation comments. Tags are declared in resource
+header files (<filepath>.rh</filepath>). You can configure the <codeph>epocrc</codeph> tool
+to recognise the comment definitions from such files through the <filepath>epocrc.config</filepath> configuration
+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
+configuration file format</xref>. </p>
+<p>The following is the BNF description for declaring a new tag: </p>
+<p><i><codeph><tag-declaration></codeph></i>
+</p>
+<p><b>tag-declaration ::=</b>
+ </p>
+<p><b><codeph>@declaretag </codeph></b><i><codeph><tag-type> <new-tag-name>
+[<description>] <tag-type></codeph></i>
+</p>
+<p><b>tag-type ::=
+</b> </p>
+<p><b><codeph>single | multiple | text | void</codeph></b></p>
+<p>Where, <varname>tag-type</varname> is used to specify the type value the
+tag can take. If you want the tag to take a single value, use "<codeph>single</codeph> "
+as the tag type. If you want the tag to take a single value from a set of
+values, use "<codeph>multiple</codeph> " as the tag type. For example, the <codeph>@uicontext</codeph> tag
+is of <codeph>multiple</codeph> type. If you want the tag not to take any
+value, use "<codeph>void</codeph> " as the tag type. If you want the tag to
+take free text, use "<codeph>text</codeph> " as the tag type. For example,
+the <codeph>@description</codeph> tag is of <codeph>text</codeph> type. </p>
+<p>For example, the following declares a tag called “visible” of type single: </p>
+<codeblock id="GUID-8C1F4921-CF51-57FA-8DDB-A9106B0AAF26" xml:space="preserve">@declaretag single visible</codeblock>
+<p>If you had declared the tag as <codeph>single</codeph> or <codeph>multiple</codeph>,
+you must declare its values. Value declaration is not required for other tag
+types. </p>
+<p>The following is the BNF description for declaring values for a tag: </p>
+<p><i><codeph><tag-value-declaration></codeph></i></p>
+<p>
+<b>tag-value-declaration ::=</b></p>
+<p>
+ <b>@tagvalue</b> <i><codeph><tag-name> <list-of-values></codeph></i></p>
+<p>Where, <varname>tag-name</varname> is the name of the tag declared earlier.
+If the tag is of multiple type, the <varname>list-of-values</varname> lists
+a set of values for the tag, otherwise a single value must be specified. </p>
+<p>For example, the following declares that the permitted value for the visible
+tag is "yes": </p>
+<codeblock id="GUID-EE092FF4-FA7A-591B-9103-5875CE422224" xml:space="preserve">@tagvalue visible yes</codeblock>
+<p>After declaring the values for the tag, you must specify whether the tag
+is required or optional for an RLS item. The BNF description for this is as
+follows: </p>
+<p><i><codeph><tag-required-statement></codeph></i></p>
+<p><b>
+tag-required-statement ::=</b></p>
+<p>
+ <b>@tagrequired</b><i><codeph> <tag-name> <rls-type-identifier>
+<tag-optional-statement></codeph></i>
+</p>
+<p><b>tag-optional-statement ::=</b></p>
+<p>
+ <b>@tagoptional</b> <i><codeph><tag-name>=[<default-value>] <rls-type-identifier>
+<rls-type-identifier></codeph></i>
+</p>
+<p><b>rls-type-identifier ::=</b></p>
+<p>
+ <b><codeph>rls_string | rls_string8 | rls_byte | rls_word | rls_long |
+rls_double</codeph></b></p>
+<p>Where, <varname>tag-name</varname> is the name of the declared tag, <varname>default-value</varname> is
+the default value used for optional tags. </p>
+<p>For example, the following declares that the visible tag is optional, and
+has a default value of “yes” for rls_string items: </p>
+<codeblock id="GUID-8793CE31-6D00-5607-AD69-77E7FC7B5D54" xml:space="preserve">@tagoptional visible=yes rls_string</codeblock>
+</conbody></concept>
\ No newline at end of file