Text string localization text-string-localization

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=, avoiding client-side localization, and allowing applications to switch locales simply by sending the appropriate locale= value with the IS text requests.

Scope section-a03f48e3bc0e4ab281909a2bd441a3c2

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

Any subelement 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.

Any single- or double-quoted attribute value, except the values of the coords= and shape= attributes.
The value of any target.*.label and target.*.userdata property.
The value of any property.

String syntax section-d12320edf300409f8e17565b143acafc

Localization-enabled string elements in the image catalog consist of one or more localized strings, each preceded by a localization token.

[ defaultString ]*{ localizationToken localizedString }
^loc= locStr ^
Internal locale ID for the localizedString following this localizationToken .
Localized string.
String to be used for unknown locales.

The locId must be ASCII and may not include ‘^’.

The ‘^’ may occur anywhere in substrings with or without HTTP-encoding. The server matches the entire localizationToken ^loc=locId^ pattern to separate substrings.

The stringElements, which do not include at least one localizationToken, are not considered for localization.

The translation map section-f7ce3df91b724adf95cee44eac4915d4

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.

The translation process section-a2a8a3e5850f4f7c9d2318267afe98a2

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 the example request:

val1=111 str1=Dutch1 val2=value2 str2=Dutch2 str3=Dutch3

Unknown locales section-26dfeefbd60345de94bbfeaaf7741223

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. Therefore, the following is returned if this translation map is applied to the request /is/image/myCat/myItem?req=&locale=ja:

val1=111 str1=Default1 val2=value2 str2= str3=Default3

Examples section-ae6ff7fb90754b839f04ed08aadffa3f

Language families

Multiple locId values may be associated with each locale in the translation map. The reason is that it allows supporting country-specific or region-specific variations (for example, US English versus UK English) for select stringElements while handling most contents with common base locales (for example, International English).

For the example, support is added for US-specific English ( *locId* EUS) and UK-specific English ( *locId* EUK), to support the occasional alternative spelling. If EUK or EUS does not exist, it falls 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.

The attribute::LocaleStrMap would look like this:


The following table describes the output for some representative stringElement and locale combinations:

Output string

en, en_us, en_uk

de, de_at, de_de

all others





en, en_us


de, de_de


all others






^ loc=en^English^loc=USE^US-English^loc=D^German^loc=DDE^Deutsch

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


de, de_at, de_de

all others