SESM Internationalization and Localization

SESM Components for Internationalization and Localization

The Cisco SESM web components include a set of Java classes and JSP tag libraries that help the deployer to internationalize and localize an SESM web application. These Java classes and techniques extend the classes and techniques that are part of the J2EE classes. The Localization tag library provides methods for setting and changing the localization context associated with the subscriber's HTTP session. For example, the Localization tag library allows a web application to change the locale and time zone of the subscriber's session.

It is not required that a Cisco SESM web application use the extended classes and techniques that are provided with the SESM software. An SESM web application can use conventional Java techniques for internationalization and localization. However, the classes and tags provided with the Cisco SESM software are specifically designed for use with a web application.

The localizable elements are stored in a set of properties files, one for each language-region combination. If an SESM web application uses resource bundles, the web application determines the subscriber's locale and then loads the appropriate resource bundle. If the subscriber switches locales, the web application can load a different resource bundle.

Resource bundles allow you to design and write an SESM web application that can be easily localized for the subscriber's language and region. An SESM web application can add additional resource bundles if a new locale is required.

The following sections provide some general information on resource bundles, properties files, and their use with a Cisco SESM web application. For detailed information on resources bundles, see the description of these classes at the Java 2 platform area of the java.sun.com web site:

• java.util.ResourceBundle
  
  
• java.util.Locale
  
  
• java.util.TimeZone
  
  
• java.text.MessageFormat
  
  

# English version of properties file AMGreeting = Good Morning PMGreeting = Good Evening NotValid = Invalid Value

The French version of the properties file is:

# French version of properties file AMGreeting = Bonjour PMGreeting = Bonsoir NotValid = Valeur Incorrecte

The value part of the key-value pair can include HTML markup. The value is passed straight through to the HTML page with no changes. Because the L10nContext class and the Localization tag library do not process special HTML characters when retrieving a value from a properties file, you can use HTML markup in the value. Special HTML characters that appear in a value and that are not part of HTML markup must use ISO 8859-1 character encodings. For example, if you want the less-than character (<) to appear in a value as something other than HTML markup, it must be coded as &lt.

You can find information on how to write and retrieve the entries in a properties file from these sources:

• context—Sets the characteristics of the current localization context (L10nContext).
  
  
• locale, timeZone, and language—Get a string describing the specified characteristic of the current localization context.
  
  
• country—Gets a string for a country specified by the attribute used with the tag.
  
  
• format—Converts currency, number, date, and time values according the formatting conventions associated with the Java class java.text.MessageFormat and the current L10nContext localization context. Also, formats an internationalized object
  
  
• resource—Obtains a resource from the resource bundle specified for the current localization context and for a specified key.
  
  
• template—Replaces tokens in a template with parameter values. The template tag can be used with the resource tag for token replacement in a resource.
  
  

The Localization tag library is specifically designed for web application localization. The standard Java Locale.getDefault method gets the current value of the default locale for this instance of the Java Virtual Machine (JVM). This default locale is shared across all applications running on that JVM.

1. A parent context tag.

2. If no parent context tag is used, the values come from a localization context stored in an L10nContext object. The context tag software searches for a localization context having (in this order) page, request, session, or application scope. It uses the first context found.

3. If none of the preceding exist, the values come from the default localization context, which it obtains with the L10nContext.getDefault method.

A web application can override the current localization context's inherited values with the context tag attributes such as locale, preferredLocales, timeZone, and resourceBundleName. For example, a web application can set the locale of a user's localization context to Germany for the duration of an HTTP session as follows:

A localization context object can exist for each of four scopes: page, request, session, and application. As shown in the preceding example, the scope attribute defines the scope of a localization context and can be specified with any other context tag attribute.

The current localization context, including all its characteristics, can be specified by setting the context using the context attribute and an existing L10nContext object. For example:

If a tag in the Localization tag library is used inside the tag body of a context tag, the tag's functionality reflects the localization context. In the following example, the currency amount is formatted according to German conventions (99,99 DM) because the formatting occurs within the context tag body where the localization context's locale is Germany.

If a tag in the Localization tag library is used outside the tag body of a context tag, the localization context is the same as having a parent context tag with no attributes set.

The following example uses the country tag and its various attributes to obtain text descriptions for some countries.

The following example uses the format tag to format:

• A double value into a currency amount
  
  
• A Date value into a time
  
  
• A Date value into a long time
  
  

The following example uses the resource tag to obtain the resource associated with the key PleaseAuthenticate from the messages.properties resource bundle of the NWSP sample web application.

The template tag can be used with the resource tag to get a resource from a resource bundle and to replace tokens in the resource with specified parameter values. In a properties file, the value part of a key-value pair is a template, a message format, that can contain one or more tokens. As an example, assume the following key-value pair in a properties file:

The following template tag uses the resource tag in its body to retrieve the value from and replace tokens in the preceding properties file entry:

For the preceding example, the generated HTML page displays the following:

When you use the value default for the defaultTimeZone parameter, a time-zone map associates a time zone with a specific locale. The L10nContext class uses the time-zone mapping for the web application default localization context. If the subscriber subsequently changes the preferred locale, the L10nContext software selects a new time zone that matches the new locale.

Two L10nContextDecorator servlet initialization parameters are used to define a time-zone map.

For both of these parameters, you can separate the values by whitespace or commas.

The following example shows how to use the timeZoneMapCountries and timeZoneMapTimeZones parameters.