JezK
Edit File: Internationalization-of-Document-Strings.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ --> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <!-- This manual is for GNU Texinfo (version 6.8, 8 June 2021), a documentation system that can produce both online information and a printed manual from a single source using semantic markup. Copyright (C) 1988, 1990-1993, 1995-1999, 2001-2021 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". --> <title>Internationalization of Document Strings (GNU Texinfo 6.8)</title> <meta name="description" content="Internationalization of Document Strings (GNU Texinfo 6.8)"> <meta name="keywords" content="Internationalization of Document Strings (GNU Texinfo 6.8)"> <meta name="resource-type" content="document"> <meta name="distribution" content="global"> <meta name="Generator" content="texi2any"> <meta name="viewport" content="width=device-width,initial-scale=1"> <link href="index.html" rel="start" title="Top"> <link href="Command-and-Variable-Index.html" rel="index" title="Command and Variable Index"> <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> <link href="Generic-Translator-texi2any.html" rel="up" title="Generic Translator texi2any"> <link href="Invoking-pod2texi.html" rel="next" title="Invoking pod2texi"> <link href="Customization-Variables.html" rel="prev" title="Customization Variables"> <style type="text/css"> <!-- a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em} a.summary-letter {text-decoration: none} blockquote.indentedblock {margin-right: 0em} div.display {margin-left: 3.2em} div.example {margin-left: 3.2em} kbd {font-style: oblique} pre.display {font-family: inherit} pre.format {font-family: inherit} pre.menu-comment {font-family: serif} pre.menu-preformatted {font-family: serif} span.nolinebreak {white-space: nowrap} span.roman {font-family: initial; font-weight: normal} span.sansserif {font-family: sans-serif; font-weight: normal} span:hover a.copiable-anchor {visibility: visible} ul.no-bullet {list-style: none} --> </style> </head> <body lang="en"> <div class="section" id="Internationalization-of-Document-Strings"> <div class="header"> <p> Next: <a href="Invoking-pod2texi.html" accesskey="n" rel="next">Invoking <code>pod2texi</code>: Convert POD to Texinfo</a>, Previous: <a href="Customization-Variables.html" accesskey="p" rel="prev">Customization Variables</a>, Up: <a href="Generic-Translator-texi2any.html" accesskey="u" rel="up"><code>texi2any</code>: The Generic Translator for Texinfo</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html" title="Index" rel="index">Index</a>]</p> </div> <hr> <span id="Internationalization-of-Document-Strings-1"></span><h3 class="section">19.5 Internationalization of Document Strings</h3> <span id="index-I18n_002c-of-document-strings"></span> <span id="index-Internationalization-of-document-strings"></span> <span id="index-Document-strings_002c-internationalization-of"></span> <span id="index-Output-document-strings_002c-internationalization-of"></span> <span id="index-Translating-strings-in-output-documents"></span> <span id="index-documentlanguage-customization-variable"></span> <p><code>texi2any</code> 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 <code>documentlanguage</code> at the time of the string being output (see <a href="_0040documentlanguage.html"><code>@documentlanguage <var>ll</var>[_<var>cc</var>]</code>: Set the Document Language</a>, for the Texinfo command interface). </p> <span id="index-libintl_002dperl-Gettext-implementation"></span> <p>The Gettext framework is used for those strings (see <cite><a data-manual="gettext" href="../gettext/index.html#Top">Gettext</a></cite>). The <code>libintl-perl</code> package is used as the <code>gettext</code> 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. <code>libintl-perl</code> 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 <code>gettext</code> (the choice can be made at build-time). </p> <span id="index-texinfo_005fdocument-Gettext-domain"></span> <span id="index-Perl-format-strings-for-translation"></span> <p>The Gettext domain ‘<samp>texinfo_document</samp>’ 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 <code>%s</code> and the like, but by ‘<samp>{arg_name}</samp>’. (This convention is common for <code>gettext</code> in Perl and is fully supported in GNU Gettext; see <a data-manual="gettext" href="../gettext/perl_002dformat.html#perl_002dformat">Perl Format Strings</a> in <cite>GNU Gettext</cite>.) For example, in the following, ‘<samp>{section}</samp>’ will be replaced by the section name: </p> <div class="example"> <pre class="example">see {section} </pre></div> <p>These Perl-style brace format strings are used for two reasons: first, changing the order of <code>printf</code> 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. </p> <p>The expansion of a translation string is done like this: </p> <ol> <li> First, the string is translated. The locale is <var>@documentlanguage</var><code>.</code><var>@documentencoding</var>. <span id="index-us_002dascii-encoding_002c-and-translations"></span> <p>If the <var>@documentlanguage</var> has the form ‘<samp>ll_CC</samp>’, that is tried first, and then just ‘<samp>ll</samp>’. If that does not exist, and the encoding is not <code>us-ascii</code>, then <code>us-ascii</code> is tried. </p> <p>The idea is that if there is a <code>us-ascii</code> encoding, it means that all the characters in the charset may be expressed as @-commands. For example, there is a <code>fr.us-ascii</code> locale that can accommodate any encoding, since all the Latin 1 characters have associated @-commands. On the other hand, Japanese has only a translation <code>ja.utf-8</code>, since there are no @-commands for Japanese characters. </p> </li><li> Next, the string is expanded as Texinfo, and converted. The arguments are substituted; for example, ‘<samp>{arg_name}</samp>’ is replaced by the corresponding actual argument. </li></ol> <p>In the following example, ‘<samp>{date}</samp>’, ‘<samp>{program_homepage}</samp>’ and ‘<samp>{program}</samp>’ are the arguments of the string. Since they are used in <code>@uref</code>, their order is not predictable. ‘<samp>{date}</samp>’, ‘<samp>{program_homepage}</samp>’ and ‘<samp>{program}</samp>’ are substituted after the expansion: </p> <div class="example"> <pre class="example">Generated on @emph{{date}} using @uref{{program_homepage}, @emph{{program}}}. </pre></div> <p>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 ‘<samp>@pxref</samp>’ translation string can be like this: </p> <div class="example"> <pre class="example">see {node_file_href} section `{section}\' in @cite{{book}} </pre></div> <p>which allows for specifying a string independently of the output format, while nevertheless with rich formatting it may be translated appropriately in many languages. </p> </div> <hr> <div class="header"> <p> Next: <a href="Invoking-pod2texi.html">Invoking <code>pod2texi</code>: Convert POD to Texinfo</a>, Previous: <a href="Customization-Variables.html">Customization Variables</a>, Up: <a href="Generic-Translator-texi2any.html"><code>texi2any</code>: The Generic Translator for Texinfo</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Command-and-Variable-Index.html" title="Index" rel="index">Index</a>]</p> </div> </body> </html>