User's Manual for i18n4data
By Huang Neng Geng
The i18n for data (abbreviated as i18n4data) provides a solution to manage the complexity of creating internationalized web applications developed using Java. The i18n4data has similar functionality to the internationalization available in the i18n tag library under Apache Software Foundation, but was implemented in a different way.
The name of i18n for data means that the internationalization is not only for interface message, but also for user's data. By using i18n4data, an application developer is able to make an existing java web project internationalized with least coding. It also helps to develop a new internationalized java web project by reducing the work on data structure design and software design related to language problems.
The i18n4data is a java servlet filter to make your java based project internationalization. It supports the translation of both interface message and user's data to various languages. There are two build in dictionaries to fulfill the task. The two dictionaries are for messages and user's data separately, which are maintained by you through a build in servlet page. Therefore, the user's data will be translated into various languages exactly defined by you. This is truly important for those who want to publish their information with precise meaning into different languages.
2.1 System requirements
The i18n4data requires no software other than a servlet container that supports servlet filter feature. The following environments has been tested and should work properly:
1. Download i18n4data from sourceforge.net.
2. Uncompress it to your web application directory, for example,
3. Copy following content and paste it into file web.xml in directory WEB-INF. Then restart your application server.
4. (Optional) Make changes to configuration file WEB-INF /i18n4data.xml or your source code (if it is AJAX enabled) to meet your need.
5. That's all. Run your application and enjoy it.
3 Definition of terms
Unlike i18n message bundle, all the translations in i18n4data are stored in a database. Bellow are some definitions used in i18n4data:
4 A quick look
The treatment of interface message is automatically done by i18n4data. However, for the user's data, there are some differences.
1. Textual user data (such as product name) that are recognized as keys are treated in the following way:
Therefore, an end user will read translations of one language the user select rather than the original key name.
When a key is located in a form (input text field or hidden field), it will be remained in the original form, that is to say, not to be translated. For AJAX enabled pages, it is a little different way and will be discussed later.
2. Non-textual user data (numbers, date, long text such as description) will not be recognized as a key and will be treated in a normal way.
5 Guide for end users
The web application has the same user interface after internationalized by i18n4data. End users of the web application use it in the same way only in one exception.
If i18n4data filter mode is set to auto, it is the responsible of end users to define a key. To define a key, the end user should input the text data with a preceding character "\". Then i18n4data will treat that text as a key. If a user want to input a text with leading "\", the user may input the text with double "\\", which indicates that there one "\" as text.
If i18n4data filter mode is set to code, it is the responsible of application developers or application administrators to define key fields. After define key fields, end users use the application exactly the same as before.
In both mode (auto and code), it is necessary for staff to maintain the dictionary. When a new key is added, the dictionary (database) will insert that key a new record. And staff should translate it into different languages. These can be done through an edit page provided by i18n4data. The link for edit page is automatically added at the bottom of each page by default. For a big system like an ERP system, the translation work might be very huge.
Fig. 1 showed an example of e-shop web site. When users select a language from the drop down menu and refresh the page, all message and data will change to the selected language.
Fig. 2 showed a key is being edited. The key name is in English and displayed in a text box field in a form for editing. The key will be translated into text of selected language after editing if the dictionary has the translation for that language (Fig. 3).
Fig. 4 showed a new key is create and displayed as "[catalog.key name]" because it does not have any translations in the dictionary. It will remain the same until translation for that key is added.
6 Guide for maintenance
The maintenance work of dictionaries for i18n4data is huge. Fortunately, i18n4data provides an easy interface for dictionary maintenance.
All key entries are inserted into the dictionary automatically by i18n4data. If i18n4data fails to find a key entry, it will insert a record in the dictionary.
A key entry could be deleted from the dictionary manually. The deletion is permanent. If a key entry is deleted and i18n4data fails to find the key entry later, i18n4data will create the key entry again. However, the new key entry does not have correspondence translations and need to be translated again.
Key name and catalog could not be modified after it was created. Only translations are editable.
All key entries are organized by catalog. Maintenance users may browse entries by catalog or by searching criteria or both. Translations for three languages are displayed. Users may edit translations for all languages of a key entry at the same time. Users also may edit all selected key entries of translation for only one language at the same time. Users also may select all key entries that do not have translation of one language.
There are two dictionaries, one for interface message, one for user's data. Fig. 5 showed interface message key entry list. An user may select a working language from menus at the up right corner. An user may click to reload the dictionary (also reload i18n4data configuration file). Select to list all key entries that do not have translation for one language. Click key entry to edit the key for all languages (Fig. 6). Select to edit all key entry for one language (Fig. 7).
For security reason, not all users are able to edit the dictionary. The permissions are assigned by administrators.
7 Guide for application administrators and developers
The i18n4data is developed by using Java 5.0. The development environment is:
For application administrators and developers, only limited JSP knowledge is required to configure i18n4data to work properly with the application.
To understand the work that i18n4data doing, it is explained how the i18n4data works, which is the basic of i18n4data. However, this knowledge is not a must to understand i18n4data.
7.1 Mapping and filter
The i18n4data uses servlet filter technology to filter all request and response to fulfill the key identifying and translating work.
Each key name will have a catalog prefix, which is maintained by i18n4data automatically. The i18n4data achieves it by maintaining a field-mapping table, in which a table contains form's field and catalog pairs are stored. When user's data is sending to web server by POST method, the form's field name will be sent to server at the same time. Then i18n4data check the form's field name of the user data and find out the correspondent catalog for it. The user's data which are not associate with a catalog is not recognized as a key.
Note: The form's field name is defined in HTML file, typically a text box input field. It is not the column's name of a table in database.
2 Filter request
It happens when a web server receives users data input (request). After receiving the request, at the server end, the i18n4data will treat every input data in following way:
1. First, look for page based field mapping. If found, use the catalog prefix.
2. If not found, look for global (configuration based) field mapping. If found, use the catalog prefix.
3. If still not found, then
If in auto mode or development mode, check user＊s input:
4. Otherwise, user's data is NOT recognized as a key even start with "\". Then treat it as normal data.
3 Filter response
It happens when a web server sends data to users. Before sending the response, at the web server end, the i18n4data will filter the text and make translation to keys.
1. For normal html contents: The i18n4data filter user＊s data and interface messages and response translate for these keys. For example, a key "\product.printer" will be translated into "Imprimante" in French.
The i18n4data uses hsqldb-1.8.09 to store the dictionaries by default. There are no views, stored procedures, and triggers. It should work on most database management system. A best practice is to store interface message dictionary in hsqldb and store the user data's message dictionary in the database used by application. This strategy may help to maintain the consistence between application data and user data's message.
Application administrators and developers are responsible to make settings in configuration file (i18n4data.xml). Bellow is an example:
Note on configuration file:
1. Supported languages: The i18n4data uses the standard country code and language code for languages. The number of languages supported by i18n4data does not have limit.
2. Security level:
3. Default language mode: If set on, when a translation for one language could not found, use default language's translation. Note: Default language is deferent from system language.
4. Debug mode: For developers use only.
5. Development mode
a) Path: Each mapping will to match a path to take effect. The path may be an exactly a real path, start from the project root path, such as "/admin/itemList.jsp" or "/servlet/ItemList". The path may also contains wildcard character, such as "/servlet/Item.*" means to match "/servlet/ItemList", "/servlet/ItemXX", and "/servlet/Item.do", etc. Note the wildcard character IS ".*' rather than "*".
b) Filter mode:
c) Filter mapping: To define a field-catalog pair.
7. jdbc-data: The parameters in this section is to define jdbc parameters for user's data dictionary.
8. jdbc-message: The parameters in this section is to define jdbc parameters for interface message dictionary.
9. Navigation mode:
10. ajax-content: This is for AJAX enabled page. If defined in following way:
A key "\product.printer" will be translated into HTML code "[tag1]product.printer[tag2][tag3]Imprimante[tag4]" in French.
7.4 Code modification
1 Dealing with interface message
The developers of application should make changes to codes to deal with interface message's translation. There are three methods in I18nMessage for developers to define an interface message key:
In the jsp page, find every message that should be translated, and use one of above method to convert it into a key.
An example would be look like this:
In this case, a key called "eshop_customer.List" is defined and automatically insert into the message dictionary. Before it is translated in the dictionary, it will be displayed as "[eshop_customer.List]", which means it is a key in the entry of the dictionary. After it is translated, it will be displayed as a translation.
For details about these methods, see API document included in the package.
2 Dealing with user's data
The difference between the translation of interface message and user's data is the way a key is defined. Instead of change the application codes to define a key, a configuration file is used to define which form's field should be a key.
3 Global configuration
Sometimes, it is necessary to make changes to i18n4data configuration to use its advanced feature. These changes include:
1. Set current language.
2. Set security for different users.
3. Set page based field-catalog mappings.
4. and more
The i18n4data provides a set of API for application developers. See 7.6 API document.
7.5 Make a search
It is always a good idea to provide end users search function. The i18n4data provides an API that return keys from search string of translation in a given language.
For details, see code in examples.
7.6 AJAX problem
For details, see code in examples.
7.7 API document
The i19n4data provides some API for application developers. Bellowing are a brief description to the API. For more information about them, see standard java doc API documents.
There one example to demonstrate the feature of i18n4data. It can be download from sourceforge.net or the project web site.
9 License agreement
The i18n4data use the Apache license 2.0 agreement.
10 Contact address
Huang Neng Geng