Internationalization

17 Internationalization

Oracle Visual Builder Add-in for Excel includes several features that support distributing your integrated workbook to other locales and in other languages.

These features include:

A localized add-in
Support for a user's preferred regional data formats
Support for translating the integrated workbook using resource bundle files

If a business user opens an integrated workbook in the Chinese edition of Excel, the add-in displays all add-in labels such as icon labels, menu items, and buttons in the Chinese language.

Description of excel-language.png follows

Description of the illustration excel-language.png

If the workbook itself has been translated, the add-in can display Chinese text for strings such as business object field titles, the form label in a Form-over-Table layout, and workbook's help text.

Languages and Formats

Refer to this table for the settings used for Add-in, workbook, and REST languages and formats.

Area	Description	Controlled By	Notes
Add-in labels: language		Preferred Add-in Language
Add-in windows: text orientation	Add-in windows include designer windows, task panes, and pop-ups displayed to business users such as Search. Text orientation is left-to-right or right-to-left.	Preferred Add-in Language
Workbook labels: language	Workbook labels include column headers, help text, and so on. This does not include data from the services.	Preferred Add-in Language	If translations are available. See Manage Workbook Translations.
REST requests: accept-language header		Preferred Add-in Language	Results depend on the service.
Worksheet Cells: non-string formats		Cell styles and Windows Regional formats	See Appearance of an Integrated Excel Workbook.
Add-in windows: non-string formats	Add-in windows include designer windows, task panes, and pop-ups displayed to business users such as Search	Windows Regional formats
Add-in installer: language		Windows display language
Login web browser: language		Preferred Add-in Language	You may need to clear the browser cache when the preferred language is changed.

Refer to the following table for internationalization/localization terms and definitions.

Language or Format	Definition
Preferred Add-in Language	The preferred Add-in Language defaults to Excel's display language. Users may change the preferred language. See Change the Add-in's Language.
Windows Regional formats	The Windows Regional format is set from the Region page. Open Settings and search for "Region".
Windows display language	Windows display language is set from the Language page. Open Settings and search for "Language".

Add-in Localization

The add-in is available in over 30 languages. By default, it automatically detects the user's preferred language from Microsoft Excel and uses that language where possible. When a business user opens an integrated workbook in Excel, everything in the add-in is displayed in the desired language—from the Oracle Visual Builder ribbon's icon labels and menu commands to add-in windows such as the Status Viewer and the Network Monitor.

The date, date-time, and number formats used by the add-in are also culture-sensitive. These data format types depend on the business user's preferences as defined in the Windows region settings. So a US user will see US dates and a French user will see French dates. See Appearance of an Integrated Excel Workbook.

REST Service Localization

The add-in also supports retrieving localized text from your REST service if the service supports it.

Every request the add-in makes to the service includes the accept-language header. The language setting specified for Excel is used for requests, including the describe requests that fetch the initial business object field titles.

Workbook Translations

The add-in also supports localizing text strings in the integrated workbook, such as business object field titles, variable names, and help text for fields and finders. See Manage Workbook Translations.

Manage Workbook Translations

If you plan to distribute your integrated workbook in another language, you can extract the base language file from the workbook and send it for translation. This translation file includes workbook-specific text strings such as field titles and help text for you to translate into your target language.

Once translated, simply import translation files for each required language through the add-in. When you distribute your localized workbook to your business users, the add-in displays the translated strings if the preferred language is available.

Translate Your Integrated Workbook

To translate your integrated workbook into another language, extract the workbook’s translation file using Oracle Visual Builder Add-in for Excel and send it for translation. When you get the translated files back, import them into your workbook.

The extracted translation file only includes text strings that are currently used in your workbook’s layouts. Field titles, variable names, and help text for fields and finders that are not in use are not included in the translation file. If you change the configuration of the workbook, extract the translation file again to pick up any new strings.

Note:

Fields included dynamically from polymorphic business objects are not included in the translation file.

To translate your workbook:

Open the workbook you want to translate.
Click the Oracle Visual Builder tab from the Excel ribbon.
Choose Manage Translations from the Advanced menu to open the Translation Manager.

Description of the illustration translation-manager.png
From the Translation Manager, click Extract and save the translation JSON file to your local drive.
Submit the file to your translation team for translation.

When creating a translation file for a specific locale, your translators will translate the strings and set the locale for the file before sending it back.
When you get the translated files back, open the Translation Manager and click Import.
From the Import Translations dialog, navigate to the location of the translated file or files, then select them.
You can use the Shift and Ctrl keys to select multiple files for import.
Click Open to import the files.
Save and publish the workbook before distributing it to your business users.

