20 Internationalizing and Localizing Pages

This chapter describes how to configure JSF pages or an application to display text in the correct language of a user's browser.

This chapter includes the following sections:

Section 20.1, "Introduction to Internationalization and Localization of ADF Faces Pages"
Section 20.2, "Defining Locales and Resource Bundles"
Section 20.3, "Using Automatic Resource Bundle Integration in JDeveloper"
Section 20.4, "Configuring Optional ADF Faces Localization Properties"

20.1 Introduction to Internationalization and Localization of ADF Faces Pages

Internalization is the process of designing and developing products for easy adaptation to specific local languages and cultures. Localization is the process of adapting a product for a specific local language or culture by translating text and adding locale-specific components. A successfully localized application will appear to have been developed within the local culture. JDeveloper supports easy localization of ADF Faces components using the abstract class java.util.ResourceBundle to provide locale-specific resources.

When your application will be viewed by users in more than one country, you can configure your JSF page or application to use different locales so that it displays the correct language for the language setting of a user's browser. For example, if you know your page will be viewed in Italy, you can localize your page so that when a user's browser is set to use the Italian language, text strings in the browser page will appear in Italian.

ADF Faces components may include text that is part of the component, for example the af:table component uses the resource string af_table.LABEL_FETCHING for the message text that is displayed in the browser while the table is fetching data during the initial load of data or while the table is being scrolled. JDeveloper provides automatic translation of these text resources into 28 languages. These text resources are referenced in a resource bundle. If you set the browser to use the language in Italy, any text contained within the components will automatically be displayed in Italian. For more information on skins and resource bundles, see Chapter 19, "Customizing the Appearance Using Styles and Skins".

For any text you add to a component, for example if you define the label of an af:commandButton component by setting the text attribute, you must provide a resource bundle that holds the actual text, create a version of the resource bundle for each locale, and add a <locale-config> element to define default and support locales in the application's faces-config.xml file. You must also add a <resource-bundle> element to your application's faces-config.xml file in order to make the resource bundles available to all the pages in your application. Once you have configured and registered a resource bundle, the Expression Language (EL) editor will display the key from the bundle, making it easier to reference the bundle in application pages.

To simplify the process of creating text resources for text you add to ADF components, JDeveloper supports automatic resource bundle synchronization for any translatable string in the visual editor. When you edit components directly in the visual editor or in the Property Inspector, text resources are automatically created in the base resource bundle.

Note:

Any text retrieved from the database is not translated. This document explains how to localize static text, not text that is stored in the database.

Figure 20-1 shows the SRList page in a browser using English (United States) locale.

Figure 20-1 SRList Page in English

Although the title of this page is My Service Requests, instead of having My Service Requests as the value for the title attribute of the af:panelPage component, the value is bound to a key in the UIResources resource bundle. The UIResources resource bundle is registered in the faces-config.xml file for the application, as shown in Example 20-1.

Example 20-1 Resource Bundle Element in JSF Configuration File

<resource-bundle>
  <var>res</var
  <base-name>resources.UIResources</base-name>
</resource-bundle>

The resource bundle is given a variable name (in this case, res) that can then be used in EL expressions. On the page, the title attribute of the af:panelPage component is then bound to the srlist.pageTitle key in that resource bundle, as shown in Example 20-2.

Example 20-2 Component Text Referencing Resource Bundle

<af:panelPage text="#{res['srlist.pageTitle']}

The UIResources resource bundle has an entry in the English language for all static text displayed on each page in the application, as well as for text for messages and global text, such as generic labels. Example 20-3 shows the keys for the SRList page.

Example 20-3 Resource Bundle Keys for the SRList Page Displayed in English

#SRList Screen
srlist.pageTitle=My Service Requests
srlist.menubar.openLink=Open Requests
srlist.menubar.pendingLink=Requests Awaiting Customer
srlist.menubar.closedLink=Closed Requests
srlist.menubar.allRequests=All Requests
srlist.menubar.newLink=Create New Service Request
srlist.selectAnd=Select and 
srlist.buttonbar.view=View
srlist.buttonbar.edit=Edit

Figure 20-2 also shows the SRList page, but with the browser set to use the Italian (Italy) locale. Note that text in the banner image and data retrieved from the database are not translated.

Figure 20-2 SRList Page in Italian

