A translation can be inserted in the designer either by clicking this icon:
- or by referring to a translation in a text element.
A similar XPath function is the built-in function, ng:translate.
The translations can be used if you e.g. want to create a single template, that can output in multiple languages depending on the preferred language of the receiver. So instead of inserting text constants, you can refer to a translation file (one file per language) with a key. You need to create the translation files yourself and upload them to the Library.
Before you can refer to a translation you need to define and load it in the library in the translations library.
The translation files must be UTF-8 encoded text files and the contents must be formatted like this:
m0.1 = Make
m0.2 = Type
m0.2a = Variant
m0.2b = Version
Where the leftmost part (before the '='-sign) is the key for the lookup. The key must be a single word without spaces.
The rightmost part (after the '='-sign) is the resulting text in the specific language. This text must end with carriage return and line feed.
The format of the translation file names is fixed. You define a default translation file e.g. "translationCOC.properties". This file will be the default (root) translation file to be used for any undefined languages. Notice: The key name: *OTHERWISE* is as reserved name, which can be used in the default 'root' translation file (the one without a locale) to return a predefined value, if a specified key was not found in the translation file, when the translation file is used in e.g. either a translation element or in the ng:translate function.
Please note regarding underscore _
Please note, that the underscore character, '_' is a protected character in the name of the translation files and should not be a part of either the folder names used for the translations and the only place to use underscore in the name of the translation file is at the end to delimit the two parts of the locale.
Translation files for specific languages must be named with underscore followed by the language e.g. like so:
translate.properties
translate_de.properties
translate_de_DE.properties
translate_en.properties
translate_en_GB.properties
translate_en_US.properties
The topics covered below are:
1.How to drag a translation text into the template.
2.How to refer to a translation in a text element.
3.How to select the language depending on a variable or XPath expression.
4.The way InterFormNG2 decides for which value to return when a translation is used.
5.How to use *OTHERWISE* key to handle a reference to a key, that does not exist in the translation files: Description is here and an example is here.
How to drag a translation text into the template
The quickest way to insert a translation text is to drag it from a translation file. You do that by clicking the translation element in the designer:
And from here you can select and drag the translation key, that you want to use into the result window:
This creates a new text element, that refers to the selected translation file and key.
How to refer to a translation in a text element
Instead of dragging a translation text into your template, you can also change an existing text element (that e.g. is currently a fixed text), so that it refers to a translation file and key to make it a dynamic language.
To change a text element you can either double click on the text element or right click on it and select 'Text properties'.
How you select 'Translation' in the top, click the 'Translation file' entry field to select the translation file from a drop down list, and click the entry field for the 'Translation key' to select the key from the drop down list:
How to set the translation language dynamically
To set the language of your translated text dynamically (depending on the input XML file), you have these options:
1.Insert the expression for the dynamic language on the template properties.
2.Set the expression for the language on each text element.
Set the dynamic language on the template properties
If your translation texts refer to the default language, then you can set the language on the properties of the template for them. To add such an expression you double click (or right click on it and select 'template properties') on the template element in the element list:
Then you see this pop up window:
For the source you select 'Expression' and for the expression you can now (hopefully) setup an XPath expression, which sets the language for all the text elements referring to a translation with the default language.
Set a dynamic language on each text element
If you cannot set a dynamic language for the complete template like above, then you can consider to set a dynamic language on each text element. You set that up by opening the properties of the text element e.g. by double clicking on it:
In the screen above we have chose Expression for the source and for the expression we clicked the magnifying glass on the right to select a node from the sample input XML file.
You can also refer to a variable in the expression (can also be found via the magnifying glass) and/or a longer XPath expression.
Which value is returned in a translation
InterFormNG2 can go through several steps in order to decide which value to return in either the translation element or in the ng:translate function.
The value is found in two steps:
1.First a matching translate file is found.
2.Then a matching key is found.
Let us keep in mind, that you can have multiple translation files covering multiple languages like this:
translate.properties
translate_de.properties
translate_de_DE.properties
translate_en.properties
translate_en_GB.properties
translate_en_US.properties
When you use the translation, then you refer to the part of the file name, that is to the left of the dot i.e. translate in this case.
If the selected locale is either null (like '') or an unknown locale, then the no language has been selected and the translate.properties file is used.
If you select the locale as the first 2 character id e.g. "en" or "de", then the translation files translate_en.properties or translate_en.properties are used.
If you select the locale as a 5 character id e.g. "en_GB', then the translate_en_GB.properties translation file is used. If you however refer to a 5 character id e.g. "en_AU", and there is no matching translate file, then InterFormNG2 will search for the translate_en.properties file (trying a match for the 2 first characters), then if that properties file is also not found, then InterFormNG2 will try to match the initial part of the selected translation file (the default/root) file: translate.properties.
Matching the key and returning the value
After InterFormNG2 has found a matching translation file, then it will look up in the translation file to find a match with the key name, that was selected for this look up.
The value to return is found via this list:
Is the key found in the selected translation file as described in the section, matching the translate file? If yes, then return the found value and stop.
If not found, then remove the last 3 characters from the translation file used to search the more generic file e.g. if a key name is not found in the translate_de_DE.properties file, then InterFormNG2 will now search the translate_de.properties file (if the file exists). If a value is found, then this is returned.
If is there also no match found in the generic properties file above, then InterFormNG2 will try to find a match in the root/default properties file - which in the example above is translate.properties. If there is a match, then this value will be returned.
If there is even no match in the root/default file, then InterFormNG2 will look a key named *OTHERWISE* in the root/default translation file. If there is not such key name, then InterFormNG2 will fail with an error, that reports a missing key in a translation file. If there is such a key name, then the value for this key is returned.
