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 automatically substitutes locale-specific images and other content where available.
The locale is specified in Image Serving requests with the locale= command.
NOTEScope
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:
en,_E,|en_us,_E,|en_uk,_E,|fr,_F,|de,_D,|de_at,_D,|de_de,_D,|,_E,
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 (that is, 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 is returned for all requests with unknown locale= values.
Examples
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 are 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 |
| w2 | myImg-W2, myImg-W, myImg |
| m1 | myImg-M1, myImg-M, myImg |
| m2 | myImg-M2, myImg-M, myImg |
| all others | myImg |
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 |
|---|---|
| fr | 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 |