Translations

Container Compatibility

This feature is compatible with version 4.20 and later of the JourneyApps Container.

Edit Translations Files

A language can be added to your app via the Add language action in OXIDE. This initializes a YAML file for the language, which stores the language's translation strings.

The following languages are currently supported:

• Arabic (since version 4.86.1 of the JourneyApps Runtime - see the developer notes section below).

• English (US) - default

• Chinese (Simplified)

• Dutch

• French

• German

• Italian

• Japanese

• Korean

• Portuguese (Brazil)

• Russian

• Spanish (Latin America)

• Swedish

YAML files can be accessed in OXIDE via the command palette, or in the Languages section in the App Tree panel.

An example translation file is given below:

# translations/es-419.yml
Name: Español
NameShort: Esp.
common:
months:
January: Enero
February: Febrero
March: Marzo
April: Abril
May: Mayo
June: Junio
July: Julio
August: Agosto
September: Septiembre
October: Octubre
November: Noviembre
December: Diciembre
greeting: ¡Hola {name}!

YAML oddities

YAML has some standards that you might run into:

1. Words such as YES, yes, No, etc are reserved and will break your app if you use them

2. The colon (:) is a reserved symbol, so your translation needs to be surrounded by quotes if you have a colon in your string

3. Given the above, it's HIGHLY recommended that you always enclose your strings in quotes

4. Quotes themselves are reserved characters in YAML and need to be escaped using a quote. This means you may end up with a translation entry like this:

view.path.string: 'YAML has its quirks and it''s important to be aware of them.'

Call Translation Resources

Strings can be translated using the JavaScript/TypeScript t(key, params) function. The t function accepts a translation key and an optional string interpolation hash. The current locale is used to find the appropriate translation. If a translation cannot be found then key will be returned and a warning logged to the console.

Translations from JavaScript

Example view XML:

main.view.xml

<view title="JS Translations">
    <var name="name" type="text" />
    <var name="month" type="text" />
    <var name="greeting1" type="text" />
    <var name="greeting2" type="text" />

    <text-input bind="name" required="false" />
    <info>month: {month}</info>
    <info>greeting1: {greeting1}</info>
    <info>greeting2: {greeting2}</info>
    <button label="Demo Translations" on-press="$:foo()" validate="false" />
</view>

Example view JavaScript:

main.js

function foo() {
    view.month = t("common.months.January");
    view.greeting1 = t("greeting", {name: "Joe"});
    view.greeting2 = t("greeting", {name: view.name});
}

Translations from XML

The translation function can also be accessed from view XML.

Example view XML:

main.view.xml

<view title="XML Translations">
    <var name="name" type="text" />

    <text-input bind="name" required="false" />
    <info>Month (XML): {$:t("common.months.February")}</info>
    <info>Greeting 1 (XML): {$:t("greeting", {name: "Joe"})}</info>
    <info>Greeting 2 (XML): {$:t("greeting", {name: view.name})}</info>
</view>

Enable a language for app users

To enable a language so that it is selectable by app users, fire the Enable language action via the command palette or by right-clicking on the YAML file in the App Tree panel.

Developer notes for Arabic

Version compatibility

• Arabic was introduced as a supported app language in version 4.86.1 of the JourneyApps Runtime.

• For TypeScript apps the JourneyApps Runtime Build version needs to be 2.1.5 or greater. This version can be configured in your app's package.json file. You need to run the Update yarn.lock action in OXIDE after making updates to this file.

Arabic differs from all other supported app languages in that it is displayed from right-to-left. Right-to-left language support was added to the JourneyApps Runtime in version 4.86.1 so that there is almost no additional configuration that the developer is required to implement when adding Arabic as a language.

The Runtime automatically displays all UI components and runtime elements as right-to-left when a user selects Arabic as their language. Often this means that the specified default for an alignment or positioning attribute is different in Arabic than it is for other languages.

As an example, let's look at the icon-position attribute where the default value is left. In Arabic, the default icon-position for components is right, since elements are read from left to right. This value can still be overwritten in Arabic as with any other language by setting/updating the attribute.

Here is a summary of updates the JourneyApps Runtime makes when a user selects Arabic as their app language:

1. The app font changes to Noto Sans if installed on the user's device

2. UI components and other runtime elements switch to right-to-left mode:

   1. Text is generally right-aligned

      1. There are some exceptions: e.g. button labels. The developer can manually right align this text if required on an app, view or component level (using component configuration).

   2. Icons, radio buttons, checkboxes, etc, are generally aligned to the right of text

      1. User-defined icons (e.g. icon=“fa-arrow-right”) are not updated by the Runtime. The developer would need to do this for directional icons - see the section below.

   3. An example runtime element update is the app header, which is mirrored in Arabic:

      
   4. Runtime-level directional icons are mirrored: e.g. the navigational “Back” button switches from < to >

User-defined directional icons

Developers will need to update user-defined directional icons when implementing Arabic, e.g:

<button label="Navigate Back" icon="fa-arrow-left" validate="false" />

Which looks as follows in English:

Will update to the following in Arabic by the runtime (the icon position updates to the right of the text):

However, the icon itself should most likely also be mirrored. For this developers could use journey.locale to dynamically update icons based on the user's language:

main.view.xml

<button label="Navigate Back" icon="$:mirrorIcon()" validate="false" />

main.js

function mirrorIcon() {
    if (journey.locale == "ar") {
        return "fa-arrow-right";
    }
    else {
        return "fa-arrow-left"
    }
}