Add multilingual support to your application Follow

General

AuraPlayer installation includes a special JS utility file that may be used to add multi language support to your application. The following article will describe how to setup your application and use this utility. 

You can find a demo application here. It is highly recommend, after reading this article, to upload the demo application into your ServiceManager server and overview the code before implementing it on your real application.

Setup

Add i18n utility file to the application

If you have a new version of ServiceManager the i18n utility file is already included in SM deployment all you need to do is to add the following line to beginning of the application "Common JS":

//<script type="text/javascript" src="res/api18n/api18n.js"></script>

If you have an old version of SM you may download the file from Here and upload it to your SM server under the apps directory (goto admin/server files, select the apps directory and upload the file). Once you uploaded the file add the following line to beginning of the application "Common JS":

//<script type="text/javascript" src="../api18n.js"></script>

Add configuration object and translate execution

Add the following section to your application "Common JS" section. See embedded comments for more details.

// i18n configuration object
app.languageConfiguration = {
dictionaryService: '<name of dictionary JS service>', //The name of the dictionaru JS service
defaultLanguage: 'english',  //must be one of the langauges defined below
languages: [ //all supported languages in the dictionary should be added to app.languageConfiguration
  {
     title: 'EN', //title to be used in the default languages toolbar
     language: 'english' //name to be used in the dictionary service
  },
  {
     title: '<aditional language title>',
     language: '<aditional language name>'
  },
 ]
};

// Optional - disable language default menu, replaced with LOV in login page
createLanguageMenu = function () {};

// Translate logout menu tests
function translateLogoutPopup() {
    app.logoutTitle = getTranslationForId("@logout_popup_title");
    app.logoutMessage = getTranslationForId("@logout_popup_message"); 
    app.logoutYesButton = getTranslationForId("@logout_popup_yes");
    app.logoutNoButton = getTranslationForId("@logout_popup_no"); 
}

// Clean dictionary cache to ensure reload of new definitions (should be called in the login page)
function initI18n() {
    cleanLanguageDictionary();
}

// Upload i18n module and execute page translation (should be called on pageChanged event)
function invokeI18n() {
    loadLanguageModule();
    translateLogoutPopup();
}

Events.pageChanged = function(){
    // Execute translation on each page load
    invokeI18n();
};

Create Dictionary service

The i18n utility uses a JS service to serve the dictionary data for your text translations. The name of this service should be set in the configuration object as described in the section above (i.e dictionaryService: '<name of dictionary JS service>' ). 

The JS service body should be in the following format:

return {
  "dictionary" : {
     "Common":{
         "name1": {
              "english": "<Value in english>",
              "spanish": "<Value in spanish>"
           },
         ...
    },
    "<page1 name>":{
          "<name1>": {
              "english": "<Value in english>",
              "spanish": "<Value in spanish>"
            },
          "<name2>": {
              "english": "<Value in english>",
              "spanish": "<Value in spanish>"
           },
         ...
    },
    "<page2 name>":{
       ...
    },
    ...
  }
};

Under the dictionary section you may define the "Common" section and a section for each page in the application.

The "Common" section holds translations for UI components that are displayed in multiple pages. For example, if you have an "OK" button that is rendered on several pages, you may define it once under the "Common" section and it will translate for each page (if exists). Translations that are defined under specific page name will translate only for this specific page. 

Each section is built of key name and a group of translations (one per language). A key may be one of the following:

1. Name of a visualizer component (i.e field name, button name, table column name, menu name).
2. Component id identified as jquery selector - #<id> (e.g. "#button1").
3. Component identified jquery class selector - .<class name> (e.g. ".class1").
4. Component id starting with "@" (e.g. "@button1"), will be discussed below under "Dynamic text translation".

Select preferred language

The i18n utility creates by default a language selection bar on any page with no left side menu (usually the login page)  and inside the left side menu for any page that has a menu.

It is recommended to override the default implementation with your own UI. To see an example of how to set the language selection as List of Value field, refer to the Login page in the Demo application. 

How to translate static texts on a page

Once the the setup is done and the dictionary service is in place, the i18n utility will automatically translate any text that was set correctly on the dictionary. No additional action is needed. 

How to translate dynamic texts

Texts that are created dynamically through JS code like popup titles and messages needs to be translated explicitly. This could done by using the "getTranslationForId(id, param1, param2,...)" function. 

The "getTranslationForId" function takes an id as the first parameter and an optional dynamic list of values for a translation text with embedded parameters.

The "id" should be a component id with "@" as a prefix (e.g. "@button1").

A translation text with parameters will be in the format of "... ${1}... ${2}..."
(e.g. "Expense Report ${1} was submitted"). 

Examples: