Online Help for ADF Localization Sample Application

What does this sample show?

The goal of this sample application is to demonstrate how to effectively localize ADF UIX and JSP applications into multiple languages.  This sample application consists of 2 applications - one named UIX_Browse_Emp.uix  and the other JSP_Browse_Emp.jsp.   Each of these applications has been localized for Spanish (Spain) language / locale.

To view the application in Spanish,  simply set your browser to Spanish (Spain),  and run the Index.JSP page,  select the page of your choice and it should appear in Spanish.

Internet Explorer: Tools -> Internet Options -> General-> LanguagesNetscape/Mozilla: Edit -> Preferences -> Navigator -> Languages

 

Why is this important?

Web applications are usually globally distributed,  and their users need to have interfaces in their own language and numeric and date formats according to their local norms.  Translating applications is usually an expensive and difficult process.  Fortunately, Oracle ADF simplifies the process of localizing your J2EE applications.


How was this sample created?

The sample ADF-UIX and ADF-JSP pages were built using JDeveloper 10g's drag-and-drop functionality,  with Jakarta Struts as our applications framework.  Once built,  the applications must now be localized:

Configuration:

We must configure our application to specify where our resource files are,  and in the case of UIX,  the language(s) our components are to support.
Struts configuration:

We built our application using Jakarta Struts,  so we must configure our application to specify the location of localizable resources.  Configuration of ResourceBundle location is set in the Struts-Config.xml file,  using the  message-resources tag. 

Example:  . <message-resources parameter="view.ApplicationResources"/>

The "view." prefix indicates that our sample application properties file is located in the \View\src\view directory;  since "\View\src" is the root directory.

Once defined, the resources can be referenced using the Jakarta <bean> tag.

UIX Configuration:
UIX components are provided with translations for numerous languages and locales.  By default UIX applications do not have any language / locale limitations,  and will therefore load translated component resources matching the client's browser language preferences,  if they are available.  For reasons of maintaining consistency of the User Interface,  it may be desirable to limit UIX language / locale support to match only the languages we translate in our UI.

Example of Localized UIX Components

To configure UIX language / locale preferences,  we edit View\public_html\WEB-INF\uix-config.xml:

Add these tags to the  <default-configuration> tag:
 
<supported-locales>
    <default-locale>en-US</default-locale>
    <supported-locale>es</supported-locale>
</supported-locales>

where default-locale specifies what locale to display when browser language preference does not match any of the supported locale..  Locale format is 2 char ISO language code+"_"+(optional) 2 char ISO country code. Add as many supported-locales as your application supports.

You may add as many <supported-locales> as your application supports.  but <default-locale> MUST precede any <support-locale> definitions.

ResourceBundles:

Once the basic application is built and configured,  our next task is to identify and export all the strings needing localization to their respective ResourceBundle containers in preparation for translation.

The Java platform provides robust built in localization support,  which means we don't have to do much coding in order for our application to load at runtime the correct language resources to match our user's browser language settings.  The foundation of Java's multilingual support is its ResourceBundle architecture.  ResourceBundles are containers of localizable elements.  organized in key-value pairs.  Separate containers (files) are created for each language our application supports.

Java ResourceBundles are subclasses into ListResourceBundle,  which are backed by Class (compiled Java ) files,  and PropertyResourceBundle,  which are backed by Properties text files.

ListResourceBundle
PropertyResourceBundle:
Base (English) ListResourceBundle:

JDeveloper 10g automatically generates a ListResourceBundle Java file when strings are set in the Entity Object Editor.  Most strings are set in the "Control Hints" screen:

 

The resulting file EmployeesImplMsgBundle.java  is generated in the \Model\src\model\common directory.  Next,  we copy this file to EmployeesImplMsgBundle_es.java in the same directory,  and we subclass the constructor (our changes in bold)::

        public class EmployeesImplMsgBundle_es extends EmployeesImplMsgBundle

