Internationalization#

ResourceBundle is used to handle the ReportNode messages internationalization. It enables to load locale translation from properties files containing locale-specific data (dictionary with key = value).

As usual for resource bundles:

  • the default translation for any translation key must be present in the reports.properties file,

  • a locale dictionary is represented by a reports_<locale>.properties file in the bundle with the locale as suffix (for instance: for the locale en_US the dictionary is in the reports_en_US.properties),

  • if no dictionary is present for a given locale (for any of its suffixes) then the mechanism is to fall back to the JVM default locale dictionary,

  • if a translation key is not present in a locale dictionary the mechanism is to fall back to a more general dictionary and if there is still no match the ultimate fallback is on the default dictionary.

Currently, only US English (default language) and French dictionaries are maintained in powsybl repositories. If other languages are needed, you need to add your resource bundle files to your classpath, with the appropriate base name and file name.

Best practices#

Keys#

The keys in the properties files are expected to be ordered in alphabetical order.

The keys are expected to be prefixed with a repository prefix, followed by a module prefix, possibly a submodule prefix, all separated with a . character. For instance, the key core.iidm.modification.voltageLevelRemoved corresponds to a report in powsybl-iidm-modification module, which is a submodule of powsybl-iidm inside the powsybl-core repository.

Bundles#

To facilitate the translations, it is recommended to have a single resource bundle per repository. For instance, all the reports within powsybl-core are gathered into a single resource bundle, located in the commons module, its bundle base name being com.powsybl.commons.reports.

Services#

To make your resource bundle easily available to the user with the ReportNodeBuilder::withAllResourceBundlesFromClasspath method, please add an implementation of ReportResourceBundle marked as a service for all the added bundles.

Unit test#

If test message templates are needed, it is recommended to have the following test resource bundle basename: "i18n.reports".

Going further#

  • If you need internationalization but ResourceBundle does not suit your needs, you can add a custom message template provider at the ReportNode root creation. Your custom message template provider needs to provide a string based on a message key and a Locale.

  • The ReportNode provided serializer writes the dictionary of all the keys used in the Locale provided at root creation. If you need a multilingual JSON file, note that the JSON format supports a list of dictionaries. The ReportNode deserializer allows to choose one dictionary among the provided list (see import).