Localization in Tomcat

This document attempts to provide information necessary for development of localized content that is served under Tomcat.

The audience of this document is developers of Tomcat applications, internationalization and localization experts that need to perform conversions of content to specific locales.

The document is divided into several sections.

How to organize Localized Resources in Tomcat

This section will describe the schemes that are available under Tomcat to provide access to localized versions of resources, including but not limited to HTML pages, javascript files, image files, etc.

Tomcat provides three mechanisms that enable it to serve localized versions of content:

• no lookup for localized resource
• file based organization for lookup of localized resource
• docbase based organization for lookup for localized resource

File based organization for localized resource lookup

This type of organization of localized content attempts to find the localized version of the resource queried based on the basename of the resource, using the lookup conventions specified in java.lang.ResourceBundle.

For example, assume the following scenario:



• User's Locale: fr_CA
• Webserver's Locale: es_AR
• docbase: /myapp
• User's URL query: /myapp/index.html

This scheme will try to look up for the resource in the following priority order:



• /myapp/index_fr_CA.html
• /myapp/index_fr.html
• /myapp/index_es_AR.html
• /myapp/index_es.html
• /myapp/index.html

When using this scheme, all localized versions will end up residing on the same directory where the default (the one without the localized name) file is located.

Developer's note: there is no need to change the URLs on each one of the localized versions of the files provided.

Docbase based organization for localized resource lookup

This type of organization of the localized resources attempts to find the localized version of the resource queried based on the existence of a localized document hierarchy under the 'docbase' directory. The organization of the documents is similar to the one that JavaHelp uses.

For example, assume the following scenario:



• User's Locale: fr_CA
• Webserver's Locale: es_AR
• docbase: /myapp
• User's URL query: /myapp/index.html

This scheme will try to look up for the resource in the following priority order:



• /myapp/fr_CA/index.html
• /myapp/fr/index.html
• /myapp/es_AR/index.html
• /myapp/es/index.html
• /myapp/index.html

When using this scheme, all localized versions will end up residing on different directories. All the files for a specific locale will appear in subdirectories under a common parent [docbase]/[locale] directory.

Developer's note: on the localized version(s) of the file, there may be a need to change the URLs. This, especially when there are relative references in those URLs (for example, accessing documents in a directory above).

Implementation Topics

The org.apache.tomcat.request.StaticInterceptor class is used to handle the lookup for localized resources.

This is accomplished by specifying on the corresponding entry on server.xml. The StaticInterceptor class includes a property called localization that can be set to any of the values below:



• "file"
• "docbase"

Below is an example of what the StaticInterceptor entry should look for file-based lookup.

<RequestInterceptor className="org.apache.tomcat.request.StaticInterceptor" debug="0" localization="file" suppress="false" />

Below is an example of what the StaticInterceptor entry should look for docbase-based lookup.

<RequestInterceptor className="org.apache.tomcat.request.StaticInterceptor" debug="0" localization="docbase" suppress="false" />

The default mode is set not to perform localized resource lookup.

Futures and Extensibility

The mechanism by which the above mentioned file organization schemes has been implemented can be extended to support future types of localization organization.

This section concerns Jakarta developers. Tomcat users may skip this section.

The steps to carry this out include modification of the org.apache.tomcat.request.StaticInterceptor, org.apache.tomcat.util.FileUtil, org.apache.tomcat.core.Context as appropriate.

Among the activities required the team will have to develop localized lookup methods (in FileUtil), code to invoke the lookup methods (in StaticInterceptor and Context.

Copyright © 1999-2001, Apache Software Foundation