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.