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.

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.