The I18N-Related Tags

E-Mail

Add Note

Add Bookmark

	JSTL: JSP Standard Tag Library Kick Start By Jeff Heaton
	Table of Contents

	Chapter 10. Understanding JSTL Internationalization

To create a multilingual JSTL Web application, you must isolate all language-dependent parts of the program to one area. The language-dependent parts are the strings that your program displays.

To make our forum example multilingual, we must go through the individual source files and find all the strings that are currently in the English language. We then have to move these strings to a resource bundle.

A resource bundle is a collection of strings in one particular language, such as English. When you want your program to support languages other than English, you simply translate the resource bundle to another language. These resource bundles are then made available to the Web application. Your program can dynamically choose between resource bundles and change the language that people are using as they work with the application.

A resource bundle is something that exists in standard Java as well as JSTL. In fact, you may have already worked with resource bundles. Later in this chapter, we describe how to create them, but let's begin by explaining the tags that you can use to work with resource bundles. The first tag that we'll look at is the <fmt:setLocale> tag, which enables you to select the locale that your Web application is being used from.

Using the <fmt:setLocale> Tag

The <fmt:setLocale> command is used to set the locale of a Web session. It lets you set the locale for one user or for the entire Web application. Usually, it is preferable to have the Web server maintain individual locales for each of the logged-in users. The locale determines how resource bundles are chosen and how other formatting operations act. There is one form of the <fmt:setLocale> tag:

<fmt:setLocale value="locale" [variant="variant"] [scope="{page|request|session|application}"]/>

The <fmt:setLocale> tag accepts these attributes:

Attribute	Required	Purpose
value	Y	Specifies a two-part code that represents the ISO-639 language code and an ISO-3166 country code.
scope	N	Specifies the scope of this locale setting. The default is page.
variant	N	Specifies a vendor- or browser-specific variant of the language referenced by value. For more information, refer to the java.util.Locale JavaDocs.

With the <fmt:setLocale> tag, you are able to set the current language and country. The scope attribute enables you to specify the locale for either the user or the entire Web application. You accomplish this by specifying one of the standard scopes page, request, session, or application. Typically, you'll use session scope and set the locale for the current user.

Using the value attribute, you can convey both the language and the country. You separate the two by either a hyphen (-) or an underscore (_). You supply the language code first. This is an ISO-639 code, and you must enter it in lowercase letters (see Table 10.1 for a list of some of the ISO-639 languages). After this, you insert either a hyphen or an underscore and then specify the country code. The country code is an ISO-3166 standard code that you must enter in uppercase letters.

Table 10.1. Some ISO-639 Languages
Language Name	Code	Language Family
ARABIC	ar	SEMITIC
AZERBAIJANI	az	TURKIC/ALTAIC
CZECH	cs	SLAVIC
DANISH	da	GERMANIC
GERMAN	de	GERMANIC
GREEK	el	LATIN/GREEK
ENGLISH	en	GERMANIC
ESPERANTO	eo	INTERNATIONAL AUX.
SPANISH	es	ROMANCE
PERSIAN (Farsi)	fa	IRANIAN
FINNISH	fi	FINNO-UGRIC
IRISH	ga	CELTIC
HEBREW	he	SEMITIC
HINDI	hi	INDIAN
CROATIAN	hr	SLAVIC
HUNGARIAN	hu	FINNO-UGRIC
ICELANDIC	is	GERMANIC
ITALIAN	it	ROMANCE
JAPANESE	ja	ASIAN
JAVANESE	jv	OCEANIC/INDONESIAN
GREENLANDIC	kl	ESKIMO
KOREAN	ko	ASIAN
LATIN	la	LATIN/GREEK
LITHUANIAN	lt	BALTIC
LATVIAN; LETTISH	lv	BALTIC
MACEDONIAN	mk	SLAVIC
MONGOLIAN	mn	[not given]
MOLDAVIAN	mo	ROMANCE
NEPALI	ne	INDIAN
DUTCH	nl	GERMANIC
NORWEGIAN	no	GERMANIC
PUNJABI	pa	INDIAN
POLISH	pl	SLAVIC
PASHTO; PUSHTU	ps	IRANIAN
PORTUGUESE	pt	ROMANCE
ROMANIAN	ro	ROMANCE
RUSSIAN	ru	SLAVIC
SANSKRIT	sa	INDIAN
SINDHI	sd	INDIAN
SLOVAK	sk	SLAVIC
SLOVENIAN	sl	SLAVIC
SERBIAN	sr	SLAVIC
SWEDISH	sv	GERMANIC
SWAHILI	sw	AFRICAN
TAJIK	tg	IRANIAN
THAI	th	ASIAN
TURKISH	tr	TURKIC/ALTAIC
UKRAINIAN	uk	SLAVIC
URDU	ur	INDIAN
UZBEK	uz	TURKIC/ALTAIC
VIETNAMESE	vi	ASIAN
YIDDISH	yi	GERMANIC
YORUBA	yo	AFRICAN
CHINESE	zh	ASIAN
ZULU	zu	AFRICAN

