Understanding Internationalization

May 2006 [Revision number: V2.1-1]

Copyright 2006 Sun Microsystems, Inc.

This tutorial provides background information to help you develop an internationalized web application with the Sun Java Studio Creator application development tool, using JavaServer Faces components. It provides an example of localizing an application for a specific locale. The Sun Java Studio Creator IDE enables you to develop localized web applications specific to a single locale or supporting many locales. The easiest way to develop an application for a single locale is to have the IDE inherit its default settings from the locale settings of your operating system. The IDE also lets you develop internationalized web applications that can be automatically localized to many different locales. The recommended way to do so is to use a properties bundle that segregates your human-readable text into one set of files for easy maintenance. Contents - What Is Internationalization - Locale, Character Sets, and Encoding - Unicode and UTF-8 - Locale Settings and Character Encodings in the IDE - Localized Project Development - Internationalization Features in the IDE - Source Encoding Settings - Supported Locales - Encoding Component - Default Locale and Response Encoding - UrlLang Property - Lang Property - Language Property - The Charset Property - The Hreflang Property - The Dir Property - Bundled Properties - Load Bundle Component Internationalization Properties in JavaServer Faces Files - The faces-config.xml File - Example Example used in this tutorial internationalizingapps_ex.zip (zip)

What Is Internationalization
Internationalization is the process of making program code generic and flexible so that it can easily accommodate specifications from markets around the world. These specifications includebut are not limited tolanguage, character sets, date and time formats, and currency symbols. Readers familiar with issues involving internationalization, localization, and character encoding may wish to skip directly to the topic Localized Project Development. Internationalization enables localization, the ability to develop a user interface for a specific locale (a geographic, political, or cultural region). It is usually identified by the two-letter ISO-639-2 language code and the two-letter ISO-3166 country code for the locale. For example, en_US represents the locale United States English. In some cases, only a language identifier is provided.

The Sun Java Studio Creator application development tool (the IDE) enables you to create localized versions of your program, where each localized version supports a target locale. It generates internationalized code, so that your program can behave as a localized application in different locales.

Locale, Character Sets, and Encoding

Character encoding issues are not exclusive to internationalization; they affect any developer whose application will run in a specified locale even if the application doesn't display messages specific to that locale. However, it is difficult to understand the process of internationalization without understanding character encoding. As already mentioned, a locale is usually identified by a two-letter language code and a two-letter country code. Each language (and in some cases, each locale) may require a different character set. The character set is the set of glyphs (the alphabet, numbers, and punctuation) used in the language. Character sets are comparatively small for European languages, numbering in the hundreds of glyphs. For other locales, especially those in Asia, character sets can number in the tens of thousands of glyphs. Character encoding is the mapping of code points, represented as integers, to the glyphs in a character set. The mapping between a code point and a symbol is typically set by a standards committee such as the International Standards Organization (ISO). Encodings can also be defined by manufacturers who want to define special glyphs of their own. Locales with large character sets require code points of at least two bytes (16 bits) to represent all of the glyphs, but variable byte-length encoding schemes have been designed to use as many as 6 bytes for some glyphs. Any single language can have more than one encoding. And, although two different character encodings may provide the same set of characters, their code points refer to different glyphs. To add to the confusion, there can be several names for the same encoding. To read more on encoding, you can go to several sources, starting with the ISO web site.

Unicode and UTF-8

Unicode is the international standard whose goal is to specify a code that maps every character needed by every written human language to a single unique integer code point. Despite difficulties, Unicode has emerged as the dominant encoding scheme in multilingual environments. The Java Studio Creator IDE defaults to the UTF-8 encoding (8-bit Unicode Transformation Format) as the most flexible implementation of the Unicode standard. It is a lossless, variable-length character encoding that uses groups of bytes to represent the Unicode standard for the alphabets of many of the world's languages. It is the default encoding for the XML format. UTF-8 uses 1 to 4 bytes per character, depending on the Unicode symbol. For example, only one UTF-8 byte is needed to encode the 128 US-ASCII characters. An ASCII file encoded in UTF-8 is exactly the same as the original ASCII file. All non-ASCII characters in the encoding are guaranteed to have the most significant bit set, whereas ASCII characters do not. This means that existing tools used with ASCII text (searching, text editing, and so on) work as expected, and that legacy systems such as emailers can transmit UTF-8. UTF-8 guarantees that no byte sequence of one character is contained within a longer byte sequence of another character. This ensures that byte-wise sub-string matching can be applied to search for words or phrases within a text. Most other variable-length 8bit encodings do not have this property, making string matching difficult.

