Internationalizing and Localizing Oracle JET Applications

Configure your application to use the Oracle JET framework's built-in support for internationalization and localization.

Topics:

Using the Oracle JET Framework's Internationalization and Localization Support

To use Oracle JET's built-in internationalization and localization support, you can simply specify one of the supported languages or locales on the lang attribute of the html element on your page. For example, the following setting will set the language to the French (France) locale.

<html lang="fr-FR">

If you want to specify the French (Canada) locale, you would specify the following instead:

<html lang="fr-CA">

Tip:

The lang specification isn’t case sensitive. Oracle JET will accept FR-FR, fr-fr, etc., and map it to the correct resource bundle directory.

When you specify the locale in this manner, any Oracle JET component on your page will display in the specified language and use locale constructs appropriate for the locale.

If the locale doesn’t have an associated resource bundle, Oracle JET will load the lesser significant language bundle. If Oracle JET doesn’t have a bundle for the lesser significant language, it will use the default root bundle. For example, if Oracle JET doesn’t have a translation bundle for fr-CA, it will look for the fr resource bundle. If the fr bundle doesn’t exist, Oracle JET will use the default root bundle and display the strings in English.

In the image below, the page is configured with the ojInputDateTime component. The figure shows the effect of changing the lang attribute to fr-FR.

If you type an incorrect value in the ojInputDateTime field, the error text is displayed in the specified language. In this example, the error is displayed in French.

Enabling Bidirectional (BiDi) Support in Oracle JET

If the language you specify uses a right-to-left (RTL) direction instead of the default left-to-right (LTR) direction, such as Arabic and Hebrew, you must specify the dir attribute on the html tag in addition to the lang attribute. The code below shows an example that specifies the Hebrew Israel (he-IL) locale with BiDi support enabled.

<html lang=he-IL dir="rtl">

The image below shows the same ojInputDateTime field that displays if you specify the Hebrew Israel locale and change the dir attribute to rtl.

Once you have enabled BiDi support in your Oracle JET application, you must still ensure that your application displays properly in the desired layout and renders strings as expected.

Note:

JET does not support the setting of the dir attribute on individual HTML elements which would cause a page to show mixed directions. Also, if you programmatically change the dir attribute after the page has been initialized, you must reload the page or refresh each JET component.

Setting the Locale Dynamically

You can configure your application to change the page's locale dynamically by using the oj.Config.setLocale() function:

setLocale(locale, callback)

The image below shows the Oracle JET JET-Localization.zip application configured to display a menu that displays a department list when clicked and a date picker. By default, the page is set to the en-US locale. Both the menu and date picker are displayed in English.

The application also includes a button set which shows the United States of America, France, and Czech Republic flags. When the user clicks one of the flags, the page locale is set to the locale represented by the flag: en-US, fr-FR, or cs-CZ.

Note:

The flags used in this example are for illustrative use only. Using national flags to select a UI language is strongly discouraged because multiple languages are spoken in one country, and a language may be spoken in multiple countries as well. In a real application, you can use clickable text instead that indicates the preferred language to replace the flag icons.

The figure below shows the updated department list after the user clicks the French and Czech Republic flags.

The code that sets the locale in this example uses the oj.Config.setLocale() function call highlighted below. The menu is refreshed in the ViewModel to reload the department list for the chosen locale.

// When the country flags are clicked we get a new language to set as the current locale
self.setLang = function(data) {
  var newLang = '';
  var lang = data.label;
  switch (lang){
    case '?eština':
      newLang = 'cs-CZ';
      break;
    case 'français':
      newLang = 'fr-FR';
      break;
    default:
      newLang = 'en-US';
  }
  oj.Config.setLocale(newLang,
        function() {
          $('html').attr('lang', newLang);
          // In this callback function we can update whatever is needed with the 
          // new locale. In this example, we reload the menu items.
          loadMenu();
        }
  );
}

When the application changes the locale by calling refresh() on the Oracle JET inputDate component, the page will automatically update to use the new locale and display the menu and date in the new locale. However, you must explicitly define the strings that appear in the menu items and then retrieve those strings using the oj.Translations.getTranslatedString() method.

getTranslatedString(key, var_args)

Note:

Do not use this functionality unless the application itself can switch the UI locale dynamically. Dynamically changing the UI locale often ends up with the UI in mixed languages or locales because the application may have cached data that are locale sensitive.

The code that loads the menu is shown below. The menu items and menu button labels are defined with a call to getTranslatedString(). The refresh() method of both the menu and date component are called after the translations and locale bundles are loaded for the new locale to refresh the display.

function DashboardViewModel() {
  self = this;

  // Setting up knockout observables for the button label and the menu items
  self.localeLabel = ko.observable();
  self.menuNames = ko.observableArray([]);

  self.changeLabel = function (event, ui) {
      console.log('this is in the change label');
      self.localeLabel(oj.Translations.getTranslatedString(ui.item.children("a").text()));
  }

  self.setLang = function(data) {
     ... contents omitted
  }
  
  // This function loads the menu items.
  function loadMenu() {
    // These two lines are pulling the translated values for the menu items from
    // the appropriate resource file in the /resources/nls directory.
    self.menuNames(
      [
        {'itemName': oj.Translations.getTranslatedString('menu1')},
        {'itemName': oj.Translations.getTranslatedString('menu2')},
        {'itemName': oj.Translations.getTranslatedString('menu3')}
      ]
    );
    self.localeLabel(oj.Translations.getTranslatedString('label'));
    
    // Since we've modified the children of the Oracle JET menu component, we need
    // to refresh the menu component to get the built-in styling again.
    $('#buttonMenu').ojMenu('refresh');

    // Since the date component uses elements from the locale bundle,
    // we must refresh the date component when the locale changes.
    $('#dateInput').ojInputDate('refresh');
  }

For information about defining your own translation strings and adding them to the Oracle JET resource bundle, see Adding Translation Bundles to Oracle JET.

When you use this approach to internationalize and localize your application, you must consider every component and element on your page and provide translation strings where needed. If your page includes a large number of translation strings, the page can take a performance hit.

Also, if SEO (Search Engine Optimization) is important for your application, be aware that search engines normally do not run JavaScript and access static text only.

Tip:

To work around issues with performance or SEO, you can add pages to your application that are already translated in the desired language. When you use pages that are already translated, the Knockout bindings are executed only for truly dynamic pieces.

Working with Currency, Dates, Time, and Numbers

When you use the converters included with Oracle JET, dates, times, numbers, and currency are automatically converted based on the locale settings. You can also provide custom converters if the Oracle JET converters are not sufficient for your application. For additional information about Oracle JET converters, see Using Oracle JET Converters. For information about adding custom converters to your application, see Using Custom Converters in Oracle JET.