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

For more information, please explore the Attic.

Tag reference sheet

Tag library reference for the following tag libraries:

i18n Tag library

null null null

This is version 1.0.

  • bundle Establishes the ResourceBundle to use for other i18n tags on the page
  • formatCurrency Formats a number as a currency using a locale
  • formatDate Formats a Date value as a date using a locale
  • formatDateTime Formats a Date value as a date-time using a locale
  • formatNumber Formats a number using a locale
  • formatPercent Formats a number as a percentage using a locale
  • formatString Outputs a String value or displays the defaultText property if the String is null
  • formatTime Formats a Date value as a time using a locale
  • ifdef This tag processes the JSP contained in its body if the given key is defined in the given (or default if not specified) bundle
  • ifndef 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
  • locale Defines a locale context
  • message Format a message (using java
  • messageArg The messageArg tag is a simpler (and usually more readable) alternative to using the Message tag's args attribute for specifying arguments to MessageFormat

Required attributes are marked with a *

<i18n:bundle>

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.

Can contain: JSP

Example

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"/>
      

Attributes

Name Description Type
baseName* Used along with the provided (or auto-sensed) locale to locate the desired ResourceBundle. String
changeResponseLocale Specifies whether or not the response locale should be changed to match the locale used by this tag. String
debug The debug flag. Logs debugging information of the bundle to the ServletContext. String
id Script variable id for use with standard null tag and as an attribute to other tags in this tag library. String
locale Allows the page developer to provide a direct object reference to the user's preferred locale. String
localeAttribute 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. String
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. String
scope Specifies the scope (application, session, request, page) that this bundle will be made available to message and other tags. String

Variables

Name Type Scope Description
specified via id java.util.ResourceBundle AT_BEGIN 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.

<i18n:formatCurrency>

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.

Can contain: JSP

Attributes

Name Description Type
defaultText String
id Script variable id for use with standard null tag and as an attribute to other tags in this tag library. String
locale String
value* String

Variables

Name Type Scope Description
specified via id java.util.Locale AT_BEGIN The scripting variable declared allows other tags or scriptlets to access the Locale defined by this tag.

<i18n:formatDate>

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.

Can contain: JSP

Attributes

Name Description Type
defaultText String
id Script variable id for use with standard null tag and as an attribute to other tags in this tag library. String
locale String
pattern String
style String
value String

Variables

Name Type Scope Description
specified via id java.util.Locale AT_BEGIN The scripting variable declared allows other tags or scriptlets to access the Locale defined by this tag.

<i18n:formatDateTime>

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.

Can contain: JSP

Attributes

Name Description Type
dateStyle String
defaultText String
id Script variable id for use with standard null tag and as an attribute to other tags in this tag library. String
locale String
timeStyle String
value String

Variables

Name Type Scope Description
specified via id java.util.Locale AT_BEGIN The scripting variable declared allows other tags or scriptlets to access the Locale defined by this tag.

<i18n:formatNumber>

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.

Can contain: JSP

Attributes

Name Description Type
defaultText String
id Script variable id for use with standard null tag and as an attribute to other tags in this tag library. String
locale String
pattern String
value* String

Variables

Name Type Scope Description
specified via id java.util.Locale AT_BEGIN The scripting variable declared allows other tags or scriptlets to access the Locale defined by this tag.

<i18n:formatPercent>

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.

Can contain: JSP

Attributes

Name Description Type
defaultText String
id Script variable id for use with standard null tag and as an attribute to other tags in this tag library. String
locale String
value* String

Variables

Name Type Scope Description
specified via id java.util.Locale AT_BEGIN The scripting variable declared allows other tags or scriptlets to access the Locale defined by this tag.

<i18n:formatString>

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

Can contain: JSP

Attributes

Name Description Type
defaultText String
id Script variable id for use with standard null tag and as an attribute to other tags in this tag library. String
value* String

Variables

Name Type Scope Description
specified via id java.util.Locale AT_BEGIN The scripting variable declared allows other tags or scriptlets to access the Locale defined by this tag.

<i18n:formatTime>

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.

Can contain: JSP

Attributes

Name Description Type
defaultText String
id Script variable id for use with standard null tag and as an attribute to other tags in this tag library. String
locale String
style String
value String

Variables

Name Type Scope Description
specified via id java.util.Locale AT_BEGIN The scripting variable declared allows other tags or scriptlets to access the Locale defined by this tag.

<i18n:ifdef>

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

Can contain: JSP

Example

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>
      

Attributes

Name Description Type
bundle An object reference to the ResourceBundle in which the key can be found. String
bundleRef The name of an attribute that contains a resource bundle. This attribute is usually defined/populated by BundleTag's id attribute. String
key* The name of the key whose value (or lack thereof) will determine whether the body of this tag is processed. String

<i18n:ifndef>

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.

Can contain: JSP

Example

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>
      

Attributes

Name Description Type
bundle An object reference to the ResourceBundle in which the key can be found. String
bundleRef The name of an attribute that contains a resource bundle. This attribute is usually defined/populated by BundleTag's id attribute. String
key* The name of the key whose value (or lack thereof) will determine whether the body of this tag is processed. String

<i18n:locale>

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.

Can contain: JSP

Attributes

Name Description Type
country String
id Script variable id for use with standard null tag and as an attribute to other tags in this tag library. String
language String
locale String
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. String
variant String

Variables

Name Type Scope Description
specified via id java.util.Locale AT_BEGIN The scripting variable declared allows other tags or scriptlets to access the Locale defined by this tag.

<i18n:message>

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.

Can contain: JSP

Example

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 %>"/>
      

Attributes

Name Description Type
args Provides an array of args for use with java.text.MessageFormat when formatting the display text. This is an alternative to using arg subtags. String
bundle An object reference to the ResourceBundle in which the key can be found. String
bundleRef The name of an attribute that contains a resource bundle. This attribute is usually defined/populated by BundleTag's id attribute. String
debug Set to "true" to log debugging messages. String
id Script variable id for use with standard null tag and as an attribute to other tags in this tag library. String
key* The key to use when retrieving the display message format from the ResourceBundle. String

Variables

Name Type Scope Description
specified via id String NESTED 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.

<i18n:messageArg>

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).

Can contain: empty

Example

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>
      

Attributes

Name Description Type
value* This attribute is to replace a positional variable in the message text. See the javadoc api for java.text.MessageText String