轉：Jakarta Project: i18n Tag library

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:

• Copy the tag library descriptor file to the /WEB-INF subdirectory of your web application.
• Copy the tag library JAR file to the /WEB-INF/lib subdirectory of your web application.
• Add a <taglib> element to your web application deployment descriptor in /WEB-INF/web.xml like this:

  <taglib>
    <taglib-uri>http://jakarta.apache.org/taglibs/i18n-1.0</taglib-uri>
    <taglib-location>/WEB-INF/i18n.tld</taglib-location>
  </taglib>
        

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

bundle	Define 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 Body	JSP
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.
Attributes	Name	Required	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.
Variables	Name	Scope	Availability
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.
Properties	None
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 Body	JSP
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.
Attributes	Name	Required	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.
Variables	Name	Scope	Availability
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.
Properties	None
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 Body	empty
Restrictions	Must reside inside the body of a message tag.
Attributes	Name	Required	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
Variables	None
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 Body	JSP
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.
Attributes	Name	Required	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.
Variables	None
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 Body	JSP
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.
Attributes	Name	Required	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.
Variables	None
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 Body	JSP
Restrictions
Attributes	Name	Required	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
Variables	Name	Scope	Availability
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.
Properties	None
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 Body	JSP
Restrictions
Attributes	Name	Required	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
Variables	Name	Scope	Availability
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.
Properties	None
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 Body	JSP
Restrictions
Attributes	Name	Required	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
Variables	Name	Scope	Availability
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.
Properties	None
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 Body	JSP
Restrictions
Attributes	Name	Required	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
Variables	Name	Scope	Availability
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.
Properties	None
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 Body	JSP
Restrictions
Attributes	Name	Required	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
Variables	Name	Scope	Availability
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.
Properties	None
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 Body	JSP
Restrictions
Attributes	Name	Required	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
Variables	Name	Scope	Availability
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.
Properties	None
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 Body	JSP
Restrictions
Attributes	Name	Required	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
Variables	Name	Scope	Availability
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.
Properties	None
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 Body	JSP
Restrictions
Attributes	Name	Required	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
Variables	Name	Scope	Availability
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.
Properties	None
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.