TRANSLATION

Introduction

The translation system in Zonemaster is a two-step process, where internal message tags are first replaced by 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.

All translation files live in the share directory in the Zonemaster::Engine source directory and all commands described here are executed from that directory.

For translators

Instructions for translators can be found at https://github.com/zonemaster/zonemaster/blob/develop/docs/internal/maintenance/Instructions-for-translators.md

For developers of Zonemaster test modules

The test module 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 event logged and to make the events easily used by other software.

Each test module must also have a method named tag_descriptions(). This method must return a reference to a hash whose entries are expected to look like this, where MESSAGE_TAG is a message, TEST_MODULE is the name of a test module tag and "Hello, {name}!" is a message id:

    MESSAGE_TAG => sub {
        __x    # TEST_MODULE:MESSAGE_TAG
          "Hello, {name}!", @_;
    },

A number of things are important here. Keys in the hashref are message tags and values are coderefs. The coderef calls Locale::TextDomain::__x() with a Perl brace format string (a.k.a. message id) and passes along its own @_). The coderef propagates the return value of Locale::TextDomain::__x(). The line immediately before the format string contains a comment consisting of the module name, a colon and the message tag.

The format strings themselves, the comments and the line numbers of the __x calls are used by the gettext tooling when updating the PO files with new message ids and old message strings.

For Zonemaster package maintainers

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. This is automatically done when following the release instructions.

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.