Example 20-4 shows the resource bundle version for the Italian (Italy) locale, UIResources_it. Note that there is not an entry for the selection facet's title, yet it was translated from Select to Seleziona automatically. That is because this text is part of the ADF Faces table component's selection facet.

Example 20-4 Resource Bundle Keys for the SRList Page Displayed in Italian

#SRList Screen
srlist.pageTitle=Miei Ticket
srlist.menubar.openLink=Ticket Aperti
srlist.menubar.pendingLink=Ticket in Attesa del Cliente
srlist.menubar.closedLink=Ticket Risolti
srlist.menubar.allRequests=Tutti i Ticket
srlist.menubar.newLink=Creare Nuovo Ticket
srlist.selectAnd=Seleziona e  
srlist.buttonbar.view=Vedere Dettagli
srlist.buttonbar.edit=Aggiorna

20.2 Defining Locales and Resource Bundles

A bundle contains a number of named resources, where the names are String. A bundle may have a parent bundle. When a resource is not found in a bundle, the parent bundle is searched for the resource. Resource bundles can be either Java classes or property files. The abstract class java.util.ResourceBundle has two subclasses: java.util.PropertyResourceBundle and java.util.ListResourceBundle. A java.util.PropertyResourceBundle is stored in a property file, which is a plain-text file containing translatable text. Property files can contain values only for String objects. If you need to store other types of objects, you must use a java.util.ListResourceBundle class instead.

To add support for an additional locale, you simply replace the values for the keys with localized values and save the property file, appending a language code (mandatory) and an optional country code and variant as identifiers to the name, for example, UIResources_it.properties.

The java.util.ListResourceBundle class manages resources in a name and value array. Each java.util.ListResourceBundle class is contained within a Java class file. You can store any locale-specific object in a java.util.ListResourceBundle class. To add support for an additional locale, you create a subclass from the base class, save it to a file with a locale or language extension, translate it, and compile it into a class file.

The ResourceBundle class is flexible. If you first put your locale-specific String objects in a java.util.PropertyResourceBundle file, you can still move them to a ListResourceBundle class later. There is no impact on your code, because any call to find your key will look in both the java.util.ListResourceBundle class and the java.util.PropertyResourceBundle file.

The precedence order is class before properties. So if a key exists for the same language in both a class file and a property file, the value in the class file will be the value presented to you. Additionally, the search algorithm for determining which bundle to load is as follows:

(baseclass)+(specific language)+(specific country)+(specific variant)
(baseclass)+(specific language)+(specific country)
(baseclass)+(specific language)
(baseclass)+(default language)+(default country)+(default variant)
(baseclass)+(default language)+(default country)
(baseclass)+(default language)

For example, if your browser is set to the Italian (Italy) locale and the default locale of the application is US English, the application will attempt to find the closest match, looking in the following order:

it_IT
it
en_US
en
The base class bundle

Tip:

The getBundle method used to load the bundle looks for the default locale classes before it returns the base class bundle. If it fails to find a match, it throws a MissingResourceException error. A base class with no suffixes should always exist as a default. Otherwise, it may not find a match and the exception is thrown.

20.2.1 How to Define the Base Resource Bundle

You must create a base resource bundle that contains all the text strings that are not part of the components themselves. This bundle should be in the default language of the application. You can create a resource bundle as a property file, as an XLIFF file, or as a java class. After a resource bundle file has been created, you can edit the file using the Edit Resource Bundles dialog.

To create a resource bundle as a property file or an XLIFF file:

In JDeveloper, create a new file.
- In the Application Navigator, right-click where you want the file to be placed and choose New from the context menu to open the New Gallery.
  
  Note:
  If you are creating a localized version of the base resource bundle, save the file to the same directory as the base file.
- In the Categories tree, select General, and in the Items list, select File. Click OK.
- In the Create File dialog, enter a name for the file using the convention <name><_lang>.properties, where the <_lang> suffix is provided for translated files, as in _de for German, and omitted for the base language.
  
  Note:
  If you are creating a localized version of a base resource bundle, you must append the ISO 639 lowercase language code to the name of the file. For example, the Italian version of the UIResources bundle is UIResources_it.properties. You can add the ISO 3166 uppercase country code (for example it_CH, for Switzerland) if one language is used by more than one country. You can also add an optional nonstandard variant (for example, to provide platform or region information).
  If you are creating the base resource bundle, do not append any codes.
