16 Internationalization
Oracle Visual Builder Add-in for Excel includes several features that support distributing your integrated workbook to other locales and in other languages.
- A localized add-in
- Support for localized REST service text
- Support for translating the integrated workbook using JSON files
If a business user opens a integrated workbook in Chinese, the add-in displays all add-in labels such as icon labels, menu items, and buttons in the Chinese language. If the REST service has been localized into Chinese, the add-in retrieves and displays Chinese text for business object fields, service response messages, and so on.
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 fields that have not been translated in the service description, the form label in a Form-over-Table layout, and workbook's help text.
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. Localized text strings include field titles, row finder names, custom action results, and error messages.
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.
Note:
If your workbook doesn't have a localized translation file for your language, you can use the Refresh Field Titles command to fetch localized field titles from the REST service for your integrated workbook, if your language is supported. You should not use this command if the workbook includes a translation file for your language. See Refresh All Field Titles.
Because business object field titles are owned by the service, contact the service owner for any missing translations or languages or use the translation process covered in Manage Workbook Translations.
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:
- Choose Manage Translations from the Advanced menu to open the Translation Manager.
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 workbook is not localized but the REST service provides localized text in your language, the add-in can retrieve localized text based on your language setting. Use the Refresh Field Titles command to update your workbook.
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 the illustration excel-choose-lang.png
Refresh All Field Titles
You can refresh all field titles in your integrated workbook if, for example, you want to display field titles in another language.
Imagine, an invoices workbook was configured and tested with English as the current language, so all field titles are in English and this information is saved with the workbook. Now imagine this workbook was sent to someone in France for data entry. That person has Windows and Excel configured for French, and she would like to see field titles in French as well. Refreshing the field titles enables this data entry operator to see field titles in French.
When you refresh field titles, Oracle Visual Builder Add-in for Excel fetches the service description for each business object, if possible, and refreshes all of the business object's field titles. If a catalog has any business objects that are not used in a layout, the unused business objects are not refreshed. When it finishes, any affected layouts are redrawn automatically.
The add-in uses saved metadata path information to access the service description document. For older workbooks or catalogs with a service type of "other", the metadata path settings are empty. In this case, the add-in sets the metadata path to the default values for the service framework type before starting the refresh. These settings can be viewed from the General page of the Business Object Editor.
Before you begin, upload any pending changes to your workbook. If you don't, your pending changes will be discarded during the refresh.
Caution:
A refresh wipes out any local changes made to field titles using the Business Object Field Editor. Make a backup copy of the workbook before performing a refresh of your field titles.To refresh the field titles in your workbook:
When the refresh is complete, the add-in displays the results of the refresh in the Status window.
If the add-in is unable to fetch the service description for a given business object, the business object is skipped and the details are logged. To troubleshoot the error, open the log console and repeat the process to discover the cause. See Log Console.
If the error is caused by incorrect or missing path details, consult with the REST API owner and update the path information, including the base path and metadata path settings, as required. See Manage Metadata Path Information.
Note:
When the add-in fetches the service description from the metadata path, it includes the accept-language header as described in Natural Language Support. A given service may or may not have translations for the requested language. For any missing translations, contact the owner of the service.
Oracle REST Data Services (ORDS) do not provide localized service descriptions.