11 Internationalizing Your Integrated Excel Workbook

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:

• About Internationalizing Your Integrated Excel Workbook

• Using Resource Bundles in an Integrated Excel Workbook

• Known Issues and Limitations

• Localization in ADF Desktop Integration

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 runtime.

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 business 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. See Working with Styles.

For information about internationalizing Fusion web applications, see Internationalizing and Localizing Pages in Developing Web User Interfaces with Oracle ADF Faces.

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, you can configure your integrated Excel workbook for a specific local language or culture by providing translations of the user-visible strings that appear to business users at runtime. See Localization in ADF Desktop Integration.

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

Figure 11-1 Integrated Excel Workbook in Japanese

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. The following sections describe other functionality 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. See Securing Your Integrated Excel Workbook.

• Validating integrated Excel workbook: You can configure server-side and client-side data entry validation for the Fusion web application and the integrated Excel workbook. See Adding Validation to Your 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. See Deploying Your Integrated Excel Workbook .

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. You can use JDeveloper to create and manage resource bundles in your Fusion web application.

You can register multiple resource bundles with an integrated Excel workbook. At runtime, ADF Desktop Integration downloads only those string key values that the integrated Excel workbook uses from registered resource bundles during workbook initialization. Assume, for example, that you register resource bundle A with an integrated Excel workbook that references three string key values from resource bundle A. During workbook initialization, ADF Desktop Integration downloads the three string key values that the workbook references from resource bundle A.

Note:

If you register more than 20 resource bundles with an integrated Excel workbook, ADF Desktop Integration logs a warning message. For information about add-in logging, see About Add-in Log Files.

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 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. ADF Desktop Integration uses the value _ADFDIres to uniquely identify this resource bundle. Many EL expressions reference string values in this resource bundle.

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. See Using Resource Bundles in an Integrated Excel Workbook.

You may also find it helpful to understand the functionality that can be added using other ADF Desktop Integration features. See 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 11-2.

   Figure 11-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 17-17.

Tip:

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

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

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

• Properties bundle (.properties)

• List resource bundle (.rts)

• Xliff resource bundle (.xlf)

For information about resource bundles, see Manually Defining Resource Bundles and Locales in Developing Web User Interfaces with Oracle ADF Faces.

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 business user closes and reopens the workbook so that it retrieves the modified value from the Fusion web application. For information about the ClearAllData workbook action, see Table 17-16.

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}

Known Issues and Limitations

This topic lists the known issues and limitations when internationalizing your integrated Excel workbook.

• Do not change the list separator in Windows Settings. The comma character is expected.

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 business 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.

Note:

Microsoft has a concept of "culture", whereas Java has a concept of "locale". These concepts, while not identical, are roughly equivalent. While these concepts also apply to settings for culture-sensitive data formatting, such as date and number formatting, this topic only deals with language and translation.

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

Figure 11-3 Localization in ADF Desktop Integration

Description of "Figure 11-3 Localization in ADF Desktop Integration"

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

Table 11-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 the Language page in Windows Settings.
Microsoft Excel	Microsoft Excel language settings
Web pages displayed in ADF Desktop Integration Dialog actions	Usually controlled by Microsoft Excel's Language Preferences
ADF Desktop Integration add-in resources	Microsoft Excel language settings
ADF Desktop Integration server resources	Microsoft Excel language preferences
ADF Desktop Integration custom resource bundles	Microsoft Excel language preferences
ADF Desktop Integration installer	Windows display language

Microsoft Language Settings

Microsoft has one set of culture settings available at the operating system level and a separate set for Excel. You can, therefore, configure Windows to run using Spanish and, on the same machine, configure Excel to use German.

To open the Language page in Windows 10, select Start > Settings > Time & language > Language.

Access Excel language settings by selecting File > More > Options > Language.

Note:

The add-in uses the first available language in the Office display language list. The language set in the Office authoring languages and proofing list is not relevant for the add-in.

Note:

The configuration of these settings is not available to all users on all editions and versions. This guide does not address how to set up localized and/or multi-lingual versions of these third-party products.

Web Browser Language Settings

The add-in uses Microsoft WebView2 to display web pages within Excel. If a web page provider such as a web application provides localized versions of these pages, it uses the Excel language preference to determine which version to display. The preferred browser language setting is typically transmitted to the server in the HTTP headers using the Accept-Language header field.

If the user changes the language preference used by Excel, it may be necessary to clear the embedded web browser cache. See Delete the WebView2 Browser Cache.

Note:

The add-in has no control over these preferences nor over whether or how web applications respect them.

ADF Desktop Integration Client Resources

The add-in contains a number of translatable resources for displaying user-visible texts at runtime in the user’s preferred language. The texts include (client-side) error messages as well as labels, prompts, and titles used in add-in dialogs displayed at runtime. These texts have been localized into the standard Oracle runtime languages.

The add-in uses the Excel preferred language for client-side runtime translations. If the preferred language is not available, the add-in falls back to the default resource bundle which is English.

ADF Desktop Integration Server Resources

The add-in fetches some messages from the web application. These messages include all server-side error messages, as well as label hints for attribute bindings.

For a more consistent choice of language for translations, the add-in’s client component automatically includes Excel language preferences in its server requests using the Accept-Language header field. The add-in's server component uses this header field when attempting to localize these server messages.

The add-in uses the first value from the Accept-Language header field. If this language is not available, the add-in falls back to English. Secondary languages from Accept-Language are not considered.

The add-in also provides application developers with a mechanism to override this behavior by supplying a custom user preference handler to control the choice of locale used for server-side resources. See Configuring Fusion Web Application to Override Server-Side Locale Settings.

ADF Desktop Integration Custom Resource Bundles

The add-in provides developers with the ability to register custom resource bundles with each workbook. Developers may then use translation resources from these bundles in the add-in UI component configuration, such as for a ribbon command label. The add-in server component requests a localized version of each custom resource bundle. The language rules for this translation are the same as for ADF Desktop Integration Server Resources.

Mixed Language Configurations

Most users use consistent settings for each element of the technology stack. As a result, these users usually see messages in the same language.

Some elements of the technology stack may not provide translations for a given language. In this case, that element falls back to a secondary or default language or according to rules designed by the provider of that element.

If different elements are configured for different language preferences, the user sees a mixture of languages. It is possible to create a configuration where multiple languages are visible at the same time. Each element of the technology stack tries to adhere to the user’s explicit preferences.

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 Microsoft Excel's user interface 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.

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 11-1 shows a sample implementation of a user preference handler.

Note:

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

Example 11-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();
  }
}

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. See Localization in ADF Desktop Integration.

You may also find it helpful to understand the functionality that can be added using other ADF Desktop Integration features. See 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 11-2.

   Table 11-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 11-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>

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

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