Enter the content for the file. You can enter the content manually by entering the key-value pairs. You can use the Edit Resource Bundle dialog to enter the key-value pairs, as described in Section 20.2.2, "How to Edit a Resource Bundle File".
- If you are creating a property file, create a key and value for each string of static text for this bundle. The key is a unique identifier for the string. The value is the string of text in the language for the bundle. If you are creating a localized version of the base resource bundle, any key not found in this version will inherit the values from the base class.
  Note:
  All non-ASCII characters must be UNICODE-escaped or the encoding must be explicitly specified when compiling, for example:
```
javac -encoding ISO8859_5 UIResources_it.java
```
  For example, the key and the value for the title of the SRList page is:
```
srlist.pageTitle=My Service Requests
```
- If you are creating an XLIFF file, enter the proper tags for each key-value pair. For example:
```
<?xml version="1.0" encoding="windows-1252" ?>
<xliff version="1.1" xmlns="urn:oasis:names:tc:xliff:document:1.1">
  <file source-language="en" original="myResources" datatype="xml">
    <body>
      <trans-unit id="NAME">
        <source>Name</source>
        <target/>
        <note>Name of employee</note>
      </trans-unit>
      <trans-unit id="HOME_ADDRESS">
        <source>Home Address</source>
        <target/>
        <note>Adress of employee</note>
      </trans-unit>
      <trans-unit id="OFFICE_ADDRESS">
        <source>Office Address</source>
        <target/>
        <note>Office building </note>
      </trans-unit>
    </body>
  </file>
</xliff>
```
After you have entered all the values, click OK.

To create a resource bundle as a Java class:

In JDeveloper, create a new Java class:
- In the Application Navigator, right-click where you want the file to be placed and choose New to open the New Gallery.
  
  Note:
  If you are creating a localized version of the base resource bundle, it must reside in the same directory as the base file.
- In the Categories tree, select General, and in the Items list, select Java Class. Click OK.
- In the Create Java Class dialog, enter a name and package for the class. The class must extend java.util.ListResourceBundle.
  
  Note:
  If you are creating a localized version of a base resource bundle, you must append the ISO 639 lowercase language code to the name of the class. For example, the Italian version of the UIResources bundle might be UIResources_it.java. You can add the ISO 3166 uppercase country code (for example it_CH, for Switzerland) if one language is used by more than one country. You can also add an optional nonstandard variant (for example, to provide platform or region information).
  If you are creating the base resource bundle, do not append any codes.
Implement the getContents() method, which simply returns an array of key-value pairs. Create the array of keys for the bundle with the appropriate values. Or use the Edit Resource Bundles dialog to automatically generate the code, as described in Section 20.2.2, "How to Edit a Resource Bundle File". Example 20-5 shows a base resource bundle Java class.

Note:
Keys must be String objects. If you are creating a localized version of the base resource bundle, any key not found in this version will inherit the values from the base class.
Example 20-5 Base Resource Bundle Java Class
```
package sample;

import java.util.ListResourceBundle;

public class MyResources extends ListResourceBundle {
  public Object[][] getContents() {
    return contents;
}
static final Object[][] contents {
  {"button_Search", Search"},
  {"button_Reset", "Reset"},
  };
}
```

20.2.2 How to Edit a Resource Bundle File

After you have created a resource bundle property file, XLIFF file, or Java class file, you can edit it using the source editor.

To edit a resource bundle after it has been created:

In JDeveloper, choose Tools > Edit Resource Bundles from the main menu.
In the Edit Resource Bundles dialog, select the resource bundle file you want to edit from the Resource Bundle dropdown list, as shown in Figure 20-3, or click the Search icon to launch the Select Resource Bundle dialog.

Figure 20-3 Edit Resource Bundle Dialog
In the Select Resource Bundle dialog, select the file type from the File type dropdown list. Navigate to the resource bundle you want to edit, as shown in Figure 20-4. Click OK.

Figure 20-4 Select Resource Bundle Dialog
In the Edit Resource Bundles dialog, click the Add icon to add a key value pair, as shown in Figure 20-5. When you have finished, click OK.

Figure 20-5 Adding Values to a Resource Bundle

20.2.3 How to Register Locales and Resource Bundles in Your Application

You must register the locales and resource bundles used in your application in the faces-config.xml file.

To register a locale for your application:

