Object ID translation

Image Serving provides a mechanism to translate external object ids to locale-specific object (catalog) IDs. The primary application is for providing locale-specific content and content shared amongst multiple locales without the client application needing to know the locale-specific object IDs.

The application can be written using only global object IDs and Image Serving will automatically substitute locale-specific images and other content where available.

The locale is specified in Image Serving requests with the locale= command.


Object ID translation is only applicable for catalog-based use of Image Serving. File names cannot be translated.


All references to entries in image, SVG, and static content catalogs are considered for translation-fonts and ICC profile references are not translated. In addition to the object in the path of /is/image and /is/static requests, these commands and catalog attributes are subject to ID translation: src=, mask=, template=, defaultImage=, attribute::DefaultImage, and attribute::Watermark.

The ID translation map

attribute::LocaleMap defines the rules used by the server to determine the ID of the localized content, given as inputs the generic object ID and the locale= value.

attribute::LocaleMap consists of a list of input locales (matching the values specified with locale=), each with none or more output locale suffixes ( *locSuffixes*).

For example, attribute::LocaleMap might look like this:


The request /is/image/myCat/myImg?locale=de_de would return the image associated with the catalog entry myCat/myImg_D (assuming that such a catalog entry exists).

Refer to the description of attribute::LocaleMap for details.

The translation process

Given the example above, the server first looks for the locale " de_de" in the ID translation map. It then iterates over the locSuffixes associated with this entry-in this case " _D" and “” (empty suffix). For each iteration, the suffix is appended to the image ID and the resulting id tested for existence in the catalog. If found, that catalog entry is used, otherwise the next one is tested. For this example, these entries are checked: myCat/myImg_D, and myCat/myImg. If no match is found, the server returns an error or a default image (if so configured).

Unknown locales

In the above example, attribute::LocaleMap includes an empty locale which defines the default translation rule, used for unknown locale= values (i.e. those not explicitly listed in the translation map). If this translation map were applied to the request /is/image/myCat/myImg?locale=ja, it would resolve to myCat/myImg_E, if it exists, or otherwise myCat/myImg.

If a translation map does not specify a default translation rule, an error will be returned for all requests with unknown locale= values.


Multi-tiered lookup

It is often desirable to group locales (for example, European, Middle Eastern, North American) to address regional standards. This can be achieved with a multi-tiered lookup.

For this example, we want to support collections for Western and Middle Eastern use. Both collections are based on the generic image collection, and both add or modify some images. Both collections are then further refined for specific locales ( m1, m2 for two middle-eastern variants, and w1, w2, and w3 for three Western locales), except that images are shared for w1 and w3. Unknown locales are mapped only to the generic collection and do not have access to locale-specific images.

attribute::LocaleMap: w1,-W,|w2,-W2,-W,|w3,-W,|m1,-M1,-M,|m2,-M2,-M,|,

The following table illustrates which catalog entries will be considered, and the order in which they are considered for the generic input ID myImg:

locale Catalog IDs to be searched

w1, w3

myImg-W, myImg


myImg-W2, myImg-W, myImg


myImg-M1, myImg-M, myImg


myImg-M2, myImg-M, myImg

all others


Search for specific IDs

Some image naming conventions may not support generic image IDs internally. The generic IDs from the request must always be mapped to a specific ID in the catalog; often the exact specific ID may not be known.

For this example, images for all languages may have _1, _2, or _3 suffix. Images specific to French locales may have _22 or _23 suffix, and images specific to German locales may have _470 or _480 suffix.

attribute::LocaleMap: ,_1,_2,_3|fr,_22,_23,_1,_2,_3|de,_470,_480,_1,_2,_3| de_at,_470,_480,_1,_2,_3| de_de,_470,_480,_1,_2,_3

The following table illustrates which catalog entries are considered, and the order in which they are considered for the generic input ID myImg:

locale Output IDs to be searched


myImg_22, myImg_23, myImg_1, myImg_2, myImg_3

de , de_at , de_de

myImg_470, myImg_480, myImg_1, myImg_2, myImg_3

all others

myImg_1, myImg_2, myImg_3

See also

attribute::LocaleMap , attribute::DefaultLocale, locale=, req=xlate

On this page