Text string localization

Last update: August 31, 2023

CREATED FOR:

  • Developer
  • User

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

Text string localization is applied to all string elements which include the localization token ^loc= *locId*^ in the following catalog fields:

Catalog fieldString element in field
catalog::ImageSet

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.

catalog::MapAny single- or double-quoted attribute value, except the values of the coords= and shape= attributes.
catalog::TargetsThe value of any target.*.label and target.*.userdata property.
catalog::UserDataThe value of any property.

String syntax

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 ^
locIdInternal locale ID for the localizedString following this localizationToken .
localizedStringLocalized string.
defaultStringString 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

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

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

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