Open the faces-config.xml file and click the Overview tab in the editor window. The faces-config.xml file is located in the <View_Project>/WEB-INF directory.
In the editor window, select Application.

In the Locale Config area, click New to open the Property Inspector to add the code for the locale, as shown in Figure 20-6.

Figure 20-6 Adding a Locale to faces-config.xml

After you have added the locales, the faces-config.xml file should have code similar to the following:

<locale-config>
      <default-locale>en</default-locale>
      <supported-locale>ar</supported-locale>
      <supported-locale>ca</supported-locale>
      <supported-locale>cs</supported-locale>
      <supported-locale>da</supported-locale>
      <supported-locale>de</supported-locale>
      <supported-locale>zh_Ch</supported-locale>
 </locale-config>

To register the resource bundle:

Open the faces-config.xml file and click the Overview tab in the editor window. The faces-config.xml file is located in the <View_Project>/WEB-INF directory.
In the editor window, select Application.
In the Resource Bundle section, click Add to enable editor input. Enter the fully qualified name of the base bundle that contains messages to be used by the application and a variable name that can be used to reference the bundle in an EL expression, as shown in Figure 20-7.

Figure 20-7 Adding a Resource Bundle to faces-config.xml

After you have added the resource bundle, the faces-config.xml file should have code similar to the following:
```
<resource-bundle>
      <base-name>oracle.fodemo.storefront.StoreFrontUIBundle</base-name>
 <var>res</var>
```

20.2.4 How to Use Resource Bundles in Your Application

With JSF 1.2 you are not required to load the base resource bundle on each page in your application with the <f:loadBundle> tag.

To use a base resource bundle on your page:

Set your page encoding and response encoding to be a superset of all supported languages. If no encoding is set, the page encoding defaults to the value of the response encoding set using the contentType attribute of the page directive. Example 20-6 shows the encoding for the SRList page.

Example 20-6 Page and Response Encoding

<?xml version='1.0' encoding='windows-1252'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.0"
          xmlns:h="http://java.sun.com/jsf/html"
          xmlns:f="http://java.sun.com/jsf/core"
          xmlns:af="http://xmlns.oracle.com/adf/faces"
          xmlns:afc="http://xmlns.oracle.com/adf/faces/webcache">
  <jsp:output omit-xml-declaration="true" doctype-root-element="HTML"
              doctype-system="http://www.w3.org/TR/html4/loose.dtd"
              doctype-public="-//W3C//DTD HTML 4.01 Transitional//EN"/>
  <jsp:directive.page contentType="text/html;charset=UTF-8"/>
  <f:view>

Tip:

By default JDeveloper sets the page encoding to windows-1252. To set the default to a different page encoding:

From the menu, choose Tools > Preferences.
In the left-hand pane, select Environment if it is not already selected.
Set Encoding to the preferred default.

Bind all attributes that represent strings of static text displayed on the page to the appropriate key in the resource bundle, using the variable defined in the faces-config.xml file for the <resource-bundle> element. Example 20-7 shows the code for the View button on the SRList page.
Example 20-7 Binding to a Resource Bundle
```
<af:commandButton text="#{res['srlist.buttonbar.view']}"
                  . . . />
```

20.2.5 What You May Need to Know About Custom Skins and Control Hints

If you use a custom skin and have created a custom resource bundle for the skin, you must also create localized versions of the resource bundle. Similarly, if your application uses control hints to set any text, you must create localized versions of the generated resource bundles for that text.

20.3 Using Automatic Resource Bundle Integration in JDeveloper

By default, JDeveloper supports the automatic creation of text resources in the default resource bundle when editing ADF Faces components in the visual editor. To treat user-defined strings as static values, disable Automatic Synchronize Bundle in the Project Properties dialog, as described in Section 20.3.1, "How to Set Resource Bundle Options".

Automatic resource bundle integration can be configured to support one resource bundle per page or project, or multiple shared bundles.

Users can edit translatable text strings using any one of the following methods:

In the visual editor, enter the new text directly in the component. Click the component to bring up a text input window, as shown in Figure 20-8.

Figure 20-8 Adding Text to a Component
From the text input window, choose Select Text Resource to launch the Edit Source dialog, as shown in Figure 20-9. The dialog can also be accessed by right-clicking the component and choosing Select Text Resource for, or from the Property Inspector, by clicking the icon to the right of a translatable property and selecting Select Text Resource.

