10 Internationalizing Your Integrated Excel Workbook

This chapter describes internationalization issues to consider when developing an integrated Excel workbook.

This chapter includes the following sections:

Section 10.1, "Introduction to Internationalizing Your Integrated Excel Workbook"
Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook"
Section 10.3, "Localization in Oracle ADF Desktop Integration"

10.1 Introduction to Internationalizing Your Integrated Excel Workbook

The Oracle ADF Desktop Integration module provides a number of features that allow you to deliver integrated Excel workbooks as part of an internationalized Fusion web application. One of the principal features is the use of resource bundles to manage the localization of user-visible strings that appear in Oracle ADF components at design time. It also uses resource bundles to manage the user-visible strings that appear in these components at runtime. The use of resource bundles is described in more detail later in this chapter.

Note the following points about internationalization and localization in an integrated Excel workbook:

Internationalized Data

The Oracle ADF Desktop Integration module supports both single- and double-byte character sets. It marshals data transmitted between an Excel worksheet and a Fusion web application into XML payloads. These XML payloads use UTF-8 encoding with dates, times, and numbers in canonical formats.
Locale

The locale of the machine where the Excel workbook is used determines the format for dates, times, and numbers. These settings (formats and the locale of the machine) may differ from the settings used by the Fusion web application. The Oracle ADF Desktop Integration module does not attempt to synchronize these settings, but does make sure that data retains its integrity. The Oracle ADF Desktop Integration module does not provide a mechanism for end users to change the language or display settings of the Oracle ADF components in an integrated Excel workbook at runtime.

When configuring or applying styles to ADF components in an integrated Excel workbook, configure or choose styles that are locale-sensitive. For more information, see Section 9.2, "Working with Styles".

For information about internationalizing Fusion web applications, see the "Internationalizing and Localizing Pages" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

10.2 Using Resource Bundles in an Integrated Excel Workbook

The Oracle ADF Desktop Integration module uses resource bundles to manage user-visible strings that appear in the ADF components of an integrated Excel workbook at design time and runtime. JDeveloper stores resource bundles in the Oracle ADF Desktop Integration project.

You can register up to twenty resource bundles containing string values you define with an integrated Excel workbook. A resource bundle must not exceed 1 MB in size. If you attempt to register:

More than twenty resource bundles
A resource bundle that exceeds 1 MB in size

the Oracle ADF Desktop Integration module writes a warning to the client-side log file and stops registration of additional resource bundles or resource bundle data after the 1 MB limit is reached. For example, if resource bundle A measures 2 MB and resource bundle B measures 1 MB, the Oracle ADF Desktop Integration module registers the first megabyte of data in resource bundle A and all of the data in resource bundle B. For information about client-side logging, see Section C.3.2, "About Client-Side Logging".

The Resources workbook property specifies what resource bundles an integrated Excel workbook can use. This property specifies an array of resource bundles (ResourceBundle[] Array) in the integrated Excel workbook. Each element in the array has a property that uniquely identifies a resource bundle (Alias) and a property that identifies the path to the resource bundle in the JDeveloper desktop integration project (Class). For example, EditPriceList-DT.xlsx in the Master Price List module references the res resource bundle that has the following value for the Class property:

oracle.fodemo.masterpricelist.resources.UIStrings

More information about the Resources workbook property can be found in Section A.12, "Workbook Actions and Properties".

By default, the Oracle ADF Desktop Integration module provides a reserved resource bundle that supplies string key values used by many component properties at runtime. When you convert an Excel workbook to integrate it with a Fusion web application, the reserved resource bundle is registered by default with the workbook. The Oracle ADF Desktop Integration module uses the value _ADFDIres to uniquely identify this resource bundle. Many EL expressions reference string values in this resource bundle. For example, the following EL expression is the default value of the Label property for the Login menu item in WorkbookMenuItems:

#{_ADFDIres['TOOLBAR_MENU_CMD_LOGIN']}

where _ADFDIres identifies the reserved resource bundle and TOOLBAR_MENU_CMD_LOGIN is the key that identifies the string (Login...) in the resource bundle to use at runtime for the Login menu item.

If you register another resource bundle, you can replace default string key values assigned from the _ADFDIres resource bundle to many of the ADF component properties.

10.2.1 How to Register a Resource Bundle in an Integrated Excel Workbook

You register a resource bundle by adding an element to the ResourceBundle[] Array using the ResourceBundle Collection Editor.

To register a resource bundle:

In the Excel workbook, click Workbook Properties in the Oracle ADF Desktop Integration Designer to display the Edit Workbook Properties dialog box.
Click the ellipsis button (...) beside the input field for Resources to display the ResourceBundle Collection Editor shown in Figure 10-1.

Figure 10-1 ResourceBundle Collection Editor
Specify values for the resource bundle and then click OK.

For information about the values to specify for a resource bundle, see the entry for Resources in Table A-18.

10.2.2 How to Replace String Key Values from the Reserved Resource Bundle

You can replace a string key from the reserved resource bundle by specifying a string key from a resource bundle that you registered with the integrated Excel workbook.

