<?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

/*&...*/. 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>