TranslationAPI

TranslationAPI provides mechanisms by which we can adapt the created functionalities for other language versions.

Translation files

Translations are stored in the form key=value in *.properties files. Depending on the language for which we prepare translations, the files should have an appropriate name, e.g.:

The order of downloading translations from files works as follows:

Let's assume that the following translation files are available:

• messages_en.properties
• messages_pl.properties
• messages.properties

If the user's language is English (en) then the order of downloading translations will be as follows:

1. messages_en.properties
2. messages.properties

 greetings=Witaj {0}

 greetings=Greetings {0}

Registration of translators

When registering an object Translator it is required to specify the range (scope) in which the translation data will be available. We distinguish between 2:

1. server: translations are used on the server side (e.g. in automated tasks, controllers, etc.).
2. browser: translations are used on the user interface side in the browser

Registration can be done either through an API (see JavaDoc)  or in a declarative way described in the chapters:

• Translation of client projects and libraries
• Plugin translations

Server translations

All translations are retrieved using the class com.suncode.pwfl.translation.Translator. Translator objects fetched can be from the registry TranslatorRegistry (we retrieve it from the context using @Autowired ) or using the helper class : Translators:

// By name
Translator t = Translators.get("cuf");

// For class
Translator t = Translators.get(ExampleClass.class);

Examples of use Translator:

Translator t = ...
 
// By key for the current user language ( message.key=Witaj )
String m = t.getMessage("message.key");
assertEquals(m, "Witaj")
 
// By key for the specified language ( message.key=Hello )
String m = t.getMessage("message.key", Locale.ENGLISH);
assertEquals(m, "Hello")

// By key with arguments ( message.key=Hello {0} {1} )
String m = t.getMessage("message.key", "Jan", "Nowak");
assertEquals(m, "Hello Jan Nowak")

User interface translations (browser)

Translation of the user interface in the browser must be implemented through the JS API provided. The object responsible for handling translations in the browser is PW.I18N. It provides a simplified API that only allows downloading message translations for the current language of the logged-in user.

The download of the translation is implemented by invoking:

PW.I18N.t(<translator>, <key>, <arg1, arg2, arg3, ...>);
 
// where:
// 		<translator> -> translator name
//		<key> -> message key
//		<arg1, arg2, arg3, ...> -> any number of message arguments (standard notation {0}, {1})
//	np:
 
// for the key value 'Greetings "{0} {1}"' will return 'Greetings " Jan Kowalski.
PW.I18N.t('cuf', 'cuf.greetings', 'Jan', 'Kowalski'); 

It is a good practice to create a function that allows you to download translations for a specific translator without specifying its name all the time:

// During initialization
CUF.t = PW.I18N.createT('cuf');
 
// Continue in the program without specifying the translator key
CUF.t('message.key');

Translation of client projects and libraries

We start translating client projects or libraries by creating a plusworkflow-translators.xml file that provides information about the location of translation files. We usually add this file in the src/main/resources/plusworkflow-translators.xml directory of our project if it is a Maven project. The structure of the file is as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<translators>
	<translator name="simple-translator">
		<bundle scope="server" location="translations/messages" encoding="UTF-8"/>
		<bundle scope="browser" location="translations/messages_browser"/>
	</translator>
</translators>

The file allows you to register multiple translators identified by a unique name, which is then used to download translations. Description of the meaning of each line in the file:

3: the <translator> element with the required name attribute which must contain the unique name of this translator (it is possible to declare multiple translators)

4: the <bundle> which contains translations used on the server side (scope="server" – domyślny) along with encoding ( encoding="UTF-8" – domyślnie) and their location ( location="translations/messages" )

5-6: specifying the packages for which we are registering this translator (tylko dla scope="server")

8: declaration of <bundle> which contains translations used on the browser side (scope="browser")

The localization of the translation files includes the prefix of the translation files. The actual files must have the extension *.properties and optionally the language they refer to, e.g:

• translations/messages_pl.properties
• translations/messages_en.properties

At system startup, all translators already so declared will be registered in the translator registry TranslatorRegistry.

Plugin translations

In order to apply the above mechanisms to translate plugins, the <i18n> module must be defined in the suncode-plugin.xml plugin descriptor.

Mamy do dyspozycji postać skróconą:

 <?xml version="1.0" encoding="UTF-8"?>
<plugin key="example-plugin" name="I18N Usage">
	<i18n key="i18n" />
</plugin>

Which is equivalent to the following definition:

 <?xml version="1.0" encoding="UTF-8"?>
<plugin key="example-plugin" name="I18N Usage">
	<i18n key="i18n">
		<bundle scope="server" encoding="UTF-8" location="locale/messages"/>
		<bundle scope="browser" encoding="UTF-8" location="locale/messages_browser"/>
	</i18n>
</plugin>