Locale Settings and Character Encodings in the IDE

The Java Studio Creator IDE gives you control of locale and character encoding in several ways. As the preceding discussion points out, locale and character encoding are separate settings. However, you will usually find an association between the two settings because of font availability. NOTE: A typeface is a design of a set of letters, numbers, and special symbols that share a particular appearance, such as the Helvetica or Times Roman typefaces. A font is an implementation of a typefaces character set. At one time, fonts were expressed in hardware. However, modern fontsoften dynamically generatedare available as software associated with an operating system. As a developer, you must consciously target the platforms and character encodings that will support your application. For web

applications, the target platform for your development effort is not a computer or even an operating system, but a web browser. Popular browsers, in turn, are implemented for several operating systems. Because fonts are distributed with operating systems, popular browsers must accommodate each system's available character encodings. A modern browser can handle many different font encodings. In the Java Studio Creator IDE, you will typically select a specific character encoding, such as Shift_JIS encoding whenever you specify the locale ja_JP, or Big5 encoding whenever you specify a traditional Chinese locale such as zh_TW. Browsers provide preference settings to inform internationalized sites of the user's preferred language. The web server receiving this information attempts to serve pages in the preferred language of the client browser. The ability to specify character encodings as well as locales is important because not all encodings for a specific language are the same. For example, consider Figure 1, which shows a sample of Chinese text displayed in three different encodings on the same browser. The encoding in each case is the response encoding, the encoding specified by the web server when it composes a page and sends it to the client browser. When the browser receives a page specified in, for example, UTF-8 encoding, it attempts to render the page using its UTF-8 fonts.

Figure 1: Rendering Differences in Chinese Character Encodings The circled characters in Figure 1 show that UTF-8, Big5, and GB2312 can have significant differences when displayed on the same browser. GB2312 encoding is typically used in mainland China; Big5 in Taiwan. One character code at the bottom the Big5 encoding sample is not rendered as a Chinese glyph at all, indicating that the passage was probably intended for GB2312 (simplified Chinese) encoding. Fonts used for UTF-8 encoding are similar to those used for Big5 in this sample, although different punctuation spacings produce different line breaks. To further complicate the situation, different browsers may behave differently. For this reason, some web applications, especially those adapted for Chinese, give the user a choice of encodings.

Localized Project Development

The Java Studio Creator IDE enables you to develop web-based applications in many languages. To successfully deploy and test while developing a web-based application in a specific language, you must start up the IDE on a development computer with the same character encoding as the target computer where you plan to run the server. The browser must also support the target language. As you develop your application, all JavaServer Pages (JSP) files and Java source files may be maintained in the native encoding of your operating system, as is true of many other popular IDEs. This feature allows the IDE to work interchangeably with other tools. Alternatively, you may choose to store all JSP and Java source files in UTF8 encoding. The use of UTF-8 circumvents encoding problems if you need to share your files in an internationally distributed development team. In such cases, you can maintain a central source code repository because the operating system encodings used to write files will not differ among locales. Additionally, you can work with multiple languages in a single JSP page by setting up the environment to use UTF-8 encoding. However, this option is only available on platforms that support UTF-8 fonts. Only one completely reliable way exists to change the default encoding that is used by the virtual machine and the runtime system. You must change the locale of the underlying operating system before you start the IDE. For example, on Windows XP Professional, you set the locale from the Regional and Language Options control panel. If you change the encoding or locale of your project midstream, the text or language directives in your project JSP and Java files may lose synchronization. As a result, your application could become corrupted. To recover, go back through the project and ensure that all Java files are of the same source encoding and that all existing JSP tags correctly coincide with the project default language and locale encoding settings. See the section Changing Source Encoding In Existing Projects for more information.

Internationalization Features in the IDE

