What are Translation Resources?

To ease with translation, all strings in an App UI—such as headings, labels, and messages—can be stored in a separate external file, rather than hard-coded in the App UI. This means you can translate the App UI by simply downloading this file, translating it, and uploading a newly translated file.

During runtime, the App UI uses the language file corresponding to the user’s browser language setting unless you set a different locale for it programmatically.

Translation Bundles and Files

A translation bundle is a set of translation files that has one file for each supported language. Typically, each file contains all the text strings in an App UI in the supported language.

Your extension may include one or more translation bundles. Let’s say you are extending an Oracle Cloud App, like Digital Sales. Your extension will contain one translation bundle for Digital Sales, as well as one for the Unified Application, which is the basis for all Oracle Cloud Applications. If you also created your own App UI within this same extension, you'd have yet a third translation bundle, this time for the text strings for your new UI components.

Translatable Strings

A translation file is a JSON file that stores the App UI’s translatable strings for a given language. These strings are stored in key-value pairs, where the translation key is a unique ID in the bundle for the translatable string. It is this bundle/key that you use to bind a UI component’s text property value to the string in the translation file.

Let’s say you have a number of fields and lists for entering or selecting the city for an employee or site. Rather than setting each component’s text property to “City”, you can add the string to the JSON file and instead set the component’s text property to reference the string’s key.

Here’s an example of a key-value pair in a JSON file for the string, “City”:

"siteCity": "City",
"@siteCity": {
  "description": "The name of the city where the office or employee is located",
}

In this example, the key is siteCity and the translatable string is City. The entry also includes a description field that helps your translators understand the context for the translatable string. For example, without a description, your translators may have difficulty telling if “Title” refers to personal title, such as “Ms” or “Mr”, or to a professional title, such as “Senior Software Developer” or “Director of Marketing”. A brief description here can remove any uncertainty.

You can reuse a translation key in multiple places and, if required, modify the key value to update all instances at once. Using our previous example, you might use the translation key siteCity on a Contact page and on the employee Profile page. If you later decide to use "Municipality" instead of "City", you can change the value of the key to update what gets displayed on the Contact and Profile pages.

Let's take a look at how this all fits together in practice. For example, you might decide to include a text field for the employee's city on your Profile page. Initially, you set the "label-hint" property to "City".

If you look at the code for this page, you'll see that the input text field includes a “label-hint” property set to “City”:

<oj-input-text label-hint="City" class="oj-flex-item oj-sm-12 oj-md-6"></oj-input-text>

If you decide to use the siteCity translation key for the field's “label-hint” property, you'll get this code instead:

<oj-input-text label-hint="[[$translations.extensionBundle.siteCity()]]" class="oj-flex-item oj-sm-12 oj-md-6"></oj-input-text>

In this case, $translations.extensionBundle.siteCity() is a JavaScript function where:

$translations indicates that this refers to a translation;
extensionBundle is the bundle where the key is stored;
siteCity is the translation key; and
() is the arguments list you can use to pass parameters to the function. In this case, the arguments list is empty.