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 excel-language.png follows](img/excel-language.png)
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. Refer to the following table for internationalization/localization terms and definitions.
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. |
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
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.
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.
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:
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.
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 excel-choose-lang.png follows](img/excel-choose-lang.png)
Description of the illustration excel-choose-lang.png
Internationalization Notes
- The add-in installers are localized in over 30 languages. The installers automatically pick the Windows display language set in Windows Settings as the preferred language for add-in installation.
- 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.