Note:

If business users have a different add-in language setting than the one used for the integrated workbook, they are prompted to redraw all layouts when they open the workbook for the first time. If they choose to redraw the workbook, any data and changes to the layouts are discarded.

Clearing all layouts when the language changes is recommended since some data, such as lists of values, may be language-sensitive. Downloading in one language and uploading in a different language may not succeed.

If they choose to skip the redraw, they can manually redraw the workbook later using either the Clear Layout or Download Data icons from the Oracle Visual Builder tab.

About Translation Files

A translation file is a JSON file in Application Resource Bundle (ARB) format that stores the workbook’s translatable strings for a given language. Each translatable string is stored in a key-value pair and includes additional attributes that help you and your translators understand the context.

Here’s an example of an entry for a Business Object field, "First Name", in an Employees workbook:

    "50689d80-c95c-4353-9032-cf4251d4abec.Title": "First Name",
    "@50689d80-c95c-4353-9032-cf4251d4abec.Title": {
        "context": "layout: TBL731992735, business object: Employees, field: firstName",
        "description": "The field title used as a column header or a form label.",
        "source_text": "First Name"
    },

The first line contains the translation key (50689d80-c95c-4353-9032-cf4251d4abec.Title) and translatable string value (First Name) separated by a colon. The key is a unique ID for the string in the workbook. The value is the string that your translator will translate into the target language, for example, “Prénom” for French.

Keep in mind that translation keys are different for each workbook. Two workbooks may have the same translatable string—say, “First Name”—but these strings will have different keys. For this reason, you can’t share translation files between workbooks.

Each key-value pair also includes some additional attributes that help translators understand how to translate the text string: context, description, and source_text. The context and description provide information about where in the workbook the string is used.

The source text is the original value for the string in the base language. In the base language file, the source text is always the same as the value. In the translated files, the value is translated but the source value remains unchanged. The source text value allows someone to inspect the translations and compare the strings easily.

The translation file also includes some global attributes (prefixed with @@) that apply to the translation file as a whole. Here is an example of the global attributes (locale, context, and last_modified) for an Employees workbook:

{
    "@@locale": "en-US",
    "@@context": "Integrated Excel Workbook: employees.xlsx",
    "@@last_modified": "2022-12-07T15:19:16.8664548-05:00",

The locale attribute provides the language code for the text strings stored in this file; in this case U.S. English (en-US). This is the value that you’ll need to change to indicate the new language when you translate the file. For Brazilian Portuguese, you’d use the value “pt-BR”. The locale attribute requires an IETF BCP 47 language tag.

On import, the add-in relies on the value of @@locale to identify the language for the translation file. The file name is not used for this purpose.

Change the Add-in's Language

You can change the language that the Excel add-in uses. Do this if you want to evaluate your integrated workbook with different languages.

To change the add-in language:

In Excel, click the Oracle Visual Builder tab.
Choose Select Language from the Advanced menu.
From the Add-in Language list that appears, select the language you want to use. The list displays the languages that the add-in supports.
Click OK.
Clear the embedded browser cache. See Clear the Embedded Browser Cache.
Restart Excel to make your changes take effect.

The add-in's user interface elements (Download Data and so on) now use the language you selected. If the workbook has been localized for the preferred language, the add-in uses that localization as well.

If the preferred language uses a right-to-left writing system, the add-in's windows appear in right-to-left mode. The language that Excel uses remains unchanged, as does the format used for dates, times, and numbers. See Excel or Windows options to change Excel’s language and formats for dates, times, and numbers. See also Natural Language Support.

During development, the add-in displays localized text for read-only property values in the design editors and dialogs. If a property is editable, the add-in displays the default language (or "base" language) value instead. When working in a language other than the base language, you may see localized values in some places and base values in others. When editing a property in the designers, you edit the base value. There is no change to the translated value already imported regardless of the current preferred culture.

The language that you choose for the add-in language is stored in a local file in the Windows user profile. You can select the Use Excel’s Language Setting option in the Add-in Language drop-down list to remove this setting for the current user.

Description of excel-choose-lang.png follows

Description of the illustration excel-choose-lang.png

Internationalization Notes

Some login pages used by some services may include a language selector. The language selector may have some influence over the login page for that service. However, it has no influence over the language choices for the add-in in general.
If you change Windows Regional formats, you must restart Excel for the add-in to use the new settings.