JSF Framework

Home » JSF Framework » Tutorials » Internationalization

Internationalization

Internationalization

Internationalization and localization allow your web application to adapt dynamically to the locale of the client browser. This example page demonstrates how to enable a JSF Edition web application to support internationalization and localization.

Prerequisites and Intended Audience

Software

The following software is required to build and deploy the example:

  • Backbase Enterprise Ajax 4.2.0 - JSF Edition (and higher)
  • JDK 1.4.2 or above
  • Application server that supports Java Servlets 2.3 and JSP 2.0 specifications

Competencies

Experience to the level indicated is required with the following technologies:

  • Java beginner
  • JSF beginner

Resources

To implement the steps described in this examples page, you can either create a new application using the blank.war bundled with the JSF Edition or you can use the Backbase Eclipse plugin to create a new project. For more information, see the JSF Edition Deployment Guide and Application Development Guide listed in the Additional Resources.

Overview

An Introduction to Internationalization and Localization

Internationalization is the process of designing a software application so that it adapts dynamically to the locale of the client system. Localization is the process of enhancing an application with locale-specific text and components. The overall effect is that your application will conform dynamically to the language, number and time formats defined by a particular locale.

Often the term i18n is encountered in the context of internationalization and localization. It is simply an abbreviation for internationalization, with the number 18 indicating that eighteen characters separate the i from the n.

Until recently, locale and language definitions conformed to the ISO 639 two-character and three-character codes. However, as described at Language tags in HTML and XML, efforts to harmonize the ISO character codings have resulted in a registry for all language subtags at the IANA Language Subtag Registry.

For more information, please refer to Java Internationalization.

Feature list

This Examples Page demonstrates how to internationalize your JSF Edition web application, and how to extend your application with support for the Dutch language.

The following features of i18n are demonstrated in this example:

  • Application configuration
  • Localization of Backbase JSF components
  • Localized validation
  • Localization of Backbase client widgets

To demonstrate JSF Edition web application i18n support, a page will be constructed that contains a drop-down list, an input field with validation, and a calendar, all of which will be configured to support Dutch as well as English (the default language).

Enabling Internationalization

There are various ways to change the default language of your JSF Edition web application, including:

  • When a browser connects to your JSF Edition web application, it usually includes an Accept-Language value in the HTTP header (for more information, please refer to the Additional Resources). By setting the default and supported locales in the faces-config.xml file (or another application configuration resource) your JSF Edition web application uses the specified locale or reverts to the default.
  • Setting the locale attribute on the f:view element:
    <f:view xmlns:f="http://java.sun.com/jsf/core" locale="nl">
      <bjsf:application xmlns:bjsf="http://www.backbase.com/2007/jsf">
        <f:verbatim>
          <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="<%=application.getInitParameter('com.backbase.bjsf.CLIENT_BOOT_DIR')%>/bindings/config.xhtml_btl.chameleon.xml" parse="xml"></xi:include>
          <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="<%=application.getInitParameter('com.backbase.bjsf.CLIENT_BOOT_DIR')%>/bindings/www.backbase.com.2007.jsf.client/server.xml" parse="xml"></xi:include>
          <bjsfc:server xmlns:bjsfc="http://www.backbase.com/2007/jsf/client" url="index.jsf" identify="id" loadingMessage="__loadingMsg"></bjsfc:server>
          <b:loadingMessage xmlns:b="http://www.backbase.com/2006/btl" id="__loadingMsg">Loading...</b:loadingMessage>
        </f:verbatim>
        <bjsf:loadBundle basename="language_nl" var="msg"></bjsf:loadBundle>

        <%-- your code goes here --%>

      </bjsf:application>
    </f:view>
               
  • Call the setLocale method of the UIViewRoot object.

In this examples page, your application is enabled for dynamic internationalization by adding an application entry to the JSF configuration file:

<faces-config>
  <application>
    <locale-config>
      <default-locale>en</default-locale>
      <supported-locale>nl</supported-locale>
    </locale-config>
  </application>
</faces-config>
       

The application also leverages the setLocale method to allow the language to be changed manually. The following code fragment is added to the backing bean to enable the language to be toggled between English and Dutch:

FacesContext context = FacesContext.getCurrentInstance();

Locale currentLocale = context.getViewRoot().getLocale();

Locale nl = new Locale("nl");
if(currentLocale.equals(nl)) {
   context.getViewRoot().setLocale(Locale.ENGLISH);
} else {
   context.getViewRoot().setLocale(nl);
}
       

Creating the Resource Bundles

Locale-specific text for labels and messages is stored in a resource bundle. The locale-specific values are applied at runtime to those components whose attribute values are mapped to keys in the resource bundle.

