10 Internationalizing Your Integrated Excel Workbook

This chapter describes internationalization issues to consider when developing an integrated Excel workbook, how to use resource bundles, and how to localize the integrated Excel workbook.

This chapter includes the following sections:

• Section 10.1, "About Internationalizing Your Integrated Excel Workbook"

• Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook"

• Section 10.3, "Localization in ADF Desktop Integration"

10.1 About Internationalizing Your Integrated Excel Workbook

ADF Desktop Integration provides several 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. This chapter also describes the use of resource bundles.

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

• Internationalized Data

  ADF Desktop Integration 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 system where the Excel workbook is used determines the format for dates, times, and numbers. These settings (formats and the locale of the system) may differ from the settings used by the Fusion web application. ADF Desktop Integration does not attempt to synchronize these settings, but it ensures that the data retains its integrity. ADF Desktop Integration 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 more information about internationalizing Fusion web applications, see the "Internationalizing and Localizing Pages" chapter in the Developing Web User Interfaces with Oracle ADF Faces.

10.1.1 Internationalizing Integrated Excel Workbook Use Cases and Examples

You can create integrated Excel workbooks for your internationalized Fusion web application. Designing your integrated Excel workbook as part of the internationalized Fusion web application helps in its easy adaptation to specific local languages and cultures. Using resource bundles and other components, you can configure your integrated Excel workbook for a specific local language or culture by translating text and adding locale-specific components at design time, and also at runtime. For more information, see Section 10.3, "Localization in ADF Desktop Integration."

Figure 10-1 shows an example of an integrated Excel workbook configured for the Japanese language.

Figure 10-1 Integrated Excel Workbook in Japanese

10.1.2 Additional Functionality for Internationalizing Integrated Excel Workbook

After you have internationalized your integrated Excel workbook, you may find that you need to add additional functionality to configure your workbook. Following are links to other functionalities that you can use:

• Security: Whether you are using a secure Fusion web application or not, you must be aware of security implementations in your integrated Excel workbook. For more information, see Chapter 11, "Securing Your Integrated Excel Workbook."

• Validating integrated Excel workbook: You can configure server-side and client-side validation for the Fusion web application and the integrated Excel workbook. For more information, see Chapter 12, "Adding Validation to an Integrated Excel Workbook."

• Publishing and deploying integrated Excel workbook: The final step after you design and validate your integrated Excel workbook is to publish and deploy it. For more information, see Chapter 14, "Deploying Your Integrated Excel Workbook."

10.2 Using Resource Bundles in an Integrated Excel Workbook

ADF Desktop Integration 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 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 megabyte. If you attempt to register more than twenty resource bundles or a resource bundle that exceeds 1 megabyte, ADF Desktop Integration writes a warning to the client-side log file and stops registration of additional resource bundles or resource bundle data after the 1 megabyte limit is reached.

For example, if resource bundle A measures 2 megabyte and resource bundle B measures 1 megabyte, ADF Desktop Integration 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 (Resources list) 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, EditCustomers-DT.xlsx in the Summit sample application for ADF Desktop Integration references the res resource bundle that has the following value for the Class property:

oracle.summitdi.resources.UIResources

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

By default, ADF Desktop Integration provides a reserved resource bundle that supplies string key values used by many component properties at runtime. When you enable an Excel workbook to integrate it with a Fusion web application, the reserved resource bundle is registered by default with the workbook. ADF Desktop Integration uses the value _ADFDIres to uniquely identify this resource bundle. Many EL expressions reference string values in this resource bundle.

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 Resources list using the Edit Resources dialog.

Before you begin:

It may be helpful to have an understanding of how to use resource bundles. For more information, see Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook."

You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 10.1.2, "Additional Functionality for Internationalizing Integrated Excel Workbook."

To register a resource bundle:

1. Open the integrated Excel workbook.

2. In the Workbook group of the Oracle ADF tab, click Workbook Properties.

3. In the Edit Workbook Properties dialog, click the browse (...) icon beside the input field for Resources to display the Edit Resources dialog shown in Figure 10-2.

   Figure 10-2 Edit Resources Dialog

   
   

4. 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-21.

Tip:

While registering a resource bundle class, do not include the file extension.

10.2.2 How to Override Resources That Are Not Configurable

The overridable resources contains several user-visible runtime strings that you cannot replace by configuring the properties of the ADF Desktop Integration components. Examples include the strings that appear in the default upload dialog illustrated in Figure 7-11.

To replace these user-visible runtime strings, you create a resource bundle in your Fusion web application that contains the string keys from the overridable resource that ADF Desktop Integration supports. Appendix E, "String Keys in the Overridable Resources" lists these string keys. You define values for the string keys listed in Appendix E to override in the resource bundle you create.