To create an internationalized application, you must manage locale and character encoding parameters. The IDE lets you manage character encodings and locales, primarily through a set of encoding properties and options. Although standardizing on a single encoding such as UTF-8 is highly desirable because of its acceptance by ASCII-centric programs, the present state of technology requires compromise because some existing platforms cannot handle UTF-8, or there is some compelling cultural or legacy requirement. In general, UTF-8 encoding is recommended for all language encodings except Simplified Chinese, where other encodings such as GB2312 predominate. Therefore, you may need to change the default behavior. The remainder of this tutorial explains the features, properties, and options of the IDE that affect localization and internationalization.

Source Encoding Settings

Source Encoding settings determine the character encoding for source files (.jsp and .java files) in your project. The settings produce headers and tags in the source files that allow the readers of the files to interpret them correctly. Default Source Encoding Option The Default Encoding option sets the default encoding for new project source files. If you do not enter a value for the option, the IDE uses a source encoding based on the current locale and encoding settings for your computer. The value of the option can be overridden by properties in individual source files. To change the default source encoding, choose Tools > Options from the menu bar and click the Advanced radio button (see Figure 2). Select the Java Sources option and, if necessary, expand the Expert category to reveal the Default Encoding option. If the value of the option is blank, the IDE uses the default system encoding. To change the encoding, click in the value field to the right of the Default Encoding property and enter the encoding of your choice. Alternatively, click the button next to the value field and enter an encoding in the resulting dialog box.

Figure 2: Java Sources Default Encoding Option Individual Java Source File Encoding When you edit a Java source file in the Java Editor or select its name in the Projects or Files window, the Properties window displays the file's Text > Encoding property (see Figure 3). This is the source encoding of the individual Java file. If there is no entry for this property, the IDE uses the Default Encoding option for the page. To change the Encoding property, click the button to the right of the property and enter a different encoding, such as UTF-8 or Shift_JIS.

Figure 3: Page Text Source Encoding Property If you need to change the source encoding property for a file, the new encoding does not take effect until the project has been saved. If you discard your changes, the property will persist in the Properties window, but the file will not have been saved in the new encoding. You must save your file with the new encoding for it to have the new encoding next time you work with it. If your file has not been changed, make a small edit so you can save the file. For example, add and then delete a character so that you can save your file. If you change the encoding for a Java source file, you must change other existing Java files to match. All Java files are passed to the compiler at the same time, and the compiler can only accept one encoding flag. Therefore, all Java source files must be in the same encoding for each build. To synchronize the settings in your source files, touch each of them (add and delete a character) and save the project. If your Java source contains hard-coded strings, they will be changed when you change the encoding for the source file and save it. So, for example, if you begin with UTF-8 encoding and you change the encoding to Shift_JIS, the IDE will convert the file when you save it in the new encoding. The hard-coded strings will appear correctly in the new encoding when displayed to the user.

Changing Source Encoding in Existing Projects The Default Encoding property for the project determines the encoding of new source files. However, if you change this property in a project midstream, existing source files retain their original encodings. The text encodings of Java files should be changed to match the new Default Encoding property. Likewise, if you change the encoding of your existing Java files, you should change the default source encoding property to match so that new files will be synchronized. To change the source encoding for an existing project: 1. Change the project Default Encoding option (as described in Default Source Encoding Option). You now need to change the source encoding for the Java source files already in the project. 2. Select a Java source file in the Files window, as shown in the following figure.

Figure 4: Selecting a Source File in the Files Window 3. View the properties for the file in the Properties window. If the Text > Encoding property is not blank, select and delete the entry to apply the default value, or enter a different encoding. Alternatively, click the button next to the property and edit the value in the dialog box. If the IDE prevents you from editing the value, edit and save the file as described in the next two steps, then try again. 4. Double-click the file node in the Files window to open the file in the Java Editor. 5. Enter and delete a character in the file and select File > Save to save the file. 6. Repeat steps 2 through 5 for each Java source file in the project.

Supported Locales
The locales supported by your application can be set in the faces-config.xml file. You can view or edit this file by viewing the project's Files window, then expanding the project_name > web > WEB-INF node. For more information, see The facesconfig.xml File. Also, for your application to display correctly in the desired locales, you can add localized strings to the project's resource bundle. The resource bundle stores selected characteristics of each locale as key-value pairs in properties files, typically one file for each locale. The properties files are used to store localized strings. The properties files can be seen when a page is displayed in the Visual Designer. In the Files window, view the files by expanding the project_name > src > project_name > bundle.properties node. In the Projects window, view the files by expanding the project_name > Source Packages > project_name > bundle.properties node. Bundled property files are explained in the section Bundled Properties.