To replace a string key value from the reserved resource bundle:

Click Workbook Properties in the Oracle ADF Desktop Integration Designer.
Click Toolbar Menu and click the ellipsis button (...) beside the input field for WorkbookMenuItem[] Array.
Click the ellipsis button (...) beside the input field for the Label property to display the expression builder.
Write an EL expression to retrieve the string key value you want to display at runtime.

Figure 10-2 shows an example where the EL expression references a string key (key_Login) defined in a resource bundle (res). This EL expression replaces the default EL expression that references a string key in the _ADFDIres resource bundle.

Figure 10-2 Expression Builder Replacing a Key String Value
Click OK.

10.2.3 How to Override the Reserved Resource Bundle

The reserved resource bundle contains a number of user-visible runtime strings that you cannot replace by configuring the properties of the Oracle ADF Desktop Integration module components. Examples include the strings that appear in the default upload dialog box illustrated in Figure 7-5.

To replace these user-visible runtime strings, you create a resource bundle in your Fusion web application that contains the string keys from the reserved resource bundle that the Oracle ADF Desktop Integration module supports for override. Appendix F, "String Keys in the Reserved Resource Bundle" lists these string keys. You define values for the string keys listed in Appendix F that you want to override in the resource bundle you create.

To override the reserved resource bundle:

Create a resource bundle in your Fusion web application.

For information about creating a resource bundle, see the "Defining Locales and Resource Bundles" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.
Define the string key values you want to appear at runtime in the resource bundle for the string keys listed in Appendix F, "String Keys in the Reserved Resource Bundle".
Set _ADFDIres as the value of the Alias property when you register the resource bundle you created in Step 1.

For information about how to register a resource bundle, see Section 10.2.1, "How to Register a Resource Bundle in an Integrated Excel Workbook".

Table F-1 describes the string keys in the reserved resource bundle that the Oracle ADF Desktop Integration module supports for override. Supply an alternative value to the value listed in the English value column for each string key in the reserved resource bundle that you want to override.

10.2.4 What Happens at Runtime When You Override the Reserved Resource Bundle

The Oracle ADF Desktop Integration module retrieves the values of string keys listed in Table F-1 that you defined in the resource bundle you created. It retrieves the values of other string keys that you did not define in the resource bundle you created from the reserved resource bundle.

10.2.5 What You May Need to Know About Resource Bundles

See the following sections for additional information about resource bundles in an integrated Excel workbook.

Resource Bundle Types

The Oracle ADF Desktop Integration module supports use of the following types of resource bundle:

Properties bundle (.properties)
List resource bundle (.rts)
Xliff resource bundle (.xlf)

For more information about resource bundles, see the "Manually Defining Locales and Resource Bundles" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.

Caching of Resource Bundles in an Integrated Excel Workbook

The Oracle ADF Desktop Integration module caches the values of string keys from the resource bundles that an integrated Excel workbook retrieves when it first connects to the Fusion web application. If you change a string key value in a resource bundle after an integrated Excel workbook has cached the previous value, the modified value does not appear in the workbook unless the ClearAllData workbook action is invoked and the end user closes and reopens the workbook so that it retrieves the modified value from the Fusion web application. For more information about the ClearAllData workbook action, see Table A-17.

EL Expression Syntax for Resource Bundles

The Oracle ADF Desktop Integration module requires that you enclose the string key name in EL expressions using the [] characters, as in the following example:

#{res['StringKey']}

The Oracle ADF Desktop I ntegration module does not support the following syntax:

#{res.StringKey}

10.3 Localization in Oracle ADF Desktop Integration

The Oracle ADF Desktop Integration module integrates several diverse sets of technologies. Each of these technologies provides various options for controlling the choice of natural human language when localization occurs.

When an end user interacts with an integrated Excel workbook, various elements are involved. Each of these elements has its own set of supported languages and resource translations. In such a scenario, the translation of language is the responsibility of the respective publisher.

Table 10-1 presents a summary of elements involved and their role in translation:

Table 10-1 Summary of Localization

Area subject to localization	Determination of language to use
Microsoft operating system	Operating system language settings. You can choose the language through Regional Settings on Control Panel.
Microsoft Office	Microsoft Office language settings
Web pages displayed in ADF Desktop Integration Dialog actions	Usually controlled by Microsoft Internet Explorer's Language Preferences.
ADF Desktop Integration client resources	Microsoft Office language settings
ADF Desktop Integration server resources	Microsoft Internet Explorer language preferences
ADF Desktop Integration custom resource bundles	Microsoft Internet Explorer language preferences

Figure 10-3 illustrates how various elements involved in a Fusion web application play their role in translation.

Figure 10-3 Localization in ADF Desktop Integration

Figure illustrates localization in ADFdi.

For more information about localization in ADF Desktop Integration, see "Oracle ADF 11g Desktop Integration Localization Whitepaper" on OTN at:

http://www.oracle.com/technology/products/jdev/11/collateral/adfdi_localization.pdf