How to Handle Translation

Temenos Explorer supports multiple languages. This guide will explain how it does this, how you can add additional languages and/or translations and apply these when the user chooses a new language.

Includes

The Temenos Explorer translation functionality is included in /TemenosExplorer/public/bundle.js and this will need to be included in your plugin's index.html file.

Here is a code snippet that you can copy/paste into the <head> element of your plugin's index.html file using the correct relative paths:

<head>
  <script src="../../bundle.js" defer></script>
</head>

Translation File

Format

Translation files are plain text JavaScript and contain the definition of a translations object:

const translations = {
  "firstName": {
    "en": "First Name",
    "fr": "Prénom", 
    "de": "Vorname", 
    "es": "Vorname",
  },
  "lastName": {
    "en": "Surname",
    "fr": "Nom de famille", 
    "de": "Nachname", 
    "es": "Apellido",
  }
}

The translations object contains translation entries. Each translation entry contains a mapping between language ISO codes and the corresponding translation value. Translation entries are identified by a translation key, a unique string used in your code to lookup the required translation:

languageMap.getTranslation("firstName");

It is possible to group translation entries:

const translations = {
  "customerFields": {
    "firstName": {
      "en": "First name",
      "fr": "Prénom", 
      "de": "Vorname", 
      "es": "Vorname",
    },
    "lastName": {
      "en": "Surname",
      "fr": "Nom de famille", 
      "de": "Nachname", 
      "es": "Apellido",
    }
  },
  "accountFields": {
    "accountNumber": {
      "en": "Account number",
      "fr": "Numéro de compte", 
      "de": "Accountnummer", 
      "es": "Número de cuenta",
    },
    "sortCode": {
      "en": "Surname",
      "fr": "Code de tri", 
      "de": "Bankleitzahl", 
      "es": "Código de clasificacion",
    }
  }
}

Grouped translation entries are identified by a compound key made up of the group key and the translation key separated by a period:

languageMap.getTranslation("customerFields.firstName");

Global Access

It is recommended that you store the translations object defined in your translation file in the window object to make it globally accessible throughout your plugin:

window["translations"] = translations;

Temenos Explorer Translation File

Temenos Explorer has a translations file where translations for the Temenos Explorer menu, app bar and dialogs are located:

/TemenosExplorer/public/TA_translations.js

You are able to update the content of this translation file but be aware that this is a shared asset and may be updated by other developers.

Plugin Translation File

Each plugin will have a translation file to provide translations for the plugin and all content it renders. This file must be located somewhere within the plugin folder. More details on how to create a translation file for your plugin can be found below.

Adding Translations to a Plugin

Step 1 - Create a translation file

To add translations to your plugin you must first create a translation file. This should be added within your plugin folder, e.g.:

/TemenosExplorer/public/plugins/MyPlugin/translations.js

Step 2 - Define a `translations` object

Create a translations object and populate it with the required translations following the translation file format. Be sure to store the translations object in the window object at the end:

// Define translations object with translations for all required display text for all required languages
const translations = {
  "firstName": {
    "en": "First Name",
    "fr": "Prénom", 
    "de": "Vorname", 
    "es": "Vorname",
  },
  "lastName": {
    "en": "Surname",
    "fr": "Nom de famille", 
    "de": "Nachname", 
    "es": "Apellido",
  }
}

// Store in the window object
window["translations"] = translations;

Step 3 - Load translations and dependencies in your plugin

In your plugin's index.html file include bundle.js and your translation file:

<head>
  <script src="../../bundle.js" defer></script>
  <script type="module" src="./translations.js"></script>
</head>

Step 4 - Set up your language map

When your plugin is loaded you will need to initialise the language map. This is a JavaScript class available via bundle.js which consumes the translations object you have defined and provides methods for looking up translations.

To create a new instance of the LanguageMap class you will need to pass in the following parameters:

LanguageMap

Parameter	Type	Description
`translations`	object	The `translations` object defined by you which should be available via `window["translations"]`.
`languageISOCodeProvider`	object	The language ISO code provider gives access to the currently selected language. This is already defined in `bundle.js` and available via `window["languageISOCodeProvider"]`.
`defaultLanguageISOCode`	string	The default language to use, e.g. "en". This must match the language ISO codes used in the translation file.

So in your plugin's initialisation script you will have the following code:

// Initialise the language map for accessing translations
var languageMap = new LanguageMap(window["translations"], window["languageISOCodeProvider"], "en");

Step 5 - Getting translations

Wherever you need to render translated text in your plugin you need to call the getTranslation method on the language map to get the translated text:

LanguageMap.getTranslation

Parameter	Type	Description
`translationKey`	string	The translation key for looking up a translation in the `translations` object
`defaultValue`	string	The default value to use if no entry is found in the `translations` object

For example:

languageMap.getTranslation("firstName", "First name");

Step 6 - Listen for and respond to language changes

When the user chooses a new language from the Temenos Explorer settings screen, a language event will be dispatched which you can detect in your plugin. To listen for the language event you will need to add an event listener to the top object which represents the browser's window object. Your plugin is rendered within an iFrame, so listening for the language event on the window object will not work as this is a reference to the plugin's iFrame only.

The newly selected language is available via top["language"].

When a language change is detected, you will need to update the language of the language ISO code provider available via window["languageISOCodeProvider"].

// Add event listener for change of language
top.addEventListener("language", () => {
  // Get new language and store in plugin window object (in case you need to reference it later)
  window["language"] = top["language"];

  // Update language ISO code provider
  window["languageISOCodeProvider"].setLanguageISOCode(window["language"]);

  // Trigger re-render
});

Once you have updated the language ISO code provider you need to trigger a re-render of your plugin to update the content with translations for the newly selected language.

Includes

Translation File

Format​

Global Access​

Temenos Explorer Translation File​

Plugin Translation File​

Adding Translations to a Plugin

Step 1 - Create a translation file​

Step 2 - Define a translations object​

Step 3 - Load translations and dependencies in your plugin​

Step 4 - Set up your language map​

Step 5 - Getting translations​

Step 6 - Listen for and respond to language changes​