2010-04-14 - Jakarta Taglibs has been retired.

For more information, please explore the Attic.

Jakarta Project: i18n Tag library

Version: 1.0

Table of Contents

Overview

The i18n custom tag library contains tags that help manage the complexity of creating internationalized web applications. These tags provide similar (though not identical) functionality to the internationalization available in the struts framework, but do not require adopting the entire struts framework.

"i18n" is a common abbreviation for internationalization, because there are 18 letters between the first "i" and the last "n".

For more information on internationalization with Java, the java.sun.com site contains a good tutorial written by Dale Green.

Requirements

This custom tag library requires no software other than a servlet container that supports the JavaServer Pages Specification, version 1.1 or higher.

Configuration

Follow these steps to configure your web application with this tag library:

To use the tags from this library in your JSP pages, add the following directive at the top of each page:

<%@ taglib uri="http://jakarta.apache.org/taglibs/i18n-1.0" prefix="i18n" %>

where "i18n" is the tag name prefix you wish to use for tags from this library. You can change this value to any prefix you like.

Tag Summary

i18n Tags
bundleDefine a resource bundle for use by other i18n tags.
message Displays internationalized text from a resource bundle.
messageArg Specifies arguments to be used by the message tag's MessageFormat.
ifdef Allows jsp to be evaluated (or not) on a per locale basis.
ifndef Allows jsp to be evaluated (or not) on a per locale basis.
locale Defines a locale context.
formatString Formats a string.
formatNumber Formats a number.
formatCurrency Formats currency.
formatPercent Formats a percentage.
formatDateTime Formats a date/time.
formatDate Formats a date.
formatTime Formats a time.
 

Tag Reference

bundle Availability: 1.0

Establishes the ResourceBundle to use for other i18n tags on the page. Also determines the most appropriate Locale to use based on browser settings if a locale is not provided.

Tag BodyJSP    
Restrictions

This tag must be placed early in the page (before any HTML) in order for the output stream's content type to be set from the selected locale. If a locale (or localeRef) is not provided, the "best" locale will be determined from the browser settings and available locales for the requested bundle.

AttributesNameRequired Runtime Expression Evaluation Availability
 id  No   Yes  1.0
 

Script variable id for use with standard jsp:getProperty tag and as an attribute to other tags in this tag library.

 baseName  Yes   Yes  1.0
 

Used along with the provided (or auto-sensed) locale to locate the desired ResourceBundle.

 changeResponseLocale  No   No  1.0
 

Specifies whether or not the response locale should be changed to match the locale used by this tag.

 scope  No   No  1.0
 

Specifies the scope (application, session, request, page) that this bundle will be made available to message and other tags.

 locale  No   Yes  1.0
 

Allows the page developer to provide a direct object reference to the user's preferred locale.

 localeAttribute  No   Yes  1.0
 

DEPRECATED - use localeRef Allows the page developer to provide the name of an attribute whose value is the user's preferred locale. This attribute may exist in the page, request, session, or application scope.

 localeRef  No   Yes  1.0
 

Allows the page developer to provide the name of an attribute whose value is the user's preferred locale. This attribute may exist in the page, request, session, or application scope.

 debug  No   Yes  1.0
 

The debug flag. Logs debugging information of the bundle to the ServletContext.

VariablesNameScopeAvailability
  id attribute value   Start of tag to end of page  1.0
 

The scripting variable declared allows other tags or scriptlets to access the ResourceBundle defined by this tag. This is useful for allowing multiple bundle declarations per page or for creating localization debug pages by listing all key/value pairs in a bundle.

 PropertiesNone
Examples Define a bundle using browser preference to determine locale.  
 


<i18n:bundle baseName="org.apache.taglibs.i18n.i18n-test"/>
          

Define a bundle using browser preference to determine locale, and declaring the scripting variable "bundle".  
 


<i18n:bundle baseName="org.apache.taglibs.i18n.i18n-test"
             id="bundle"/>
          

Define a bundle using a scriptlet variable to specify the locale.  
 


<i18n:bundle baseName="org.apache.taglibs.i18n.i18n-test"
             locale="<%= localeVar %>"/>
          

Define a bundle using a page, request, session, or application attribute to specify the locale.  
 


<i18n:bundle baseName="org.apache.taglibs.i18n.i18n-test"
             localeRef="userLocale"/>
          

message Availability: 1.0