Using the <fmt:setBundle> Tag

The <fmt:setBundle> tag loads a resource bundle and stores it in the specified scoped variable. Using this tag, you can load a resource bundle that will be used by subsequent <fmt:message> tags. The <fmt:setBundle> tag has one form:

<fmt:setBundle basename="basename" [var="varName"] [scope="{page|request|session|application}"]>

These attributes are accepted by the <fmt:setBundle> tag:

Attribute	Required	Purpose
basename	Y	Specifies the base name of the resource bundle that is to be loaded.
scope	N	Specifies the scope of the variable contained in the var attribute. The default is page.
var	N	Specifies a scoped variable that will hold the newly instantiated resource bundle.

A resource bundle is a Java class that extends the java.util.ListResourceBundle class. The base name specifies the name of the class that implements the base resource bundle, which a program uses when it can't locate any other suitable resource bundle. You use the basename attribute to specify the full name of the resource bundle class. In our sample program later in this chapter, the base name of the resource bundle is com.heaton.bundle.Forum.

Using this base name allows a program to load the correct resource bundle using the current locale. For example, suppose you have a program that uses the languages English, Spanish, and Chinese. The English translation is stored in the base resource bundle, named com.heaton.bundle.Forum. The Spanish translation is stored in the bundle specified by com.heaton.bundle.Forum_es, and the Chinese translation is stored in the bundle specified by com.heaton.bundle.Forum_zh. The program uses the current locale (referenced in the <fmt:setLocale> tag) to determine which resource bundle variant it should load.

The program loads the resource bundle into the scoped variable specified by the var attribute. You can specify the scope of this variable by using the scope attribute. Once loaded, the resource bundle must be passed to the <fmt:message> tag in order for the multilingual text to be displayed.

You have several options when determining the scope. Loading a resource bundle as request or page scope means that the resource bundle will have to be reloaded frequently. Because of this, programmers rarely choose request or page scope.

If you load your resource bundle as application scope, then every user will have access to it. This is a good solution when you've designed your Web site to support several languages, but will have one language specified by the Webmaster. You can define this language in the web.xml file so that you can easily specify it as the default language.

Usually, you want to allow your users to pick their own language. To do this, you should use the session scope, which lets you load a different resource bundle for each user. This means that all users can see the Web site content in the language of their choice.

Using the <fmt:bundle> Tag

You use the <fmt:bundle> tag to specify a resource bundle to be used with the JSTL tags inside the body of the <fmt:bundle> and ending </fmt:bundle> tags. The <fmt:bundle> tag has one form:

<fmt:bundle basename="basename"/> </fmt:setBundle>

The <fmt:setBundle> tag accepts the following attributes:

Attribute	Required	Purpose
basename	Y	Specifies the base name of the resource bundle that is to be loaded.
prefix	N	Specifies a prefix that will be added to every key attribute specified in the <fmt:message> tags.

The <fmt:bundle> tag will make the specified bundle available to all <fmt:message> tags that occur between the bounding <fmt:bundle> and </fmt:bundle> tags. This saves you the extra step of having to specify the resource bundle for each of your <fmt:message> tags. For example, the following two <fmt:bundle> blocks would produce the same output:

<fmt:bundle basename="com.heaton.bundles.Forum">     <fmt:message key="login.title"/> </fmt:bundle> <fmt:bundle basename="com.heaton.bundles.Forum" prefix="login.">     <fmt:message key="title"/> </fmt:bundle>

Using the <fmt:message> Tag

You use the <fmt:message> tag to access the language-specific strings inside a resource bundle. As you construct your multilingual Web applications, you can sprinkle <fmt:message> tags throughout your program in place of language-specific strings. There are three forms of the <fmt:message> tag:

// Syntax 1: Without body content   <fmt:message key="messageKey"   [bundle="resourceBundle"]   [var="varName"]   [scope="{page|request|session|application}"]/> // Syntax 2: With a body to specify message parameters   <fmt:message key="messageKey"   [bundle="resourceBundle"]   [var="varName"]   [scope="{page|request|session|application}"]>   <fmt:param> subtags   </fmt:message> // Syntax 3: With a body to specify key and optional message parameters   <fmt:message [bundle="resourceBundle"]   [var="varName"]   [scope="{page|request|session|application}"]>   key   optional <fmt:param> subtags   </fmt:message>

