=head1 TRANSLATION

=head2 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 F<share> directory in the
L<Zonemaster::Engine> source directory and all commands described here are
executed from that directory.

=head2 For translators

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

=head2 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 C<tag_descriptions()>.
This method must return a reference to a hash whose entries are expected to look
like this, where C<MESSAGE_TAG> is a message, C<TEST_MODULE> is the name of a
test module tag and C<"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.

=head2 For Zonemaster package maintainers

In order to make a new translation usable, it must be compiled to C<mo> format
and installed. The first step needs the C<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 F<share> directory and run C<make>.
This is automatically done when following the release instructions.

For the new translation to actually be installed, the C<mo> file must be added
to the F<MANIFEST> file. At the end of the C<make> run, it should have printed
a list of all the paths that has to be there. Just open F<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 F<MANIFEST>, the normal Perl
C<make install> process will install it.