Encoding Component
The Encoding component is used to set dynamically the locale for a page in your application. It is available from Palette > Advanced > Encoding. By default, the Encoding component obtains the encoding from your application bean. To see how it works: 1. View a page in the Visual Designer. 2. In the Palette window, click the Components tab. 3. Expand the Advanced category and drag an Encoding component onto a page in the Visual Designer. 4. In the Outline window, an instance of the component will appear in the page > html > head > node (see Figure 5). When you select the encoding component node, the Properties window shows that its value is bound to the application beans localeCharacterEncoding property in this case, #{ApplicationBean1.localeCharacterEncoding}.

Figure 5: Viewing Properties for the Encoding Component 5. In the Outline window, double-click the application bean node (ApplicationBean1) to open the Java source file for the bean in the Java Editor. 6. Near the bottom of the file, locate the getLocaleCharacterEncoding() method. This method returns a character encoding based on the Locale defined for the current JavaServer Faces view. The default behavior of this method in the standard ApplicationBean1 class is as follows: If the locale for this request is Simplified Chinese (zh_CN), return GB2312. Otherwise, return UTF-8. You can change the default behavior by editing the getLocaleCharacterEncoding() method to return a different locale. For example, if the locale is found to be RU_ru, you could return the encoding KOI8-R instead of UTF-8.

Default Locale and Response Encoding

You will now explore how your web application responds to client browser requests for a specific locale. If a browser requests a locale that your application can support, your web application will respond with pages generated for the requested locale. If your web application does not support the requested locale, it will respond by generating a web page for the locale specified by the localeCharacterEncoding property of your application bean. For example, if the user's web browser requested the Russian locale, the application would use the bundle_ru_RU. properties file instead of the default bundle.properties file to build that user's web page. Bundled property files are explained in the section Bundled Properties. The Response Encoding property is the default character encoding that the application server uses when it responds to a browser request. Its value is a code that specifies the character encoding used in the page. Character encoding is expressed as the

charset parameter of the HTTP Content-Type tag in the submitted page header. If the browser requests a different locale, a response encoding for that locale is used instead, if possible. When a client browser requests a page from your web application, the default response of the application is as follows:
q

The application opens a JSP file, converts the file into internal Java Unicode, using the tag <jsp.directive. page ... pageEncoding="xxxx" ... /> to determine the files encoding, and brings it into memory. Following the directives in the JSP file and the HTML style sheet, the application generates the required servlet and HTML in the encoding specified in the tag <jsp:directive.page ... contentType="text/html; charset=xxxx" ... /> The application assembles the complete page, encodes it in the specified encoding, and delivers it to the client browser through the web server.

The client browser can attempt to override the default response encoding by asking for a specific language in its request Russian, for example. The web application may accept that request, note that Russian is available in the web application in UTF-8 encoding, and deliver the page in UTF-8 encoding with string elements from the Russian resource bundles. Alternatively, you could have decided to specify your application's Russian response encoding as KOI8-R, an encoding still popular in Russia. In this case, your application converts the JSP file into Unicode in memory, then converts that intermediate representation into KOI8-R and delivers the page. The client browser displays the page in Russian and accepts user input as KOI8-R encoding. When the user submits the page,the client browser includes a header notifying the web server that the page is encoded in KOI8-R, enabling the server to interpret the request. Each request and response is associated with an encoding. If a client browser does not send an encoding specification, the application server assumes that the request is in the same encoding as the response it sent most recently.

Changing Response Encoding of a Page You can change the response encoding for individual JSP files in the IDE project. 1. In the IDE's Visual Designer, click the background of the page and view the properties for the page. The Properties window will show the Advanced > Response Encoding property, similar to the following figure.

Figure 6: Viewing Response Encoding Property 2. If the Response Encoding property is not blank, select and delete the entry to apply the default value, or enter a different encoding. Alternatively, click the button next to the property and edit the value in the dialog box. 3. View the source file for the page by clicking the JSP tab. 4. Enter and delete a character in the file so that it can be saved, and select File > Save to save the file.