The <fmt:message> tag accepts the following attributes:

Attribute	Required	Purpose
bundle	N	Specifies the resource bundle that is to be used. If this tag occurs from within a <fmt:bundle> tag, then no bundle has to be specified. You could set a default localization context, either by using a <setBundle> tag or in the configuration file; in either case, you don't have to specify a bundle.
key	N	Specifies the lookup key that identifies the desired string inside the bundle.
scope	N	Specifies the scope of the scoped variable referenced by the var attribute. If the var attribute is not needed, then the scope attribute should not be specified. The default is page.
var	N	Specifies a scoped variable that will receive the value of the string that is being looked up. If no var attribute is specified, then the output will be written to the page.

The first syntax specifies a message that contains no body text. You use the first syntax if you simply want to display a string that contains no parameters. The second syntax allows you to specify parameter values, which we discuss further in the next section. The third syntax lets you use parameter values as well as specify the key of the string, all in the body of the <fmt:message> tag. You use the third syntax if you need to dynamically define the key with an embedded tag.

The <fmt:message> tag is the most commonly used internationalization tag in JSTL. To create a multilingual Web application, you must insert the <fmt:message> tag at every position in which you would normally have language-specific text. This results in a large number of <fmt:message> tags. The following code shows how you'd use the <fmt:message> tag:

<p><fmt:message key="login.note" bundle="${lang}"/> </p>

In this code, the <fmt:message> tag is freely mixed with other HTML code. Here, we are reading a string from the bundle identified by the scoped variable lang and identified by the key login.note. Both of these values are entirely arbitrary and can be set to any value that you can easily remember. Later in this chapter, we'll show you how to create resource bundles and assign these keys.

It is also possible to copy the string directly from the resource bundle into a scoped variable. You accomplish this by specifying a scoped variable in the var attribute. The value obtained by looking up the key in the resource bundle is copied directly to the variable specified by the var attribute. You can also specify a scope for this variable by using the scope attribute.

Using the <fmt:param> Tag

We have just seen how the <fmt:message> tag can be used to inject multilingual text in the HTML code of JSP pages. The <fmt:message> tag is quite flexible in that you can specify parameters for inclusion in the output. You do this by using the <fmt:param> tag, of which there are two forms:

// Syntax 1: Value specified via attribute value   <fmt:param value="messageParameter"/> // Syntax 2: Value specified via body content   <fmt:param>   body content   </fmt:param>

The <fmt:param> tag accepts one attribute:

Attribute	Required	Purpose
value	N	Specifies the value that is to be inserted for the parameter.

The first syntax uses the value tag to specify the value that is to be inserted for the parameter. The second syntax uses the body of the tag to specify that value.

To use the <fmt:param> tag in your code, you must include parameters in your resource bundle strings. You do this by placing brace-delineated numbers inside your message text. For example, the following string would accept one parameter:

Welcome back {0}!

This string allows a parameter to be inserted in place of the {0} parameter. To make use of this parameter, use the following code:

<fmt:message key="welcome" bundle="${lang}">   <fmt:param value="${user}"/> </fmt:message>

Here, the value stored in the scoped variable user is inserted as the first parameter. Parameter numbers always start with 0. The first <fmt:param> tag specified fills in parameter 0; the second fills in parameter 1.

One limitation of JSTL messages is that they are based on the Java class java.text.MessageFormat. As a result, you are restricted to only 10 parameters. If you need more than 10, you will have to use multiple tags.

Using the <fmt:requestEncoding> Tag

The <fmt:requestEncoding> tag is used to specify the encoding type used by forms that post data back to the Web application. There is one form of the <fmt:requestEncoding> tag:

<fmt:requestEncoding [value="charsetName"]/>

The <fmt:requestEncoding> tag accepts one attribute:

Attribute	Required	Purpose
value	N	Name of character encoding you want to apply when decoding request parameters.

You use the <fmt:requestEncoding> tag when you want to specify character encoding for decoding data posted from forms. This tag must be used with character encodings that are different from ISO-8859-1. The tag is required since most browsers do not include a Content-Type header in their requests.

The purpose of the <fmt:requestEncoding> tag is to specify the content type of the request. You must specify the content type, even if the encoding of the page generating the response is specified via the contentType attribute of a page directive. This is because the response's actual locale (and thus character encoding) may differ from the value specified in the page directive. If the page contains an I18N-capable formatting action that sets the response's locale (and thus character encoding) by calling ServletResponse.setLocale(), any encoding specified in the page directive will be overridden.