ji18n Tag Library Documentation

Library Version: 1.0
Library URI: /WEB-INF/ji18n.tld
JSP Required: 1.1

A library of internationalization tags.

Tag Summary
<ji18n:include> A tag to include localized pages.
<ji18n:includeBody> A tag to include the main page body in templates.
<ji18n:message> A tag to generate internationalized messages.
<ji18n:resource> A tag to specify the resource file for a page.
<ji18n:url> A tag to generate a localized URL.

Library Description

A library of JSP tags for internationalized messages, URLs and templates.

Technical Note: For more detailed information, consult the section on Internationalization in the Java Developers Guide.

Tag Details

<ji18n:message> Tag

Tag Handler Class: org.chwf.taglib.ji18n.MessageTag
Tag Body Content: JSP
Tag Attributes: name, key, resource

This tag is used to generate internationalized messages in JSP pages from data in configuration files. The tag specifies a lookup name and the location of a resource property file. The message lookup process follows a pattern similar to that used by Java's ResourceBundle.

<ji18n:message name="message1" />

Messages are defined in the /WEB-INF/classes/page_config/chrysalis.xml configuration file. See the Page Configuration documentation for further details.

In addition to the normal configuration files, you explicitly define the location of a particular message file, with the "resource" attribute. The message files can use Java's properties file format.

<ji18n:message name="message1" resource="message_file" />
# In file "message_file.properties"
message1=This is message one.
message2=And here is message two.

Message properties files are loaded via the Java classpath. The simplest place to put the message files is beneath the /WEB-INF/classes/ directory. If the resource name includes directory information, the message file must be in a subdirectory.

<ji18n:message name="message1" resource="directory/message_file" />
[Located at "/WEB-INF/classes/directory/message_file.properties"]

Message properties files for different languages need to have a "locale suffix" added to their name. These suffixes are derived from the ISO standard two-letter language codes. For example, the suffix for French is "_fr".

# In file "message_file_fr.properties"
message1=C'est message un.
message2=Et ceci est message deux.

Messages may include argument insertion points marked by {#}, where "#" is a number.

# In the message resource properties file:
message.with.arguments=Two values are inserted: {0} and {1}.

Values for the insertion points may be specified using <jutil:param> tags.

<ji18n:message name="message.with.arguments">
  <jutil:param name="value1">Value 1</jutil:param>
  <jutil:param name="value2">Value 2</jutil:param>
</ji18n:message>
[Results in "Two values are inserted: Value 1 and Value 2."]

The parameter names are unimportant, but the order of the parameters must match the numerical order of the insertion points. The first parameter is inserted for {0}, the second for {1} and so on.

Technical Note: This tag uses the same search algorithm defined for the org.chwf.config.Config class.

Tag Attributes
  • name (Optional): The lookup name for the message. Must have either name or key attribute.
  • key (Optional): Deprecated: Use name attribute instead. Will be removed by Chrysalis 1.1 release.
  • resource (Optional): The message resource location. If omitted, derives the message resource from the JSP URI: "/page_config" + URI - (context path and ".jsp" extension).

<ji18n:resource> Tag

Tag Handler Class: org.chwf.taglib.ji18n.ResourceTag
Tag Body Content: JSP
Tag Attributes: basename

This tag specifies the resource file for all the following message tags in the page. It is equivalent to setting the resource attribute for all the message tags.

<ji18n:resource basename="message_file" />

Tag Attributes
  • basename (Required): The basename of the resource file.

<ji18n:include> Tag

Tag Handler Class: org.chwf.taglib.ji18n.IncludeTag
Tag Body Content: JSP
Tag Attributes: name, key, resource

This tag is similar to the <ji18n:message> tag, except that the retrieved property value is treated as a URI and the specified page is included (if it exists).

Tag Attributes
  • name (Optional): The lookup name for the message. Must have either name or key attribute.
  • key (Optional): Deprecated: Use name attribute instead. Will be removed by Chrysalis 1.1 release.
  • resource (Optional): The message resource location. If omitted, derives the message resource from the JSP URI.

<ji18n:includeBody> Tag

Tag Handler Class: org.chwf.taglib.ji18n.IncludeBodyTag
Tag Body Content: empty

This tag is used in template pages to indicate the insertion point for the main page body. When this tag is encountered, processing is forwarded to the main JSP, whose output is inserted in the template. For example:

Page Source Code
Main Page <p>Page body.</p>
Template Page <h1>Header</h1>
<ji18n:includeBody />
<h6>Footer</h6>
Output <h1>Header</h1>
<p>Page body.</p>
<h6>Footer</h6>

<ji18n:url> Tag

Tag Handler Class: org.chwf.taglib.ji18n.UrlTag
Tag Body Content: JSP
Tag Attributes: value, i18n

This tag generates a localized URL. It performs the following transformation on the URL value:

  • Prepends the context path to the URL.
  • Appends localization information to the file name, based on the value of the i18n attribute.

To localize by language, use the value i18n="LANGUAGE".

<ji18n:url value="/images/logo.gif" i18n="LANGUAGE" />

In the above example, the URL will be:

  • English Locale: "/[context]/images/logo_en.gif"
  • French Locale: "/[context]/images/logo_fr.gif"

To localize by language, use the value i18n="COUNTRY".

<ji18n:url value="/images/logo.gif" i18n="COUNTRY" />

In the above example, the URL will be:

  • US Locale: "/[context]/images/logo_en_US.gif"
  • France Locale: "/[context]/images/logo_fr_FR.gif"

If there is no i18n attribute valule, the tag merely prepends the context path.

<ji18n:url value="/images/logo.gif" />
  • "/[context]/images/logo.gif"

Tag Attributes
  • value (Required): The url value to be localized.
  • i18n (Optional): How to localize, by "LANGUAGE" or by "COUNTRY".