UrlLang Property
The urlLang property applies to the link components Hyperlink and Image Hyperlink. It specifies the language used in the resource referred to by the url property of these components. In the rendered page, the property is expressed as the hreflang attribute of the HTML <a> tag.

1. Drag a Hyperlink or Image Hyperlink component from the JSF Palette onto the Visual Editor. 2. Select the component (not the hyperlink text inside it). NOTE: If you have selected the text, you can expand it to the component by pressing the Esc key or clicking the component a second time. Alternatively, you can select the component in the Application Outline, as shown in the following figure.

Figure 7: Viewing Properties for a Hyperlink Component 3. View the Advanced properties on the Properties window. You will see the urlLang property. 4. To edit a language code, click the ellipsis button (...) to open the Property Editor, in which you can change the value of the property. The following figure shows the Properties Editor for the urlLang property. A value of ru has been entered so that only language codes containing these consecutive characters are displayed.

Figure 8: Properties Editor for urlLang Property, Use Value You can either define the language code directly on the Use Value panel shown in the preceding figure or use the Use Binding panel to bind the property to a bean property (either data provider or object) and enable your application to set the language code dynamically. The IDE uses the same editor interface for the urlLang and lang properties (lang is discussed below). The following figure shows lang being bound to a pattern in a projects session bean. Binding to a property of the session bean is useful when you want to bind the component property to a property of the session bean in which you maintain the language codes for your application.

Figure 9: Properties Editor for lang Property, Use Binding

Lang Property
The lang property specifies the language used in the generated markup for a Grid Panel component. The property is visible in the Properties window when you select a Grid Panel component in the Visual Designer. The lang property is expressed as the HTML lang attribute in the <a href> tag. This attribute specifies the character encoding of the resource designated by the link. It is intended to allow user agents to render content meaningfully based on accepted cultural practice for a given language. It can be used to declare the language of a web page or a portion of a web page. Clicking the button next to the property brings up the same Properties Editor shown in Figures 8 and 9.

Language Property
A Language property is associated with each JSP page of your application. The property specifies the language used in the generated markup for the page. It is expressed as the lang attribute of the <head> HTML tag. To change the property value, display a page in the Visual Designer and view its properties in the Properties window. Click the ellipsis button (...) next to the Advanced > Language property. If a component on the page has a lang property setting different from this setting, then the value of the lang property is used for that component.

The Charset Property

The charset property is associated with the url property of link components such as Hyperlinks, and specifies the character encoding of the document or resource that is the target of the link. It is expressed as the charset attribute of the the HTML <a> tag when the page is rendered. For a list of encodings, refer to http://www.iana.org/assignments/character-sets. Strictly speaking, character sets are not encodings; however, the HTML specification has given the encoding attribute the charset name.

10

To view the property: 1. View a page in the Visual Designer. 2. If there is no Link component on the page, drag a Link component onto the page in Design view. 3. In the Outline window, select the page > html > head > link1 node as shown in the following figure and view the Link components properties in the Properties window.

Figure 10: Selecting a Link Component Instance in the Outline Window

To change the charset property: 1. Click the ellipsis button next to the charset property in the Properties window. 2. A dialog box opens in which you can choose an encoding. The dialog box is similar to the one shown in Figures 8 and 9. In the Use Value pane, use the Filter field to enter a character string that narrows your view of available character sets. The encoding you specify provides a hint of the encoding of the target. This hint helps the browser to link appropriately. The list in the dialog box shown in Figure 8 is the published list of all character encodings in official use, as defined by the W3C. However, the list may be incomplete in that it may not have all known aliases of each encoding. Adding a New Encoding Because some proprietary encodings may exist that are not available from the list, you can add one by clicking the New button in the dialog box. Proprietary encodings are sometimes developed by organizations that wish to display special characters not available elsewhere. Such sites generally must prompt the user to download a proprietary font package and encoding before the site can be viewed.

The Hreflang Property

The hreflang property applies to Standard link components. It is used and edited just as the urlLang property is for Basic and Advanced link components. New projects should avoid using Standard components.

The Dir Property

