OJET: Internationalization - Localization

In this post I will bring my thoughs and first experience by making an Oracle JET Application ready for Multilanguage. Probably, not the best practices yet, but it is an initial step


My application (ojet-internationalization) can be found in:
https://github.com/DanielMerchan/ojet-examples


How to make your Oracle JET Application ready for Multilanguage?

This is well explained in the official documentation: https://docs.oracle.com/en/middleware/jet/6.1/develop/internationalizing-and-localizing-applications.html

 But, in this post I will bring what I did and my feelings.
  1. I created a Factory utility Module called Languages.js in js/utils. This factory contains an array of the supported languages in Oracle JET and some wrapper methods I used / un-used meanwhile my app was changing.

    setLocale: (newLocale, langCallback) => {
            console.log(`Old locale: ${Languages.getCurrentLocale()} and New Locale: ${newLocale}`);
            oj.Config.setLocale(newLocale, () => {
                $('html').attr('lang', newLocale);
                if (newLocale.startsWith('ar')) {
                    $('html').attr('dir', 'rtl');
                } else {
                    $('html').attr('dir', 'ltr');
                }
                langCallback();
                // Dispatch a JS Event to allow other modules to subscribe and change translations accordingly.
                document.dispatchEvent(new CustomEvent('localeChangedEvent'));
            });
        },
  2. I added the utils/Languages to the define and function blocks of the appController.js to be able to use the Factory I just defined.

    define(['ojs/ojcore', 'knockout', 'ojs/ojmodule-element-utils', 'utils/Languages', 'ojs/ojarraydataprovider', 'ojs/ojlistdataproviderview', 'ojs/ojmodule-element', 'ojs/ojrouter', 'ojs/ojknockout', 'ojs/ojarraytabledatasource',
  'ojs/ojoffcanvas', 'ojs/ojselectcombobox'],
  function(oj, ko, moduleUtils, Languages, ArrayDataProvider, ListDataProviderView) {
  3. Following best practices, I created my Resource Bundle files under /resources/nls folder and updated the main.js to merge the Out-of-the-Box OJET Translations with my Custom Translations. I was dissapointed you can only register 1 Resource Bundle as clearly said in the official documentation. So, I recommend you structure your Resource Bundle by blocks as I did. Have a look into menu, footer, nav sections in mytranslations.js
    requirejs.config(
{
  baseUrl: 'js',

  // Path mappings for the logical module names
  // Update the main-release-paths.json for release mode when updating the mappings
  paths:
  //injector:mainReleasePaths
  {
    'knockout': 'libs/knockout/knockout-3.4.2.debug',
    'jquery': 'libs/jquery/jquery-3.3.1',
    'jqueryui-amd': 'libs/jquery/jqueryui-amd-1.12.1',
    'promise': 'libs/es6-promise/es6-promise',
    'hammerjs': 'libs/hammer/hammer-2.0.8',
    'ojdnd': 'libs/dnd-polyfill/dnd-polyfill-1.0.0',
    'ojs': 'libs/oj/v6.1.0/debug',
    'ojL10n': 'libs/oj/v6.1.0/ojL10n',
    'ojtranslations': 'libs/oj/v6.1.0/resources',
    'text': 'libs/require/text',
    'signals': 'libs/js-signals/signals',
    'customElements': 'libs/webcomponents/custom-elements.min',
    'proj4': 'libs/proj4js/dist/proj4-src',
    'css': 'libs/require-css/css',
    'touchr': 'libs/touchr/touchr'    
  }
  //endinjector
  ,config: {
    ojL10n: {
      merge: {
        'ojtranslations/nls/ojtranslations': 'resources/nls/mytranslations'
      }
    }
  }


    define({
    "root": {
        "app": {
            "appName": "OJET Internationalization Example"
        },
        "nav": {
            "dashboard": "Dashboard",
            "incidents": "Incidents",
            "customers": "Customers",
            "about": "About"
        },
        "menu": {
            "languages": "Languages",
            "preferences": "Preferences",
            "help": "Help",
            "about": "About",
            "signOut": "Sign Out"
        },
        "footer": {
            "aboutOracle": "About Oracle",
            "contactUs": "Contact Us",
            "legalNotices": 'Legal Notices',
            "termsOfUse": "Terms of Use",
            "yourPrivacyRights": "Your Privacy Rights"
        }
    },
    "es": true
});
  4. I added two functions in appController.js which are called initTranslations and refreshTranslations
    1.  The initTranslations is a function I always add in the modules (xx.js) to initate the initial value of our custom translations.
      self.initTranslations = () => {
        // Header
        // Application Name used in Branding Area
        self.appName = ko.observable(oj.Translations.getTranslatedString("app.appName"));
        // Navigation Labels
        self.dashboardMenuLabel = ko.observable(oj.Translations.getTranslatedString('nav.dashboard'));
        self.incidentsMenuLabel = ko.observable(oj.Translations.getTranslatedString('nav.incidents'));
        self.customersMenuLabel = ko.observable(oj.Translations.getTranslatedString('nav.customers'));
        self.aboutMenuLabel = ko.observable(oj.Translations.getTranslatedString('nav.about'));
        // Menu Labels
        self.preferencesLabel = ko.observable(oj.Translations.getTranslatedString('menu.preferences'));
        self.laguangesLabel = ko.observable(oj.Translations.getTranslatedString('menu.languages'));
        self.helpLabel = ko.observable(oj.Translations.getTranslatedString('menu.help'));
        self.aboutLabel = ko.observable(oj.Translations.getTranslatedString('menu.about'));
        self.signOutLabel = ko.observable(oj.Translations.getTranslatedString('menu.signOut'));
        // Footer Labels
        self.aboutOracleLabel = ko.observable(oj.Translations.getTranslatedString('footer.aboutOracle'));
        self.contactUsLabel = ko.observable(oj.Translations.getTranslatedString('footer.contactUs'));
        self.legalNoticesLabel = ko.observable(oj.Translations.getTranslatedString('footer.legalNotices'));
        self.termsofUseLabel = ko.observable(oj.Translations.getTranslatedString('footer.termsOfUse'));
        self.yourPrivacyRightsLabel = ko.observable(oj.Translations.getTranslatedString('footer.yourPrivacyRights'));
        console.log("AppController Translations initiated!");
      }
    2. The refreshTranslations is a function I always add in the modules (xx.js) to refresh the custom translations and add custom logic if necessary when a language changes.

      self.refreshTranslations = () => {
        // Header
        // Application Name used in Branding Area
        self.appName(oj.Translations.getTranslatedString("app.appName"));
        // Refresh Navigation Labels
        self.dashboardMenuLabel(oj.Translations.getTranslatedString('nav.dashboard'));
        self.incidentsMenuLabel(oj.Translations.getTranslatedString('nav.incidents'));
        self.customersMenuLabel(oj.Translations.getTranslatedString('nav.customers'));
        self.aboutMenuLabel(oj.Translations.getTranslatedString('nav.about'));
        // Refresh Labels
        self.preferencesLabel(oj.Translations.getTranslatedString('menu.preferences'));
        self.laguangesLabel(oj.Translations.getTranslatedString('menu.languages'));
        self.helpLabel(oj.Translations.getTranslatedString('menu.help'));
        self.aboutLabel(oj.Translations.getTranslatedString('menu.about'));
        self.signOutLabel(oj.Translations.getTranslatedString('menu.signOut'));
        // Refreshc Labels
        self.aboutOracleLabel(oj.Translations.getTranslatedString('footer.aboutOracle'));
        self.contactUsLabel(oj.Translations.getTranslatedString('footer.contactUs'));
        self.legalNoticesLabel(oj.Translations.getTranslatedString('footer.legalNotices'));
        self.termsofUseLabel(oj.Translations.getTranslatedString('footer.termsOfUse'));
        self.yourPrivacyRightsLabel(oj.Translations.getTranslatedString('footer.yourPrivacyRights'));
        console.log("AppController Translations refreshed");
      }
  5.  I added a oj-select as the language selector, but you can add whatever control you want in the index.html for managing the Language. The logic of the Localisation can be found in the setLangAction function of the appController.js
    // Change Language
      self.setLangAction = event => {    // Change Language Event
        const newLocale = event.target.value;
        Languages.setLocale(newLocale, self.refreshTranslations);
      }
  6. The code of setLangAction changes the Locale by using the utility wrapper of the Languages module (wraps the oj.Config.setLocale and other code) and also throws a custom event called localeChangedEvent. Other modules like dashboard.js, customers.js etc.. will need to listen to this event to invoke their owns refreshTranslations functions when the locale has changed. Remember that the Oracle JET components changes its language without any other extra code, but our custom translations needs to be refreshed.

    Languages.js
    setLocale: (newLocale, langCallback) => {
            console.log(`Old locale: ${Languages.getCurrentLocale()} and New Locale: ${newLocale}`);
            oj.Config.setLocale(newLocale, () => {
                $('html').attr('lang', newLocale);
                if (newLocale.startsWith('ar')) {
                    $('html').attr('dir', 'rtl');
                } else {
                    $('html').attr('dir', 'ltr');
                }
                langCallback();
                // Dispatch a JS Event to allow other modules to subscribe and change translations accordingly.
                document.dispatchEvent(new CustomEvent('localeChangedEvent'));
            });
        },

    dashboard.js
    // Localisation
      self.initTranslations = () => {
        self.dashboardTitle = ko.observable(oj.Translations.getTranslatedString('dashboard.dashboardTitle'));
      };

      self.refreshTranslations = () => {
        self.dashboardTitle(oj.Translations.getTranslatedString('dashboard.dashboardTitle'));
      };

      self.initTranslations();

      // Listen to a Locale Change
      document.addEventListener("localeChangedEvent", function () {
        self.refreshTranslations();
      });

What was my feeling compared to Oracle ADF or just Java Server Faces?

I think is "too much" dirty code compared to a regular J2EE - JSF - ADF Application. In JSF / Oracle ADF you an easily split the Resource Bundle in multiple smaller files more maintainable and also requires less work on the side of the change of Localization.

Summary

This diagram describes how Multilanguage more or less works in Oracle JET.

Comments

Post a Comment

Popular posts from this blog

OJET: Build and Deploy in an Application Server

Image
There are some other sources where an Oracle JET Application is packaged and deployed as a WAR in Oracle WebLogic Application Server (Arda Eralp) https://blogs.oracle.com/ardaeralp/deploy-oracle-jet-application-to-weblogic-server (Andrejus Baranovski's) http://andrejusb.blogspot.com/2016/07/serving-oracle-jet-application-from.html They may look bit old or maybe because they call directly grunt tasks by using the grunt-cli . In this post I will update a bit these posts in Oracle JET 6.1.0 and the usage of ojet build (instead of calling the grunt tasks) for also building the corresponding WAR file. The example can be found in my GIT repository: https://github.com/DanielMerchan/ojet-examples Let's start... Install grunt-war module in your Oracle JET Application. npm install grunt-war --save-dev Create a war.js (or call it whatever you want) in /scripts/grunt/config folder under your souce files. This is a sample code inside of it, check https://www.npmjs.com/packag...
Read more

OJET: Select All options using only Checkboxset

Image
This is an example on how to select all other options by using another oj-checkboxset. GitHub: ojet-checkbockset-select-all The idea is to keep track of the selection and make use of the on-value-changed as described in the following code. self.colorOptions = ko.observableArray([ { id: "blueopt", value: "blue", color: "Blue" }, { id: "greenopt", value: "green", color: "Green" }, { id: "redopt", value: "red", color: "Red" }, { id: "limeopt", value: "lime", color: "Lime" }, { id: "aquaopt", value: "aqua", color: "Aqua" }, ]); self.selectAll = ko.observableArray([]); self.currentColor = ko.observableArray(["red"]); self.selectAllOptionChanged = (event) => { const newSelection = event.detail.value; if (newSelection.indexOf('all')...
Read more

WebCenter Content: Check-in sin Primary File

Image
En esta entrada se explican dos ascpectos relacionados con los Primary File: Primary File fields Permitir que un Check-in no obligue a subir un fichero asociado para todos los contenidos. Cómo permitir Check-in para un perfil específico y ocultar los campos de Primary File de un formulario de Check-in . Permitir Check-in sin Primary File Para permitir los Check-in sin Primary asociado para todos los contenidos de WebCenter Content solo hay que añadir la siguiente variable a la configuración: AllowPrimaryMetaFile=true Configuración de Oracle WebCenter Content Permitir Check-in y ocultar los campos para un Profile específico En caso de requerir realizar la acción para ciertos perfiles de WebCenter Content. Seguir los siguientes pasos: Crear una nueva regla que se activará con las condiciones de Check-in Regla que se activa con Check-in En la pestaña de Side Effects añadir el siguiente IdocScript que permitirá la creación de contenido sin Primary File y ade...
Read more