Translation handling

This chapter contains information about the handling of translation from the NLS interface.

Translation formats

Using the one of the methods NLS.get(String key, Object…​ args) or NLS.get(Class<?> key, String subKey, Object…​ args) the passed args will be used to format the translation value (if the value is correct).

NILS comes with two implementation using formatting:

  • TranslationFormatter.MESSAGE_FORMAT : This implementation uses MessageFormat.format()

  • TranslationFormatter.STRING_FORMAT : This implementation uses String.format()

The default is the MESSAGE_FORMAT varient (as offen used by resource bundles).

The NilsConfig has an option to change this: translationFormatter(TranslationFormatter).

You can also implement your own TranslationFormatter and set it with these options.

During the translation of a format an exception could be thrown, if a format or the syntax is invalid.

Missing Translations

NILS provides two behaviours if translations could not be found:

  1. Return the requested key with some characters around it.

  2. Throw an Exception, that the translation could not be found.

The first one is the default case. If a translation key was not found the translation surrounded by [ and ] will be returned (i. e. [persons.name]).

The NilsConfig provides methods to configure this:

  • suppressErrors(true) : Sets the flag to true, no exception is thrown. The default is throwing an Exception.

  • escapePattern("@{0}") : Escape a missing translation in the format @persons.name. The default is [{0}]. The escapePattern must contain the string "{0}".

Include Translations

This section descriptions the core concept of include translations keys. It uses ResourceBundles for the explaination. See the adapter documentation for the information how includes are configured and handled.

NILS provides a simple way to include translations from already defined keys.

Let’s asume you have a class person with the attribute surname, firstName and birthday. Also you have an inherited class called Employee. Normally you must define all keys in a ResourceBundle like

Person.surname = Surname
Person.firstname = First name
Person.birthday = Birthday

Employee.surname = Surname
Employee.firstname = First name
Employee.birthday = Birthday

With NILS you can include the keys from the Person easyly by using the include tag at the Employee.

Person.surname = Surname
Person.firstname = First name
Person.birthday = Birthday

Employee._include = Person      (1)
Employee.surname = Family name  (2)
1 This line include all keys from Person. If your application request for example Employee.firstname NILS will do a lookup and return the value from Person.firstname.
2 Employee overwrites the key for surname. So Employee.surname will return 'Family name' instead of 'Surname'.

If you want to include more that one base you can add the values semicolon separated:

Employee._include = Person;com.myproject.BaseClass

The ordering is important. The first look up will be taken on Person. If 'Person' has no translation for the requested key, com.myproject.BaseClass will be called next.

The NilsConfig provides a method to configure the include tag:

  • includeTag(String): Set the tag used for including other keys. The default is _include.