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-file ::=: <rls-entry>*

<rls-entry>

rls-entry ::=: <rls-item>

<rls-item>

rls-item ::=: <type>[<length> <cardinality>] <symbolic-identifier> <value>

<type>

type ::=: rls_string | rls_string8 | rls_byte | rls_word | rls_long | rls_double

<value>

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:

@localize: 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 'yes'. To disallow any change to the RLS item, set it to 'no'. By default, the translator is allowed to change an RLS item, if the corresponding localisation comment does not include this tag.

For example:
```
/*&
@localize yes
*/
rls_string STRING_1 "Device locked"
```
@description: 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:
- The context in which the string is used and the purpose of the dialog or views using the string.
- Its relationships with other strings.
- If the localisable strings represent file names or URIs that must point to existing objects, describe those objects briefly.
- If the RLS items are tagged with @restriction other, describe the restriction.
@restriction: This is an optional tag used to specify the scope of the RLS item. The possible values for this tag are:
- uri 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.
- file 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.
- trademark 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.
- other 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.
For example:
```
/*& @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"
```
@uicontext: This is a mandatory tag for RLS items defined using rls_string and rls_string8. 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 OS developers, which are extended by the platform suppliers. The developers must use the values defined for the platforms on which they are developing.

The possible values for this tag are:
- notvisible to specify that the item does not appear in the UI.
- pluginname to specify that the string is the name of an ECOM (or other) plug-in.
- system to specify that the item may appear in the UI, but the component that supplies the UI does not mandate where.
- errortext to specify that the string is used by the error resolver.
- fragment to specify that the item is part of a string that appears in the UI. For example, a list separator.
- appname to specify the application name in the APP_REGISTRATION_INFO structure.
- appgroup to specify the application group in the APP_REGISTRATION_INFO structure.
For example:
```
/*&
@uicontext dialog_title
*/
rls_string STRING_1 "Device locked"
```
@group: 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:
```
@tagvalue group <your-group-name> [group-description]
```
Where, your-group-name is a name for the group, and group-description is an optional description about the group.

For example,
```
/*&
@tagvalue group lock_dialog
*/
```
You can use the group defined above as follows:
```
/*&
@localize yes
@group lock_dialog
*/
rls_string STRING_1 "Device locked"
```
@uispec: This is an optional tag used to specify where in the specifications document the RLS item appears.

For example:
```
/*&
@uispec UIQ/ringtones-specification.doc/4.31
*/
rls_string STRING_2 "happy bugle.wav"
```

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>

tag-declaration ::=: @declaretag<tag-type> <new-tag-name> [<description>]

<tag-type>

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>

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>

tag-required-statement ::=: @tagrequired <tag-name> <rls-type-identifier>

<tag-optional-statement>

tag-optional-statement ::=: @tagoptional <tag-name>=[<default-value>] <rls-type-identifier>

<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