The process of designing an application (or page content) so that it can be adapted to various languages and regions without requiring any engineering changes is known as internationalization, or I18N for short. Once a web application has been internationalized, it can be adapted for a number of regions or languages by adding locale-specific components and translating text. This process is known as localization.
There are two approaches to internationalizing a web application:
Any action that requires a locale first calls the getLocales() method on the incoming request, which provides a list, in order of preference, of the locales that the client wants to use. This list is processed differently depending on whether the action is an I18N or a formatting tag.
For each of the client's preferred locales (in order of preference), the action checks if there is a matching locale for the resource bundle in question, by passing the resource bundle's base name and the client's requested locale to the java.util.ResourceBundle.getBundle() method. The returned locale may either match both the country and language of the requested locale (exact match), only its language, or neither. If there is an exact match, it is used, and no further client locales are checked. Otherwise, the first match on language is used. If no such match exists, the fallback locale is used by searching the javax.servlet.jsp.jstl.i18n.fallbackLocale attribute in the page, request, session (if valid), and application scope(s) (in this order) (see Section 16: Configuration parameters). If this attribute does not exist, the default locale of the JSP container's Java runtime is used.
For example, if the client's preferred locales were ja, en-UK, en-US, en-CA, and fr (in this order), and the available ones (for the resource bundle in question) en and fr, the best match would be en; if the available ones were en, en-US, and fr, then the best match would be en-US.
The behavior is implementation-defined if the set of available resource bundles changes during execution of the page. Implementations may thus cache the best matching locale for a given resource bundle when one is found.
If the formatting action is enclosed within a <bundle> action, the locale of the parent bundle is used as the formatting locale.
Otherwise, if the javax.servlet.jsp.jstl.i18n.basename attribute is set, the best matching locale for that base name is determined (according to the algorithm described in Section 2.1.1) and used as the formatting locale.
Otherwise, the formatting action checks, for each of the client's preferred locales (in order of preference), if there is a matching locale available. The <formatNumber> and <parseNumber>, and the <formatDate> and <parseDate> actions determine the available locales by calling java.text.NumberFormat.getAvailableLocales() and java.text.DateFormat.getAvailableLocales(), respectively. If there is an exact match (that is, a client locale matches both the language and country of an available locale), it is used, and no further client locales are checked. Otherwise, the first match on language is used. If no such match exists, the default locale of the JSP container's Java runtime is used. Once the best matching locale has been determined, it is cached, so that any subsequent formatting actions on the same page do not have to determine it again.
The javax.servlet.jsp.jstl.i18n.locale attribute is searched in the page, request, session (if valid), and application scope(s) (in this order).
Because this proposal's I18N tags address situations requiring multiple locales, they are perhaps more likely than most to output characters that cannot be accommodated by the default ISO-8859-1 character encoding.
Page authors should take note of this and consider using the page directive's contentType attribute to explicitly set the character encoding in the Content-Type response header in situations where the default (ISO-8859-1) is not sufficient.
The javax.servlet.jsp.jstl.i18n.timeZone attribute may be set directly by application code for any of the JSP scopes. For example, an application might let its users pick their preferred time zone and then set the javax.servlet.jsp.jstl.i18n.timeZone attribute accordingly. Alternatively, the <timeZone> action may be used to set the javax.servlet.jsp.jstl.i18n.timeZone attribute for the current page context. This may be useful in the case where a client's preferred time zone is retrieved from a database (using the JSTL database tags) and imported into the page using the <timeZone> tag.
The javax.servlet.jsp.jstl.i18n.timeZone attribute is searched in the page, request, session (if valid), and application scope(s) (in this order). If not found, the JSP container's time zone is used.
The locale specified by the value attribute must contain a two-letter (lower-case) language code (as defined by ISO-639), and may contain a two-letter (upper-case) country code (as defined by ISO-3166). Language and country codes must be separated by hyphen ('-') or underscore ('_').
Optionally, a (vendor- or browser-specific) variant may be specified using the variant attribute. See the java.util.Locale javadocs for more information on variants.
Example:
<fmt:locale value="en-US" variant="UNIX"/>
By using this action, the browser-sensing capabilities for locales described in Section 2 of this functional description are disabled. This means that if this action is being used, it should be declared at the beginning of a page, before any other I18N/Formatting tags. Otherwise, a different locale might be used up to the position in the page where the <locale> action is specified.
<fmt:timeZone value="America/Los_Angeles">
<fmt:formatDate type="time"/>
</fmt:timeZone>
The time zone may be specified as either an abbreviation (such as "PST"), a full name (such as "America/Los_Angeles"), or a custom format (such as "GMT-8:00). See java.util.TimeZone.getTimeZone() for more details on the supported time zone formats.
The var attribute may be used to expose the time zone as a JSP-scoped attribute of type java.util.TimeZone (with visibility AT_END), so that it can be referenced by any subsequent <formatDate> actions that are not nested inside a <timeZone> action and take a timeZone attribute:
<fmt:timeZone value="America/Los_Angeles"
var="losAngelesTimeZone"/>
<fmt:formatDate type="time" timeZone="$losAngelesTimeZone"/>
A <timeZone> action that is specified without a body and without the var attribute can be used to set or override the javax.servlet.jsp.jstl.i18n.timeZone attribute in the scope given by the scope attribute (default: "page"), thereby making its time zone the (new) default in that scope:
<fmt:timeZone value="America/Los_Angeles"/>
<fmt:formatDate type="time"/>
<fmt:bundle basename="com.acme.labels.ButtonLabels">
<user-of-bundle/>
</fmt:bundle>
The resource bundle's locale is determined according to Section 2 of this functional description.
The var attribute may be used to expose the resource bundle as a JSP-scoped attribute of type java.util.ResourceBundle (with visibility AT_END), so that it can be referenced by any subsequent <message> actions that take a bundle attribute:
<fmt:bundle basename="com.acme.labels.ButtonLabels"
var="buttonLabels"/>
<fmt:message key="Submit" bundle="$buttonLabels"/>
Exposing a resource bundle via the var attribute is useful if the bundle needs to be accessed multiple times.
A <bundle> action that is specified without a body and without the var attribute can be used to set or override the javax.servlet.jsp.jstl.i18n.basename attribute in the scope given by the scope attribute (default: "page"), thereby making its base name the (new) default in that scope:
<fmt:bundle basename="com.acme.labels.ButtonLabels"/>
<fmt:message key="Submit"/>
The prefix attribute is provided as a convenience for very long key names: Its value is prepended to any message key (see the <message> action) that is to be looked up in the resource bundle that was loaded by this action.
The resource bundle in which to look up the message key may be given by the bundle attribute. If this attribute is missing, and the <message> action is nested inside a <bundle> tag, the resource bundle to use is taken from the enclosing <bundle> tag. Otherwise, the resource bundle with the default base name given by the javax.servlet.jsp.jstl.i18n.basename attribute is used, which is searched in the page, request, session (if valid), and application scope(s) (in this order).
The <message> action outputs its result to the current JspWriter object, unless the var attribute is specified, in which case the result is stored in the named JSP attribute.
Example:
<fmt:message key="Welcome"/>
<%-- Key is looked up in default bundle --%>
<fmt:bundle basename="Errors" var="errorBundle"/>
<fmt:bundle basename="Greetings">
<fmt:message key="Welcome"/>
<%-- Key is looked up in parent <bundle> tag --%>
<fmt:message key="WrongPassword"
bundle="$errorBundle"/> <%-- Key is looked up in errorBundle --%>
</fmt:bundle>
If the given key is not found in the resource bundle, or a resource bundle with the given base name does not exist, a message is logged to the servlet context, and an error message of the form "???<key>???" (where <key> is the name of the undefined key) is output to the current JspWriter object.
If the message corresponding to the given key is compound, that is, contains one or more variables, it can be supplied with argument values for these variables by using a <messageArg> subtag for each argument value. This procedure is referred to as parametric replacement. If the message is compound, but no <messageArg> subtags are given, the message is left unmodified.
If the parent <bundle> action specifies a prefix attribute, its value is prepended to any key names to be looked up in that bundle. For example, using the prefix attribute, the key names in:
<fmt:bundle basename="Labels">
<fmt:message key="com.acme.labels.firstName"/>
<fmt:message key="com.acme.labels.lastName"/>
</fmt:bundle>
may be abbreviated to:
<fmt:bundle basename="Labels" prefix="com.acme.labels.">
<fmt:message key="firstName"/>
<fmt:message key="lastName"/>
</fmt:bundle>
The argument values for parametric replacement must be supplied via <messageArg> subtags. Each <messageArg> subtag replaces one parameter in the pattern. Parametric replacement takes place in the order of the <messageArg> subtags. If no <messageArg> subtag is given, the specified pattern is left unmodified.
The result is output to the current JspWriter object, unless the var attribute is given, in which case it is stored in the named JSP attribute.
The <messageFormat> action is useful if a pattern needs to be supplied from sources other than resource bundles, or if a pattern extracted from a resource bundle needs to be used multiple times.
For example, when displaying a list of products, the same internationalized message (pattern) would be used to display the price, but rather than looking up the same pattern for every single product, the pattern could be looked up once (using the <message> action) and then passed in to the <messageFormat> action for each product, as follows:
<fmt:bundle basename="..." var="i18n"/>
<fmt:message key="store.product.price" bundle="$i18n"
var="priceMsg"/>
<c:forEach ...>
... <fmt:messageFormat value="$priceMsg">...</fmt:messageFormat>
</c:forEach>
instead of the less efficient alternative:
<fmt:bundle basename="..." var="i18n"/>
<c:forEach ...>
... <fmt:message key="store.product.price"
bundle="$i18n">...</fmt:message>
</c:forEach>
One <messageArg> action must be specified for each variable in the compound message or pattern. Parametric replacement takes place in the order of the <messageArg> tags.
The argument value can be specified either via the value attribute:
<fmt:message key="Welcome"> <fmt:messageArg value="$dateArg"/> </fmt:message>or inline via the tag's body content:
<fmt:message key="Welcome">
<fmt:messageArg>
<acme:doIt .../>
</fmt:messageArg>
</fmt:message>
Depending on the value of the type attribute, which must be one of "number", "currency", or "percent" (default: "number"), the numeric value specified by the value attribute is formatted as a number, currency, or percentage, respectively, using the default formatting pattern for numbers (currencies, percentages) of the page's locale, which is determined according to Section 2 of this functional description.
The result is output to the current JspWriter object, unless the var attribute is given, in which case it is stored (as a string) in the named JSP attribute.
Example: The output of
<fmt:formatNumber value="9876543.21" type="currency"/>
varies with the page's locale (given in parentheses), as follows:
9 876 543,21 F (fr_FR)
9.876.543,21 DM (de_DE)
$9,876,543.21 (en_US)
When formatting the given value as a number, the predefined formatting pattern of the page's locale can be overridden by using the pattern attribute, allowing page authors to control the display of leading and trailing zeros, prefixes and suffixes, grouping (thousands) separators, and the decimal separator of the formatted number. The given pattern string must follow the Number Format Pattern Syntax specified in the tutorial trail on internationalization at java.sun.com.
For example, a pattern of ".000" will cause any numeric value formatted with it to be represented with 3 fraction digits, adding trailing zeros if necessary, so that
<fmt:formatNumber value="12.3" pattern=".000"/>
will output "12.300".
Likewise, a pattern of "#,#00.0#" specifies that any numeric value formatted with it will be represented with a minimum of 2 integer digits, 1 fraction digit, and a maximum of 2 fraction digits, with every 3 integer digits grouped. Applied to "123456.7891", as in:
<fmt:formatNumber value="123456.7891" pattern="#,#00.0#"/>
the formatted output will be "123,456.79" (note that rounding is handled automatically).
The value and pattern attributes accept both string literals and EL values. If the input to the value attribute is a string literal, it is first parsed into an instance of java.lang.Number according to the default pattern of the page's locale. If the numeric string uses a format different from the locale's default, it must be parsed using the <parseNumber> action.
The type attribute accepts (case-insensitive) literals only, causing an error at translation-time validation if the specified literal is illegal.
The pattern attribute may be used only when formatting numbers (that is, if the type attribute is missing or is equal to "number"). Using it with a type attribute equal to "currency" or "percent" causes a translation-time error.
Depending on the value of the type attribute, which must be one of "number", "currency", or "percent" (default: "number"), the string specified via the value attribute is parsed as a number, currency, or percentage, respectively, using the default formatting pattern for numbers (currencies, percentages) of the page's locale, which is determined according to Section 2 of this functional description.
If the number specified via the value attribute uses a format different from the page locale's default, the pattern required to parse it may be specified using the pattern attribute.
If the var attribute is given, the parsing result (of type java.lang.Number) is stored in the named JSP attribute. Otherwise, it is output to the current JspWriter object using java.lang.Number.toString().
The value and pattern attributes accept both literals and EL values, whereas the type attribute accepts (case-insensitive) literals only, causing an error at translation-time validation if the specified literal is illegal.
The pattern attribute may be used only when parsing numbers (that is, if the type attribute is missing or equals "number"). Using it with a type attribute equal to "currency" or "percent" causes a translation-time error.
Depending on the value of the type attribute, which must be one of "time", "date", or "both" (default: "date"), only the time, the date, or both the time and date components of the date specified via the value attribute are formatted, using one of the predefined formatting styles for dates (specified via the dateStyle attribute) and times (specified via the timeStyle attribute) of the page's locale, which is determined according to Section 2 of this functional description. Legal values for the dateStyle and timeStyle attributes are "default", "short", "medium ", "long", and "full" (default: "default").
If the value attribute is missing, the current date and time are used.
Any time information is represented in the time zone given by the timeZone attribute. If this attribute is missing, and the <formatDate> action is nested inside a <timeZone> tag, the time zone to use is taken from the enclosing <timeZone> tag. Otherwise, the default time zone given by the javax.servlet.jsp.jstl.i18n.timeZone attribute is used, which is searched in the page, request, session (if valid), and application scope(s) (in this order). If not found, the JSP container's time zone is used.
The action's result is output to the current JspWriter object, unless the var attribute is given, in which case it is stored (as a string) in the named JSP attribute.
Example: Assuming a current date of Oct 22, 2001 and a current time of 4:05:53 PM,
<fmt:formatDate timeStyle="long" dateStyle="long"/>
will output
October 22, 2001 4:05:53 PM PDT
for the U.S. and
22 octobre 2001 16:05:53 GMT-07:0
for the French locale.
Page authors may also apply a customized formatting style for their times and dates by specifying the pattern attribute. The specified formatting pattern must use the Date Format Pattern Syntax specified in the tutorial trail on internationalization at java.sun.com.
Example: Assuming the same current date and time as in the above example, the output of
<fmt:formatDate pattern="EEE, MMM d, ''yy"/>
will be
Mon, Oct 22, '01
for the U.S. locale.
The value and pattern attributes accept both string literals and EL values (which must evaluate to objects of type java.util.Date in the case of the value attribute). If the input to the value attribute is a string literal, it is first parsed into an instance of java.util.Date according to the default pattern of the page's locale. If the date string uses a different pattern, the <parseDate> action must be used.
The type, timeStyle, and dateStyle attributes take (case-insensitive) literals only, causing an error at translation-time validation if the specified literal is illegal.
Depending on the value of the type attribute, which must be one of "time", "date", or "both" (default: "date"), the date string given via the value attribute is expected to contain only a time, a date, or both a time and date component, respectively. It is parsed according to the default formatting pattern for dates and times of the page's locale, which is determined according to Section 2 of this functional description.
If the given date string uses a different format, the pattern required to parse it may be specified via the pattern attribute.
If the var attribute is given, the parsing result (of type java.util.Date) is stored in the named JSP attribute. Otherwise, it is output to the current JspWriter object using java.util.Date.toString().
The value and pattern attributes accept both literals and EL values. The type attribute takes (case-insensitive) literals only, causing an error at translation-time validation if the specified literal is illegal.
<fmt:exception value="$exception" bundle="$errorMessages"/>
If no value attribute is given, and this action is used in an error page, the exception of the error page is used.
Developers may designate an exception as localizable by having it implement the javax.servlet.jsp.jstl.i18n.LocalizableException interface, which is defined as follows:
public interface LocalizableException {
/**
* Returns the
exception's message key from which the exception's
* localized message
is derived via a resource bundle lookup.
*/
public String getMessageKey();
/**
* Returns the
arguments for parametric replacement on the exception's
* localized message.
*/
public Object[] getMessageArgs();
}
If the given exception is not an instance of this interface, the <exception> action uses its fully qualified class name as the key to look up in the resource bundle for exception messages.
Otherwise, the <exception> action uses the return value of the exception's getMessageKey method as the key . If getMessageKey returns null, the exception's fully qualified class name is used as the key.
The key is looked up in the resource bundle given by the bundle attribute. If this attribute is missing, and the <exception> action is nested inside a <bundle> tag, the resource bundle to use is taken from the enclosing <bundle> tag. Otherwise, the default resource bundle for exception messages, whose default base name is given by the javax.servlet.jsp.jstl.i18n.exception.basename scoped attribute, is used. This attribute is searched in the page, request, session (if valid), and application scope(s) (in this order).
The result of looking up the key in the resource bundle is used as the localized exception message. If the key is not found in the resource bundle, or the default resource bundle for exception messages does not exist, the return value of the exception's getLocalizedMessage method is used as the localized exception message. If the exception is an instance of the LocalizableException interface, the return value of the excpetion's getMessageArgs method is used for parametric replacement on the localized exception message.
The <exception> action outputs the localized exception message to the current JspWriter object.
If the stackTrace attribute is given with a value of true, the exception's stacktrace is printed out in addition to its localized exception message.
Example:
<web-app>
<context-param>
<param-name>javax.servlet.jsp.jstl.i18n.basename</param-name>
<param-value>com.acme.MyResources</param-value>
</context-param>
</web-app>
Example:
<web-app>
<context-param>
<param-name>javax.servlet.jsp.jstl.i18n.exception.basename</param-name>
<param-value>com.acme.MyExceptionResources</param-value>
</context-param>
</web-app>
Example:
<web-app>
<context-param>
<param-name>javax.servlet.jsp.jstl.i18n.fallbackLocale</param-name>
<param-value>fr-CA</param-value>
</context-param>
</web-app>
Example:
<web-app>
<context-param>
<param-name>javax.servlet.jsp.jstl.i18n.timeZone</param-name>
<param-value>"America/Los_Angeles"</param-value>
</context-param>
</web-app>
The convenience method, named getLocalizedMessage and exposed by the org.apache.taglibs.jstl.extra.i18n.Locale class, looks up a given message key in the resource bundle with a given base name (or the default base name), whose locale is determined according to the locale-determination logic described in Section 2.1.1, and optionally performs parametric replacement on the result of the lookup before returning it.
getLocalizedMessage comes in the following overloaded flavors:
/**
* Retrieves the localized message corresponding
to the given key.
*
* The given key is looked up in the resource
bundle whose base
* name is retrieved from the javax.servlet.jsp.jstl.i18n.basename
scoped
* attribute and whose locale is determined
according to the
* algorithm described in Section 2.1.1
of the functional description.
*
* If the javax.servlet.jsp.jstl.i18n.basename
attribute is not found
* in any of the scopes, or no resource
bundle with that base name exists,
* or the given key is undefined in the
resource bundle that was loaded as
* a result of this call, the string "???<key>???"
is returned,
* where "<key>" is replaced with the
given key
*
* @param pageContext the page in which
the given key must be localized
* @param key the message key to be looked
up
*
* @return the localized message corresponding
to the given key
*/
public static String getLocalizedMessage(PageContext
pageContext,
String key);
/**
* Retrieves the localized message corresponding
to the given key.
*
* The given key is looked up in the resource
bundle with the given
* base name whose locale is determined
according to the
* algorithm described in Section 2.1.1
of the functional description.
*
* If no resource bundle with the given
base name exists,
* or the given key is undefined in the
resource bundle that was loaded as
* a result of this call, the string "???<key>???"
is returned,
* where "<key>" is replaced with the
given key
*
* @param pageContext the page in which
the given key must be localized
* @param key the message key to be looked
up
* @param basename the resource bundle
base name
*
* @return the localized message corresponding
to the given key
*/
public static String getLocalizedMessage(PageContext
pageContext,
String key,
String basename);
/**
* Retrieves the localized message corresponding
to the given key and
* performs parametric replacement using
the arguments specified in the
* <tt>args</tt> parameter.
*
* The given key is looked up in the resource
bundle whose base
* name is retrieved from the javax.servlet.jsp.jstl.i18n.basename
scoped
* attribute and whose locale is determined
according to the
* algorithm described in Section 2.1.1
of the functional description.
*
* Before being returned, the result of
the lookup undergoes parametric
* replacement, using the arguments specified
in the <tt>args</tt>
* parameter.
*
* If the javax.servlet.jsp.jstl.i18n.basename
attribute is not found
* in any of the scopes, or no resource
bundle with that base name exists,
* or the given key is undefined in the
resource bundle that was loaded as
* a result of this call, the string "???<key>???"
is returned,
* where "<key>" is replaced with the
given key
*
* @param pageContext the page in which
the given key must be localized
* @param key the message key to be looked
up
* @param args the arguments for parametric
replacement
*
* @return the localized message corresponding
to the given key
*/
public static String getLocalizedMessage(PageContext
pageContext,
String key,
Object[] args);
/**
* Retrieves the localized message corresponding
to the given key.
*
* The given key is looked up in the resource
bundle with the given
* base name whose locale is determined
according to the
* algorithm described in Section 2.1.1
of the functional description.
*
* Before being returned, the result of
the lookup undergoes parametric
* replacement, using the arguments specified
in the <tt>args</tt>
* parameter.
*
* If no resource bundle with the given
base name exists,
* or the given key is undefined in the
resource bundle that was loaded as
* a result of this call, the string "???<key>???"
is returned,
* where "<key>" is replaced with the
given key
*
* @param pageContext the page in which
the given key must be localized
* @param key the message key to be looked
up
* @param args the arguments for parametric
replacement
* @param basename the resource bundle
base name
*
* @return the localized message corresponding
to the given key
*/
public static String getLocalizedMessage(PageContext
pageContext,
String key,
Object[] args,
String basename);
| I18N Tags | |
| Element | Sample usage |
| <locale>
value variant scope Establishes the locale specified by the value attribute for the variant given by the variant attribute. |
<fmt:locale value="en-US" variant="UNIX"/> |
| <timeZone>
value var scope Establishes the time zone given by the value attribute. |
<fmt:timeZone value="America/Los_Angeles">
<fmt:formatDate type="time"/> </fmt:timeZone> |
| <bundle>
basename prefix var scope Loads the resource bundle whose base name is specified by the basename attribute, and optionally exposes it in the named scoped attribute. |
<fmt:bundle basename="Greetings" var="greetingBundle"/> |
| <message>
key bundle var scope Fetches the localized message corresponding to the key specified by the key attribute from the resource bundle given by the bundle attribute, and performs parametric replacement on the retrieved message using the argument values supplied via <messageArg> subtags |
<fmt:message key="Welcome" bundle="$greetingBundle"/> |
| <messageFormat>
value var scope Performs parametric replacement on the pattern specified by the value attribute using the argument values supplied via <messageArg> subtags |
<fmt:messageFormat value="$priceMsg">
<fmt:messageArg value="$priceArg"/> </fmt:messageFormat> |
| <messageArg>
value Supplies the argument specified by the value attribute (if present) or the tag body to its parent <message> action for parametric replacement |
<fmt:message key="Welcome" bundle="$greetingBundle">
<fmt:messageArg value="$dateArg"/> </fmt:message> |
| <formatNumber>
value type pattern var scope Formats the given numeric value as a number, currency, or percentage using the locale's predefined or the specified (customized) formatting pattern |
<fmt:formatNumber value="9876543.21" type="currency"/> |
| <parseNumber>
value type pattern var scope Parses the given numeric string using the locale's default or the specified (customized) formatting pattern |
<fmt:parseNumber value="$num" var="parsed"/> |
| <formatDate>
value type dateStyle timeStyle pattern timeZone var scope Formats the given date using the locale's predefined or the specified (customized) formatting pattern |
<fmt:formatDate timeStyle="long" dateStyle="long"/> |
| <parseDate>
value type pattern var scope Parses the given date string using the locale's default or the specified (customized) formatting pattern |
<fmt:parseDate value="May 22, 2001 4:05:53 PM PDT" var="parsed"/> |
| <exception>
value bundle stackTrace Displays the exception given by the value attribute (or the error page's exception if no value attribute is given) in its localized form |
<fmt:exception bundle="$errorMessages"/> |