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.
The following literals can be used to define an RLS item:
|
<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,
|
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'
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"
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