64 lines
2.8 KiB
Plaintext
64 lines
2.8 KiB
Plaintext
|
=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.
|