Struts: The Complete Reference, 2nd Edition

Internationalizing Tiles

Similar to other areas of Struts, Tiles fully supports internationalization. Remember that internationalization is the process of tailoring content to a specific locale or region. For Tiles, internationalization means tailoring Tiles definitions and attributes to a specific locale. That way, the U.S. and French versions of a Web site can each have their own language-specific definitions and attributes, for example.

Although Tiles' internationalization support is similar to the core internationalization support in Struts, it's intended to allow you to provide locale-specific layout differences, not to internationalize text or messages. That should be done with the core Struts internationalization features. Tiles internationalization support is for such things as the differences in the size of internationalized images or the length of internationalized text. For example, using Tiles' internationalization support, you can define one version of a definition that handles the appropriate sizing for images and text for the United States and a second version designed for France, which accommodates the larger images and longer text necessary for the French content. Tiles simply provides the mechanism to define the layout appropriately for each locale.

To tailor Tiles definitions and attributes to a specific locale, you have to create a Tiles XML configuration file for each locale. Each locale-specific configuration file is distinguished by its filename using the same naming scheme that is used for Java Resource Bundles. Thus, to create English and French versions of a set of definitions and their attributes, you would create a file named tiles-defs_en.xml for the English version and a file named tiles-defs_fr.xml for the French version. The suffix portion of each filename contains the language code for the locale that the file is intended for. At run time, Tiles uses the locale object that Struts stores in the session (or from the request if Struts is configured that way) to determine which configuration file it should use definitions from to process the current request. Each configuration file should have the same definitions with the same attributes. All of the names of definitions and attributes must be the same (that is, line up) in each file. The values of the definitions and attributes, however, will be specific to the locale of the particular file.

Parallel to the way Java Resource Bundles function, Tiles will attempt to find definitions and attributes for the current request's locale in a configuration file specific to that locale. If the definitions and attributes are not found in the locale-specific configuration file, Tiles will attempt to load them from the default configuration file whose filename does not contain any locale information (e.g., tiles-defs.xml). This is especially helpful when you want to tailor only a few definitions to a specific locale. To accomplish this, create a default configuration file (tiles-defs.xml) that contains all the "master" Tiles definitions and attributes. Then, create locale-specific configuration files (e.g., tiles-defs_fr.xml or tiles-defs_es.xml) that override definitions in the default configuration file. You can choose to override as few or as many definitions as you like. At run time, if Tiles cannot find a locale-specific version of a definition, it will automatically use the definition from the default configuration file.

To illustrate how Tiles' internationalization supports works, let's step through an example scenario. Assume that you have a Web site that is available in English (default), French, and Spanish versions. This requires three Tiles configuration files.

The first file, tiles-defs.xml, which is shown next, houses the master Tiles definitions for the Web site. Because the default language for the site is English, the English definitions will reside in this file and serve as the default definitions for the other languages when the other languages are not overriding the definitions in this file.

<?xml version="1.0"?> <!DOCTYPE tiles-definitions PUBLIC "-//Apache Software Foundation//DTD Tiles Configuration 1.3//EN" "http://struts.apache.org/dtds/tiles-config_1_3.dtd"> <tiles-definitions> <!-- Search Page --> <definition name="search.page" path="/mainLayout.jsp"> <put name="header" value="/header.jsp"/> <put name="body" value="/search.jsp"/> <put name="footer" value="/footer.jsp" /> </definition> <!-- View Employee Page --> <definition name="viewEmployee.page" path="/mainLayout.jsp""> <put name="header" value="/header.jsp"/> <put name="body" value="/viewEmployee.jsp"/> <put name="footer" value="/footer.jsp" /> </definition> </tiles-definitions>

This configuration file contains two basic page definitions that utilize the same page layout and simply provide different values for the body attribute.

The second file, tiles-defs_fr.xml, provides French-specific definitions and attributes:

<?xml version="1.0"?> <!DOCTYPE tiles-definitions PUBLIC "-//Apache Software Foundation//DTD Tiles Configuration 1.3//EN" "http://struts.apache.org/dtds/tiles-config_1_3.dtd"> <tiles-definitions> <!-- Search Page --> <definition name="search.page" path="/mainLayout_fr.jsp"> <put name="header" value="/header_fr.jsp"/> <put name="body" value="/search_fr.jsp"/> <put name="footer" value="/footer_fr.jsp" /> </definition> <!-- View Employee Page --> <definition name="viewEmployee.page" path="/mainLayout_fr.jsp""> <put name="header" value="/header_fr.jsp"/> <put name="body" value="/viewEmployee_fr.jsp"/> <put name="footer" value="/footer_fr.jsp" /> </definition> </tiles-definitions>

The definitions in this file mirror those of the default configuration file, with the exception that the values for the definitions and attributes are different. The definition and attribute names are the same so that they match up with those in the default file. Notice that the values for the definition paths are set to a JSP named mainLayout_fr.jsp. That is a French-specific version of mainLayout.jsp. If the layout JSP itself did not need to change to accommodate the French version, you would leave the path set to /mainLayout.jsp and specify only French-specific versions of the attributes inside the definitions. It's up to you to determine how much customization you need or want for each locale.

The third file, tiles-defs_es.xml, includes the Spanish-specific definitions and attributes. This file, shown next, includes only a Spanish-specific version of the search.page definition.

<?xml version="1.0"?> <!DOCTYPE tiles-definitions PUBLIC "-//Apache Software Foundation//DTD Tiles Configuration 1.3//EN" "http://struts.apache.org/dtds/tiles-config_1_3.dtd"> <tiles-definitions> <!-- Search Page --> <definition name="search.page" path="/es/mainLayout.jsp"> <put name="header" value="/es/header.jsp"/> <put name="body" value="/es/search.jsp"/> <put name="footer" value="/es/footer.jsp" /> </definition> </tiles-definitions>

Because this file contains only a Spanish version of the search.page definition, if a request is made for the Spanish version of the viewEmployee.page definition, Tiles will (after not finding it in tiles-defs_es.xml) look for it in the default configuration file, tiles-defs.xml. Notice that the attributes in this file point to JSPs underneath an es directory. There are many ways you can organize your application's content to support internationalization. This example places the locale-specific files in a directory dedicated to that locale. The French configuration file points to files whose locale is part of the filename. Which approach you take to organizing content is up to you.