Format a message (using java.text.MessageFormat) from the value resulting from looking up the provided key within the default or specified resource bundle. Arguments to MessageFormat can be supplied as an object array or as subtags within the message tag body.

Tag BodyJSP    
Restrictions

Message tags require that a default bundle be provided (by placing a bundle tag prior to the message tag) or that a bundle or bundleRef attribute be supplied to the tag.

AttributesNameRequired Runtime Expression Evaluation Availability
 id  No   Yes  1.0
 

Script variable id for use with standard jsp:getProperty tag and as an attribute to other tags in this tag library.

 key  Yes   Yes  1.0
 

The key to use when retrieving the display message format from the ResourceBundle.

 args  No   Yes  1.0
 

Provides an array of args for use with java.text.MessageFormat when formatting the display text. This is an alternative to using arg subtags.

 bundle  No   Yes  1.0
 

An object reference to the ResourceBundle in which the key can be found.

 bundleRef  No   Yes  1.0
 

The name of an attribute that contains a resource bundle. This attribute is usually defined/populated by BundleTag's id attribute.

 debug  No   Yes  1.0
 

Set to "true" to log debugging messages.

VariablesNameScopeAvailability
  id attribute value   Nested within tag  1.0
 

The scripting variable declared allows other tags or scriptlets to access the String created by this tag. If id is specified the String will not be printed by this tag, just stored into the id.

 PropertiesNone
Examples Display a plain message using the default (first defined) bundle.  
 


<i18n:message key="column1.header"/>
          

Display a plain message using a specified bundle.  
 


<i18n:bundle baseName="org.apache.taglibs.i18n.i18n-test"
             id="bundle"/> <!-- the default -->
<i18n:bundle baseName="org.apache.taglibs.i18n.i18n-test2"
             id="bundle2"/> <!-- the alternate -->
<i18n:message key="column1.header" bundle="<%= bundle2 %>" />
          

Display a message with arguments. In the example below, the English value for the key "datetxt" is "Welcome, today is {0,date,short}."  
 


<%
  Object msgArgs[] = {new Date()};
%>
<i18n:message key="datetxt" args="<%= msgArgs %>"/>
          

messageArg Availability: 1.0

The messageArg tag is a simpler (and usually more readable) alternative to using the Message tag's args attribute for specifying arguments to MessageFormat. Note that if you use arguments for your message tags, java.util.MessageFormat puts some restrictions on the characters you are allowed to use. The one that is most likely to affect you is the requirement that single apostrophies should be escaped by another apostrophe (so, you replace ' with '' in your resource bundle properties file).

Tag Bodyempty    
Restrictions

Must reside inside the body of a message tag.

AttributesNameRequired Runtime Expression Evaluation Availability
 value  Yes   Yes  1.0
 

This attribute is to replace a positional variable in the message text. See the javadoc api for java.text.MessageText

VariablesNone
Examples Provide a date and number to be formatted in the message in the right location and according to the user's locale.  
 


<i18n:message key="test2"> 
   <i18n:messageArg value="<%= dateArg %>" /> 
   <i18n:messageArg value="<%= numberArg %>" /> 
</i18n:message>
          

ifdef Availability: 1.0

This tag processes the JSP contained in its body if the given key is defined in the given (or default if not specified) bundle.

Tag BodyJSP    
Restrictions

ifdef tags require that a default bundle be provided (by placing a bundle tag prior to the message tag) or that a bundle or bundleRef attribute be supplied to the tag.

AttributesNameRequired Runtime Expression Evaluation Availability
 key  Yes   Yes  1.0
 

The name of the key whose value (or lack thereof) will determine whether the body of this tag is processed.

 bundle  No   Yes  1.0
 

An object reference to the ResourceBundle in which the key can be found.

 bundleRef  No   Yes  1.0
 

The name of an attribute that contains a resource bundle. This attribute is usually defined/populated by BundleTag's id attribute.

VariablesNone
Examples Display a special disclaimer if there is one to display.  
 


   <i18n:ifdef key="specialDisclaimer"> 
     <H3>DISCLAIMER</H3> 
     <i18n:message key="specialDisclaimer" /> 
     Only those locales that have a specialDisclaimer key in 
     their ResourceBundle will see the special disclaimer text. 
   </i18n:ifdef>
          

ifndef Availability: 1.0

This tag processes the JSP contained in its body if the given key is NOT defined in the given (or default if not specified) bundle.

Tag BodyJSP    
Restrictions

