Supporting globalization

The WebSphere Commerce architecture is designed to support globalization. Globalization is the proper design and execution of systems, software, services, and procedures so that one instance of software, running on a single server or end-user machine, can process multilingual data and present culturally correct data in a multicultural environment such as the Internet. WebSphere Commerce is translated to the following 13 languages:

Translated languages

Language & Country or Region	Identifier
English (United States)	en_US
French (France)	fr_FR
German (Germany)	de_DE
Italian (Italy)	it_IT
Spanish (Spain)	es_ES
Portuguese (Brazil)	pt_BR
Chinese-simplified (China)	zh_CN
Chinese-traditional (Taiwan)	zh_TW
Korean (Korea, South)	ko_KR
Japanese (Japan)	ja_JP
Russian (Russia)	ru_RU
Romanian (Romania)	ro_RO
Polish (Poland)	pl_PL

This includes the software, documentation, user interfaces such as Management Center, WebSphere Commerce Accelerator, and the Administration Console, and the samples. We can add support for other languages. We can translate many of the features of the site, such as product descriptions, messages, and text on the pages.

WebSphere Commerce includes several features that allow you to create a site that can be tailored to fit the needs of an international or culturally diverse customer base. Using Java technology and a flexible database schema, some of the cultural characteristics of the site that can vary depending on location or customer preference are:

Language

A store can be viewed in more than one language. For example, we can allow users to choose the language in which they would like to view the site, or we can want to automatically select a default language, which is the store's default language.

Currency

A store can display prices in more than one currency. In WebSphere Commerce, the selection of a specific currency is not related to the selection of a particular language.

Cultural format

Data can be displayed in various customizable formats. Customers from different cultures can have different expectations about how certain information should be displayed. For example, a decimal number can be indicated by using either a comma or a period, depending on the language, country, or region of the customer.

Address

Addresses can be entered, stored, and displayed in various formats, to conform to different international standards.

Taxation

Taxation rules can be defined for different jurisdictions. This includes rules for sales and other business taxes.

Shipping

Shipping rules and carriers can be defined for different jurisdictions.

Payment method

Payment methods can be defined for different jurisdictions.

Prices

The price can be set in one currency and a conversion factor can convert from this currency to other currencies, or the price can be set per currency.

Online catalog content

Product and category descriptions, attributes, and images can be varied across locations. WebSphere Commerce allows a merchant to manage online catalog content for selectable display format by defining each format within the language table. We can also maintain a master product catalog that can be shared by a number of stores.

The WebSphere Commerce database allows you the flexibility to create and maintain internationally recognizable data by using Unicode UTF-8 encoding, (IBM i) or UCS-2, which can be converted into most international encoding formats when sent to a web browser. For a working sample of a site globalized for many countries, see any of the starter stores.

The Administration Console and WebSphere Commerce Accelerator support globalized usage. These tools display in any of the thirteen national languages that WebSphere Commerce supports, however, we might need to maximize the WebSphere Commerce Accelerator window to view menu items which are otherwise truncated. The Administration Console and WebSphere Commerce Accelerator use a programming model that allows for additional languages to be added without affecting the general functioning or look-and-feel of the pages.

We can translate the WebSphere Commerce tools into other languages, just as you would translate a store or a website. To translate the tools modify the appropriate properties files located under the following directory: workspace_dir\stores\properties\com\ibm\commerce\tools\

Note: If you do not want to restart WebSphere Application Server every time a properties file is changed, perform the following steps:

1. Open the WebSphere Commerce configuration file.

2. Change the value of developmentMode to "true". Default is "false".

3. Restart WebSphere Application Server

Starter stores

The starter stores provide a foundation to create the store. All the starter stores demonstrate how we can create and maintain a globalized site.

The starter stores allow customers to select the language in which they would like to view the site. The list is displayed in a list on the left frame throughout the site. Customers can navigate through the site, viewing it in the language of their choice.

The starter stores use the single template for all stores and languages programming model. Each supported language has its own property file, which contains the translated text and messages for that language. All store archives contain: publishNLS.properties and publishNLS_en_US.properties. These are used in the publish wizard.

Note: _ locale represents all the supported locales of the store.

Within the property file, a number of elements of the page are translated:

Text

Textual page content.

Labels

Form field labels.

Messages

Error, status, and confirmation messages.

Alternate text

For images, Java applets, and other embedded objects.

Resource bundles

From the command context, the locale is used to retrieve the storetext Properties Java object, which obtains its values from the storetext_locale.properties file in the appropriate locale specific directory. The template then has access to each of the properties as needed, through the use of the getString() method of the ResourceBundle object.

Determining the character set

The character set in which the text is displayed in a browser is defined in the property file using the ENCODESTATEMENT property. For example, the storetext_en_US.properties file contains the statement:

ENCODESTATEMENT = text/html; charset=ISO_8859-1

