BEA Logo BEA WebLogic Commerce Server Release 3.1.1

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy


   WebLogic Commerce Server Doc Home   |   Product Catalog Management   |   Previous Topic   |   Next Topic   |   Contents   |   Index

Product Catalog Internationalization Support


Internationalization is an important part of the development process for companies doing business in both domestic and overseas markets. However, providing a multilingual product catalog via the Web adds complexity to the internationalization effort and may require additional modifications to the catalog architecture. Although the strings displayed to users can easily be translated by editing various property files (such as, maintaining dynamic multilingual catalog content and allowing the user to specify a language preference can be more difficult.

Note: For more information about the file, see Using the File.

To meet these objectives, the BEA WebLogic Commerce Server includes several features that you can utilize to build a multilingual product catalog. These features will help you internationalize your system and render a localized version of each category or item on a Web page, including text descriptions, images, item cost, type of currency, and so on. This topic describes these features in detail.

Note: It is important that you understand the architecture of the product catalog before reading about support for internationalization. For more information about the product catalog architecture, see Catalog Architecture and Services.

This topic includes the following sections:


Support for Multiple Languages

BEA recognizes that an e-commerce Web site may need to support international users. To meet this requirement, a company may want to display their product catalog items in several languages. For example, a Canadian company may display product items to their potential customers in both English and French. Some European companies may support ten or more languages to localize their pages and ensure the success of their e-business. This section explains how you can use the built-in language attribute to support multiple languages.

Language and Country Codes

The best practice language descriptions defined by RFC 1766 include a two letter language code, optionally followed by a two letter country code. (These language codes are obtained from the ISO 639 and ISO 3166 standards, respectively.) For example, a language description of "en-uk" indicates that the language is English and that the country is the United Kingdom.

About the CatalogRequest Object

The first parameter to every product catalog API is a CatalogRequest object, which contains a language attribute. The language attribute is a String that should conform to the format described in Language and Country Codes.

The language attribute of the CatalogRequest object informs the product catalog system about the language a user would like to receive. For example, if the catalog contains both an "en-US" and an "en-GB" version of SKU 1001 and the incoming CatalogRequest object has specified the language as "en-GB", then code can be written to return the "en-GB" version of SKU 1001 according to the user's language preference.

An example of setting the language on a CatalogRequest object is shown in Listing 7-1.

Listing 7-1 Setting the Language on a CatalogRequest Object

CatalogManager cm = null;
// lookup the CatalogManager using JNDI (omitted)

CatalogRequest cr = cm.createCatalogRequest();


Once you have set the language attribute, you can use the CatalogRequest object in other API calls, as shown in Listing 7-2.

Listing 7-2 Using the CatalogRequest Object

final int viewSize = 50;
ViewIterator subIterator = cm.getCategoryManager(cr).
getSubCategories(cr, CategoryKey.ROOT, viewSize);

Persisting Language Information to the Catalog Database

Each product item, category, and product image also has a language attribute. This individualized information is stored in the database and later used to retrieve information based on a user's specified language preference.

Product Items and Categories

Items and categories within the product catalog each have a language attribute as defined in the Dublin Core Standard. The format of the language attribute for product items and categories should conform to that described in Language and Country Codes.

Note: For more information about WebLogic Commerce Server and the Dublin Core Standard, see The Catalog Schema Is Based on Dublin Core Standard.

An example of creating a new item with a language specification and persisting it to the database is shown in Listing 7-3.

Listing 7-3 Creating and Persisting an Item with a Language Specification

MutableProductItem mutItem = CatalogFactory.createMutableProductItem(new ProductItemKey( "SKU001")); 

// set the language attributes on the item 

ImageInfo smallImage = mutItem.getImage(SMALL_IMAGE_INDEX);
mutItem.setImage(SMALL_IMAGE_INDEX , smallImage);

// create the new item 

CatalogManager cm = null; 

// lookup the CatalogManager using JNDI (omitted) 

// create an administration catalog request object 
// (required for write access to the catalog)

CatalogRequest cr = cm.createAdminCatalogRequest(); 

// create the new item using the ProductItemManager 

cm.getProductItemManager().createItem(cr, mutItem);

Image Support

As shown in Listing 7-3, each image associated with an item or category also has a language attribute for storing mulilingual images. This attribute allows you to provide a description of the product item or category in one language, while displaying an image that corresponds to the version of the item that is available for speakers of that language (that is, the item version for a particular country or region). In this case, the appropriate image would be chosen based on the language specified in the CatalogRequest object to ensure that customers are previewing the version of the product for their country.

Note: For more information about the CatalogRequest object, see About the CatalogRequest Object.

Limiting Search Results by Language

The default CatalogQueryManager Tier 1 Service Provider provides you with the ability to limit search results by language. To activate this feature, set the language attribute on the CatalogRequest object to non-null, using the format described in Language and Country Codes. An example is shown in Listing 7-1.

If CatalogRequest.getLanguage() is non-null, then search results will be limited to the language specified (exact, case-sensitive matches only). If CatalogRequest.getLanguage() is null, then search results are not automatically limited to a language.

The CatalogRequest.getLanguage()method originally contains a value set by the catalog.request.language.default property of the file. In the version of this file that ships with the WebLogic Commerce Server product, the catalog.request.language.default property is commented out, meaning that the default language is null. This portion of the default file is shown in Listing 7-4.

Listing 7-4 Default Language for Catalog Requests as Set in the File

# If this entry is not specified the default language will be set # to null.
# catalog.request.language.default=en_US

Note: In the current release, the language attribute of the CatalogRequest object is only used when searching the catalog (if non-null). The other APIs do not use this attribute and will return catalog items irrespective of that specified in the language attribute.

Additionally, the language attribute can be used in expression-based queries when CatalogRequest.getLanguage() is null (for example, "description like '*black*' && (language like '*en*' || language == null) ").


Using the Catalog Architecture to Maintain Internationalized Product Catalogs

Depending on your business and technical requirements, you can use the catalog architecture in several different ways to maintain internationalized product catalogs. The criteria for selection of an effective method include:

This section describes four methods for maintaining internationalized product catalogs.

Method 1: Filtering Product Catalog Content

The first method for internationalization of product catalogs:

If you want to filter product catalog content, each JSP template will require modification. All language versions of a category or product item will be returned from the database, but the JSP template will contain logic that essentially filters the information shown to the user based on their specified language preference. If the language attribute of the category or item does not match that of the user's specified language, the item or category is not displayed. Else, if the language attribute does match that of the user's selected language, you will want to display that item or category.

Note: If you use this method, be sure you also add code in your JSP templates to display the correct number of returned results (that is, the number of results for the specified language only) to the user.

The content filtering method is simple because it does not require EJB coding or redeployment, and still allows you to utilize the Administration Tools and DBLoader utility as in the out-of-the-box product. Also, if multilingual items are not mapped into non-country specific categories, it is not necessary to filter items in addition to the categories. For example, if the current category has a language attribute value of "en-GB", then you can assume that all the items within this category will also have a language of "en-GB".

Note: For more information about the DBLoader utility available in the WebLogic Commerce Server, see Using the Product Catalog Database Loader.

Method 2: Parsing Language-Specific Data

Although the content filtering method previously described is simple, it is not the most elegant method for maintaining internationalized product catalogs. As a more complex but elegant solution, the second method for internationalization of product catalogs:

Two Languages

Recall that in the product catalog JSP templates, there are two JSPs (containing two separate images) that are responsible for displaying item summary and item detail information. Out of the box, these pages contain very similar content. However, they can be customized to render a product item in two different languages. For example, instead of clicking the View Details link on the item summary page (which loads the item details page with nearly the same information), the user could click a link that allows them to view the item in French instead of English. The parsing logic for extracting the language-specific data from the product item attributes would be invoked from the relevant display JSP.

Note: For more information about the product catalog JSP templates, see The Product Catalog JSP Templates and Tag Library.

Multiple Languages

If it is necessary to display information about product items in more than two languages, a master identifier can be used instead, as a reference (proxy) to several language-specific identifiers. For example, a master identifier of 100 can be thought of as a category and used to locate a number of language-defined subcategories. A language-specific identifier of 100A can contain English versions of a product item, an identifier of 100B can contain German versions, and so on. All but the master identifier should be marked as invisible and orphaned to ensure that the user cannot reach them directly by searching or by browsing the product catalog.

Note: To facilitate multilingual searches, language-specific identifiers should just be marked orphaned and not marked invisible, as the user should be able to reach these items through searches.

To display the categories in several languages, the language-specific identifiers (or subcategories) of the master identifier should be encoded within a field of the master identifier. The display JSP used to render the master identifier should be modified to perform a JSP include of the localized version of the master identifier. To prevent the user from browsing the localized categories, their top-level parent category can be set to something other than root. Alternatively, if the localized categories are required to be accessible from the Administration Tools, the template JSPs used to display the siblings and child categories can be modified to exclude the top-level parent of the localized categories.

Then, within the display JSPs for the product item, the master identifier can be parsed to locate the correct language-specific item (identifier) and its data substituted.

Method 3: Multiple Product Catalog Instances

The third method for internationalization of product catalogs:

Before learning more about the multiple instances method, it is important that you understand what a schema file is and how it can be used for product catalog internationalization.

Figure 7-1 shows the same product catalog architecture that is described in Catalog Architecture and Services.

Figure 7-1 Product Catalog Architecture

A schema file is the primary means for deploying multiple product catalogs and is therefore one way to support internationalization. An instance of a Tier 2 Service Provider can be bound to a schema file, which exists in the deployment descriptor for the Tier 2 session bean. The schema file contains the names of the database tables, columns, and SQL statements that the Tier 2 Service Provider will use for persistence.

By deploying multiple instances of the CatalogManager session bean (and the Tier 1 and Tier 2 session beans) multiple catalog instances can be deployed. Binding the new Tier 2 session beans to different schema files provides for the maintenance of independent, language-specific catalogs. Each CatalogManager should be bound to a JNDI name appropriate for the language of the catalog. For example:

When a catalog function is required, a CatalogManager should be looked up using the appropriate JNDI name.

Note: The WebLogic Commerce Server Administration Tools work against a CatalogManager instance bound to the JNDI name com.beasys.commerce.ebusiness.catalog.CatalogManager, which is not customizable. Therefore, organizations using the multiple instances method will need to administer additional catalogs via SQL or develop their own GUI tools.

Although the two product catalogs are totally independent, the category and item identifiers between catalogs should be the same to ensure that data can be easily updated using the DBLoader utility.

Note: For more information about the DBLoader utility available in the WebLogic Commerce Server, see Using the Product Catalog Database Loader.

Method 4: Language-Based Service Routing

The fourth method for internationalization of product catalogs:

Instead of creating multiple instances, redeploying the Services, and binding the Services to different schema files as described in Method 3: Multiple Product Catalog Instances, you can simply create and redeploy a new CatalogManager session bean to return an instance of a Tier 1 Service based on the language specified in the CatalogRequest object.

The new CatalogManager session bean should extend the existing CatalogManager to examine the language attribute of the incoming CatalogRequest object. By deriving a new class from the CatalogManagerImpl object and overridding the Service accessor method, you can easily implement language-based service routing, as shown in the following example:

public ProductItemManager getProductItemManager (CatalogRequest request)

The overridden getProductItemManager() method will return an instance of a ProductItemManager session bean, which delgates to a JdbcProductItemManager session bean. The JdbcProductItemManager, in turn, is bound to a schema file for the language required.

Note: Using the language-based service routing method, the WebLogic Commerce Server's Administration Tools will work as expected, because there is still only one CatalogManager instance.