diff -r 4816d766a08a -r f345bda72bc4 Symbian3/PDK/Source/GUID-141633B8-A3D4-5BBB-97C5-3D928746ECE7.dita --- a/Symbian3/PDK/Source/GUID-141633B8-A3D4-5BBB-97C5-3D928746ECE7.dita Tue Mar 30 11:42:04 2010 +0100 +++ b/Symbian3/PDK/Source/GUID-141633B8-A3D4-5BBB-97C5-3D928746ECE7.dita Tue Mar 30 11:56:28 2010 +0100 @@ -1,303 +1,303 @@ - - - - - -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 platform 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> -

-

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 + + + + + +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 platform 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 developers, which are extended +by the platform suppliers. The Symbian 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 pluginname +*/ +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 \ No newline at end of file