Text string localization allows image catalogs to contain multiple locale-specific representations for the same string value.
The server returns to the client the representation matching the locale specified with locale=
, thereby avoiding client-side localization and allowing applications to switch locales simply by sending the appropriate locale=
value with the IS text requests.
Text string localization is applied to all string elements which include the localization token ^loc= *
locId*^
in the following catalog fields:
Catalog field | String element in field |
---|---|
catalog::ImageSet |
Any sub-element containing a translatable string (delimited by any combination of separators ',' ';' ':' and/or the start/end of the field). A 0xrrggbb color value at the beginning of a localizable field is excluded from localization and passed through without modification. |
catalog::Map |
Any single- or double-quoted attribute value, except the values of the coords= and shape= attributes. |
catalog::Targets |
The value of any target.*.label and target.*.userdata property. |
catalog::UserData |
The value of any property. |
Localization-enabled string
elements in the image catalog consist of one or more localized strings, each preceded by a localization token.
stringElement |
[ defaultString ]*{ localizationToken localizedString } |
localizationToken |
^loc= locStr ^ |
locId |
Internal locale ID for the localizedString following this localizationToken . |
localizedString |
Localized string. |
defaultString |
String to be used for unknown locales. |
locId
must be ASCII and may not include ‘^’.
‘^’ may occur anywhere in sub-strings with or without HTTP-encoding. The server matches the entire localizationToken
^loc=locId^
pattern to separate substrings.
stringElements
which do not include at least one localizationToken
are not considered for localization.
attribute::LocaleStrMap
defines the rules used by the server to determine which localizedStrings
to return to the client. It consists of a list of input locales
(matching the values specified with locale=
), each with none or more internal locale ids ( locId
). For example:
attribute::LocaleStrMap= en,E|nl,N|de,D|,
Empty locId
values indicate that the defaultString
should be returned, if available.
Refer to the description of attribute::LocaleStrMap
for details.
Given the example translation map above and the request /is/image/myCat/myItem?req=&locale=nl
, the server first looks for " nl
" in the locale map. The matched entry nl,N
indicates that for each stringElement
, the localizedString
marked with ^loc=N^
should be returned. If this localizationToken
is not present in the stringElement
, an empty value is returned.
Let’s say catalog::UserData
for myCat/myItem
contains the following (line breaks inserted for clarity):
val1=111?? str1=Default1^loc=N^Dutch1^loc=D^German1?? val2=value2?? str2=^loc=E^English2^loc=N^Dutch2^loc=D^German2?? str3=Default3^loc=N^Dutch3^loc=D^German3
The server would return the following in response to our example request:
val1=111 str1=Dutch1 val2=value2 str2=Dutch2 str3=Dutch3
In the above example, attribute::LocaleStrMap
has an entry with an empty locale
value. The server uses this entry to handle all locale=
values which are not explicitly specified otherwise in the translation map.
The example translation map specifies that in such a case the defaultString
should be returned if available. Thus, the following would be returned if this translation map were applied to the request /is/image/myCat/myItem?req=&locale=ja
:
val1=111 str1=Default1 val2=value2 str2= str3=Default3
Language families
Multiple locId
values may be associated with each locale
in the translation map. This allows supporting country-specific or region-specific variations (e.g US English vs UK English) for select stringElements
while handling most contents with common base locales (e.g. International English).
For our example, we want to add support for US-specific English ( *
locId* EUS
) and UK-specific English ( *
locId* EUK
), to support the occasional alternative spelling. If EUK or EUS do not exist, we would fall back to E. Similarly, Austrian-specific German variants ( DAT
) could be made available where needed while returning common German localizedStrings
(marked with D
) most of the time.
attribute::LocaleStrMap
would look like this:
en,E|en_us,EUS,E|en_uk,EUK,E|de,D|de_at,DAT,D|de_de,D
The following table describes the output for some representative stringElement
and locale
combinations:
stringElement | locale | Output string |
---|---|---|
^loc=E^English^loc=D^German |
en, en_us, en_uk de, de_at, de_de all others |
English German - |
^loc=E^English^loc=UKE^UK-English^loc=D^German^loc=DAT^Austrian |
en, en_us en_uk de, de_de de_at all others |
English UK-English German Austrian - |
^ loc=en^English^loc=USE^US-English^loc=D^German^loc=DDE^Deutsch Note that for this example the locId DDE does not exist in attribute::LocaleStrMap , and thus the substring associated with this locId is never returned. |
en, en_uk en_us de, de_at, de_de all others |
English US-English German - |