Globalization tips

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

Handling apostrophes and special characters

Translated Java properties files for some Western European languages such as French and Italian may contain some special characters such as double apostrophes (") and single apostrophe ('), which need to be escaped when imported into JSP pages. Not escaping these special characters will lead to JavaScript errors and the required GUI pages won't be displayed.

Escaping special characters in the tools JSP files

The JavaScript "alert" UI element uses the single and double apostrophes as syntax elements and thus those characters need to be escaped before a string that contain them is passed to an "alert" statement.

If your JSP contains the following piece of code:

<javascript><javascript>
alert('<%= myResouceBundle.get("alertMessage") %>');
</javascript>
</javascript>

The code would break if the "alertMessage" string in the translated properties file contains single or double apostrophes in it. An easy way to fix this is to use a method called toJavaScript in the com.ibm.commerce.tools.util.UIUtil class:

<%@ page import="com.ibm.commerce.tools.util.*" %>
<javascript>
alert('<%= UIUtil.toJavaScript( (String)
myResouceBundle.get("alertMessage")) %>');
</javascript>

This util method escapes such special characters as backslash(\), single quotes ('), double quotes ("), and new line (\n).

Note: Only JSP files and view commands that write directly to the out:JspWriter object need to observe the preceding guideline. JavaScript files are OK because they don't directly include anything from the resource bundle. Controller commands (which send back error messages to the client side) are also OK. The tools framework takes care of those messages.

In New Dynamic List, all these special characters (that is ', '') are handled by the tools framework internal code, so you don't need to process them by calling UIUtil.toJavascript().

Apostrophe handling with MessageFormat

When using java.text.MessageFormat to construct messages displayable for end users, developers have to account for the fact that MessageFormat strips off all single apostrophes from the message.

If the message has a variable, then replace single quotes with two quotes:

baseMessage = EspUtil.replace(baseMessage, "'", "''");
String formattedMessage;
try {
formattedMessage = MessageFormat.format(baseMessage, args);
} catch (IllegalArgumentException e) { ... }

Where EspUtil.replace() is a method that replaces all occurrences of one string with another in a String, as follows:

public final static String replace(String source, String pattern,
String
replacement)
{
if (source == null || pattern == null || replacement == null)
{
return null;
}
int pos = source.indexOf(pattern);
int count = -1;
while (pos != -1 && count != 0)
{
source = source.substring(0, pos) + replacement +
source.substring(pos + pattern.length());
pos = source.indexOf(pattern, pos + replacement.length());
count--;
}
return source;
}

Use locale-dependent Cascading Style Sheets (CSS)

Each language needs its own customizable attributes such as font size, font family, images, and so on. To allow for customization, the tools framework provides a separate centre.css for each locale (for example, centre_en_US.css, centre_fr_FR.css, centre_ja_JP.css, and so on.). All tools developers must use these locale-dependent CSS files for each and every JSP.

To load the locale-dependent CSS file:

1. Include com.ibm.commerce.tools.util.UIUtil

2. Add the following tag to your JSP:

   <LINK REL=stylesheet HREF="<%= UIUtil.getCSSFile(locale)
   %>"
   TYPE="text/css">

3. Note: getCSSFile(locale) returns the CSS file name depending on locale and falls back to centre.css if center_locale.css doesn't exist.

National language-enabled alert, confirm, and prompt dialogs

A Web browser's default alert(), confirm() and prompt() functions do not use UTF-8 encoding to display messages. Therefore double-byte characters messages are corrupted if viewed on an English (or other single-byte) browser.

The tools framework provides a new set of dialogs to make these functions national language-enabled. Those dialogs are:

• alertDialog (replacing alert)

• promptDialog (replacing prompt)

• confirmDialog (replacing confirm)

The syntax of using these three dialogs are the same as those of standard JavaScript functions. The following is an example of how to use each of these three dialogs:

alertDialog("message");
rval = promptDialog("prompt message"); // will return a string
rval = confirmDialog("confirm message"); // will return a boolean

Input field validation: UTF-8 Input validation

With DBCS languages such as Chinese and Japanese, there are many thousands of characters, far too many to store using only 1 or 2 bytes. Therefore, most traditional DBCS characters are encoded using three bytes in UTF-8.

All text fields that map to database columns should validate the maximum number of character allowed to be entered, taking into account the number of bytes needed to store each character in a UTF-8 database. For example, if the length of the database column is 10, your code should check for 10 English characters but only allow about three Japanese characters. To check the input length, by converting to UTF-8, tools framework developers should use the following JavaScript function (Util.js):

function isValidUTF8length(UTF8String, maxlength)

Submit NL command parameters using hidden forms

Special care must be taken when encoding national language characters as part of command parameters submission. Because of the inability of a URL string to properly encode national characters, national language URL parameters must be submitted in a hidden form format (using the "Post" submission method). When a form is submitted by the browser, the data is encoded automatically based on the current encoding setting of the browser.

The WebSphere Commerce tools framework provide the following mechanism to ensure that the URL parameters (NVPs) are submitted in a hidden form format:

When setting a URL (if it may contain double-byte characters) always use the top.setContent() method. Do not use window.location.replace() or location.href=myURL. Another advantage of top.setContent() is that it triggers the ToolsUICenter to display the progress indicator properly. Call the method as follows:

top.setContent( String PanelName, String ViewCommand, Boolean
addToBreadCrumbTrail, String urlParameter);

Example:

var urlPara = new Object();
urlPara.XMLFile = "my.xml";
urlPara.Search = "japanese";
top.setContent("My Link", "MyViewCommand", true, urlPara)

Related concepts
WebSphere Commerce configuration file (wc-server.xml)
Outbound messaging system
Globalized catalog content
Cultural considerations
Localized store assets
Globalization in the messaging system
Programming models for globalized stores
Globalized store design
Supporting globalization
Globalized tools framework

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
Creating a language selection drop-down list
Formatting addresses and names in the tools