The dir property applies to layout components that may contain text display or entry components. To view the property, select a Grid Panel component in the Visual Designer and look in the Advanced category. The dir property is used to indicate the directionality of text and is useful when text does not inherit the correct directionality (for example, because the text is English but the primary language for the page is Hebrew). The property is expressed as the dir

11

attribute of the HTML <input> tag in the rendered page. Strictly speaking, this attribute is not part of language encoding. However, it controls how alphabets are displayed. The property's values can be one of the following: LTR (Left-to-right) RTL (Right-to-left)

Bundled Properties
An application can be localized by specifying a single locale and encoding, or simply by setting your operating system to the locale and encoding of the target platform before you open the IDE. However, to internationalize a project, the best practice is to segregate all user-visible strings into bundled properties files so that they can be easily translated for various locales. When you create a new project, the IDE creates a Bundle.properties file that serves as the default language and locale for your project. The default is based on your computers system settings for language and locale. You can then add properties to the file in the form of pairs of key-value strings, with values expressed in the language of the locale. When you add a locale to the bundle, you create a new properties file specific to that locale. The properties file for each locale you add contains the same keys, but the values are specific to the locale. When a client browser specifies one of the locales, the application can compose a page in the requested locale using elements from that locale's resource bundle and the encoding you have specified elsewhere in your properties settings. To add a locale to your project, right-click the bundle.properties node in the Files or Projects window and choose Add Locale, as shown in the following figure.

Figure 11: Adding a Locale A New Locale window opens in which you can enter language, country, and variant codes, select them individually from drop-down lists, or choose combinations from a list of predefined locales, as shown in the following figure.

12

Figure 12: Specifying a New Locale To edit a properties file, you can double-click its node in the Files or Projects window. The Java Editor will open, and you can enter key-value pairs in the form of key=value, as shown in the following figure.

Figure 13: Editing a .properties File in Java Editor To edit the bundle in a Properties Editor: 1. Right-click on the bundle.properties node in the Files or Projects window. 2. Choose Open from the contextual menu, as shown in the following figure.

13

Figure 14: Opening a Properties Bundle The Properties Editor opens, as shown in the following figure.

Figure 15: Editing a Properties Bundle 3. Edits you make to Key values in the first column will be applied to all bundled properties files. You can edit the keys or values directly in the table or in the text entry fields below the table. Comment fields are provided to help you remember the use of each key-value pair. 4. Clicking the New Property button opens a dialog box in which you can enter a new key, value, and comment. Your entries are applied to all the files in the bundle. You can then edit the values for the new property in each locale. 5. To remove the current property, click the Remove Property button. Your project accesses the bundled properties files through a <f:loadBundle> tag that is added to a page's JSP file when you

14

drop a Load Bundle component onto the page in the Visual designer (see below). When you deploy your application, the properties files are copied to the WEB-INF/classes/projectname directory for you, so that it is available for the <f:loadBundle> tag to load. When your web application receives a request from a client browser to compose a page, it checks for a locale request. The application then searches for the properties file that matches the locale, substitutes the values in the file for the keys wherever they appear in your project, and composes the page in the proper encoding.

Load Bundle Component

The Load Bundle component is available from the Palette under the Advanced category. When you drag it onto a page in the Visual Designer, it creates a custom <f:loadBundle> tag in the JavaServer Pages code for a page. The tag exposes a resource bundle as a Map and lets you use the locales you have added to the resource bundle. The Load Bundle component is best understood by referring to the example at the end of this tutorial.

Internationalization Properties in JavaServer Faces Files

When you view the JSP source for a page (by clicking the JSP tab in the Visual Designer), you see the effects of some of the internationalization features. Three lines near the beginning of a JSP file reflect the property values for source encoding, response encoding, and default locale. The following lines result from a source encoding of UTF-8, a default locale of ja-JP, and a response encoding of Shift_JIS. Code Sample 1: Page Encoding <?xml version="1.0" encoding="UTF-8"?> ... <jsp:directive.page contentType="text/html;charset=Shift_JIS" pageEncoding="UTF-8"/> ... <html lang="ja-JP" xml:lang="ja-JP">

Your system might display different default encoding aliases, depending on your operating system and locale. For example, you might see MacRoman, MS950, or SJIS. Your native encoding name will be translated to a valid Internet Assigned Numbers Authority (IANA) encoding to be used by the IDE when it encodes the JavaServer pages (JSPs) for your project. Note that the value of the following properties should be the same in your JSP files:
q q q

