Localizing Adventure Builder

Adventure Builder is much like Pet Store but it is the next generation so the data is stored a little differently. Both applications share the  same framework so all of the programmatic portions are the same. It  may be helpful to look at Pet Store in that it has been localized  into three languages.

Here is a set of steps that should get you up and running in another language.


1. Localize and Populate the Data


The data used by the Adventure Builder web site is maintained in a file called adventurebuilder/setup/sql/pointbase.sql. This file is responsible for both creating the tables and for populating the tables with data. You may choose to modify this file by adding entries for the content you choose to localize. It is recommended that you localize all the entries if you expect the web site to work properly.

Notice that all the tables now have a column called local. This will need to be ISO 639 Language code and the ISO 3166 Country  code with an '_' between them. For example Japanese would be 'ja_JP' and traditional Chinese would be 'zh_CN' and so forth. See the Standard Locale Naming Conventions for more details. In the case of AdventureBuilder you can not set the locale with Just a Language code, you need to also add a country code. Remember to keep this naming consistent throughout the application or the localized content will not be displayed.

If you were going to localize the following category name "Island Adventures" from United States English

INSERT INTO category VALUES ('ISLAND', 'en_US', 'Island Adventures', 'Experience an island paradise in a way fit for your needs.','Island_Adventures.gif');