Because encoding is specified within the property file instead of in the JSP template, the character set can be different for each language. The default character encoding for theWebSphere Application Server is located in:

• WAS_installdir\bin\wsinstance\propdefaults\encoding.properties

The character-encoding of the generated JSP page is set using the following statement in the JSP template:

<%response.setContentType(storetext.getString("ENCODESTATEMENT"));%>

for JTSL:

<c:set property="contentType"
target="${pageContext.response}">
<fmt:message key="ENCODESTATEMENT" bundle="${storeText}" />
</c:set>

Note: When setLocal is called using:

(<fmt:setLocale value="${CommandContext.locale}" />)

the default character encoding is selected from the WebSphere Application Server. JSTL takes the last set of character encoding as the returned encoding that will be sent to the web browser. in most cases people will not have problem with this. they only get into trouble when dealing with bidi languages where they can have multiple ISO character encodings per locale.

At run time, each requested JavaServer Page includes the EnvironmentSetup.jsp or EnvironmentSetup.jspf file. The command context is retrieved from this file.

Note: This is for stores created with the Store Creation Wizard only. When a seller creates a store, this is not a regular store publish, and additional store language assets beyond the store default language are not carried over into the store. So, if a seller adds a supported language to a store, the store assets for that language are not available. If a supported language is going to be added to a store, ensure that the translated assets (properties files) are available to the store or the store pages will not function correctly.

Displaying translated images

The locale and language are retrieved at run time to determine the correct folder in which to look for the image file. The template may look for the file ConsumerDirect\ language_Locale\images\go_button.gif , where language_Locale is replaced by the display format from the command context. For example, the resulting page will display the image: ConsumerDirect\en_US\images\colors\color1\go_button.gif.

Displaying catalog content

The catalog contains multiple translations, one for each supported locale. At run time, the command context is sent through a data bean to determine which translation to retrieve from the database and display on the page.

Resource bundles and property files

Resource bundles and property files allow you to maintain collections of Java objects that are locale-specific for our JavaServer Pages. When the page needs a locale-specific resource, such as a form field label, a graphical user interface message, or a value for a drop-down menu, the page can load it from the resource bundle or property file that is appropriate for the selected locale, allowing the customer to view the page in their own language. In this way, we can create JSP templates that are largely independent of the customer's locale, isolating all of the locale-specific information in the resource bundles or property files.

Although resource bundles and property files perform similar functions, there are some differences in the manner in which they are processed. The following table shows some of the important differences between resource bundles and property files:

Property files	ListResource bundles
Text files	Compiled format
Slight performance degradation	Slight performance boost
If a property file is changed, WebSphere Application Server must be restarted to see the changes.	If a resource bundle is changed, it must be recompiled and WebSphere Application Server must be restarted to see the changes.
Language and locale dependent. One file should exist for each locale. We need to run native2ascii on non-ISO-8859-1 characters.	Language and locale dependent. One file should exist for each locale. We need to run native2ascii on non-ISO-8859-1 characters.

For an example of how property files can be used in a site globalized for many countries, refer to the starter stores.

Data storage and transfer

A single store can display pages in multiple languages, even when the languages use different character sets. To accomplish this, data is stored in the WebSphere Commerce database in a universal format that can be applied to a wide number of languages. Since not all web browsers support the same character sets, when the data is requested by a JavaServer Page, it is converted into an appropriate character set.

The following is a description of how data travels from the database to the browser:

1. Text data is stored in the WebSphere Commerce database using Unicode UTF-8 encoding (IBM i) or UCS-2.

2. JDBC drivers load the data from the database, converting it from UTF-8 to Java's native 16-bit Unicode encoding.

3. The JSP files output the data using the Java 16-bit encoding.

4. The WebSphere Application Server converts the JSP file output from 16-bit Unicode to the target encoding. The encoding can either be specified in the JSP file or in a property file. For example, to specify Shift-JIS encoding for a Japanese page:

   • JSP file <%@ page contentType="text/html; charset=Shift-JIS"%>.

   • Property file ENCODESTATEMENT = text/html; charset=Shift-JIS The character-encoding of the generated JSP file is set using the following statement in the JSP template: <%response.setContentType(fashionflowtext.getString ("ENCODESTATEMENT")); %>

   • JSTL: <c:set property="contentType" target="${pageContext.response}"> <fmt:message key="ENCODESTATEMENT" bundle="${storeText}" /> </c:set>

   Since not all browsers can understand every encoding scheme, IBM recommends that you specify the more well known encoding schemes, such as UTF-8 and Shift-JIS.

5. The converted data is sent back to the browser.

6. The browser interprets the HTTP reply based on the encoding specified in the header.

   

The following describes how data travels from the browser to the database:

1. Data is entered in the browser. Multilingual data can be entered using an input method editor.

2. WebSphere Commerce converts the data coming from the browser into Java 16-bit encoding using the setCharacterEncoding() method. Each LANGUAGE_ID in the LANGUAGE table is mapped to an encoding value using the ENCODING column. This value is used to interpret the data coming from the browser.

