[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
22.6 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 section @documentlanguage ll[_cc]
: Set the Document Language, for the Texinfo
command interface).
The Gettext framework is used for those strings (see Top in Gettext). 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 gettext
(the choice can be made
at build-time).
The Gettext domain ‘texinfo_document’ is used for the strings.
Translated strings are written as Texinfo, and may include
@-commands. In translated strings, the varying parts of the string
are not usually denoted by %s
and the like, but by
‘{arg_name}’. (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}
These Perl-style brace format strings are used for two reasons: first,
changing the order of printf
arguments is only available since
Perl 5.8.0; second, and more importantly, the order of arguments
is unpredictable, since @-command expansion may lead to different
orders depending on the output format.
The expansion of a translation string is done like this:
- 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’. If that does not exist, and the encoding is not
us-ascii
, thenus-ascii
is tried.The idea is that if there is a
us-ascii
encoding, it means that all the characters in the charset may be expressed as @-commands. For example, there is afr.us-ascii
locale that can accommodate any encoding, since all the Latin 1 characters have associated @-commands. On the other hand, Japanese has only a translationja.utf-8
, since there are no @-commands for Japanese characters. - Next, the string is expanded as Texinfo, and converted. The arguments are substituted; for example, ‘{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 having translations available in different encodings for encodings which can be covered by @-commands, and also specifying how the formatting for some commands is done, independently of the output format—yet still be language-dependent. 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.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on October 2, 2013 using texi2html 5.0.