Essential Internationalisation Framework
9 min
Introduction
The Essential Meta Model supports the ability to capture and model the knowledge about your organisation in multiple languages using the Synonym class. Within Essential Viewer, the internationalisation (i18n) framework uses the selected language to dynamically render the names and descriptions of any element. Not just that, the static web content (‘chrome’) can also be rendered in the selected language dynamically. These capabilities mean that framework allows different users to see the same Views from the same Viewer instance in different languages. In this short article, we describe how to take advantage of these powerful multi-language capabilities.
Modelling in multiple languages
Any element in the Essential repository can have one or more Synonyms defined for it. Each Synonym is an element in its own right with a language attribute that defines the language that is being used for the name and description attributes in that Synonym. Modelling in multiple languages is simply a case of defining the translations for the name and description of any of the elements in your repository using Synonym instances and specifying the relevant language. The Essential Viewer internationalisation framework will take of rendering these elements in the selected language.
View Chrome in multiple languages
The ‘chrome’ in the views is all the static text that is ‘coded’ into the View template XSL file – things like the section headers, the page headings and titles. The internationalisation framework enables any of this kind of text to be dynamically translated into the selected language along with the content from the repository. However, to ensure the most accurate translations, this content is translated using a set of phrase-based language lookups. Any content that is to be translated by the framework is “tagged” by surrounding the static text with a call to the internationalisation framework.
Tagging Static Content
Tagging the text in your View Template that you want to be translated is easy and all the Views you get out of the box are already tagged. Once you have finished editing one of the existing Views or created your new View template, surround each static phrase with the following ‘tag’:
eas:i18n e.g.
You can set up a macro in your XML editor and add these tags with a simple key combination.
Language Files
As the Essential Viewer is rendering each View, it processes each of these tags and looks for a translation in the relevant language file. A language file is a simple XML document each of which is named using the ISO two-part language identifier, e.g. en-gb.xml. These are stored in the ‘language’ folder of Essential Viewer and this also contains a ‘flags’ folder where the images for the flag for each language are stored as PNG files, again named using the ISO language code, e.g. en-gb.png.
There is a single XML language file per language, which contains the translations for all the phrases used across all the Views. Many of the phrases are re-used across many Views. Each XML language file defines each phrase using a message tag. Each of these contains:
name the phrase ‘key’ in English
value the translated phrase in the relevant language
If no translation is found, the tagged phrase itself is returned to ensure that there is always some text rendered on the page.
To define a new set of translations, copy the en-bb.xml file and save it to your desired language, e.g. es-es.xml, fr-fr.xml, fr-ca.xml, and complete each value tag with the translation of the corresponding name tag.
Two XSL transformation templates are also included in the language folder to help build or extend these language files:
getChromeText.xsl – Run this transform over your tagged-up View Template to generate a set of message tags ready to be translated and included in your language XML file.
dedup_messages.xsl – Many phrases are re-used across the Views, so duplicate phrase keys (the name) are often produced by ‘getChromeText.xsl’. Run this transform over your language XML file after you’ve added your new phrases to remove any duplicates.
Configuration
Having prepared your Views and created the translations some simple configuration within your Essential repository is required to prime the internationalisation framework. New languages can be added to Essential by creating new instances of the Language and Report Language classes in the Utilities and Essential Viewer section of the Essential repository respectively. Enable the new language and define the new XML language and PNG flag files, you can have all the existing Views in your preferred language.
Contributing to the Essential Project
Creating new language files of translations in your language is an easy way to contribute to the Essential Project. Contact us to send in your language file and help us build up the portfolio of available languages.
Updated 31 October 2023