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.
locale is specified in Image Serving requests with the
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:
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
attribute::LocaleMap consists of a list of input locales (matching the values specified with
locale=), each with none or more output locale suffixes (
attribute::LocaleMap might look like this:
/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.
Given the example above, the server first looks for the
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. If no match is found, the server returns an error or a default image (if so configured).
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
If a translation map does not specify a default translation rule, an error will be returned for all requests with unknown
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 (
m2 for two middle-eastern variants, and
w3 for three Western locales), except that images are shared for
w3. Unknown locales are mapped only to the generic collection and do not have access to locale-specific images.
The following table illustrates which catalog entries will be considered, and the order in which they are considered for the generic input ID
|locale||Catalog IDs to be searched|
myImg-W2, myImg-W, myImg
myImg-M1, myImg-M, myImg
myImg-M2, myImg-M, 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
_3 suffix. Images specific to French locales may have
_23 suffix, and images specific to German locales may have
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
|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
myImg_1, myImg_2, myImg_3