Advanced Internationalization in Oracle JET
Written by Carlos Santos and João Tiago
How to easily manage translations in Oracle JET applications seems to be a topic often asked by the community. This guide provides a simple yet powerful methodology to accomplish this.
Oracle JET components (based on Alta UI) fully support translations ‘out of the box’. What you need to do in essence is change the lang attribute on your <html> tag. This obviously does not mean that your own texts/components will be translated automatically, that’s what we aim to fix with this guide.
In order to setup support for our own translations we need to set few things:
1. Add a flag pack on your project
eg, css/images/flags
In order to avoid performance issues prefer vector formats, minify and compress SVG assets, etc. In here we simply use png’s.
2. Setup the nls folder
Create a nls folder under js/resources (to match specification of scaffolded app). Add a folder to support as many languages as you like, it should match ISO specification, you can find HTML ISO Language Code Reference here.
Each folder should contain a l10.js file as well as l10.js file that will be your default translation file.
NOTE: The default translation file will always be accessed. Meaning you should have AT LEAST one reference to your translation string within this file, even if you didn’t ‘setup’ translation for each language you plan to support.
BONUS CONTENT: Use Notepad++ functionalities or Excel’s Text to Columns to easily extract your texts and manage your translations
3. Add a Select One element to your page
<oj-select-one id="homepageLanguagePicker" on-value-changed="[[setLang]]" style="max-width:20em; padding-bottom: 20px">
<!-- ko foreach: languagesSupported -->
<oj-option value="[[langValue]]">
<span slot="startIcon">
<img data-bind="attr: {src: './css/images/flags/' + langFlag + '.png'}" role="presentation" style="vertical-align:middle" />
<oj-bind-text value='[[langName]]'></oj-bind-text>
</span>
</oj-option>
<!-- /ko -->
</oj-select-one>
We have given our element a specific id, homepageLanguagePicker, assigned a function call whenever it’s value changes (on-value-changed), setLang, this is where we will actually change the html lang.
Took advantage of the Knockout foreach to span multiple oj-options reading data from our JavaScript (in this example hard-coded, could be a Service call). Each <oj-option> will display a flag using langFlag and it’s text (also a translatable String) through langName.
NOTE: You can always consider using another approach to <oj-select-one> using the options and value attributes instead of the KO for each approach.
4. Add the logic in JavaScript
DISCLAIMER: In this guide we’re using ojet-accelerator package to assist development. But we will show you what is “under the hood” so you can accomplish the same result in your code.
We’ve defined an Observable Array with the properties needed by our Select One, including the ISO specification for the language.
Notice how we assigned an Observable to one of our properties, and how we reference “lang-en” String defined in step 2.
// List of Languages Supported
self.languagesSupported = ojet.createArray([{
langValue: "en",
langFlag: "United-States",
langName: ojet.createText('lang-en')
},
{
langValue: "pt",
langFlag: "Portugal",
langName: ojet.createText('lang-pt')
}]);This enables you to, for example, translate an <oj-table> column headers configuration texts through this same mechanic, an <oj-input-text> placeholder, a <span> or <oj-bind-text> value, etc.
createText: function (translationString) {
let textObs = ko.observable(oj.Translations.getTranslatedString(translationString));
$('#homepageLanguagePicker').on('translateEvent', function () {
textObs(oj.Translations.getTranslatedString(translationString));
});
return textObs;
}This is the key takeaway for the entire process, in here we return an KO Observable that refers to the translated String within our nls files. It then listens to our custom JavaScript event ‘translateEvent’ which is triggered when we change the value on our translations Select One, defined in step 3.
Finally the function executed on on-value-changed, setLang.
This function accesses oj.Config to set the Locale to our newLang (referenced in the value of our oj-option), eg, “en”. The callback triggers our custom event.
// Language Selection
self.setLang = function (event) {
const newLang = event.detail.value;
ojet.ojConfig().setLocale(newLang,
function () {
$('html').attr('lang', newLang);
// Triggers an event to update other texts
jQuery('#homepageLanguagePicker').trigger(jQuery.Event("translateEvent"));
});
};5. Final Result
Lastly here’s the final result, you not only have a nice looking Select One to manage your supported languages, but it also gets translated (much like everything else you apply createText to) within your application.
You can find Oracle JET official documentation on internationalizing OJET applications here
For Oracle JET consulting inquiries feel free to contact me directly at joao_t332@hotmail.com
