<?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>&lt;rls-file&gt;</codeph></i>
</p>
<p><b>rls-file ::=</b>
    </p>
<p><i><codeph>&lt;rls-entry&gt;* &lt;rls-entry&gt;</codeph></i>
</p>
<p><b>rls-entry ::=</b>
   </p>
<p> <i><codeph>&lt;rls-item&gt; &lt;rls-item&gt;</codeph></i>
</p>
<p><b>rls-item ::=</b>
    </p>
<p><i><codeph>&lt;type&gt;[&lt;length&gt; &lt;cardinality&gt;] &lt;symbolic-identifier&gt;
&lt;value&gt; &lt;type&gt;</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>&lt;value&gt;</codeph></i>
</p>
<p><b>value ::=</b>
   </p>
<p> <i><codeph>&lt;text&gt; | &lt;number&gt;</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 (&lt;&gt;) </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&lt;32&gt; STRING_1 "Example menu item"&lt;0x2026&gt;
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
/*&amp;...*/. 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">/*&amp;
@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">/*&amp; @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">/*&amp;
@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 &lt;your-group-name&gt; [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">/*&amp;
@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">/*&amp;
@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">/*&amp;
@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>&lt;tag-declaration&gt;</codeph></i>
</p>
<p><b>tag-declaration ::=</b>
    </p>
<p><b><codeph>@declaretag </codeph></b><i><codeph>&lt;tag-type&gt; &lt;new-tag-name&gt;
[&lt;description&gt;] &lt;tag-type&gt;</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>&lt;tag-value-declaration&gt;</codeph></i></p>
<p>
<b>tag-value-declaration ::=</b></p>
<p>
    <b>@tagvalue</b> <i><codeph>&lt;tag-name&gt; &lt;list-of-values&gt;</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>&lt;tag-required-statement&gt;</codeph></i></p>
<p><b>
tag-required-statement ::=</b></p>
<p>
    <b>@tagrequired</b><i><codeph> &lt;tag-name&gt; &lt;rls-type-identifier&gt;
&lt;tag-optional-statement&gt;</codeph></i>
</p>
<p><b>tag-optional-statement ::=</b></p>
<p>
    <b>@tagoptional</b> <i><codeph>&lt;tag-name&gt;=[&lt;default-value&gt;] &lt;rls-type-identifier&gt;
&lt;rls-type-identifier&gt;</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>