xml version=1.0 encoding, as shown in the code example above pageEncoding, as shown in the code example The Source Encoding property and the text encoding of the individual Java source files (discussed previously in the section Default Source Encoding Option)

For localized applications, the value of the following properties should be the same. For internationalized applications, these values may be overridden at run time.
q q

contentType=text/html;charset, as shown in the code example Response Encoding property (discussed in the section entitled Default Locale and Response Encoding)

15

The faces-config.xml File

The faces-config.xml file, visible in the Files window beneath your project's web > WEB-INF node, is used to set the default and supported locales for your project, as illustrated in the following example.

Example
This simple example shows you how to localize an application for the Japanese locale. To complete this tutorial, you must understand how to set up your development system and web browser for the Japanese language and locale. Setting Up a Localized System Before creating your project, you must set up your development system for the target language and locale. The IDE inherits the language and locale settings of your system. (The specifics of how to do this for each operating system are beyond the scope of this tutorial. Consult the documentation for your system to enable the named locale.) This tutorial uses ja_JP, the Japanese language and locale. You must also set up your web browser to display Japanese characters. Consult the documentation for your browser for details. Creating a Localized Project 1. Open the Java Studio Creator IDE. From the Welcome page, click Create New Project. Name the project HelloWideWorld 2. In the Visual Designer, drag a Static Text component from the Palette onto Page1. 3. In the Files window, expand the project's Web > WEB-INF node and double-click the faces-config.xml file. The file will open for editing. 4. Remove the comments from the <application> tag. Edit the tag to make Japanese the default locale and English a supported locale. Your code should look like the following code sample: Code Sample 2: Edited <application> Tag in faces-config.xml File <faces-config> <application> <locale-config> <default-locale>ja</default-locale> <supported-locale>en</supported-locale> </locale-config> </application> </faces-config>

5. Save the faces-config.xml file. 6. In the File window, expand the HelloWideWorld > src > hellowideworld node and right-click the Bundle. properties node. Choose Open from the contextual menu. The Properties Editor opens. 7. In the Properties Editor, click New Property. In the resulting New Properties dialog box, enter hello for key, hello world for value, and Greeting for comment, as shown in the following figure.

16

Figure 16: New Property Dialog Box 8. In the Files Window, right-click the HelloWideWorld > src > hellowideworld > Bundle.properties node and choose Add Locale from the contextual menu. The Add Locale dialog box opens. 9. In the New Locale dialog box, enter the Language Code en and Country Code US, as shown in the following figure.

Figure 17: New Locale Dialog Box 10. In the Files window, double-click the HelloWideWorld > src > hellowideworld > Bundle.properties > default language node. The default language properties bundle file opens in a text editor. 11. Enter character codes for Japanese greeting. The characters are the value of the hello key. The contents of the file should look like the following code sample: Code Sample 3: Edited Default Language File #Greeting hello=\u3053\u3093\u306B\u3061\u306F\u4E16\u754C

12. Save the file and close the text editor. 13. Click the Properties Editor tab. The value of the hello key in the default language column should be shown in Japanese characters. Note that you can edit these characters directly in the Properties Editor as Japanese text, either from the keyboard or by copying and pasting from another application. In this example, you entered the Japanese characters as ASCII code in the text editor instead. 14. Close the Properties Editor. 15. View Page1 in the Visual Designer. From the Components Palette, drag the Advanced > Load Bundle component onto the page background. This component creates a <f:loadBundle> tag in the JavaServer Pages code for the file. 16. Click the JSP tab in the Visual Designer and locate the <f:loadBundle> tag. It should read as follows:

17

<f:loadBundle basename="hellowideworld.Bundle" var="messages1"/> You will use the value of var to bind the text of the Static Text component to the value of the hello key in the resource bundle. 17. View Page1 in the Visual Designer and select the Static Text component. View its properties in the Properties window. 18. In the Properties window, click the ellipsis button next to the text property. Enter the value #{messages1.hello} and click OK. Note that the Static Text component no longer shows text in the Visual Designer. At run time, it will show Japanese text if the browser is enabled to display it. Otherwise, it will display English text.