ifndef tags require that a default bundle be provided (by placing a bundle tag prior to the message tag) or that a bundle or bundleRef attribute be supplied to the tag.

AttributesNameRequired Runtime Expression Evaluation Availability
 key  Yes   Yes  1.0
 

The name of the key whose value (or lack thereof) will determine whether the body of this tag is processed.

 bundle  No   Yes  1.0
 

An object reference to the ResourceBundle in which the key can be found.

 bundleRef  No   Yes  1.0
 

The name of an attribute that contains a resource bundle. This attribute is usually defined/populated by BundleTag's id attribute.

VariablesNone
Examples Display a special disclaimer if there is one to display.  
 


   <i18n:ifndef key="specialDisclaimer"> 
     <H3>DISCLAIMER</H3> 
     <i18n:message key="specialDisclaimer" /> 
     Only those locales that do NOT have a specialDisclaimer key in 
     their ResourceBundle will see the special disclaimer text. 
   </i18n:ifndef>
          

locale Availability: 1.0

Defines a locale context. This is either sepecified using the locale property, the combination of 'language', 'country' and the optional 'variant' property or the current HTTP request is used. If no other locale can be found then the default JVM locale is used. Other sub-tags will use this locale if no other locale is specified.

Tag BodyJSP    
Restrictions

AttributesNameRequired Runtime Expression Evaluation Availability
 id  No   Yes  1.0
 

Script variable id for use with standard jsp:getProperty tag and as an attribute to other tags in this tag library.

 locale  No   Yes  1.0
 

 localeRef  No   Yes  1.0
 

Allows the page developer to provide the name of an attribute whose value is the user's preferred locale. This attribute may exist in the page, request, session, or application scope.

 language  No   Yes  1.0
 

 country  No   Yes  1.0
 

 variant  No   Yes  1.0
 

VariablesNameScopeAvailability
  id attribute value   Start of tag to end of page  1.0
 

The scripting variable declared allows other tags or scriptlets to access the Locale defined by this tag.

 PropertiesNone
Examples No example provided (yet).  
 




          

formatString Availability: 1.0

Outputs a String value or displays the defaultText property if the String is null. The defaultText defaults to "".

Tag BodyJSP    
Restrictions

AttributesNameRequired Runtime Expression Evaluation Availability
 id  No   Yes  1.0
 

Script variable id for use with standard jsp:getProperty tag and as an attribute to other tags in this tag library.

 value  Yes   Yes  1.0
 

 defaultText  No   Yes  1.0
 

VariablesNameScopeAvailability
  id attribute value   Start of tag to end of page  1.0
 

The scripting variable declared allows other tags or scriptlets to access the Locale defined by this tag.

 PropertiesNone
Examples No example provided (yet).  
 




          

formatNumber Availability: 1.0

Formats a number using a locale. A pattern can be specified such as '##,###.##'. If the value is null then the default text is used. If no locale is specified then the parent <i18n:locale> tag is used. If no parent <i18n:locale> tag exists then the locale is taken from the current request. If still no locale could be found then the current JVM locale is used.

Tag BodyJSP    
Restrictions

AttributesNameRequired Runtime Expression Evaluation Availability
 id  No   Yes  1.0
 

Script variable id for use with standard jsp:getProperty tag and as an attribute to other tags in this tag library.

 value  Yes   Yes  1.0
 

 pattern  No   Yes  1.0
 

 locale  No   Yes  1.0
 

 defaultText  No   Yes  1.0
 

VariablesNameScopeAvailability
  id attribute value   Start of tag to end of page  1.0
 

The scripting variable declared allows other tags or scriptlets to access the Locale defined by this tag.

 PropertiesNone
Examples No example provided (yet).  
 




          

formatCurrency Availability: 1.0

Formats a number as a currency using a locale. If the value is null then the default text is used. If no locale is specified then the parent <i18n:locale> tag is used. If no parent <i18n:locale> tag exists then the locale is taken from the current request. If still no locale could be found then the current JVM locale is used.

Tag BodyJSP    
Restrictions

AttributesNameRequired Runtime Expression Evaluation Availability
 id  No   Yes  1.0
 

Script variable id for use with standard jsp:getProperty tag and as an attribute to other tags in this tag library.

 value  Yes   Yes  1.0
 

 locale  No   Yes  1.0
 

 defaultText  No   Yes  1.0
 