3. The data is sent to the database where it is converted from Java 16-bit to UTF-8 encoding, which is how it is stored in the database as shown in the following diagram:

   

Multilingual data entry

If the browser supports Unicode, then we can display multiple languages simultaneously in a browser. However, your operating system may not have the characters you need to enter text in some languages. To do this, you may need to use an input method editor. An input method editor is a software component that converts key presses into text input which cannot be typed directly. Input method editors are normally used to input text for languages which have more characters than can fit on a standard keyboard, such as Japanese, Chinese and Korean, Thai and Hindi. A common input method editor tool is Microsoft Global Input Method Editor (IME) which is available from the Microsoft Web site. The Global IME is appropriate for both customers to enter data on shopping pages, and for administrators to enter data in the WebSphere Commerce Accelerator and the Administration Console.

If you choose not to use an input method editor, we can also enter data in different languages provided that you have a number of machines setup, each using a different operating system language with a suitably configured browser. A browser automatically supports the language that is native to the machine on which it is installed. For example, to enter Japanese and German data, we can setup two machines, one using a German operating system and one using a Japanese operating system, each with a browser capable of displaying data from that operating system. For more information, consult the documentation for our operating system or Web browser.

Unicode

WebSphere Commerce text data is encoded using the Unicode character set. Unicode can display characters used in all major languages, including European, Middle Eastern and Asian languages. In WebSphere Commerce, the Unicode UTF-8 standard is used to store data in multiple languages in the same database instance. Although customers do not need to have a Unicode-enabled browser to view sites driven by WebSphere Commerce, administrators may need one if they want to view their site in more than one language on the same machine. To view the site in a language other than English, you need a Unicode enabled browser. For more information about Unicode, visit the Unicode Web site.

Display formats

Display formats allow a single store to sell to a globalized, multilingual customer base. Each display format can be identified by three factors: a language, a region, and a variant we can define. We can design the site to display different content to groups that differ on any of these factors. For example, you could use language and locale to have a separate format for US English and Canadian English. These display formats can have the same text, but different currencies and units of measurement. We can add a display format for Canadian French. This display format could display the same currency and units of measurement as Canadian English, though the text will be in Canadian French. You could even use the third factor to have a separate format for specific audiences within a culture, such as teens, scientists, or technical professionals, tailoring the site to suit their expectations.

Customers can either choose the format in which they want to view the site, or we can set a default value for them. Information regarding the format is passed through a URL parameter when we want to change the language. For example, if you pass in langId=-2, the session sets the current language to French. The langId is stored in the session. When the customer requests a page the display format determines the Web assets and catalog information to retrieve.

• Programming models for globalized stores
  We can use one of three programming models for globalized stores.

• Cultural considerations
  In software development, cultural formatting refers to the selection of culturally sensitive information such as a country's numeric format, monetary format, date and time formats, and calendar format. Such information varies from one region to another because of which the software application cannot mandate any cultural formats.

• Globalized catalog content
  The WebSphere Commerce catalog subsystem is designed to facilitate the creation and processing of globalized catalogs. All catalog descriptive tables are qualified by a language format column known as language_id qualifies all catalog descriptive tables. At run time, the command context is sent through a data bean to determine which translation to retrieve from the database and display on the page

• Globalized store design
  A store typically contains several types of pages. A globalized store is a store in which all pages are enabled for globalization. In WebSphere Commerce, globalization enablement of store pages is accomplished through the use of language-independent and culturally sensitive templates.

• Localized store assets
  Globalization permeates the WebSphere Commerce product. As a result, localization is embedded in most of the store data assets. This section highlights the store assets to which localization is most relevant. The following are the localized store assets:

• Globalized tools framework
  As is the case with globalized stores in WebSphere Commerce, all tools pages are enabled for globalization. The globalization enablement of tools pages is accomplished through the use of a set of tools framework's functions and utilities.

• Globalization in the messaging system
  The WebSphere Commerce messaging system gives WebSphere Commerce the ability to communicate with its external environment (back-end and external systems), as well as send notification to customers and administrators that events have occurred within WebSphere Commerce. This is accomplished through two subsystems: an inbound system that manages inbound messages coming from back-end and external systems, and an outbound messaging system that allows us to send notification to users (such as sending e-mail messages notifying a customer about a password reset).

• Globalization tips
  The section covers the general tips on globalization specific to WebSphere Commerce.

Related tasks
Adding a currency to WebSphere Commerce
Address and name formatting in the tools
Creating a globalized store
Creating a new display format
Creating and using resource bundles in the tools framework
Currency and number formatting
Date and time formatting
Setting the dir attribute for bidi specifications
Encoding for e-mail transmission
Name and address formatting
Use resource bundles in store pages

Related reference
Globalization tips
WebSphere Commerce JSP programming best practices