Add (don't delete the previous entry) the following to provide a Japanese localized version of this entry:

INSERT INTO category VALUES ('ISLAND', 'ja_JP', 'Island Adventures for Japan', 'Experience an island paradise in a way fit for your needs.','Island_Adventures.gif');

Populating the Data

 The Adventure Builder workspace contains a utility that will allow you to populate database on any database supporting JDBC with any encoding supported by Java. We recommend using UTF-8 as the encoding in that you can include contain in multiple languages in the same file. You may also want to consider having the localized  content in a separate file. Keep in mind you do not need to have the database creating in the localized files. The database tables are designed to support multiple languages. The populating tool may be used as an ant task in the adventurebuilder/setup/setup.xml file. The following task will populate data to the Pointbase Database that comes with the Java 2 Enterprise Edition 1.4 Platform Edition.

   <target name="populate2">
    <java classname="com.sun.j2ee.blueprints.populate.web.PopulateTables" fork="yes">
       <classpath path="lib/populator/populate.jar:${j2ee.home}/pointbase/lib/pbclient.jar"/>
       <arg line="-target file://${basedir}/setup/sql/pointbase.sql"/>
       <arg line="-driver com.pointbase.jdbc.jdbcUniversalDriver"/>
       <arg line="-databaseURL jdbc:pointbase:server://{db.port}/${db.name}"/>
       <arg line="-verbose true"/>
       <arg line="-encoding UTF-8"/>
       <arg line="-userName pbpublic"/>
       <arg line="-password pbpublic"/>
    </java>
   </target>

In this case it is assumed that you have also saved the adventurebuilder/setup/sql/pointbase.sql file encoded as UTF-8. Make sure your JDBC drivers and database support the encoding of the language you are using.

Enable Localized Database Data to Be Displayed by the Application in JSP Pages

All pages that contain the localized data will need to have the data base queries set to lookup the correct data.  For example in all the DB calls we are looking up the English data. So you will need to change this from:

 <sql:query var="packageContents">
 select p.name, p.description,p.location, p.price , l.name as lodgingname, l.description as lodgingdescription, l.price as lodgingprice, p.imageuri, l.imageuri as lodgingimageuri from package p, lodging l where p.lodgingid = l.lodgingid and p.packageid = ? and p.locale = ?
 <sql:param>${param.PACKAGE_ID}</sql:param>
 <sql:param>en_US</sql:param>
</sql:query>

To:

 <sql:query var="packageContents">
 select p.name, p.description,p.location, p.price , l.name as lodgingname, l.description as lodgingdescription, l.price as lodgingprice, p.imageuri, l.imageuri as lodgingimageuri from package p, lodging l where p.lodgingid = l.lodgingid and p.packageid = ? and p.locale = ?
 <sql:param>${param.PACKAGE_ID}</sql:param>
 <sql:param>ja_JP</sql:param>
</sql:query>

2. Enable the ChangeLocaleHTMLAction:

Add the following line to the mappings.xml file located in:

adventurebuilder/apps/customerwebsite/src/conf/ directory

 <url-mapping url="changelocale.do" screen="main.screen" >
 <web-action-class>com.sun.j2ee.blueprints.waf.controller.web.html.impl.ChangeLocaleHTMLAction</web-action-class>
 </url-mapping>

This will default you to the front page when the language is changed (but it should be in the target language).

3. Localize the JSP pages

The directory name is this case can be any arbitrary name. In the case of Japanese I choose adventurebuilder/apps/customerwebsite/web/ja as the name. This name only has the pages referenced by the templating mechanism. All mappings to JSP pages in this directory are manually mapped in the template setup files which will be explained in setup 6. It is best to localize all the pages or put copies of the English pages in the
adventurebuilder/apps/customerwebsite/web/ja directory.

These pages will also need to contain a JSP Directive which sets the language used in that page.

<%@ page contentType="text/html;charset=UTF-8" %>

All pages will need this JSP declaration and it should be done near the top of the page before any localized content. All pages that contain the localized content including the template.jsp page and files such as the sidebar.jsp and cart.jsp will need this directive tag.

4. Provide a User Interface Button/Image to Change the Language


In your JSP page (maybe the banner) use the following form to change the language.

 <form method="post"
 action="changelocale.do">
 imageURL="images/us_flag.gif">
 <input type="hidden" name="locale" value="ja_JP"/>
 <input type="submit" value="Japanese"/>
 </form>

5. Set the Request Encoding


The Request Encoding will need to be set for language that are not support by 8895-1. To do this you can use an a filter that is mapped to every request. This should not be a problem in the case of Spanish but will be a problem in Chinese, Japanese, or Korean for example.

The encoding filter from the Pet Store Reference application may be used to set the request encoding properly for every page in the web application. You will need to also define and configure the Encoding Filter component in the web.xml as follows:

  <!-- Encoding Filter Declaration Start -->
  <filter>
    <filter-name>EncodingFilter</filter-name>
    <filter-class>com.sun.j2ee.blueprints.encodingfilter.web.EncodingFilter</filter-class>
    <init-param>
      <param-name>encoding</param-name>
      <param-value>UTF-8</param-value>
    </init-param>
  </filter>

Notice that the encoding is set to UTF-8 this will provide broad support for most languages.

You will also need to map the encoding filter to all requests using the following filter mapping entry:

  <!-- Encoding Filter Mapping Start-->
  <filter-mapping>
    <filter-name>EncodingFilter</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>
  <!-- Encoding Filter Mapping End-->

6. Add the screen definitions for the Language

You will need to provide a screendefintions file for the language you are adding. To do this create a file called screendefinitions_ja_JP.xml (in the case of Japanese) and place it in the adventurebuilder/apps/customerwebsite/web/WEB-INF/ directory. You can copy the adventurebuilder/apps/customerwebsite/src/conf/screendefinitions_en_US.xml file (but be sure to place it in the adventurebuilder/apps/customerwebsite/web/WEB-INF/ directory). You will need to change the encoding of that file as well (UTF-8 is recommended).

In this file you will provide the location relative to the context root of the localized content for each screen you want to localize. For example if you want to localize the main.screen (the front page you could change:

  <screen name="main">
    <parameter key="title" value="Welcome to the Adventure Builder Reference application" direct="true"/>
    <parameter key="banner" value="/banner.jsp" />
    <parameter key="sidebar" value="/sidebar.jsp" />
    <parameter key="body" value="/main.jsp" />
    <parameter key="footer" value="/footer.jsp" />
   </screen>

To support Japanese by doing the following.

  <screen name="main">
    <parameter key="title" value="Welcome to the Japanese Adventure Builder Reference application" direct="true"/>
    <parameter key="banner" value="/ja/banner.jsp" />
    <parameter key="sidebar" value="/ja/sidebar.jsp" />
    <parameter key="body" value="/main.jsp" />
    <parameter key="footer" value="/footer.jsp" />
   </screen>

Notice that the location of the files references the files in the adventurebuilder/apps/customerwebsite/web/ja directory that we earlier localized. If you choose not to localize some screens Adventure Builder will use the default English screens defined in the screendefinitions_en_US.xml file.

Next you will need to have the TemplateServlet load the screen definitions that you created. To do this change the following entry in the web.xml file:

<!-- Template Servlet Configuration -->
  <servlet>
    <servlet-name>TemplateServlet</servlet-name>
    <servlet-class>com.sun.j2ee.blueprints.waf.view.template.TemplateServlet</servlet-class>
    <init-param>
      <param-name>locales</param-name>
      <param-value>en_US</param-value>
    </init-param>
    <init-param>
      <param-name>default_locale</param-name>
      <param-value>en_US</param-value>
    </init-param>
    <init-param>
      <param-name>cache_previous_screen_attributes</param-name>
      <param-value>false</param-value>
    </init-param>
    <init-param>
      <param-name>cache_previous_screen_parameters</param-name>
      <param-value>false</param-value>
    </init-param>
    <load-on-startup>2</load-on-startup>
  </servlet>

To:

<!-- Template Servlet Configuration -->
  <servlet>
    <servlet-name>TemplateServlet</servlet-name>
    <servlet-class>com.sun.j2ee.blueprints.waf.view.template.TemplateServlet</servlet-class>
    <init-param>
      <param-name>locales</param-name>
      <param-value>en_US,ja_JP</param-value>
    </init-param>
    <init-param>
      <param-name>default_locale</param-name>
      <param-value>en_US</param-value>
    </init-param>
    <init-param>
      <param-name>cache_previous_screen_attributes</param-name>
      <param-value>false</param-value>
    </init-param>
    <init-param>
      <param-name>cache_previous_screen_parameters</param-name>
      <param-value>false</param-value>
    </init-param>
    <load-on-startup>2</load-on-startup>
  </servlet>

Notice that you can change the default language used by the application if you choose to do so.

7. Viewing the localized content

Keep in mind you may need to install additional fonts to view the data. You may also need to add additional input method support to enter text as well. If you have trouble viewing the content you may want to change the browser encoding before viewing the page.