|
|
|
|
|
|
Creating Localized Applications with the Internationalization Tags
This topic includes the following sections:
What Is the I18N Framework?
WebLogic Personalization Server, WebLogic Portal, Commerce services and Campaign services use the Internationalization Framework provided in WebLogic Server. Developers who are building server-side components, such as EJBs, pipeline components, or inline processors, will find the information about logging and text formatting in the WebLogic Server documentation WebLogic Server particularly useful.
Note: For detailed information about the WebLogic Server Internationalization Framework, see the topic "Using the BEA WebLogic Server Internationalization Tools and Utilities" in the BEA WebLogic Server product documentation.
For localizing JavaServer Pages (JSPs), the WebLogic Personalization Server provides a simple framework that allows access to localized text labels and messages. The WebLogic Personalization Server's internationalization (I18N) framework is accessible from JSPs through a small I18N tag library. An example is shown in Figure 11-1. The JSP extension tag library provides the following services:
The Internationalization Framework makes it possible to dynamically retrieve all the strings that the user sees from the <i18n:getMessage> tag, and avoid embedding strings statically (that is, avoid hard-coding them) in your JSP page.
Figure 11-1 An Example of Internationalization Code
Localizing Your JSP
The conventions used in the I18N tag library are based on the more general conventions used to internationalize Java applications. To understand the conceptual foundations for the <i18n:getMessage>tag, see the Javadoc for java.text.MessageFormat in the Sun Microsystems, Inc. Java 2 SDK, Standard Edition documentation. To better understand the ideas that served as the foundation for these tags, study the Javadoc for java.util.ResourceBundle and java.util.Locale.
The following tags are included in the I18N framework:
<i18n:getMessage>
<i18n:localize>
<i18n:getMessage>
This tag retrieves a localized label or message (based on the absence/presence of an args attribute). The tag optionally takes a bundle name, language, country, and variant to aid in locating the appropriate properties file for resource bundle loading.
This tag is used in the localization of JSP pages. All pages that have an internationalization requirement should use this tag.
For more information about the <i18n:getMessage> tag, see Personalization Server JSP Tag Library Reference.
<i18n:localize>
This tag allows you to specify a language, country, variant, and resource bundle name to use throughout a page when accessing resource bundles via the <i18n:getMessage> tag. This is a convenient way to specify these attributes once, so that you do not have to specify them again each time you use <i18n:getMessage> to retrieve localized static text or messages.
Note: Changes to the resource bundles will not be recognized until the server is restarted.
The <i18n:localize> tag also specifies a character encoding and content type to be specified for a JSP page. Because of this, the tag should be used as early in the page as possible-before anything is written to the output stream-so that the bytes are properly encoded. If you intend to display text in more than one language, pick a character set that encompasses all the languages on the page.
When an HTML page is included in an enclosing page (for example, as portlets are included in portal pages), only the outermost page can use the <i18n:localize> tag. This is because the <i18n:localize> tag sets the encoding for the page, and the encoding must be set in the parent (outermost) page before any bytes are written to the response's output stream. Therefore, be careful that the encoding for the parent page is sufficient for all the content on that page as well as any included pages. The child (included) pages may continue to use the <i18n:getMessage> tag. However, if the included pages are using text from their own bundle, they must provide the bundleName parameter to the <i18n:getMessage> tag.
Note: If your page contains only dynamic strings (strings retrieved using the <i18n:getMessage tag>), then do not use the <i18n:localize> tag in conjunction with the <%@ page contentType="<something>" > page directive defined in the JSP specification. The directive is unnecessary if you are using the <i18n:localize> tag, and can result in inconsistent or wrong contentType declarations.
For more information about the <i18n:localize> tag, see Personalization Server JSP Tag Library Reference.
The JspMessageBundle
The <i18n:getMessage> tag uses an implementation similar to that of java.util.ResourceBundle, but it is slightly modified. Unlike a ResourceBundle, the <i18n:getMessage> tag looks only for properties files (like the PropertyResourceBundle) within the ServletContext (on the doc path). This means that you can keep properties files containing localized text relative to the associated JSP page, instead of having to have them on the CLASSPATH.
Another difference is that the resource bundles (properties files) used by <i18n:getMessage> are specified using the "/" character instead of the ".". For instance, the path to a JspMessageBundle might look like this: /jsp/ordersystem/placeOrder.
If a bundle name is specified, then it can be specified absolutely or relatively. Absolute paths are treated as such if they begin with a "/". Paths not beginning with "/" are searched for relative to the JSP page's location.
If no bundle name is specified, then bundle name defaults to the name of the JSP page. For instance, if you have a JSP page called placeOrder.jsp, then <i18n:getMessage> would look in the same directory for a placeOrder.properties file to serve as the resource bundle for the placeOrder.jsp page.
When <i18n:getMessage>is searching for a resource bundle, it uses pageContext.getServletContext().getResourceAsStream() to load the resource bundle. Therefore, <i18n:getMessage>searches the web application for the property file rather than searching CLASSPATH. If no message bundle can be found, a MissingResourceException occurs.
How the Localization Tag Works
The <i18n:localize> tag first examines all provided attributes and default attributes, and then performs the following three steps:
If a base bundle name is not provided, the bundle name defaults to the name of the JSP page.
For example, if the name of the JSP page is placeOrder.jsp, then the default bundle name would be placeOrder. On the file system, it would look for placeOrder.properties.
The tag will first look for resource bundles that correspond to the language parameter passed in to the tag.
If no match between bundle and language is found, then the tag will try to find a match between resource bundles and languages defined in the request header.
If a match can be made, the first language that matches is the language that is used.
If no language is specified, the default is U.S. English (en_US).
If no message bundle can be found, then language is set to nothing ("") and "UTF-8" encoding will be used unless otherwise specified.
If character encoding is not specified, a charset appropriate for the language determined in step 2 is chosen.
If a character encoding is specified, then that will be the charset used by the page, regardless of what language was chosen in step 2.
Once the charset is determined, it is specified for the page by calling the setContentType() method on the servlet response. A call to setContentType() might look like this:
response.setContentType("text/html; charset=ISO-8859-1");
Character Encoding
When specifying the encoding, it is important to note that some encodings may not be supported for your particular operating system, virtual machine, or client browsers. To see what Sun Microsystems, Inc. supports in the J2SE package, see http://www.java.sun.com.
If for any reason an encoding for a language cannot be determined and none is specified, UTF-8 encoding is used.
Displaying More Than One Character Set on a Page
In general, it is best is to leave the charset parameters unspecified since this is more flexible and fault tolerant. An exception might be when two languages (such as Greek and Japanese) need to be displayed in the same page. In that case, you can set the charset to "UTF-8".
For a page with multiple charsets to display correctly, the end users must have the appropriate fonts installed on their machines. If a font cannot be found, non-printable characters will typically display in place of the missing characters. (Non-printable characters often look like rows of empty boxes.)
Default Character Encodings
Table 11-23 shows how the <i18n:localize> tag maps languages to character encodings. These are the default settings.
You can override these defaults by providing any charset tag parameter you choose. For example, in the table below, the default charset for Japanese is Shift_JIS, but you could pass in x-sjis, EUC_JP, or iso-2022-jp instead. Or, as another example, to use Chinese Taiwan locale in place of Chinese, override GB2312 with Big5.
Table 11-23 Default Character Encodings
Double-byte character encoding The Internationalization property files in the WebLogic Personalization Server are standard Java property files, and as such, they do not accept non-ASCII characters. Non-ASCII characters must be converted to Unicode escapes before being embedded into these files. The native2ascii tool can be used to convert property files to and from other character encodings. On Windows, the native2ascii tool is found in the bin directory of the JDK. For more information about Java property files and the native2ascii tool, see http://java.sun.com/j2se/1.3/docs/api/java/util/Properties.html For more information about Unicode escapes, see: http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#100850 Example To write "Hello World!" in English, the contents of the property file helloWorld_en.properties would look like this: To write "Hello World!" in Japanese, the contents of the property file helloWorld_ja.properties would look like this: This Unicode will render "Hello World!" in Japanese characters like this: Note: Japanese consists of Kanji and other character sets called Hiragana and Katakana. In this example, "Hello" is written in Hiragana and "World" is written in Kanji. Steps for Localizing Your Application helloWorld=Hello World!
helloWorld=\u3053\u3093\u306b\u3061\u306f\u3001\u4e16\u754c\u306e\u4eba\u3005\uff01
For example:
<%@ taglib uri="i18n.tld" prefix="i18n" %>
<i18n:localize language="<%=language%>"
Note: When JSP pages are being included inside an enclosing page, only the enclosing page can use the <i18n:localize> tag.
Note: Changes to the property files will not be recognized until the server is restarted.
For example: Use <i18n:getMessaage messageName="greeting"/> instead of hardcoding "Welcome!"
For example:
If the JSP is in public_html\mypage.jsp, then the bundle location could be
(absolute) "/mypage/text_us.properties" or
(relative) "text_us.properties".
Code Examples
The following examples show how to use the JSP internationalization framework with JavaScript and Java scriptlets.
Using the JSP Internationalization Framework with JavaScript
This example displays a JavaScript dialog with a localized message in it.
<%@ taglib uri="i18n.tld" prefix="i18n" %>
<%
String language="en";
%>
<i18n:localize language="<%=language%>"
bundleName="i18nJavaScriptExampleResourceBundle"/>
<script language="JavaScript">
function popDialog() {
alert("<i18n:getMessage messageName="greeting"/>")
}
</script>
<html>
<body>
<a href="javascript:popDialog();">Click here to see localized text!</a>
</body>
</html>
Using JSP Internationalization Framework with Java Scriptlets
This example gets a localized message, and uses that message in two Java scriptlets. One scriptlet prints to system out, the other inlines it into the page.
<%@ taglib uri="i18n.tld" prefix="i18n" %>
<%
String language="en";
%>
<i18n:localize language="<%=language%>"
bundleName="i18nJavaScriptExampleResourceBundle"/>
<html>
<body>
<i18n:getMessage messageName="greeting" id="theGreeting"/>
<p>
<%="Localized text for 'greeting': " + theGreeting%>
<p>
<%
System.out.println("Localized text for 'greeting': " + theGreeting);
%>
</body>
</html>
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|
