Deploying a Custom Skin File in a JAR File

21 Internationalizing and Localizing Pages 21-1 21 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 21.1, Introduction to Internationalization and Localization of ADF Faces Pages ■ Section 21.2, Using Automatic Resource Bundle Integration in JDeveloper ■ Section 21.3, Manually Defining Resource Bundles and Locales ■ Section 21.4, Configuring Pages for an End User to Specify Locale at Runtime ■ Section 21.5, Configuring Optional ADF Faces Localization Properties

21.1 Introduction to Internationalization and Localization of ADF Faces Pages

Internationalization 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 20, Customizing the Appearance Using Styles and Skins . 21-2 Web User Interface Developers Guide for Oracle Application Development Framework 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. For instance, if the title of this page is My Purchase Requests, instead of having My Purchase 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 21–1 . Example 21–1 Resource Bundle Element in JSF Configuration File resource-bundle varresvar base-nameresources.UIResourcesbase-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 myDemo.pageTitle key in that resource bundle, as shown in Example 21–2 . Example 21–2 Component Text Referencing Resource Bundle af:panelPage text={res[myDemo.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 21–3 shows the keys for the myDemo page. Example 21–3 Resource Bundle Keys for the myDemo Page Displayed in English myDemo Screen myDemo.pageTitle=My Purchase Requests myDemo.menubar.openLink=Open Requests myDemo.menubar.pendingLink=Requests Awaiting customer myDemo.menubar.closedLink=Closed Requests myDemo.menubar.allRequests=All Requests myDemo.menubar.newLink=Create New Purchase Request 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. Internationalizing and Localizing Pages 21-3 myDemo.selectAnd=Select and myDemo.buttonbar.view=View myDemo.buttonbar.edit=Edit Note that text in the banner image and data retrieved from the database are not translated. Example 21–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 21–4 Resource Bundle Keys for the myDemo Page Displayed in Italian myDemo Screen myDemo.pageTitle=Miei Ticket myDemo.menubar.openLink=Ticket Aperti myDemo.menubar.pendingLink=Ticket in Attesa del Cliente myDemo.menubar.closedLink=Ticket Risolti myDemo.menubar.allRequests=Tutti i Ticket myDemo.menubar.newLink=Creare Nuovo Ticket myDemo.selectAnd=Seleziona e myDemo.buttonbar.view=Vedere Dettagli myDemo.buttonbar.edit=Aggiorna

21.2 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 Automatically Synchronize Bundle in the Project Properties dialog, as described in Section 21.2.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. You 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 21–1 . Figure 21–1 Adding Text to a Component ■ From the text input window, choose Select Text Resource to launch the Select Text Resource dialog, as shown in Figure 21–2 . 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. 21-4 Web User Interface Developers Guide for Oracle Application Development Framework Figure 21–2 Select Text Resource Dialog ■ 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.

21.2.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: 1. In the Application Navigator, double-click the project.

2. In the Project Properties dialog, select Resource Bundle to display the resource

bundle options, as shown in Figure 21–3 . Note: JDeveloper only writes strings to a resource bundle that you enter using one of the previously-listed methods.