The EStore.International
module extends the repository definitions for existing item types that have properties that require translation (category
, product
, SKU
, etc.). It also adds several new helper item types that are used to store translated content for the existing item types. These two mechanisms work together to replace properties that require translation with derived properties that obtain their values based on the customer’s current locale. The following section describes this process in detail.
Extending the Repository Definitions
The International
module makes the following modifications to each item type that has properties that require translation:
New properties are created that correspond to the item type’s translatable properties. For example, if an item type has three translatable properties, three new properties are created. The new properties are named using the convention
<
translatableProperty
>Default
. They are tied to the original properties’ database columns and represent the default translations for the properties (thereby allowing us to redefine the original properties as derived properties). For example, theSKU
item descriptor has four properties that require translation:displayName
,description
,size
, andcolor
. TheInternational
module adds four new properties —displayNameDefault
,descriptionDefault
,sizeDefault
, andcolorDefault
— to theSKU
item descriptor. These four properties are tied to thedisplay_name
,description
,sku_size
, andcolor
columns, respectively, where the default translations for the content (English for Commerce Reference Store) are stored.A
translations
property is added to the item type. Thetranslations
property is a map whose key is alocale
and whose value is an item of type<
baseType
>Translation
, described below. Note that thelocale
key does not have to be a fully qualified locale. In fact, Commerce Reference Store only uses the language code portion of the locale. We’ll coverlocale
in more detail below as well.
The International
module defines a set of helper item types that use the naming convention <
baseType
>Translation
, where <
baseType
>
refers to an existing item type. A corresponding <
baseType
>Translation
item type is defined for all existing item types that have translatable properties (for example, a skuTranslation
item type is created to correspond with the sku
item type, a productTranslation
item type is created to correspond with the product
item type, and so on). <
baseType
>Translation
items function as containers for locale-specific content. As such, each <
baseType
>Translation
item type has properties that correspond to the translatable properties of its base item type. For example, the sku
item type has four properties that require translation — displayName
, description
, size
, and color
— therefore, the skuTranslation
item also has four properties for displayname
, description
, size
, and color
.
Each <baseType>Translation
item type has its own table in the database, where each row represents a single <basetype>Translation
item with a unique ID. For example, the crs_sku_xlate
table contains all the skuTranslation
items, the crs_prd_xlate
table contains all the productTranslation
items, and so on.
Note: For a detailed list of <
baseType
>Translation
item types created by the International
module, see Translation Items Created by the International Module.
Every base item (in other words, every SKU, every product, every category, and so on) is tied, through its translations
property, to one or more <
baseType
>Translation
items. For each base item, a separate <
baseType
>Translation
item exists for each locale (with the exception of the default locale, which we will get to momentarily). The following illustration shows three sku
items and six corresponding skuTranslation
items which contain translated content for two locales, Spanish and German:
To create the relationships that connect a base item to its <
baseType
>Translation
items, the International
module changes the definitions of the translatable properties in the existing item types. The new definitions specify that each translatable property is a derived property whose value is determined as follows:
Use the current locale to look up a corresponding
<
baseType
>Translation
item in thetranslations
property map. The property derivation attempts to find a best match. First, it searches thelocale
keys for a match on the entire locale with a variant, then it searches for a match on the locale without a variant, and finally it searches on just the language code.If a
<
baseType
>Translation
item exists for the current locale, use its value for the property.If a
<
baseType
>Translation
item doesn’t exist for the current locale, or its value for the property is null, use the<
translatableProperty
>Default
value instead.
The following illustration is a graphic representation of the repository changes made by the International
module. It shows a sku
base item with two supporting skuTranslation
items, one for German and the other for Spanish. The sku
base item has been modified to add four <
translatableProperty
>Default
properties: displayNameDefault
, descriptionDefault
, sizeDefault
, and colorDefault
. The sku
base item has also been modified to add the translations
property, which contains the map connecting the base sku
item to its German and Spanish translation items. Finally, the displayName
, description
, size
, and color
property definitions have been changed to derived properties.
Repository Item Translation Examples
The following illustration shows how the sku.displayName
property is derived for a store that has English (default), German, and Spanish translations:
In this illustration, the following happens:
giftListShop.jsp
requests thesku.displayName
property for a SKU. The locale for the request is determined according to the rules described in Determining a Customer’s Locale and, in this example, isDE_de
.The catalog repository finds the corresponding
skuTranslation
item using thesku.translations
property map. The repository determines that, for aDE_de
locale, the GermanskuTranslation
item should be referenced.The catalog repository returns the
displayName
property from the GermanskuTranslation
item.
This next illustration shows what happens when a locale is specified that doesn’t exist in the sku.translations
property map.
In this illustration, the following happens:
giftListShop.jsp
requests thesku.displayName
property for a SKU. The locale for the request is determined according to the rules described in Determining a Customer’s Locale and, in this example, isUS_en
.The catalog repository derives the display name for the SKU using the
sku.translations
property map. The repository determines that noskuTranslation
item exists for theUS_en
locale, so it returns the value from thesku.displayNameDefault
property, which for Commerce Reference Store is the English translation.
Repository Item Translation Benefits
The approach Commerce Reference Store takes to handling the translation of repository items offers several significant benefits over other internationalization approaches:
An application may switch between international and non-international modes without requiring any JSP page changes. The same property names are used in the JSP page code and each repository derives the appropriate language as necessary.
Adding another language is accomplished by adding more
<
baseType
>Translation
items, referred to by their base items through the appropriatelocale
key. No database schema changes are required to add additional languages.
Translation Items Created by the International Module
Several repository definition files in the International
module’s config.jar
file (<
ATG10dir>/CommerceReferenceStore/Store/EStore/International/config/config.jar
) define the <
baseType
>Translation
items for Commerce Reference Store.
The /atg/commerce/catalog/custom/customCatalog.xml
file defines the following <
baseType
>Translation
items for the catalog repository:
categoryTranslation
(stored in thecrs_cat_xlate
table)productTranslation
(stored in thecrs_prd_xlate
table)skuTranslation
(stored in thecrs_sku_xlate
table)featureTranslation
(stored in thecrs_fea_xlate
table)asSeenInTranslation
(stored in thecrs_asi_xlate
table)promotionalContentTranslation
(stored in thecrs_prmcnt_xlate
table)
The /atg/commerce/pricing/pricingModels.xml
file defines the following <
baseType
>Translation
items for the promotions repository:
promotionTranslation
(stored in thecrs_prm_xlate
table)closenessQualifierTranslation
(storedcrs_cq_xlate
table)
The /atg/seo/SEORepository.xml
file defines the following <
baseType
>Translation
items for the SEO repository:
SEOTranslation
(stored in thecrs_seo_xlate
table)
The /atg/store/stores/storeText.xml
file defines the following <
baseType
>Translation
items for the store text items held in the StoreRepository
:
storeTextTranslation
(stored in thecrs_txt_xlate
table)storeLongTextTranslation
(stored in thecrs_txt_long_xlate
table)
A Note About the StoreRepository
The /atg/store/stores/StoreRepository
holds store
items as well as storeText
and storeLongText
items. store
items define properties for store locations such as address, phone, and fax numbers. storeText
and storeLongText
items hold text-based content that appears on the static information pages such as About Us, Corporate Site, Careers, and so on (storeText
holds content that is 256 characters or less; storeLongText
holds content that is greater than 256 characters).
To view storeText
and storeLongText
items:
Start the Business Control Center.
Expand Merchandising, and then click Browse.
Click the arrow next to Store Text.