19.5 Internationalization of Document Strings ¶

texi2any writes fixed strings into the output document at various places: cross-references, page footers, the help page, alternate text for images, and so on. The string chosen depends on the value of the documentlanguage at the time of the string being output (see @documentlanguage ll[_cc]: Set the Document Language, for the Texinfo command interface).

The Gettext framework with the ‘texinfo_document’ domain is used for those strings (see Gettext). Translated strings are written as Texinfo, and may include @-commands. In translated strings, the varying parts of the string are denoted by ‘{arg_name}’, but not by %s and the like. (This convention is common for gettext in Perl and is fully supported in GNU Gettext; see Perl Format Strings in GNU Gettext.) For example, in the following, ‘{section}’ will be replaced by the section name:

see {section}

The expansion of a translation string is done like this:

1. First, the string is translated. The locale is documentlanguage.documentencoding.

   If the documentlanguage has the form ‘ll_CC’, that is tried first, and then just ‘ll’.

2. Next, in most cases, the string is expanded as Texinfo, and converted. The arguments are substituted; for example, ‘{arg_name}’ is replaced by the corresponding actual argument.

   It is also possible for the string and the argument to be already converted. In that case, the arguments are simply substituted. Similarly, ‘{arg_name}’ is replaced by the corresponding actual argument.

In the following example, ‘{date}’, ‘{program_homepage}’ and ‘{program}’ are the arguments of the string. Since they are used in @uref, their order is not predictable. ‘{date}’, ‘{program_homepage}’ and ‘{program}’ are substituted after the expansion:

Generated on @emph{{date}} using
@uref{{program_homepage}, @emph{{program}}}.

This approach is admittedly a bit complicated. Its usefulness is that it supports specifying the formatting of the translated string independently of the output format.

For example, the ‘@pxref’ translation string can be like this:

see {node_file_href} section `{section}' in @cite{{book}}

which allows for specifying a string independently of the output format, while nevertheless with rich formatting it may be translated appropriately in many languages.

If Perl is used for strings translation in texi2any, the libintl-perl package is used as the gettext implementation; more specifically, the pure Perl implementation is used, so Texinfo can support consistent behavior across all platforms and installations, which would not otherwise be possible. libintl-perl is included in the Texinfo distribution and always installed, to ensure that it is available if needed. It is also possible to use the system libintl-perl (the choice can be made at build-time).