Before you begin:

It may be helpful to have an understanding of how to use resource bundles. For more information, see Section 10.2, "Using Resource Bundles in an Integrated Excel Workbook."

You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 10.1.2, "Additional Functionality for Internationalizing Integrated Excel Workbook."

To override resources that are not configurable:

1. Create a resource bundle in your Fusion web application.

   For information about creating a resource bundle, see the "Manually Defining Resource Bundles and Locales" section in the Developing Web User Interfaces with Oracle ADF Faces.

2. Define the string key values you want to appear at runtime in the resource bundle for the string keys listed in Appendix E, "String Keys in the Overridable Resources."

3. 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 E-1 describes the string keys in the overridable resources that ­ADF Desktop Integration supports. Supply an alternative value to the value listed in the English value column for each string key in the overridable resource. Note that override resources should not be used in component properties, they are only intended for the original usages.

10.2.3 What Happens at Runtime: Override Resources That Are Not Configurable

ADF Desktop Integration retrieves the values of string keys listed in Table E-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.4 What You May Need to Know About Resource Bundles

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

10.2.4.1 Resource Bundle Types

ADF Desktop Integration 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 Resource Bundles and Locales" section in the Developing Web User Interfaces with Oracle ADF Faces.

10.2.4.2 Caching of Resource Bundles in an Integrated Excel Workbook

ADF Desktop Integration 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-20.

10.2.4.3 EL Expression Syntax for Resource Bundles

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

#{res['StringKey']}

Note that ADF Desktop Integration does not support the following syntax:

#{res.StringKey}

10.3 Localization in ADF Desktop Integration

ADF Desktop Integration integrates several diverse sets of technologies. Each of these technologies provides various options for controlling the choice of natural human language when you localize your Fusion web application.

When the 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

For more information about localization in ADF Desktop Integration, see the "Oracle ADF Desktop Integration Localization whitepaper" on OTN at:

http://www.oracle.com/technetwork/developer-tools/adf/overview/index-085534.html

10.3.1 Configuring Fusion Web Application to Override Server-Side Locale Settings

The server-side localization comprises of ADF Desktop Integration server resources and Application Custom Resources. By default, ADF Desktop Integration uses the client-side Internet Explorer's language preference to determine server-side localization, but you can configure the Fusion web application to determine the server-side locale. To do that, you would need to create a user preference handler and register it by adding a UserPreferences.Handler initialization parameter for ADF Desktop Integration servlet.

10.3.1.1 How to Create a User Preference Handler

To create a user preference handler, create a public java class with a public method of java.util.Locale getLocale() signature that determines the ADF Desktop Integration server-side resources locale and returns the locale as a java.util.Locale object.

Example 10-1 shows a sample implementation of a user preference handler.

Example 10-1 Implementation of a User Preference Handler

public class CustomUserPrefsHandler 
{
  public Locale getLocale ()
  {
    UserPref info = (UserPref) 
           ADFContext.getCurrent().getSessionScope().map.get("User_Pref_Info");
    return info.getLocale();
  }
}

Note:

The handler class must have a constructor with no arguments, or uses the default Java constructor.

10.3.1.2 How to Register the User Preference Handler

To register a user preference handler, add the UserPreferences.Handler initialization parameter for ADF Desktop Integration in web.xml.

Before you begin:

It may be helpful to have an understanding of how to use resource bundles. For more information, see Section 10.3, "Localization in ADF Desktop Integration."

You may also find it helpful to understand functionality that can be added using other ADF Desktop Integration features. For more information, see Section 10.1.2, "Additional Functionality for Internationalizing Integrated Excel Workbook."

To register a User Preference Handler:

1. Open the web.xml file of your Fusion web application.

2. Add an initialization parameter to configure the user preference handler, as described in Table 10-2.

   Table 10-2 Configuring Locale User Preference

   Property	Value
   Name	Enter the name of the initialization parameter as follows UserPreferences.Handler
   Value	Complete path of the handler class.

   
   

3. Save the web.xml file.

4. Rebuild and restart your Fusion web application.

Example 10-2 shows the web.xml file with UserPreferences.Handler.

Example 10-2 web.xml File With UserPreferences.Handler

<servlet>
  <servlet-name>adfdiRemote</servlet-name>
  <servlet-class>
    oracle.adf.desktopintegration.servlet.DIRemoteServlet
  </servlet-class>
  <init-param>
    <param-name>UserPreferences.Handler</param-name>
    <param-value>myCompany.XYZ.CustomUserPrefsHandler</param-value>
  </init-param>
</servlet>

In Example 10-2, myCompany.XYZ.CustomUserPrefsHandler is the complete path of the handler class.