The entries in the resource bundle are name / value pairs. The resource bundle needs to be accessible from the classpath, and is typically saved in the source package. Any directory path and file name is permissible, but the file extension properties must be used.

For this examples page, Dutch language text is thus added to a resource bundle named nls_nl.properties:

change_language=Verander taal

animal=Dier
cat=kat
dog=hond
horse=paard
bear=beer
wolf=wolf

zipcode=Postcode
zipcode_pattern=^[0-9]{4}[\\s]*[a-zA-Z]{2}$

zipcode_error_message={0} Onjuiste invoer van postcode. Graag invullen op de volgende manier: 1234 AB
validate=valideer

date=Datum
language=nl
language_flag=en.gif
     

In this code fragment, text (without any single or double quotes) is assigned to a variable. Typically, the variable conforms to the preferred coding style. In this case, an underscore is used to delineate compound names, but camelcase (changeLanguage) and full stops (change.language) are also permissible. To support different languages, the same variable names are used in different resource bundles.

Localization of Backbase JSF Components

For this examples page, the resource bundle is located in the com.backbase.bjsf.examples.internationalization package. The loadBundle component is used to load the resource bundle:

  <bjsf:loadBundle xmlns:bjsf="http://www.backbase.com/2007/jsf" basename="com.backbase.bjsf.examples.internationalization.nls" var="msg"></bjsf:loadBundle>

The basename defines the stem of the resource bundle filename. The particular language is defined by appending the IANA language code to the basename value with an underscore character. For this example, the resource bundle for Dutch-language text is named nls_nl.properties, whilst the filename for Italian-language text is nls_it.properties, and that for Japanese-language text is nls_jp.properties, etc.

To add a localized label to a component, the specific variable name is referenced and assigned to whatever attribute defines the label. In the case of the drop-down list, resource bundle variables are assigned as follows::

<bjsf:comboBox xmlns:bjsf="http://www.backbase.com/2007/jsf" filter="true" id="animals" value="#{i18n.animal}">
  <f:selectItem xmlns:f="http://java.sun.com/jsf/core" itemValue="#{msg.cat}"></f:selectItem>
  <f:selectItem xmlns:f="http://java.sun.com/jsf/core" itemValue="#{msg.dog}"></f:selectItem>
  <f:selectItem xmlns:f="http://java.sun.com/jsf/core" itemValue="#{msg.horse}"></f:selectItem>
  <f:selectItem xmlns:f="http://java.sun.com/jsf/core" itemValue="#{msg.bear}"></f:selectItem>
  <f:selectItem xmlns:f="http://java.sun.com/jsf/core" itemValue="#{msg.wolf}"></f:selectItem>
</bjsf:comboBox>
     

Localized Validation and Messaging

The principles for localized validation and messaging are identical to those for component labelling, whereby resource bundle variables are assigned to the attributes used to define strings (validation) and text (messaging):

<bjsf:panelGrid xmlns:bjsf="http://www.backbase.com/2007/jsf" columns="2" cellpadding="2" cellspacing="1" border="0">
  <bjsf:inputText id="zipcode" value="#{i18n.zipcode}">
    <t:validateRegExpr xmlns:t="http://myfaces.apache.org/tomahawk" pattern="#{msg.zipcode_pattern}" detailMessage="#{msg.zipcode_error_message}"></t:validateRegExpr>
  </bjsf:inputText>
  <bjsf:message for="zipcode" style="color:red;" tooltip="true"></bjsf:message>
  <bjsf:commandButton action="#{i18n.validate}" destinationId="dashBoard" mode="replaceChildren" value="#{msg.validate}"></bjsf:commandButton>
</bjsf:panelGrid>
     

Localization of Client Framework Widgets

Certain of the client widgets are delivered with support for localization. The language is defined by setting the language attribute of the BTL widget, as shown in the following code fragment:

<h:inputHidden xmlns:h="http://java.sun.com/jsf/html" value="#{msg.language}">
  <f:verbatim xmlns:f="http://java.sun.com/jsf/core">
    <e:handler xmlns:e="http://www.backbase.com/2006/xel" type="text/javascript" event="DOMNodeInsertedIntoDocument">
      bb.document.getElementById('calendarId').setAttribute('language', bb.evaluateSmart('.//input/property::value', this));
    </e:handler>
  </f:verbatim>
</h:inputHidden>
<f:verbatim xmlns:f="http://java.sun.com/jsf/core">
  <b:calendar xmlns:b="http://www.backbase.com/2006/btl" id="calendarId"></b:calendar>
</f:verbatim>
     

Live Demo

In the following live demo, the functionality implemented in the preceding steps is shown:

Additional Resources

For more information, please refer to the following documentation, examples and reference material: