34 Internationalizing and Localizing Pages

Assume, for example, that you have a panel box with a title of My Purchase Requests. Rather than set the literal string, My Purchase Requests, as the value of the af:panelBox component's text attribute, you bind the value of the text attribute 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 the following example.

<resource-bundle>
  <base-name>resources.UIResources</base-name>
  <var>res</var>
</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 text attribute of the af:panelBox component is then bound to the myDemo.pageTitle key in that resource bundle, as shown in the folloiwng example.

<af:panelBox text="#{res['myDemo.pageTitle']}"
    ....
    id="pb1">

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 34-1 shows the keys for the myDemo page. Example 34-2 shows the resource bundle version for the Italian (Italy) locale, UIResources_it. Note that there is no 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.

Note that text in the banner image and data retrieved from the database are not translated.

#myDemo Screen
myDemo.pageTitle=My Purchase Requests
myDemo.menubar.openLink=Open Requests
myDemo.menubar.pendingLink=Requests Awaiting customer

#myDemo Screen
myDemo.pageTitle=Miei Ticket
myDemo.menubar.openLink=Ticket Aperti
myDemo.menubar.pendingLink=Ticket in Attesa del Cliente

1. In the Applications window, double-click the project.
2. In the Project Properties dialog, select Resource Bundle to display the resource bundle options, as shown in Figure 34-2.

   Figure 34-2 Project Properties Resource Bundle dialog

   
3. If you want JDeveloper to automatically generate a default resource file, select Automatically Synchronize Bundle.
4. Select one of the following resource bundle file options:

   • One Bundle Per Project - configured in a file named <ProjectName>.properties.

   • One Bundle Per File - configured in a file named <FileName>.properties.

5. Select the resource bundle type from the dropdown list:

   • List Resource Bundle

   • Properties Bundle

   • XML Localization Interchange File Format (XLIFF) Bundle

6. Click OK.

JDeveloper generates one or more resource bundles of a particular type based on the selections that you make in the resource bundle options part of the Project Properties dialog, as illustrated in Figure 34-2. It generates a resource bundle the first time that you invoke the Select Text Resource dialog, as illustrated in Figure 34-1.

Assume, for example, that you select the One Bundle Per Project checkbox and the List Resource Bundle value from the Resource Bundle Type dropdown list. The first time that you invoke the Select Text Resource dialog, JDeveloper generates one resource bundle for the project. The generated resource bundle is a Java class named after the default project bundle name in the Project Properties dialog (for example, ViewControllerBundle.java).

JDeveloper generates a resource bundle as an .xlf file if you select the XML Localization Interchange File Format (XLIFF) Bundle option and a .properties file if you select the Properties Bundle option.

By default, JDeveloper creates the generated resource bundle in the view subdirectory of the project's Application Sources directory.

1. In the JSF page, select the component for which you want to write a runtime value.

   For example, select an af:inputText component.

2. In the Properties window, select Select Text Resource from the context menu that appears when you click the icon that appears when you hover over a property field to create a new entry in the resource bundle.

   The Select Text Resource entry in the context menu only appears for properties that support text resources. For example, the Label property of an af:inputText component.

3. Write the value that you want to appear at runtime in the Display Value input field, as illustrated in Figure 34-1.

   JDeveloper generates a value in the Key input field.

4. Optionally, write a description in the Description input field.

   Note:

   JDeveloper displays a matching text resource in the Matching Text Resource field if a text resource exists that matches the value you entered in the Display Value input field.

5. Click Save and Select.

JDeveloper writes the key-value pair that you define in the Select Text Resource dialog to the resource bundle. The options that you select in the resource bundle options part of the Project Properties dialog determine what type of resource bundle JDeveloper writes the key-value pair to. For more information, see What Happens When You Set Resource Bundle Options.

The component property for which you define the resource bundle entry uses an EL expression to retrieve the value from the resource bundle at runtime. For example, an af:inputText component's Label property may reference an EL expression similar to the following:

#{viewcontrollerBundle.Label1}

where viewcontrollerBundle references the resource bundle and Label1 is the key for the runtime value.

1. In the Applications window, right-click where you want to place the resource bundle file and choose New > From 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.

2. In the New Gallery, select General and then File, and click OK.
3. In the Create File dialog, enter a name for the file using the convention <name><_lang>.properties for the using the properties file or <name><_lang>.xlf for using the XLIFF file, where the <_lang> suffix is provided for translated files, as in _de for German, and omitted for the base language.

   Note:

   If you create 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.

4. 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 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 inherits 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 myDemo page is:

     myDemo.pageTitle=My Purchase 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>
     

5. After you have entered all the values, click OK.

1. In the Applications window, right-click where you want the file to be placed and choose New > From 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.

2. In the New Gallery, select General and then Java Class, and click OK.
3. 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.

4. Implement the getContents() method, which 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 How to Edit a Resource Bundle File. Example 34-3 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.

package sample;
 
import java.util.ListResourceBundle;
 
public class MyResources extends ListResourceBundle {
 
    @Override
    protected Object[][] getContents() {
        return contents;
    }
 
    static final Object[][] contents {
      {"button_Search", "Search"},
      {"button_Reset", "Reset"}
      };
}

1. From the main menu, choose Application > Edit Resource Bundles from the main menu.
2. 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 34-3, or click the Search icon to launch the Select Resource Bundle dialog if the resource bundle file you want to edit does not appear in the Resource Bundle dropdown list.

   Figure 34-3 Edit Resource Bundle Dialog

   
3. 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 34-4. Click OK.

   Figure 34-4 Select Resource Bundle Dialog

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

   Figure 34-5 Adding Values to a Resource Bundle

   

1. In the Applications window, expand the WEB-INF node and double-click faces-config.xml.
2. In the editor window, click the Overview tab.
3. In the overview editor, click the Application navigation tab.
4. In the Application page, in the Locale Config section, click Add to add the code for the locale, as shown in Figure 34-6.

   Figure 34-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_CN</supported-locale>
    </locale-config>

1. In the Applications window, expand the WEB-INF node and double-click faces-config.xml.
2. In the editor window, click the Overview tab.
3. In the overview editor, click the Application navigation tab.
4. In the Application page, in the Resource Bundle section, click Add and 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 34-7.

   Figure 34-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.summit.SummitADF</base-name>
      <var>res</var>
   </resource-bundle>
   

1. If your page is a JSP document, 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. The following example shows the encoding for a sample page.

   <?xml version='1.0' encoding='UTF-8'?>
   <jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
             xmlns:f="http://java.sun.com/jsf/core"
             xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
       <jsp:directive.page contentType="text/html;charset=UTF-8"/>
       <f:view>
   

2. 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. The following example shows the code for the View button on the myDemo page.

   <af:button text="#{res['myDemo.buttonbar.view']}"
                     . . . />
   

   Tip:

   If you type the following syntax in the source editor, JDeveloper displays a dropdown list of the keys that resolve to strings in the resource bundle:

   <af:button text="#{res.

   JDeveloper completes the EL expression when you select a key from the dropdown list.

3. You can also use the adfBundle keyword to resolve resource strings from specific resource bundles as EL expressions in the JSF page.

   The usage format is #{adfBundle[ bundleID ] [ resource_Key ]}, where bundleID is the fully qualified bundle ID, such as project.EmpMsgBundle, and resource_Key is the resource key in the bundle, such as Deptno_LABEL. Example 34-4 shows how adfBundle is used to provide the button text with a resource string from a specific resource bundle.

<af:button text="#{adfBundle['project.EmpMsgBundle'] ['Deptno_LABEL']}"

If you use an ADF 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.

An override bundle is a resource bundle with key-value pairs that differ from the base resource bundle that you want to use in a customizable application that you develop using the Oracle Metadata Services (MDS) framework. If you create an override bundle, you need to configure your application's adf-config.xml file to support the overriding of the base resource bundle. For example, if you have a base resource bundle with the name oracle.demo.CustAppUIBundle, you configure an entry in your application's adf-config.xml file, as shown in Example 34-5, to make it overrideable. Once it is marked as overriden, any customizations of that bundle will be stored in your customizable application's override bundle. The override bundle is maintained in both the default role in JDeveloper and in the customizable application. To avoid having to manage this override bundle in two locations, Oracle recommends that you:

• Create a separate resource bundle from the base resource bundle using JDeveloper's default role

• Add the key-value pairs that you want to override in your customizable application from the base resource bundle to this separate resource bundle

In the customizable application you pick these key-value pairs from the separate resource bundle. This makes sure that you do not create new key-value pairs in your customizable application's override bundle and that only the customizable application uses the override bundle.

For more information about the adf-config.xml file, see Configuration in adf-config.xml. For more information about creating customizable applications using MDS, see the "Customizing Applications with MDS" chapter of Developing Fusion Web Applications with Oracle Application Development Framework.

<?xml version="1.0" encoding="UTF-8" ?>
<adf-config xmlns="http://xmlns.oracle.com/adf/config"
 xmlns:config="http://xmlns.oracle.com/bc4j/configuration"
            xmlns:adf="http://xmlns.oracle.com/adf/config/properties">
...
<adf-resourcebundle-config xmlns="http://xmlns.oracle.com/adf/resourcebundle/config">
  <applicationBundleName>oracle/app.../xliffBundle/FusionAppsOverrideBundle</applicationBundleName>
  <bundleList>
    <bundleId override="true">oracle.demo.CustAppUIBundle</bundleId>
  </bundleList>
</adf-resourcebundle-config>
</adf-config>

JDeveloper generates a reference to the backing bean for the command component that you use to change the locale. Example 34-6 shows an example using the selectOneChoice component. JDeveloper also generates the required methods in the backing bean for the page. Example 34-7 shows extracts for the backing bean that correspond to Example 34-6.

<af:selectOneChoice label="Select Locale"
    binding="#{backingBeanScope.backing_changeLocale.soc1}"
    id="soc1">
	  <af:selectItem label="French" value="FR"
		 binding="#{backingBeanScope.backing_changeLocale.si1}"
		 id="si1"/>
          ...             
</af:selectOneChoice>

package view.backing;
 
...
import oracle.adf.view.rich.component.rich.input.RichSelectOneChoice;
 
public class ChangeLocale {
    ...
    ...
    private RichSelectOneChoice soc1;
	...
 
    ...
 
    ...
    public void setD2(RichDocument d2) {
        this.d2 = d2;
    }
 
    ...
 
    public void setSoc1(RichSelectOneChoice soc1) {
        this.soc1 = soc1;
    }
 
    public RichSelectOneChoice getSoc1() {
        return soc1;
    }
 
    public void setSi1(RichSelectItem si1) {
        this.si1 = si1;
    }
...
}

At runtime, an end user invokes the command component you configured to change the locale of the application. The backing bean stores the updated locale information. Pages where the locale attribute of the f:view tag reference the backing bean render using the locale specified by the end user.

The locale specified by the end user must be registered with your application. For more information about specifying a locale and associated resource bundles, see How to Register a Locale for Your Application.

1. In the Applications window, expand the WEB-INF node and double-click trinidad-config.xml.
2. In the Trinidad Configuration Elements page of the Components window, drag the localization element that you want to configure and drop it inside the <trinidad-config> element.
3. Enter the desired value.

<!-- 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>