{
 public EmployeesImplMsgBundle_es()
  {
  }

Next,  the contents of our ListResourceBundle is translated into Spanish.    Once translated, the Java file is ready to be compiled.  Note that all non-ASCII characters within the ListResourceBundle must be either be UNICODE escaped or the encoding must be explicitly specified when compiling into byte-code.  There are two ways to approach this requirement:

No further coding is required in order for translations to be displayed in either UIX or JSP pages.

Working with Properties Files:

Our PropertyResourceBundle,  or "properties files",  contains the strings for our application's user interface.  This file contains key-value pairs,  and we can add new key-value pairs as we need them.  Properties file values do not require compilation, and the values are acquired by the application at runtime. 

Create the properties files:

As mentioned previously,  the default properties file is ApplicationsResources.properties,  and it resides in the \View\src\view directory. 
So for our sample,  we created
    ApplicationsResources_es.properties
in same directory (\View\src\view) as base file
    ApplicationsResources.properties

Add the Key-Value pairs:

Strings within the JSP or UIX page are not automatically exported to the properties file, so we must identify all the strings in our application visually,  then create "keys" for them.  The keys are unique names,  and we choose names that will help us identify where the text comes from.   To help identify the origin of the strings,  they can be grouped geographically using prefixes

e.g.,  the key / value :
 errorpage.title=

tells us the string is a title string from the error page

or we can group them functionally, 

buttonsubmit=Submit

which identifies the string as the name of a button.

Once all the strings in the application are represented in the properties file,  we can copy the contents of the English file to the Spanish file, and translate the strings.

Convert Properties file content to Escaped Unicode

Once the properties files are translated,  we must ensure that the strings are in a character set encoding that will be correctly interpreted by our application and correctly displayed by the client's browser.  Although Java uses Unicode internally,  properties files must contain characters that can be represented by the ISO 8859-1 character set.  Any non-8859 character sets must be converted to escaped UTF-8 characters,  or they will appear corrupt in the browser.   

  1. native2ascii –encoding UTF8 ApplicationsResources_es.properties ApplicationsResources_es.propertiesUTF8
  2. Save the original file,  then rename the *.propertiesUTF8 to *properties

Modify Pages to Reference ResourceBundles

Once our strings are represented in our ResourceBundles,  we still have to modify our UIX and JSP pages to reference them.  The mechanism for referencing ResourceBundles differs for JSP and UIX pages.

Referencing ResourceBundles in UIX Pages

Once all the strings in our application are defined in ResourceBundles,  we must substitute all the hard coded strings in our UIX page with references to the ResourceBundle keys.
Specify ResourceBundle Data Source
In each UIX file we must specify the Data Provider which defines a provider name,  and the location of the resource file.    In our sample page UIX_Browse_Emp.uix,  we added the following provider definition:

      <provider>
             <data name="nls">
                <bundle class="view.ApplicationResources"/>
             </data>
      </provider>
Modify the UIX page
Once defined,  we reference the key using the syntax:  ${<providername>.<key>}.  For example,  in our sample application,  our title strings becomes:
<head title="${nls.empmainheader}"/>

Continue until strings are resourced.  Add new key - value pairs as needed.

Modify JSP's

JSP's use a completely different mechanism for defining and using ResourceBundles.  In fact,  there are two tags that can be used to reference the ResourceBundles:  Jakarta <bean> and the JSTL <fmt> tag libraries.  Note that in our example, we use both,  but ordinarily,  choosing and using only one of them is recommended..
Jakarta Bean Tag:
The <bean> tag is provided by the Jakarta initiative,  which means it is related to and works well with Struts.  <bean> works in conjunction with the <message-resources>  tag in the Struts-Config.xml file - see the "configuration" section above for more information.

At the top of the JSP,  we must specify the tag Library directive,  in order to load the <bean> library:
<%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="bean"%>

Now we replace all the hard coded strings tags that reference the string via its "key":   For example,  our page Title sting is replaced with:
<bean:message key="empmaintitle"/>

And we continue until strings are resourced.  And, of course,  we can add new key - value pairs as needed.

JSTL fmt Tag:
JSTL (Java Standard Tag Library) provides us with robust support for internationalization, providing extensive support for locale specific date,  numeric,  and message formats. 

To use the <fmt> tag in our JSP,  we must specify the tag Library directive as follows:
<%@ taglib uri="http://java.sun.com/jstl/fmt" prefix="fmt"%>

and we replace the hard coded strings with the following tag:
<fmt:message key="buttonsubmit"/>"

And we continue until strings are resourced.  And, of course,  we can add new key - value pairs as needed.