Figure 20-9 Select Text Resource Editor
From the text input window, select Expression Builder to launch the Expression Builder dialog. The dialog can also be accessed from the Property Inspector by clicking the icon to the right of a translatable property and selecting Expression Builder.
In the Property Inspector, enter a valid expression language string for a translatable property.

Note:
Only strings defined with automatic resource bundle integration will be managed. Preexisting text resources are not synchronized.

20.3.1 How to Set Resource Bundle Options

After you have created a project, you can set resource bundle options in the Project Properties dialog.

To set resource bundle options for a project:

In the Application Navigator, double-click the project.
In the Project Properties dialog, select Resource Bundle to display the resource bundle options, as shown in Figure 20-10.

Figure 20-10 Project Properties Resource Bundle dialog
If you want JDeveloper to automatically generate a default resource file, select Automatically Synchronize Bundle.
Select one of the following resource bundle file options:
- One Bundle Per Project - configured in a file named <ProjectName>.properties.
- One Bundle Per Page - configured in a file named <PageName>.properties.
- Multiple Shared Bundles.
Select the resource bundle type from the dropdown list:
- XML Localization Interchange File Format (XLIFF) Bundle
- List Resource Bundle
- Properties Bundle

20.4 Configuring Optional ADF Faces Localization Properties

Along with providing text translation, ADF Faces also automatically provides other types of translation, such as text direction and currency codes. The application will automatically be displayed appropriately, based on the user's selected locale. However, you can also manually set the following localization settings for an application in the trinidad-config.xml file:

<currency-code>: Defines the default ISO 4217 currency code used by oracle.adf.view.faces.converter.NumberConverter to format currency fields that do not specify a currency code in their own converter.
<number-grouping-separator>: Defines the separator used for groups of numbers (for example, a comma). ADF Faces automatically derives the separator from the current locale, but you can override this default by specifying a value in this element. If set, this value is used by oracle.adf.view.faces.converter.NumberConverter while it parses and formats.
<decimal-separator>: Defines the separator used for the decimal point (for example, a period or a comma). ADF Faces automatically derives the separator from the current locale, but you can override this default by specifying a value in this element. If set, this value is used by oracle.adf.view.faces.converter.NumberConverter while it parses and formats.
<right-to-left>: Defines the direction in which text appears in a page. ADF Faces automatically derives the rendering direction from the current locale, but you can explicitly set the default page rendering direction by using the values true or false.
<time-zone>: Defines the time zone appropriate to the selected locale. ADF Faces automatically uses the time zone used by the client browser. This value is used by oracle.adf.view.faces.converter.DateTimeConverter when it converts String to Date.
<formatting-locale> : Defines the date and number format appropriate to the selected locale. ADF Faces and Trinidad, will by default, format dates and numbers in the same locale used for localized text. If you want dates and numbers formatted in a different locale, you can use an IANA-formatted locale (for example, ja, fr-CA). The contents of this element can also be an EL expression pointing at an IANA string or a java.util.Locale object.

20.4.1 How to Configure Optional Localization Properties

You can configure optional localization properties by entering elements in the trinidad-config.xml file.

To configure optional localization properties:

Open the trinidad-config.xml file. The file is located in the <View_Project>/WEB-INF directory.
From the Component Palette, drag the element you wish to add to the file into the Structure window. An empty element is added to the page.
Enter the desired value.

Example 20-8 shows a sample trinidad-config.xml file with all the optional localization elements set.

Example 20-8 Configuring Currency Code and Separators for Numbers and Decimal Point

<!-- Set the currency code to US dollars. -->
<currency-code>USD</currency-code>

<!-- Set the number grouping separator to period for German -->
<!-- and comma for all other languages -->
<number-grouping-separator>
 #{view.locale.language=='de' ? '.' : ','}
</number-grouping-separator>

<!-- Set the decimal separator to comma for German -->
<!-- and period for all other languages -->
<decimal-separator>
 #{view.locale.language=='de' ? ',' : '.'}
</decimal-separator>

<!-- Render the page right-to-left for Arabic -->
<!-- and left-to-right for all other languages -->
<right-to-left>
 #{view.locale.language=='ar' ? 'true' : 'false'}
</right-to-left>

<formatting-locale>
 #{request.locale}
</formatting-locale>

<!-- Set the time zone to Pacific Daylight Savings Time -->
<time-zone>PDT</time-zone>