Testing Your Example Application Click the Run arrow at the top of the IDE window to deploy and run your project. If all goes well, your browser will open with Page1 and the Japanese characters will be displayed, as shown in the following figure.

Figure 18: Example Application Output

Summary
The Sun Java Studio Creator IDE enables you to develop localized web applications specific to a single locale. Before beginning development, you must set your system and browser settings to display the target locale and language. The IDE provides properties and option settings to help you develop your localized application. The IDE also lets you develop internationalized web applications that can be automatically localized to many different locales. The recommended way to do this is to use a properties bundle that segregates your human-readable text into one set of files for easy maintenance. See Also:
q q

Creating an Internationalized Application Adobe Typography Primer (PDF)

More Developer Resources: For more tutorials, articles, tips, forums, updates, and expert advice for developers, visit the Java Studio Creator developer resources on the Sun Developer Network (SDN) at http://developers.sun.com/jscreator/.

This page was last modified: May 17, 2006

18

Sun and Third-party Trademarked Terminology

The following Sun trademarked terms might be used in the Sun Java(tm) Studio Creator tutorials:
q q q q q q q q q

Sun Java Studio Creator integrated development environment (IDE) Sun Java System Application Server version number (Application Server) Java Platform, Standard Edition technology (Java SE(tm) platform) JavaServer(tm) Faces technology JavaServer Pages(tm) technology (JSP(tm) technology) Sun Java System Web Server version number (Web Server) Java Database Connectivity software (JDBC software) Enterprise JavaBeans(tm) specification (EJB(tm) specification) Solaris(tm) Operating System software (Solaris OS software)

The following third-party trademarked terms might be used in the Sun Java Studio Creator tutorials:
q q

UNIX(R) software SPARC(R) processor

Copyright 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and in other countries. U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. Use is subject to license terms. Sun, Sun Microsystems, the Sun logo, Java and the Java Coffee Cup logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.This product is covered and controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited. Note: Sun is not responsible for the availability of third-party web sites mentioned in this document and does not endorse and is not responsible or liable for any content, advertising, products, or other materials on or available from such sites or resources. Sun will not be responsible or liable for any damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services available on or through any such sites or resources.

Copyright 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, tats-Unis. Tous droits rservs. Sun Microsystems, Inc. dtient les droits de proprit intellectuels relatifs la technologie incorpore dans le produit qui est dcrit dans ce document. En particulier, et ce sans limitation, ces droits de proprit intellectuelle peuvent inclure un ou plus des brevets amricains lists l'adresse http://www.sun.com/patents et un ou les brevets supplmentaires ou les applications de brevet en attente aux tats-Unis et dans les autres pays. L'utilisation est soumise aux termes de la Licence. Sun, Sun Microsystems, le logo Sun, Java et le logo Java Coffee Cup sont des marques de fabrique ou des marques dposes de Sun Microsystems, Inc. aux tats-Unis et dans d'autres pays.Ce produit est soumis la lgislation amricaine en matire de contrle des exportations et peut tre soumis la rglementation en vigueur dans d'autres pays dans le domaine des exportations et importations. Les utilisations, ou utilisateurs finaux, pour des armes nuclaires, des missiles, des armes biologiques et chimiques ou du nuclaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou rexportations vers les pays sous embargo amricain, ou vers des entits figurant sur les listes d'exclusion d'exportation amricaines, y compris, mais de manire non exhaustive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une faon directe ou indirecte, aux exportations des produits ou des services qui sont rgis par la lgislation amricaine en matire de contrle des exportations et la liste de ressortissants spcifiquement dsigns, sont rigoureusement interdites. Sun Microsystems n'est pas responsable de la disponibilit de tiers emplacements d'enchanement mentionns dans ce document et n'approuve pas et n'est pas responsable ou iresponsable d'aucun contenu, de la publicit, de produits, ou d'autres matriaux dessus ou fournis par de tels emplacements ou ressources. Sun ne sera pas responsable ou iresponsable d'aucuns dommages ou perte causs ou allgus pour tre caus par ou en liaison avec l'utilisation de ce produit ou la confiance dans des tels contenu, marchandises, ou services disponibles sur ou par des tels emplacements ou ressources.

19