VariablesNameScopeAvailability
  id attribute value   Start of tag to end of page  1.0
 

The scripting variable declared allows other tags or scriptlets to access the Locale defined by this tag.

 PropertiesNone
Examples No example provided (yet).  
 




          

formatPercent Availability: 1.0

Formats a number as a percentage using a locale. If the value is null then the default text is used. If no locale is specified then the parent <i18n:locale> tag is used. If no parent <i18n:locale> tag exists then the locale is taken from the current request. If still no locale could be found then the current JVM locale is used.

Tag BodyJSP    
Restrictions

AttributesNameRequired Runtime Expression Evaluation Availability
 id  No   Yes  1.0
 

Script variable id for use with standard jsp:getProperty tag and as an attribute to other tags in this tag library.

 value  Yes   Yes  1.0
 

 locale  No   Yes  1.0
 

 defaultText  No   Yes  1.0
 

VariablesNameScopeAvailability
  id attribute value   Start of tag to end of page  1.0
 

The scripting variable declared allows other tags or scriptlets to access the Locale defined by this tag.

 PropertiesNone
Examples No example provided (yet).  
 




          

formatDateTime Availability: 1.0

Formats a Date value as a date-time using a locale. A dateStyle and a timeStyle (short/medium/long/full) can be specified. If the value is null then the default text is used. If no locale is specified then the parent <i18n:locale> tag is used. If no parent <i18n:locale> tag exists then the locale is taken from the current request. If still no locale could be found then the current JVM locale is used.

Tag BodyJSP    
Restrictions

AttributesNameRequired Runtime Expression Evaluation Availability
 id  No   Yes  1.0
 

Script variable id for use with standard jsp:getProperty tag and as an attribute to other tags in this tag library.

 value  No   Yes  1.0
 

 locale  No   Yes  1.0
 

 dateStyle  No   Yes  1.0
 

 timeStyle  No   Yes  1.0
 

 defaultText  No   Yes  1.0
 

VariablesNameScopeAvailability
  id attribute value   Start of tag to end of page  1.0
 

The scripting variable declared allows other tags or scriptlets to access the Locale defined by this tag.

 PropertiesNone
Examples No example provided (yet).  
 




          

formatDate Availability: 1.0

Formats a Date value as a date using a locale. A style (short/medium/long/full) can be specified or a pattern such as 'YYYY MMM ddd'. If the value is null then the default text is used. If no locale is specified then the parent <i18n:locale> tag is used. If no parent <i18n:locale> tag exists then the locale is taken from the current request. If still no locale could be found then the current JVM locale is used.

Tag BodyJSP    
Restrictions

AttributesNameRequired Runtime Expression Evaluation Availability
 id  No   Yes  1.0
 

Script variable id for use with standard jsp:getProperty tag and as an attribute to other tags in this tag library.

 value  No   Yes  1.0
 

 locale  No   Yes  1.0
 

 pattern  No   Yes  1.0
 

 style  No   Yes  1.0
 

 defaultText  No   Yes  1.0
 

VariablesNameScopeAvailability
  id attribute value   Start of tag to end of page  1.0
 

The scripting variable declared allows other tags or scriptlets to access the Locale defined by this tag.

 PropertiesNone
Examples No example provided (yet).  
 




          

formatTime Availability: 1.0

Formats a Date value as a time using a locale. A style (short/medium/long/full) can be specified. If the value is null then the default text is used. If no locale is specified then the parent <i18n:locale> tag is used. If no parent <i18n:locale> tag exists then the locale is taken from the current request. If still no locale could be found then the current JVM locale is used.

Tag BodyJSP    
Restrictions

AttributesNameRequired Runtime Expression Evaluation Availability
 id  No   Yes  1.0
 

Script variable id for use with standard jsp:getProperty tag and as an attribute to other tags in this tag library.

 value  No   Yes  1.0
 

 locale  No   Yes  1.0
 

 style  No   Yes  1.0
 

 defaultText  No   Yes  1.0
 

VariablesNameScopeAvailability
  id attribute value   Start of tag to end of page  1.0
 

The scripting variable declared allows other tags or scriptlets to access the Locale defined by this tag.

 PropertiesNone
Examples No example provided (yet).  
 




          

Examples

See the example application i18n-examples.war for examples of the usage of the tags from this custom tag library.

Java Docs

Java programmers can view the java class documentation for this tag library as javadocs.

Revision History

Review the complete revision history of this tag library.