INTRODUCTION

The translation system in Zonemaster is a two-step process, where internal message tags are first translated to English strings with argument placeholders, and a second step where GNU gettext is used to translate the strings to other languages and fill in the placeholders based on provided data.

FOR DEVELOPERS OF ZONEMASTER TEST MODULES

Your test code should produce log messages with message tags, as documented elsewhere. These tags will be used for translation to human language, for determining the severity of the even logged and to make the events easily used by other software.

Each test module must also have a method named translation(). This method must return a reference to a hash, in which the keys are message tags (short form, without module specification), and the corresponding values a string describing the meaning of the tag in English. In this string can be placeholders of the form {somename}, which will be replaced by the value of the log entry argument named somename.

The English string with its placeholders will be used as a key to look up corresponding translated strings in other languages, so be very careful about editing them!

Every time you have added, removed or modified a tag or its arguments, re-run the extract_po.pl script as descibed in the next section.

FOR TRANSLATORS

The translation files live in the subdirectory share in the Zonemaster::Engine source directory, and are named as {language_code}.po (for example, en.po, sv.po or fr.po). The master file is en.po. All other translations should be based on that file, and that file should never be edited. It is produced by running the script util/extract_po.pl, which will walk through all installed Zonemaster::Engine test modules, pull out their provided English translations and make these into a valid po file. This should only be necessary to do when a developer has added or changed a test module. If the new code is installed, just running the script works. If the new code has not been installed, run the script with an -I flag pointing at the edited module(s).

In order to make a new translation usable, it must be compiled to mo format and installed. The first step needs the msgfmt program from the GNU gettext package to be installed and available in the shell path. As long as it is, it should be enough to go to the share directory and run make.

For the new translation to actually be installed, the mo file must be added to the MANIFEST file. At the end of the make run, it should have printed a list of all the paths that has to be there. Just open MANIFEST in a text editor, check that all the lines are in there and add any that are missing (if you just added a new translation, that will be missing, for example).

Once the new translation is compiled and added to MANIFEST, the normal Perl make install process will install it.

Don't forget to commit the new po and mo files to git.