Translations

Ensemble supports localization of app content so that your app users can view the app in their preferred language.

How it works

When an app loads, Ensemble checks the defualt language of the device (e.g. languages setting in iOS, Android, or Chrome browser).

1. If device default langugae is supported by your app, Ensemble uses that language.
2. Else, Ensemble uses the app's default language.

Set up languages

In Ensemble Studio, navigate to your app and select Translations from the left menu. Add new language to start with.

Add language content

Language content is created in YAML. Add key/value pairs for each text.

Organize the content

To make it easier to find and update the text, you can create a hierarchy within language files. For instance, you can have common text under common and text related to login screen under login

common:
    submit: Submit
    error: Something went wrong. Try again.
 
login:
    login_button: Sign in
    login_error: Incorrect username or password. Please try again.
 

Reference the translation

In any screen or widget, reference the translations. E.g. for a button, assign the reference to the label property.

When refrencing translations, prepend r@ before the key assigned to the text:

- Button:
    label: r@login.login_button

Test in Preview

Use the 🌎 icon on top of the preview to select a language. The preview updates and shows the UI in the selected language.

Changing Language in Screens using Script

To enhance user experience, you can dynamically change the app's language from within your scripts. This allows users to switch languages without restarting the app.

Retrieve Supported Languages

To get an array of languages supported by your app (i.e., translations you created in Ensemble Studio), use the following code:

// Get array of supported languages
console.log(app.languages);

Get Current Language and Locale

To log the currently set language and locale:

// Log currently set language
console.log(app.language);
 
// Log currently set locale
console.log(app.locale);

Set the Locale

You can set the locale using the ensemble.setLocale method. This method updates the app's language dynamically.

// Set the locale to English
ensemble.setLocale({
  "languageCode": "en"
});

Dropdown for Language Selection

Implement a dropdown menu to allow users to select their preferred language. When a language is selected, the locale is updated accordingly.

Dropdown:
  itemTemplate:
    data: ${app.languages}
    name: language
    template:
      Text:
        text: ${language.name} (${language.nativeName})
    value: ${language.languageCode}
 
  onChange: |-
    ensemble.setLocale({ languageCode: event.data.value });

Example Usage in a Screen

Here's an example of how you might integrate the language selection dropdown into a screen:

Screen:
  - Dropdown:
      itemTemplate:
        data: ${app.languages}
        name: language
        template:
          Text:
            text: ${language.name} (${language.nativeName})
        value: ${language.languageCode}
 
      onChange: |-
        ensemble.setLocale({ languageCode: event.data.value });
 
  - Button:
      label: r@common.submit