Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Resource localisable strings

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.

Defining RLS items

The following literals can be used to define an RLS item:

Name Description

rls_string

Use this literal to define a 16-bit Unicode string

rls_string8

Use this literal to define an 8-bit Unicode string

rls_byte

Use this literal to define an 8-bit number

rls_word

Use this literal to define a 16-bit number

rls_long

Use this literal to define a long number

rls_double

Use this literal to define a decimal number

BNF description

<rls-file> ::=
<rls-entry>*
<rls-entry> ::=
<rls-item>
<rls-item> ::=
<type>[<length> <cardinality>] <symbolic-identifier> <value>
<type> ::=
"rls_string" | "rls_string8" | "rls_byte" | "rls_word" | "rls_long" | "rls_double"
<value> ::=
<text> | <number>

where,

length

The optional maximum length of the text applicable to rls_string or rls_string8 types only

cardinality

You can use the optional keyword qualifier "multi", which indicates that the localisable item may be used by more than one resource

symbolic-identifier

A unique ID for the localisable string or number

text

This is a string expression, which may include a string enclosed in double quotes (") and a character code enclosed in angle brackets (<>)

number

A numeric value for the literals rls_byte, rls_word, rls_long and rls_double

The following example shows how to define an RLS string and number:

rls_string<32> STRING_1 "Example menu item"<0x2026>
rls_byte multi NUMBER_1 17

Characters are declared using the RLS type identifiers rls_byte, rls_word or rls_long. 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:

    rls_long hotkey_zoomin 'M'

Commenting RLS items

RLS items can be tagged with appropriate comments, which are placed just before each RLS item declaration. Optionally, if a RESOURCE declaration contains localisable data, a comment can precede the RESOURCE declaration.

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.

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.

The resource compiler (epocrc) can warn if comments are missing. A Symbian OS licensee can configure the epocrc tool to emit warnings for missing comments through the epocrc configuration file.

The following is a list of tags used within the comment brackets:

Creating new RLS comment tags

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 (.rh). You can configure the epocrc tool to recognise the comment definitions from such files through the epocrc.config configuration file. For more information, refer to epocrc configuration file format.

The following is the BNF description for declaring a new tag:

<tag-declaration> ::=
"@declaretag"<tag-type> <new-tag-name> [<description>]
<tag-type> ::=
"single" | "multiple" | "text" | "void"

Where, tag-type is used to specify the type value the tag can take. If you want the tag to take a single value, use "single" as the tag type. If you want the tag to take a single value from a set of values, use "multiple" as the tag type. For example, the @uicontext tag is of multiple type. If you want the tag not to take any value, use "void" as the tag type. If you want the tag to take free text, use "text" as the tag type. For example, the @description tag is of text type.

For example, the following declares a tag called “visible” of type single:

@declaretag single visible

If you had declared the tag as single or multiple, you must declare its values. Value declaration is not required for other tag types.

The following is the BNF description for declaring values for a tag:

<tag-value-declaration> ::=
"@tagvalue"<tag-name> <list-of-values>

Where, tag-name is the name of the tag declared earlier. If the tag is of multiple type, the list-of-values lists a set of values for the tag, otherwise a single value must be specified.

For example, the following declares that the permitted value for the visible tag is "yes":

@tagvalue visible yes

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:

<tag-required-statement> ::=
"@tagrequired" <tag-name> <rls-type-identifier>
<tag-optional-statement> ::=
"@tagoptional" <tag-name>=[<default-value>] <rls-type-identifier>
<rls-type-identifier> ::=
"rls_string" | "rls_string8" | "rls_byte" | "rls_word" | "rls_long" | "rls_double"

Where, tag-name is the name of the declared tag, default-value is the default value used for optional tags.

For example, the following declares that the visible tag is optional, and has a default value of “yes” for rls_string items:

@tagoptional visible=yes rls_string