Mercurial > repos > rliterman > csp2
diff CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/gettext/gettext_13.html @ 68:5028fdace37b
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
| author | jpayne |
|---|---|
| date | Tue, 18 Mar 2025 16:23:26 -0400 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/gettext/gettext_13.html Tue Mar 18 16:23:26 2025 -0400 @@ -0,0 +1,1485 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd"> +<html> +<!-- Created on February, 21 2024 by texi2html 1.78a --> +<!-- +Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author) + Karl Berry <karl@freefriends.org> + Olaf Bachmann <obachman@mathematik.uni-kl.de> + and many others. +Maintained by: Many creative people. +Send bugs and suggestions to <texi2html-bug@nongnu.org> + +--> +<head> +<title>GNU gettext utilities: 13. The Maintainer's View</title> + +<meta name="description" content="GNU gettext utilities: 13. The Maintainer's View"> +<meta name="keywords" content="GNU gettext utilities: 13. The Maintainer's View"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="texi2html 1.78a"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +pre.display {font-family: serif} +pre.format {font-family: serif} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: serif; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: serif; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.roman {font-family:serif; font-weight:normal;} +span.sansserif {font-family:sans-serif; font-weight:normal;} +ul.toc {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> + +<table cellpadding="1" cellspacing="1" border="0"> +<tr><td valign="middle" align="left">[<a href="gettext_12.html#SEC217" title="Beginning of this chapter or previous chapter"> << </a>]</td> +<td valign="middle" align="left">[<a href="gettext_14.html#SEC262" title="Next chapter"> >> </a>]</td> +<td valign="middle" align="left"> </td> +<td valign="middle" align="left"> </td> +<td valign="middle" align="left"> </td> +<td valign="middle" align="left"> </td> +<td valign="middle" align="left"> </td> +<td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td> +<td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td> +<td valign="middle" align="left">[<a href="gettext_21.html#SEC389" title="Index">Index</a>]</td> +<td valign="middle" align="left">[<a href="gettext_abt.html#SEC_About" title="About (help)"> ? </a>]</td> +</tr></table> + +<hr size="2"> +<a name="Maintainers"></a> +<a name="SEC230"></a> +<h1 class="chapter"> <a href="gettext_toc.html#TOC223">13. The Maintainer's View</a> </h1> + +<p>The maintainer of a package has many responsibilities. One of them +is ensuring that the package will install easily on many platforms, +and that the magic we described earlier (see section <a href="gettext_2.html#SEC7">The User's View</a>) will work +for installers and end users. +</p> +<p>Of course, there are many possible ways by which GNU <code>gettext</code> +might be integrated in a distribution, and this chapter does not cover +them in all generality. Instead, it details one possible approach which +is especially adequate for many free software distributions following GNU +standards, or even better, Gnits standards, because GNU <code>gettext</code> +is purposely for helping the internationalization of the whole GNU +project, and as many other good free packages as possible. So, the +maintainer's view presented here presumes that the package already has +a ‘<tt>configure.ac</tt>’ file and uses GNU Autoconf. +</p> +<p>Nevertheless, GNU <code>gettext</code> may surely be useful for free packages +not following GNU standards and conventions, but the maintainers of such +packages might have to show imagination and initiative in organizing +their distributions so <code>gettext</code> work for them in all situations. +There are surely many, out there. +</p> +<p>Even if <code>gettext</code> methods are now stabilizing, slight adjustments +might be needed between successive <code>gettext</code> versions, so you +should ideally revise this chapter in subsequent releases, looking +for changes. +</p> + + +<a name="Flat-and-Non_002dFlat"></a> +<a name="SEC231"></a> +<h2 class="section"> <a href="gettext_toc.html#TOC224">13.1 Flat or Non-Flat Directory Structures</a> </h2> + +<p>Some free software packages are distributed as <code>tar</code> files which unpack +in a single directory, these are said to be <em>flat</em> distributions. +Other free software packages have a one level hierarchy of subdirectories, using +for example a subdirectory named ‘<tt>doc/</tt>’ for the Texinfo manual and +man pages, another called ‘<tt>lib/</tt>’ for holding functions meant to +replace or complement C libraries, and a subdirectory ‘<tt>src/</tt>’ for +holding the proper sources for the package. These other distributions +are said to be <em>non-flat</em>. +</p> +<p>We cannot say much about flat distributions. A flat +directory structure has the disadvantage of increasing the difficulty +of updating to a new version of GNU <code>gettext</code>. Also, if you have +many PO files, this could somewhat pollute your single directory. +Also, GNU <code>gettext</code>'s libintl sources consist of C sources, shell +scripts, <code>sed</code> scripts and complicated Makefile rules, which don't +fit well into an existing flat structure. For these reasons, we +recommend to use non-flat approach in this case as well. +</p> +<p>Maybe because GNU <code>gettext</code> itself has a non-flat structure, +we have more experience with this approach, and this is what will be +described in the remaining of this chapter. Some maintainers might +use this as an opportunity to unflatten their package structure. +</p> + +<a name="Prerequisites"></a> +<a name="SEC232"></a> +<h2 class="section"> <a href="gettext_toc.html#TOC225">13.2 Prerequisite Works</a> </h2> + +<p>There are some works which are required for using GNU <code>gettext</code> +in one of your package. These works have some kind of generality +that escape the point by point descriptions used in the remainder +of this chapter. So, we describe them here. +</p> +<ul> +<li> +Before attempting to use <code>gettextize</code> you should install some +other packages first. +Ensure that recent versions of GNU <code>m4</code>, GNU Autoconf and GNU +<code>gettext</code> are already installed at your site, and if not, proceed +to do this first. If you get to install these things, beware that +GNU <code>m4</code> must be fully installed before GNU Autoconf is even +<em>configured</em>. + +<p>To further ease the task of a package maintainer the <code>automake</code> +package was designed and implemented. GNU <code>gettext</code> now uses this +tool and the ‘<tt>Makefile</tt>’ in the ‘<tt>po/</tt>’ directory therefore +knows about all the goals necessary for using <code>automake</code>. +</p> +<p>Those four packages are only needed by you, as a maintainer; the +installers of your own package and end users do not really need any of +GNU <code>m4</code>, GNU Autoconf, GNU <code>gettext</code>, or GNU <code>automake</code> +for successfully installing and running your package, with messages +properly translated. But this is not completely true if you provide +internationalized shell scripts within your own package: GNU +<code>gettext</code> shall then be installed at the user site if the end users +want to see the translation of shell script messages. +</p> +</li><li> +Your package should use Autoconf and have a ‘<tt>configure.ac</tt>’ or +‘<tt>configure.in</tt>’ file. +If it does not, you have to learn how. The Autoconf documentation +is quite well written, it is a good idea that you print it and get +familiar with it. + +</li><li> +Your C sources should have already been modified according to +instructions given earlier in this manual. See section <a href="gettext_4.html#SEC17">Preparing Program Sources</a>. + +</li><li> +Your ‘<tt>po/</tt>’ directory should receive all PO files submitted to you +by the translator teams, each having ‘<tt><var>ll</var>.po</tt>’ as a name. +This is not usually easy to get translation +work done before your package gets internationalized and available! +Since the cycle has to start somewhere, the easiest for the maintainer +is to start with absolutely no PO files, and wait until various +translator teams get interested in your package, and submit PO files. + +</li></ul> + +<p>It is worth adding here a few words about how the maintainer should +ideally behave with PO files submissions. As a maintainer, your role is +to authenticate the origin of the submission as being the representative +of the appropriate translating teams of the Translation Project (forward +the submission to ‘<tt>coordinator@translationproject.org</tt>’ in case of doubt), +to ensure that the PO file format is not severely broken and does not +prevent successful installation, and for the rest, to merely put these +PO files in ‘<tt>po/</tt>’ for distribution. +</p> +<p>As a maintainer, you do not have to take on your shoulders the +responsibility of checking if the translations are adequate or +complete, and should avoid diving into linguistic matters. Translation +teams drive themselves and are fully responsible of their linguistic +choices for the Translation Project. Keep in mind that translator teams are <em>not</em> +driven by maintainers. You can help by carefully redirecting all +communications and reports from users about linguistic matters to the +appropriate translation team, or explain users how to reach or join +their team. +</p> +<p>Maintainers should <em>never ever</em> apply PO file bug reports +themselves, short-cutting translation teams. If some translator has +difficulty to get some of her points through her team, it should not be +an option for her to directly negotiate translations with maintainers. +Teams ought to settle their problems themselves, if any. If you, as +a maintainer, ever think there is a real problem with a team, please +never try to <em>solve</em> a team's problem on your own. +</p> + +<a name="gettextize-Invocation"></a> +<a name="SEC233"></a> +<h2 class="section"> <a href="gettext_toc.html#TOC226">13.3 Invoking the <code>gettextize</code> Program</a> </h2> + + +<p>The <code>gettextize</code> program is an interactive tool that helps the +maintainer of a package internationalized through GNU <code>gettext</code>. +It is used for two purposes: +</p> +<ul> +<li> +As a wizard, when a package is modified to use GNU <code>gettext</code> for +the first time. + +</li><li> +As a migration tool, for upgrading the GNU <code>gettext</code> support in +a package from a previous to a newer version of GNU <code>gettext</code>. +</li></ul> + +<p>This program performs the following tasks: +</p> +<ul> +<li> +It copies into the package some files that are consistently and +identically needed in every package internationalized through +GNU <code>gettext</code>. + +</li><li> It performs as many of the tasks mentioned in the next section +<a href="#SEC234">Files You Must Create or Alter</a> as can be performed automatically. + +</li><li> It removes obsolete files and idioms used for previous GNU +<code>gettext</code> versions to the form recommended for the current GNU +<code>gettext</code> version. + +</li><li> It prints a summary of the tasks that ought to be done manually +and could not be done automatically by <code>gettextize</code>. +</li></ul> + +<p>It can be invoked as follows: +</p> +<a name="IDX1090"></a> +<a name="IDX1091"></a> +<table><tr><td> </td><td><pre class="example">gettextize [ <var>option</var>… ] [ <var>directory</var> ] +</pre></td></tr></table> + +<p>and accepts the following options: +</p> +<dl compact="compact"> +<dt> ‘<samp>-f</samp>’</dt> +<dt> ‘<samp>--force</samp>’</dt> +<dd><a name="IDX1092"></a> +<a name="IDX1093"></a> +<p>Force replacement of files which already exist. +</p> +</dd> +<dt> ‘<samp>--po-dir=<var>dir</var></samp>’</dt> +<dd><a name="IDX1094"></a> +<p>Specify a directory containing PO files. Such a directory contains the +translations into various languages of a particular POT file. This +option can be specified multiple times, once for each translation domain. +If it is not specified, the directory named ‘<tt>po/</tt>’ is updated. +</p> +</dd> +<dt> ‘<samp>--no-changelog</samp>’</dt> +<dd><a name="IDX1095"></a> +<p>Don't update or create ChangeLog files. By default, <code>gettextize</code> +logs all changes (file additions, modifications and removals) in a +file called ‘<samp>ChangeLog</samp>’ in each affected directory. +</p> +</dd> +<dt> ‘<samp>--symlink</samp>’</dt> +<dd><a name="IDX1096"></a> +<p>Make symbolic links instead of copying the needed files. This can be +useful to save a few kilobytes of disk space, but it requires extra +effort to create self-contained tarballs, it may disturb some mechanism +the maintainer applies to the sources, and it is likely to introduce +bugs when a newer version of <code>gettext</code> is installed on the system. +</p> +</dd> +<dt> ‘<samp>-n</samp>’</dt> +<dt> ‘<samp>--dry-run</samp>’</dt> +<dd><a name="IDX1097"></a> +<a name="IDX1098"></a> +<p>Print modifications but don't perform them. All actions that +<code>gettextize</code> would normally execute are inhibited and instead only +listed on standard output. +</p> +</dd> +<dt> ‘<samp>--help</samp>’</dt> +<dd><a name="IDX1099"></a> +<p>Display this help and exit. +</p> +</dd> +<dt> ‘<samp>--version</samp>’</dt> +<dd><a name="IDX1100"></a> +<p>Output version information and exit. +</p> +</dd> +</dl> + +<p>If <var>directory</var> is given, this is the top level directory of a +package to prepare for using GNU <code>gettext</code>. If not given, it +is assumed that the current directory is the top level directory of +such a package. +</p> +<p>The program <code>gettextize</code> provides the following files. However, +no existing file will be replaced unless the option <code>--force</code> +(<code>-f</code>) is specified. +</p> +<ol> +<li> +The ‘<tt>ABOUT-NLS</tt>’ file is copied in the main directory of your package, +the one being at the top level. This file contains a reference to the +GNU gettext documentation. It also avoids an error from Automake in +packages that use the Automake option ‘<samp>gnu</samp>’ or ‘<samp>gnits</samp>’: +“error: required file './ABOUT-NLS' not found”. + +</li><li> +A ‘<tt>po/</tt>’ directory is created for eventually holding +all translation files, but initially only containing the file +‘<tt>po/Makefile.in.in</tt>’ from the GNU <code>gettext</code> distribution +(beware the double ‘<samp>.in</samp>’ in the file name) and a few auxiliary +files. If the ‘<tt>po/</tt>’ directory already exists, it will be preserved +along with the files it contains, and only ‘<tt>Makefile.in.in</tt>’ and +the auxiliary files will be overwritten. + +<p>If ‘<samp>--po-dir</samp>’ has been specified, this holds for every directory +specified through ‘<samp>--po-dir</samp>’, instead of ‘<tt>po/</tt>’. +</p> +</li><li> +The file ‘<tt>config.rpath</tt>’ is copied into the directory containing +configuration support files. It is needed by the <code>AM_GNU_GETTEXT</code> +autoconf macro. + +</li><li> +Only if the project is using GNU <code>automake</code>: +A set of <code>autoconf</code> macro files is copied into the package's +<code>autoconf</code> macro repository, usually in a directory called ‘<tt>m4/</tt>’. +</li></ol> + +<p>If your site support symbolic links, <code>gettextize</code> will not +actually copy the files into your package, but establish symbolic +links instead. This avoids duplicating the disk space needed in +all packages. Merely using the ‘<samp>-h</samp>’ option while creating the +<code>tar</code> archive of your distribution will resolve each link by an +actual copy in the distribution archive. So, to insist, you really +should use ‘<samp>-h</samp>’ option with <code>tar</code> within your <code>dist</code> +goal of your main ‘<tt>Makefile.in</tt>’. +</p> +<p>Furthermore, <code>gettextize</code> will update all ‘<tt>Makefile.am</tt>’ files +in each affected directory, as well as the top level ‘<tt>configure.ac</tt>’ +or ‘<tt>configure.in</tt>’ file. +</p> +<p>It is interesting to understand that most new files for supporting +GNU <code>gettext</code> facilities in one package go in ‘<tt>po/</tt>’ and +‘<tt>m4/</tt>’ subdirectories. Still, these directories will mostly +contain package dependent files. +</p> +<p>The <code>gettextize</code> program makes backup files for all files it +replaces or changes, and also write ChangeLog entries about these +changes. This way, the careful maintainer can check after running +<code>gettextize</code> whether its changes are acceptable to him, and +possibly adjust them. An exception to this rule is the ‘<tt>intl/</tt>’ +directory, which is removed as a whole if it still existed. +</p> +<p>It is important to understand that <code>gettextize</code> can not do the +entire job of adapting a package for using GNU <code>gettext</code>. The +amount of remaining work depends on whether the package uses GNU +<code>automake</code> or not. But in any case, the maintainer should still +read the section <a href="#SEC234">Files You Must Create or Alter</a> after invoking <code>gettextize</code>. +</p> +<p>In particular, if after using ‘<samp>gettexize</samp>’, you get an error +‘<samp>AC_COMPILE_IFELSE was called before AC_GNU_SOURCE</samp>’ or +‘<samp>AC_RUN_IFELSE was called before AC_GNU_SOURCE</samp>’, you can fix it +by modifying ‘<tt>configure.ac</tt>’, as described in <a href="#SEC239">‘<tt>configure.ac</tt>’ at top level</a>. +</p> +<p>It is also important to understand that <code>gettextize</code> is not part +of the GNU build system, in the sense that it should not be invoked +automatically, and not be invoked by someone who doesn't assume the +responsibilities of a package maintainer. For the latter purpose, a +separate tool is provided, see <a href="#SEC258">Invoking the <code>autopoint</code> Program</a>. +</p> + +<a name="Adjusting-Files"></a> +<a name="SEC234"></a> +<h2 class="section"> <a href="gettext_toc.html#TOC227">13.4 Files You Must Create or Alter</a> </h2> + +<p>Besides files which are automatically added through <code>gettextize</code>, +there are many files needing revision for properly interacting with +GNU <code>gettext</code>. If you are closely following GNU standards for +Makefile engineering and auto-configuration, the adaptations should +be easier to achieve. Here is a point by point description of the +changes needed in each. +</p> +<p>So, here comes a list of files, each one followed by a description of +all alterations it needs. Many examples are taken out from the GNU +<code>gettext</code> 0.22.5 distribution itself, or from the GNU +<code>hello</code> distribution (<a href="https://www.gnu.org/software/hello">https://www.gnu.org/software/hello</a>). +You may indeed refer to the source code of the GNU <code>gettext</code> and +GNU <code>hello</code> packages, as they are intended to be good examples for +using GNU gettext functionality. +</p> + + +<a name="po_002fPOTFILES_002ein"></a> +<a name="SEC235"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC228">13.4.1 ‘<tt>POTFILES.in</tt>’ in ‘<tt>po/</tt>’</a> </h3> + +<p>The ‘<tt>po/</tt>’ directory should receive a file named +‘<tt>POTFILES.in</tt>’. This file tells which files, among all program +sources, have marked strings needing translation. Here is an example +of such a file: +</p> +<table><tr><td> </td><td><pre class="example"># List of source files containing translatable strings. +# Copyright (C) 1995 Free Software Foundation, Inc. + +# Common library files +lib/error.c +lib/getopt.c +lib/xmalloc.c + +# Package source files +src/gettext.c +src/msgfmt.c +src/xgettext.c +</pre></td></tr></table> + +<p>Hash-marked comments and white lines are ignored. All other lines +list those source files containing strings marked for translation +(see section <a href="gettext_4.html#SEC28">How Marks Appear in Sources</a>), in a notation relative to the top level +of your whole distribution, rather than the location of the +‘<tt>POTFILES.in</tt>’ file itself. +</p> +<p>When a C file is automatically generated by a tool, like <code>flex</code> or +<code>bison</code>, that doesn't introduce translatable strings by itself, +it is recommended to list in ‘<tt>po/POTFILES.in</tt>’ the real source file +(ending in ‘<tt>.l</tt>’ in the case of <code>flex</code>, or in ‘<tt>.y</tt>’ in the +case of <code>bison</code>), not the generated C file. +</p> + +<a name="po_002fLINGUAS"></a> +<a name="SEC236"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC229">13.4.2 ‘<tt>LINGUAS</tt>’ in ‘<tt>po/</tt>’</a> </h3> + +<p>The ‘<tt>po/</tt>’ directory should also receive a file named +‘<tt>LINGUAS</tt>’. This file contains the list of available translations. +It is a whitespace separated list. Hash-marked comments and white lines +are ignored. Here is an example file: +</p> +<table><tr><td> </td><td><pre class="example"># Set of available languages. +de fr +</pre></td></tr></table> + +<p>This example means that German and French PO files are available, so +that these languages are currently supported by your package. If you +want to further restrict, at installation time, the set of installed +languages, this should not be done by modifying the ‘<tt>LINGUAS</tt>’ file, +but rather by using the <code>LINGUAS</code> environment variable +(see section <a href="gettext_14.html#SEC262">The Installer's and Distributor's View</a>). +</p> +<p>It is recommended that you add the "languages" ‘<samp>en@quot</samp>’ and +‘<samp>en@boldquot</samp>’ to the <code>LINGUAS</code> file. <code>en@quot</code> is a +variant of English message catalogs (<code>en</code>) which uses real quotation +marks instead of the ugly looking asymmetric ASCII substitutes ‘<samp>`</samp>’ +and ‘<samp>'</samp>’. <code>en@boldquot</code> is a variant of <code>en@quot</code> that +additionally outputs quoted pieces of text in a bold font, when used in +a terminal emulator which supports the VT100 escape sequences (such as +<code>xterm</code> or the Linux console, but not Emacs in <kbd>M-x shell</kbd> mode). +</p> +<p>These extra message catalogs ‘<samp>en@quot</samp>’ and ‘<samp>en@boldquot</samp>’ +are constructed automatically, not by translators; to support them, you +need the files ‘<tt>Rules-quot</tt>’, ‘<tt>quot.sed</tt>’, ‘<tt>boldquot.sed</tt>’, +‘<tt>en@quot.header</tt>’, ‘<tt>en@boldquot.header</tt>’, ‘<tt>insert-header.sin</tt>’ +in the ‘<tt>po/</tt>’ directory. You can copy them from GNU gettext's ‘<tt>po/</tt>’ +directory; they are also installed by running <code>gettextize</code>. +</p> + +<a name="po_002fMakevars"></a> +<a name="SEC237"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC230">13.4.3 ‘<tt>Makevars</tt>’ in ‘<tt>po/</tt>’</a> </h3> + +<p>The ‘<tt>po/</tt>’ directory also has a file named ‘<tt>Makevars</tt>’. It +contains variables that are specific to your project. ‘<tt>po/Makevars</tt>’ +gets inserted into the ‘<tt>po/Makefile</tt>’ when the latter is created. +The variables thus take effect when the POT file is created or updated, +and when the message catalogs get installed. +</p> +<p>The first three variables can be left unmodified if your package has a +single message domain and, accordingly, a single ‘<tt>po/</tt>’ directory. +Only packages which have multiple ‘<tt>po/</tt>’ directories at different +locations need to adjust the three first variables defined in +‘<tt>Makevars</tt>’. +</p> +<p>As an alternative to the <code>XGETTEXT_OPTIONS</code> variable, it is also +possible to specify <code>xgettext</code> options through the +<code>AM_XGETTEXT_OPTION</code> autoconf macro. See <a href="#SEC252">AM_XGETTEXT_OPTION in ‘<tt>po.m4</tt>’</a>. +</p> + +<a name="po_002fRules_002d_002a"></a> +<a name="SEC238"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC231">13.4.4 Extending ‘<tt>Makefile</tt>’ in ‘<tt>po/</tt>’</a> </h3> + +<p>All files called ‘<tt>Rules-*</tt>’ in the ‘<tt>po/</tt>’ directory get appended to +the ‘<tt>po/Makefile</tt>’ when it is created. They present an opportunity to +add rules for special PO files to the Makefile, without needing to mess +with ‘<tt>po/Makefile.in.in</tt>’. +</p> +<a name="IDX1101"></a> +<a name="IDX1102"></a> +<p>GNU gettext comes with a ‘<tt>Rules-quot</tt>’ file, containing rules for +building catalogs ‘<tt>en@quot.po</tt>’ and ‘<tt>en@boldquot.po</tt>’. The +effect of ‘<tt>en@quot.po</tt>’ is that people who set their <code>LANGUAGE</code> +environment variable to ‘<samp>en@quot</samp>’ will get messages with proper +looking symmetric Unicode quotation marks instead of abusing the ASCII +grave accent and the ASCII apostrophe for indicating quotations. To +enable this catalog, simply add <code>en@quot</code> to the ‘<tt>po/LINGUAS</tt>’ +file. The effect of ‘<tt>en@boldquot.po</tt>’ is that people who set +<code>LANGUAGE</code> to ‘<samp>en@boldquot</samp>’ will get not only proper quotation +marks, but also the quoted text will be shown in a bold font on terminals +and consoles. This catalog is useful only for command-line programs, not +GUI programs. To enable it, similarly add <code>en@boldquot</code> to the +‘<tt>po/LINGUAS</tt>’ file. +</p> +<p>Similarly, you can create rules for building message catalogs for the +‘<tt>sr@latin</tt>’ locale – Serbian written with the Latin alphabet – +from those for the ‘<tt>sr</tt>’ locale – Serbian written with Cyrillic +letters. See <a href="gettext_9.html#SEC110">Invoking the <code>msgfilter</code> Program</a>. +</p> + +<a name="configure_002eac"></a> +<a name="SEC239"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC232">13.4.5 ‘<tt>configure.ac</tt>’ at top level</a> </h3> + +<p>‘<tt>configure.ac</tt>’ or ‘<tt>configure.in</tt>’ - this is the source from which +<code>autoconf</code> generates the ‘<tt>configure</tt>’ script. +</p> +<ol> +<li> Declare the package and version. +<a name="IDX1103"></a> + +<p>This is done by a set of lines like these: +</p> +<table><tr><td> </td><td><pre class="example">PACKAGE=gettext +VERSION=0.22.5 +AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE") +AC_DEFINE_UNQUOTED(VERSION, "$VERSION") +AC_SUBST(PACKAGE) +AC_SUBST(VERSION) +</pre></td></tr></table> + +<p>or, if you are using GNU <code>automake</code>, by a line like this: +</p> +<table><tr><td> </td><td><pre class="example">AM_INIT_AUTOMAKE(gettext, 0.22.5) +</pre></td></tr></table> + +<p>Of course, you replace ‘<samp>gettext</samp>’ with the name of your package, +and ‘<samp>0.22.5</samp>’ by its version numbers, exactly as they +should appear in the packaged <code>tar</code> file name of your distribution +(‘<tt>gettext-0.22.5.tar.gz</tt>’, here). +</p> +</li><li> Check for internationalization support. + +<p>Here is the main <code>m4</code> macro for triggering internationalization +support. Just add this line to ‘<tt>configure.ac</tt>’: +</p> +<table><tr><td> </td><td><pre class="example">AM_GNU_GETTEXT([external]) +</pre></td></tr></table> + +<p>This call is purposely simple, even if it generates a lot of configure +time checking and actions. +</p> +</li><li> Have output files created. + +<p>The <code>AC_OUTPUT</code> directive, at the end of your ‘<tt>configure.ac</tt>’ +file, needs to be modified in two ways: +</p> +<table><tr><td> </td><td><pre class="example">AC_OUTPUT([<var>existing configuration files</var> po/Makefile.in], +[<var>existing additional actions</var>]) +</pre></td></tr></table> + +<p>The modification to the first argument to <code>AC_OUTPUT</code> asks +for substitution in the ‘<tt>po/</tt>’ directory. +Note the ‘<samp>.in</samp>’ suffix used for ‘<tt>po/</tt>’ only. This is because +the distributed file is really ‘<tt>po/Makefile.in.in</tt>’. +</p> +</li></ol> + + +<a name="config_002eguess"></a> +<a name="SEC240"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC233">13.4.6 ‘<tt>config.guess</tt>’, ‘<tt>config.sub</tt>’ at top level</a> </h3> + +<p>You need to add the GNU ‘<tt>config.guess</tt>’ and ‘<tt>config.sub</tt>’ files +to your distribution. They are needed because the <code>AM_ICONV</code> macro +contains knowledge about specific platforms and therefore needs to +identify the platform. +</p> +<p>You can obtain the newest version of ‘<tt>config.guess</tt>’ and +‘<tt>config.sub</tt>’ from the ‘<samp>config</samp>’ project at +‘<tt>https://savannah.gnu.org/</tt>’. The commands to fetch them are +</p><table><tr><td> </td><td><pre class="smallexample">$ wget -O config.guess 'https://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD' +$ wget -O config.sub 'https://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD' +</pre></td></tr></table> +<p>Less recent versions are also contained in the GNU <code>automake</code> and +GNU <code>libtool</code> packages. +</p> +<p>Normally, ‘<tt>config.guess</tt>’ and ‘<tt>config.sub</tt>’ are put at the +top level of a distribution. But it is also possible to put them in a +subdirectory, altogether with other configuration support files like +‘<tt>install-sh</tt>’, ‘<tt>ltconfig</tt>’, ‘<tt>ltmain.sh</tt>’ or ‘<tt>missing</tt>’. +All you need to do, other than moving the files, is to add the following line +to your ‘<tt>configure.ac</tt>’. +</p> +<table><tr><td> </td><td><pre class="example">AC_CONFIG_AUX_DIR([<var>subdir</var>]) +</pre></td></tr></table> + + +<a name="mkinstalldirs"></a> +<a name="SEC241"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC234">13.4.7 ‘<tt>mkinstalldirs</tt>’ at top level</a> </h3> + +<p>With earlier versions of GNU gettext, you needed to add the GNU +‘<tt>mkinstalldirs</tt>’ script to your distribution. This is not needed any +more. You can remove it. +</p> + +<a name="aclocal"></a> +<a name="SEC242"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC235">13.4.8 ‘<tt>aclocal.m4</tt>’ at top level</a> </h3> + +<p>If you do not have an ‘<tt>aclocal.m4</tt>’ file in your distribution, +the simplest is to concatenate the files ‘<tt>build-to-host.m4</tt>’, +‘<tt>gettext.m4</tt>’, ‘<tt>host-cpu-c-abi.m4</tt>’, ‘<tt>intlmacosx.m4</tt>’, +‘<tt>iconv.m4</tt>’, ‘<tt>lib-ld.m4</tt>’, ‘<tt>lib-link.m4</tt>’, ‘<tt>lib-prefix.m4</tt>’, +‘<tt>nls.m4</tt>’, ‘<tt>po.m4</tt>’, ‘<tt>progtest.m4</tt>’ from GNU <code>gettext</code>'s +‘<tt>m4/</tt>’ directory into a single file. +</p> +<p>If you already have an ‘<tt>aclocal.m4</tt>’ file, then you will have +to merge the said macro files into your ‘<tt>aclocal.m4</tt>’. Note that if +you are upgrading from a previous release of GNU <code>gettext</code>, you +should most probably <em>replace</em> the macros (<code>AM_GNU_GETTEXT</code>, +etc.), as they usually +change a little from one release of GNU <code>gettext</code> to the next. +Their contents may vary as we get more experience with strange systems +out there. +</p> +<p>You should be using GNU <code>automake</code> 1.9 or newer. With it, you need +to copy the files ‘<tt>build-to-host.m4</tt>’, ‘<tt>gettext.m4</tt>’, +‘<tt>host-cpu-c-abi.m4</tt>’, ‘<tt>intlmacosx.m4</tt>’, ‘<tt>iconv.m4</tt>’, +‘<tt>lib-ld.m4</tt>’, ‘<tt>lib-link.m4</tt>’, ‘<tt>lib-prefix.m4</tt>’, ‘<tt>nls.m4</tt>’, +‘<tt>po.m4</tt>’, ‘<tt>progtest.m4</tt>’ from GNU <code>gettext</code>'s ‘<tt>m4/</tt>’ +directory to a subdirectory named ‘<tt>m4/</tt>’ and add the line +</p> +<table><tr><td> </td><td><pre class="example">ACLOCAL_AMFLAGS = -I m4 +</pre></td></tr></table> + +<p>to your top level ‘<tt>Makefile.am</tt>’. +</p> +<p>If you are using GNU <code>automake</code> 1.10 or newer, it is even easier: +Add the line +</p> +<table><tr><td> </td><td><pre class="example">ACLOCAL_AMFLAGS = --install -I m4 +</pre></td></tr></table> + +<p>to your top level ‘<tt>Makefile.am</tt>’, and run ‘<samp>aclocal --install -I m4</samp>’. +This will copy the needed files to the ‘<tt>m4/</tt>’ subdirectory automatically, +before updating ‘<tt>aclocal.m4</tt>’. +</p> +<p>These macros check for the internationalization support functions +and related informations. Hopefully, once stabilized, these macros +might be integrated in the standard Autoconf set, because this +piece of <code>m4</code> code will be the same for all projects using GNU +<code>gettext</code>. +</p> + +<a name="config_002eh_002ein"></a> +<a name="SEC243"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC236">13.4.9 ‘<tt>config.h.in</tt>’ at top level</a> </h3> + +<p>The include file template that holds the C macros to be defined by +<code>configure</code> is usually called ‘<tt>config.h.in</tt>’ and may be +maintained either manually or automatically. +</p> +<p>If it is maintained automatically, by use of the ‘<samp>autoheader</samp>’ +program, you need to do nothing about it. This is the case in particular +if you are using GNU <code>automake</code>. +</p> +<p>If it is maintained manually, you can get away by adding the +following lines to ‘<tt>config.h.in</tt>’: +</p> +<table><tr><td> </td><td><pre class="example">/* Define to 1 if translation of program messages to the user's + native language is requested. */ +#undef ENABLE_NLS +</pre></td></tr></table> + + +<a name="Makefile"></a> +<a name="SEC244"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC237">13.4.10 ‘<tt>Makefile.in</tt>’ at top level</a> </h3> + +<p>Here are a few modifications you need to make to your main, top-level +‘<tt>Makefile.in</tt>’ file. +</p> +<ol> +<li> +Add the following lines near the beginning of your ‘<tt>Makefile.in</tt>’, +so the ‘<samp>dist:</samp>’ goal will work properly (as explained further down): + +<table><tr><td> </td><td><pre class="example">PACKAGE = @PACKAGE@ +VERSION = @VERSION@ +</pre></td></tr></table> + +</li><li> +Wherever you process subdirectories in your ‘<tt>Makefile.in</tt>’, be sure +you also process the subdirectory ‘<samp>po</samp>’. Special +rules in the ‘<tt>Makefiles</tt>’ take care for the case where no +internationalization is wanted. + +<p>If you are using Makefiles, either generated by automake, or hand-written +so they carefully follow the GNU coding standards, the effected goals for +which the new subdirectories must be handled include ‘<samp>installdirs</samp>’, +‘<samp>install</samp>’, ‘<samp>uninstall</samp>’, ‘<samp>clean</samp>’, ‘<samp>distclean</samp>’. +</p> +<p>Here is an example of a canonical order of processing. In this +example, we also define <code>SUBDIRS</code> in <code>Makefile.in</code> for it +to be further used in the ‘<samp>dist:</samp>’ goal. +</p> +<table><tr><td> </td><td><pre class="example">SUBDIRS = doc lib src po +</pre></td></tr></table> + +</li><li> +A delicate point is the ‘<samp>dist:</samp>’ goal, as ‘<tt>po/Makefile</tt>’ will later +assume that the proper directory has been set up from the main ‘<tt>Makefile</tt>’. +Here is an example at what the ‘<samp>dist:</samp>’ goal might look like: + +<table><tr><td> </td><td><pre class="example">distdir = $(PACKAGE)-$(VERSION) +dist: Makefile + rm -fr $(distdir) + mkdir $(distdir) + chmod 777 $(distdir) + for file in $(DISTFILES); do \ + ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \ + done + for subdir in $(SUBDIRS); do \ + mkdir $(distdir)/$$subdir || exit 1; \ + chmod 777 $(distdir)/$$subdir; \ + (cd $$subdir && $(MAKE) $@) || exit 1; \ + done + tar chozf $(distdir).tar.gz $(distdir) + rm -fr $(distdir) +</pre></td></tr></table> + +</li></ol> + +<p>Note that if you are using GNU <code>automake</code>, ‘<tt>Makefile.in</tt>’ is +automatically generated from ‘<tt>Makefile.am</tt>’, and all needed changes +to ‘<tt>Makefile.am</tt>’ are already made by running ‘<samp>gettextize</samp>’. +</p> + +<a name="src_002fMakefile"></a> +<a name="SEC245"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC238">13.4.11 ‘<tt>Makefile.in</tt>’ in ‘<tt>src/</tt>’</a> </h3> + +<p>Some of the modifications made in the main ‘<tt>Makefile.in</tt>’ will +also be needed in the ‘<tt>Makefile.in</tt>’ from your package sources, +which we assume here to be in the ‘<tt>src/</tt>’ subdirectory. Here are +all the modifications needed in ‘<tt>src/Makefile.in</tt>’: +</p> +<ol> +<li> +In view of the ‘<samp>dist:</samp>’ goal, you should have these lines near the +beginning of ‘<tt>src/Makefile.in</tt>’: + +<table><tr><td> </td><td><pre class="example">PACKAGE = @PACKAGE@ +VERSION = @VERSION@ +</pre></td></tr></table> + +</li><li> +If not done already, you should guarantee that <code>top_srcdir</code> +gets defined. This will serve for <code>cpp</code> include files. Just add +the line: + +<table><tr><td> </td><td><pre class="example">top_srcdir = @top_srcdir@ +</pre></td></tr></table> + +</li><li> +You might also want to define <code>subdir</code> as ‘<samp>src</samp>’, later +allowing for almost uniform ‘<samp>dist:</samp>’ goals in all your +‘<tt>Makefile.in</tt>’. At list, the ‘<samp>dist:</samp>’ goal below assume that +you used: + +<table><tr><td> </td><td><pre class="example">subdir = src +</pre></td></tr></table> + +</li><li> +The <code>main</code> function of your program will normally call +<code>bindtextdomain</code> (see see section <a href="gettext_4.html#SEC19">Triggering <code>gettext</code> Operations</a>), like this: + +<table><tr><td> </td><td><pre class="example">bindtextdomain (<var>PACKAGE</var>, LOCALEDIR); +textdomain (<var>PACKAGE</var>); +</pre></td></tr></table> + +<p>On native Windows platforms, the <code>main</code> function may call +<code>wbindtextdomain</code> instead of <code>bindtextdomain</code>. +</p> +<p>To make LOCALEDIR known to the program, add the following lines to +‘<tt>Makefile.in</tt>’: +</p> +<table><tr><td> </td><td><pre class="example">datadir = @datadir@ +datarootdir= @datarootdir@ +localedir = @localedir@ +DEFS = -DLOCALEDIR=$(localedir_c_make) @DEFS@ +</pre></td></tr></table> + +<p><code>$(localedir_c_make)</code> expands to the value of <code>localedir</code>, in +C syntax, escaped for use in a <code>Makefile</code>. +Note that <code>@datadir@</code> defaults to ‘<samp>$(prefix)/share</samp>’, and +<code>$(localedir)</code> defaults to ‘<samp>$(prefix)/share/locale</samp>’. +</p> +</li><li> +You should ensure that the final linking will use <code>@LIBINTL@</code> or +<code>@LTLIBINTL@</code> as a library. <code>@LIBINTL@</code> is for use without +<code>libtool</code>, <code>@LTLIBINTL@</code> is for use with <code>libtool</code>. An +easy way to achieve this is to manage that it gets into <code>LIBS</code>, like +this: + +<table><tr><td> </td><td><pre class="example">LIBS = @LIBINTL@ @LIBS@ +</pre></td></tr></table> + +<p>In most packages internationalized with GNU <code>gettext</code>, one will +find a directory ‘<tt>lib/</tt>’ in which a library containing some helper +functions will be build. (You need at least the few functions which the +GNU <code>gettext</code> Library itself needs.) However some of the functions +in the ‘<tt>lib/</tt>’ also give messages to the user which of course should be +translated, too. Taking care of this, the support library (say +‘<tt>libsupport.a</tt>’) should be placed before <code>@LIBINTL@</code> and +<code>@LIBS@</code> in the above example. So one has to write this: +</p> +<table><tr><td> </td><td><pre class="example">LIBS = ../lib/libsupport.a @LIBINTL@ @LIBS@ +</pre></td></tr></table> + +</li><li> +Your ‘<samp>dist:</samp>’ goal has to conform with others. Here is a +reasonable definition for it: + +<table><tr><td> </td><td><pre class="example">distdir = ../$(PACKAGE)-$(VERSION)/$(subdir) +dist: Makefile $(DISTFILES) + for file in $(DISTFILES); do \ + ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir) || exit 1; \ + done +</pre></td></tr></table> + +</li></ol> + +<p>Note that if you are using GNU <code>automake</code>, ‘<tt>Makefile.in</tt>’ is +automatically generated from ‘<tt>Makefile.am</tt>’, and the first three +changes and the last change are not necessary. The remaining needed +‘<tt>Makefile.am</tt>’ modifications are the following: +</p> +<ol> +<li> +To make LOCALEDIR known to the program, add the following to +‘<tt>Makefile.am</tt>’: + +<table><tr><td> </td><td><pre class="example"><module>_CPPFLAGS = -DLOCALEDIR=$(localedir_c_make) +</pre></td></tr></table> + +<p>for each specific module or compilation unit, or +</p> +<table><tr><td> </td><td><pre class="example">AM_CPPFLAGS = -DLOCALEDIR=$(localedir_c_make) +</pre></td></tr></table> + +<p>for all modules and compilation units together. +</p> +</li><li> +To ensure that the final linking will use <code>@LIBINTL@</code> or +<code>@LTLIBINTL@</code> as a library, add the following to +‘<tt>Makefile.am</tt>’: + +<table><tr><td> </td><td><pre class="example"><program>_LDADD = @LIBINTL@ +</pre></td></tr></table> + +<p>for each specific program, or +</p> +<table><tr><td> </td><td><pre class="example">LDADD = @LIBINTL@ +</pre></td></tr></table> + +<p>for all programs together. Remember that when you use <code>libtool</code> +to link a program, you need to use @LTLIBINTL@ instead of @LIBINTL@ +for that program. +</p> +</li></ol> + + +<a name="lib_002fgettext_002eh"></a> +<a name="SEC246"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC239">13.4.12 ‘<tt>gettext.h</tt>’ in ‘<tt>lib/</tt>’</a> </h3> + +<p>Internationalization of packages, as provided by GNU <code>gettext</code>, is +optional. It can be turned off in two situations: +</p> +<ul> +<li> +When the installer has specified ‘<samp>./configure --disable-nls</samp>’. This +can be useful when small binaries are more important than features, for +example when building utilities for boot diskettes. It can also be useful +in order to get some specific C compiler warnings about code quality with +some older versions of GCC (older than 3.0). + +</li><li> +When the libintl.h header (with its associated libintl library, if any) is +not already installed on the system, it is preferable that the package builds +without internationalization support, rather than to give a compilation +error. +</li></ul> + +<p>A C preprocessor macro can be used to detect these two cases. Usually, +when <code>libintl.h</code> was found and not explicitly disabled, the +<code>ENABLE_NLS</code> macro will be defined to 1 in the autoconf generated +configuration file (usually called ‘<tt>config.h</tt>’). In the two negative +situations, however, this macro will not be defined, thus it will evaluate +to 0 in C preprocessor expressions. +</p> +<a name="IDX1104"></a> +<p>‘<tt>gettext.h</tt>’ is a convenience header file for conditional use of +‘<tt><libintl.h></tt>’, depending on the <code>ENABLE_NLS</code> macro. If +<code>ENABLE_NLS</code> is set, it includes ‘<tt><libintl.h></tt>’; otherwise it +defines no-op substitutes for the libintl.h functions. We recommend +the use of <code>"gettext.h"</code> over direct use of ‘<tt><libintl.h></tt>’, +so that portability to older systems is guaranteed and installers can +turn off internationalization if they want to. In the C code, you will +then write +</p> +<table><tr><td> </td><td><pre class="example">#include "gettext.h" +</pre></td></tr></table> + +<p>instead of +</p> +<table><tr><td> </td><td><pre class="example">#include <libintl.h> +</pre></td></tr></table> + +<p>The location of <code>gettext.h</code> is usually in a directory containing +auxiliary include files. In many GNU packages, there is a directory +‘<tt>lib/</tt>’ containing helper functions; ‘<tt>gettext.h</tt>’ fits there. +In other packages, it can go into the ‘<tt>src</tt>’ directory. +</p> +<p>Do not install the <code>gettext.h</code> file in public locations. Every +package that needs it should contain a copy of it on its own. +</p> + +<a name="autoconf-macros"></a> +<a name="SEC247"></a> +<h2 class="section"> <a href="gettext_toc.html#TOC240">13.5 Autoconf macros for use in ‘<tt>configure.ac</tt>’</a> </h2> + +<p>GNU <code>gettext</code> installs macros for use in a package's +‘<tt>configure.ac</tt>’ or ‘<tt>configure.in</tt>’. +See <a href="../autoconf/index.html#Top">(autoconf)Top</a> section `Introduction' in <cite>The Autoconf Manual</cite>. +The primary macro is, of course, <code>AM_GNU_GETTEXT</code>. +</p> + + +<a name="AM_005fGNU_005fGETTEXT"></a> +<a name="SEC248"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC241">13.5.1 AM_GNU_GETTEXT in ‘<tt>gettext.m4</tt>’</a> </h3> + +<p>The <code>AM_GNU_GETTEXT</code> macro tests for the presence of the GNU gettext +function family in either the C library or a separate <code>libintl</code> +library (shared or static libraries are both supported). It also invokes +<code>AM_PO_SUBDIRS</code>, thus preparing the ‘<tt>po/</tt>’ directories of the +package for building. +</p> +<p><code>AM_GNU_GETTEXT</code> accepts up to two optional arguments. The general +syntax is +</p> +<table><tr><td> </td><td><pre class="example">AM_GNU_GETTEXT([<var>intlsymbol</var>], [<var>needsymbol</var>]) +</pre></td></tr></table> + +<p><var>intlsymbol</var> should always be ‘<samp>external</samp>’. +</p> +<p>If <var>needsymbol</var> is specified and is ‘<samp>need-ngettext</samp>’, then GNU +gettext implementations (in libc or libintl) without the <code>ngettext()</code> +function will be ignored. If <var>needsymbol</var> is specified and is +‘<samp>need-formatstring-macros</samp>’, then GNU gettext implementations that don't +support the ISO C 99 ‘<tt><inttypes.h></tt>’ formatstring macros will be ignored. +Only one <var>needsymbol</var> can be specified. These requirements can also be +specified by using the macro <code>AM_GNU_GETTEXT_NEED</code> elsewhere. To specify +more than one requirement, just specify the strongest one among them, or +invoke the <code>AM_GNU_GETTEXT_NEED</code> macro several times. The hierarchy +among the various alternatives is as follows: ‘<samp>need-formatstring-macros</samp>’ +implies ‘<samp>need-ngettext</samp>’. +</p> +<p>The <code>AM_GNU_GETTEXT</code> macro determines whether GNU gettext is +available and should be used. If so, it sets the <code>USE_NLS</code> variable +to ‘<samp>yes</samp>’; it defines <code>ENABLE_NLS</code> to 1 in the autoconf +generated configuration file (usually called ‘<tt>config.h</tt>’); it sets +the variables <code>LIBINTL</code> and <code>LTLIBINTL</code> to the linker options +for use in a Makefile (<code>LIBINTL</code> for use without libtool, +<code>LTLIBINTL</code> for use with libtool); it adds an ‘<samp>-I</samp>’ option to +<code>CPPFLAGS</code> if necessary. In the negative case, it sets +<code>USE_NLS</code> to ‘<samp>no</samp>’; it sets <code>LIBINTL</code> and <code>LTLIBINTL</code> +to empty and doesn't change <code>CPPFLAGS</code>. +</p> +<p>The complexities that <code>AM_GNU_GETTEXT</code> deals with are the following: +</p> +<ul> +<li> +<a name="IDX1105"></a> +Some operating systems have <code>gettext</code> in the C library, for example +glibc. Some have it in a separate library <code>libintl</code>. GNU <code>libintl</code> +might have been installed as part of the GNU <code>gettext</code> package. + +</li><li> +GNU <code>libintl</code>, if installed, is not necessarily already in the search +path (<code>CPPFLAGS</code> for the include file search path, <code>LDFLAGS</code> for +the library search path). + +</li><li> +Except for glibc and the Solaris 11 libc, the operating system's native +<code>gettext</code> cannot exploit the GNU mo files, doesn't have the +necessary locale dependency features, and cannot convert messages from +the catalog's text encoding to the user's locale encoding. + +</li><li> +GNU <code>libintl</code>, if installed, is not necessarily already in the +run time library search path. To avoid the need for setting an environment +variable like <code>LD_LIBRARY_PATH</code>, the macro adds the appropriate +run time search path options to the <code>LIBINTL</code> and <code>LTLIBINTL</code> +variables. This works on most systems, but not on some operating systems +with limited shared library support, like SCO. + +</li><li> +GNU <code>libintl</code> relies on POSIX/XSI <code>iconv</code>. The macro checks for +linker options needed to use iconv and appends them to the <code>LIBINTL</code> +and <code>LTLIBINTL</code> variables. +</li></ul> + +<p>Additionally, the <code>AM_GNU_GETTEXT</code> macro sets two variables, for +convenience. Both are derived from the <code>--localedir</code> configure +option. They are correct even on native Windows, where directories +frequently contain backslashes. +</p><dl compact="compact"> +<dt> <code>localedir_c</code></dt> +<dd><p>This is the value of <code>localedir</code>, in C syntax. This variable is +meant to be substituted into C or C++ code through +<code>AC_CONFIG_FILES</code>. +</p> +</dd> +<dt> <code>localedir_c_make</code></dt> +<dd><p>This is the value of <code>localedir</code>, in C syntax, escaped for use in +a <code>Makefile</code>. This variable is meant to be used in Makefiles, +for example for defining a C macro named <code>LOCALEDIR</code>: +</p><table><tr><td> </td><td><pre class="smallexample">AM_CPPFLAGS = ... -DLOCALEDIR=$(localedir_c_make) ... +</pre></td></tr></table> +</dd> +</dl> + + +<a name="AM_005fGNU_005fGETTEXT_005fVERSION"></a> +<a name="SEC249"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC242">13.5.2 AM_GNU_GETTEXT_VERSION in ‘<tt>gettext.m4</tt>’</a> </h3> + +<p>The <code>AM_GNU_GETTEXT_VERSION</code> macro declares the version number of +the GNU gettext infrastructure that is used by the package. +</p> +<p>The use of this macro is optional; only the <code>autopoint</code> program makes +use of it (see section <a href="#SEC254">Integrating with Version Control Systems</a>). +</p> + +<a name="AM_005fGNU_005fGETTEXT_005fNEED"></a> +<a name="SEC250"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC243">13.5.3 AM_GNU_GETTEXT_NEED in ‘<tt>gettext.m4</tt>’</a> </h3> + +<p>The <code>AM_GNU_GETTEXT_NEED</code> macro declares a constraint regarding the +GNU gettext implementation. The syntax is +</p> +<table><tr><td> </td><td><pre class="example">AM_GNU_GETTEXT_NEED([<var>needsymbol</var>]) +</pre></td></tr></table> + +<p>If <var>needsymbol</var> is ‘<samp>need-ngettext</samp>’, then GNU gettext implementations +(in libc or libintl) without the <code>ngettext()</code> function will be ignored. +If <var>needsymbol</var> is ‘<samp>need-formatstring-macros</samp>’, then GNU gettext +implementations that don't support the ISO C 99 ‘<tt><inttypes.h></tt>’ +formatstring macros will be ignored. +</p> +<p>The optional second argument of <code>AM_GNU_GETTEXT</code> is also taken into +account. +</p> +<p>The <code>AM_GNU_GETTEXT_NEED</code> invocations can occur before or after +the <code>AM_GNU_GETTEXT</code> invocation; the order doesn't matter. +</p> + +<a name="AM_005fPO_005fSUBDIRS"></a> +<a name="SEC251"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC244">13.5.4 AM_PO_SUBDIRS in ‘<tt>po.m4</tt>’</a> </h3> + +<p>The <code>AM_PO_SUBDIRS</code> macro prepares the ‘<tt>po/</tt>’ directories of the +package for building. This macro should be used in internationalized +programs written in other programming languages than C, C++, Objective C, +for example <code>sh</code>, <code>Python</code>, <code>Lisp</code>. See <a href="gettext_15.html#SEC263">Other Programming Languages</a> for a list of programming languages that support localization +through PO files. +</p> +<p>The <code>AM_PO_SUBDIRS</code> macro determines whether internationalization +should be used. If so, it sets the <code>USE_NLS</code> variable to ‘<samp>yes</samp>’, +otherwise to ‘<samp>no</samp>’. It also determines the right values for Makefile +variables in each ‘<tt>po/</tt>’ directory. +</p> + +<a name="AM_005fXGETTEXT_005fOPTION"></a> +<a name="SEC252"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC245">13.5.5 AM_XGETTEXT_OPTION in ‘<tt>po.m4</tt>’</a> </h3> + +<p>The <code>AM_XGETTEXT_OPTION</code> macro registers a command-line option to be +used in the invocations of <code>xgettext</code> in the ‘<tt>po/</tt>’ directories +of the package. +</p> +<p>For example, if you have a source file that defines a function +‘<samp>error_at_line</samp>’ whose fifth argument is a format string, you can use +</p><table><tr><td> </td><td><pre class="example">AM_XGETTEXT_OPTION([--flag=error_at_line:5:c-format]) +</pre></td></tr></table> +<p>to instruct <code>xgettext</code> to mark all translatable strings in ‘<samp>gettext</samp>’ +invocations that occur as fifth argument to this function as ‘<samp>c-format</samp>’. +</p> +<p>See <a href="gettext_5.html#SEC36">Invoking the <code>xgettext</code> Program</a> for the list of options that <code>xgettext</code> +accepts. +</p> +<p>The use of this macro is an alternative to the use of the +‘<samp>XGETTEXT_OPTIONS</samp>’ variable in ‘<tt>po/Makevars</tt>’. +</p> + +<a name="AM_005fICONV"></a> +<a name="SEC253"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC246">13.5.6 AM_ICONV in ‘<tt>iconv.m4</tt>’</a> </h3> + +<p>The <code>AM_ICONV</code> macro tests for the presence of the POSIX/XSI +<code>iconv</code> function family in either the C library or a separate +<code>libiconv</code> library. If found, it sets the <code>am_cv_func_iconv</code> +variable to ‘<samp>yes</samp>’; it defines <code>HAVE_ICONV</code> to 1 in the autoconf +generated configuration file (usually called ‘<tt>config.h</tt>’); it defines +<code>ICONV_CONST</code> to ‘<samp>const</samp>’ or to empty, depending on whether the +second argument of <code>iconv()</code> is of type ‘<samp>const char **</samp>’ or +‘<samp>char **</samp>’; it sets the variables <code>LIBICONV</code> and +<code>LTLIBICONV</code> to the linker options for use in a Makefile +(<code>LIBICONV</code> for use without libtool, <code>LTLIBICONV</code> for use with +libtool); it adds an ‘<samp>-I</samp>’ option to <code>CPPFLAGS</code> if +necessary. If not found, it sets <code>LIBICONV</code> and <code>LTLIBICONV</code> to +empty and doesn't change <code>CPPFLAGS</code>. +</p> +<p>The complexities that <code>AM_ICONV</code> deals with are the following: +</p> +<ul> +<li> +<a name="IDX1106"></a> +Some operating systems have <code>iconv</code> in the C library, for example +glibc. Some have it in a separate library <code>libiconv</code>, for example +OSF/1 or FreeBSD. Regardless of the operating system, GNU <code>libiconv</code> +might have been installed. In that case, it should be used instead of the +operating system's native <code>iconv</code>. + +</li><li> +GNU <code>libiconv</code>, if installed, is not necessarily already in the search +path (<code>CPPFLAGS</code> for the include file search path, <code>LDFLAGS</code> for +the library search path). + +</li><li> +GNU <code>libiconv</code> is binary incompatible with some operating system's +native <code>iconv</code>, for example on FreeBSD. Use of an ‘<tt>iconv.h</tt>’ +and ‘<tt>libiconv.so</tt>’ that don't fit together would produce program +crashes. + +</li><li> +GNU <code>libiconv</code>, if installed, is not necessarily already in the +run time library search path. To avoid the need for setting an environment +variable like <code>LD_LIBRARY_PATH</code>, the macro adds the appropriate +run time search path options to the <code>LIBICONV</code> variable. This works +on most systems, but not on some operating systems with limited shared +library support, like SCO. +</li></ul> + +<p>‘<tt>iconv.m4</tt>’ is distributed with the GNU gettext package because +‘<tt>gettext.m4</tt>’ relies on it. +</p> + +<a name="Version-Control-Issues"></a> +<a name="SEC254"></a> +<h2 class="section"> <a href="gettext_toc.html#TOC247">13.6 Integrating with Version Control Systems</a> </h2> + +<p>Many projects use version control systems for distributed development +and source backup. This section gives some advice how to manage the +uses of <code>gettextize</code>, <code>autopoint</code> and <code>autoconf</code> on +version controlled files. +</p> + + +<a name="Distributed-Development"></a> +<a name="SEC255"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC248">13.6.1 Avoiding version mismatch in distributed development</a> </h3> + +<p>In a project development with multiple developers, there should be a +single developer who occasionally - when there is desire to upgrade to +a new <code>gettext</code> version - runs <code>gettextize</code> and performs the +changes listed in <a href="#SEC234">Files You Must Create or Alter</a>, and then commits his changes +to the repository. +</p> +<p>It is highly recommended that all developers on a project use the same +version of GNU <code>gettext</code> in the package. In other words, if a +developer runs <code>gettextize</code>, he should go the whole way, make the +necessary remaining changes and commit his changes to the repository. +Otherwise the following damages will likely occur: +</p> +<ul> +<li> +Apparent version mismatch between developers. Since some <code>gettext</code> +specific portions in ‘<tt>configure.ac</tt>’, ‘<tt>configure.in</tt>’ and +<code>Makefile.am</code>, <code>Makefile.in</code> files depend on the <code>gettext</code> +version, the use of infrastructure files belonging to different +<code>gettext</code> versions can easily lead to build errors. + +</li><li> +Hidden version mismatch. Such version mismatch can also lead to +malfunctioning of the package, that may be undiscovered by the developers. +The worst case of hidden version mismatch is that internationalization +of the package doesn't work at all. + +</li><li> +Release risks. All developers implicitly perform constant testing on +a package. This is important in the days and weeks before a release. +If the guy who makes the release tar files uses a different version +of GNU <code>gettext</code> than the other developers, the distribution will +be less well tested than if all had been using the same <code>gettext</code> +version. For example, it is possible that a platform specific bug goes +undiscovered due to this constellation. +</li></ul> + + +<a name="Files-under-Version-Control"></a> +<a name="SEC256"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC249">13.6.2 Files to put under version control</a> </h3> + +<p>There are basically three ways to deal with generated files in the +context of a version controlled repository, such as ‘<tt>configure</tt>’ +generated from ‘<tt>configure.ac</tt>’, <code><var>parser</var>.c</code> generated +from <code><var>parser</var>.y</code>, or <code>po/Makefile.in.in</code> autoinstalled +by <code>gettextize</code> or <code>autopoint</code>. +</p> +<ol> +<li> +All generated files are always committed into the repository. + +</li><li> +All generated files are committed into the repository occasionally, +for example each time a release is made. + +</li><li> +Generated files are never committed into the repository. +</li></ol> + +<p>Each of these three approaches has different advantages and drawbacks. +</p> +<ol> +<li> +The advantage is that anyone can check out the source at any moment and +gets a working build. The drawbacks are: 1a. It requires some frequent +"push" actions by the maintainers. 1b. The repository grows in size +quite fast. + +</li><li> +The advantage is that anyone can check out the source, and the usual +"./configure; make" will work. The drawbacks are: 2a. The one who +checks out the repository needs tools like GNU <code>automake</code>, GNU +<code>autoconf</code>, GNU <code>m4</code> installed in his PATH; sometimes he +even needs particular versions of them. 2b. When a release is made +and a commit is made on the generated files, the other developers get +conflicts on the generated files when merging the local work back to +the repository. Although these conflicts are easy to resolve, they +are annoying. + +</li><li> +The advantage is less work for the maintainers. The drawback is that +anyone who checks out the source not only needs tools like GNU +<code>automake</code>, GNU <code>autoconf</code>, GNU <code>m4</code> installed in his +PATH, but also that he needs to perform a package specific pre-build +step before being able to "./configure; make". +</li></ol> + +<p>For the first and second approach, all files modified or brought in +by the occasional <code>gettextize</code> invocation and update should be +committed into the repository. +</p> +<p>For the third approach, the maintainer can omit from the repository +all the files that <code>gettextize</code> mentions as "copy". Instead, he +adds to the ‘<tt>configure.ac</tt>’ or ‘<tt>configure.in</tt>’ a line of the +form +</p> +<table><tr><td> </td><td><pre class="example">AM_GNU_GETTEXT_VERSION(0.22.4) +</pre></td></tr></table> + +<p>and adds to the package's pre-build script an invocation of +‘<samp>autopoint</samp>’. For everyone who checks out the source, this +<code>autopoint</code> invocation will copy into the right place the +<code>gettext</code> infrastructure files that have been omitted from the repository. +</p> +<p>The version number used as argument to <code>AM_GNU_GETTEXT_VERSION</code> is +the version of the <code>gettext</code> infrastructure that the package wants +to use. It is also the minimum version number of the ‘<samp>autopoint</samp>’ +program. So, if you write <code>AM_GNU_GETTEXT_VERSION(0.11.5)</code> then the +developers can have any version >= 0.11.5 installed; the package will work +with the 0.11.5 infrastructure in all developers' builds. When the +maintainer then runs gettextize from, say, version 0.12.1 on the package, +the occurrence of <code>AM_GNU_GETTEXT_VERSION(0.11.5)</code> will be changed +into <code>AM_GNU_GETTEXT_VERSION(0.12.1)</code>, and all other developers that +use the CVS will henceforth need to have GNU <code>gettext</code> 0.12.1 or newer +installed. +</p> + +<a name="Translations-under-Version-Control"></a> +<a name="SEC257"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC250">13.6.3 Put PO Files under Version Control</a> </h3> + +<p>Since translations are valuable assets as well as the source code, it +would make sense to put them under version control. The GNU gettext +infrastructure supports two ways to deal with translations in the +context of a version controlled repository. +</p> +<ol> +<li> +Both POT file and PO files are committed into the repository. + +</li><li> +Only PO files are committed into the repository. + +</li></ol> + +<p>If a POT file is absent when building, it will be generated by +scanning the source files with <code>xgettext</code>, and then the PO files +are regenerated as a dependency. On the other hand, some maintainers +want to keep the POT file unchanged during the development phase. So, +even if a POT file is present and older than the source code, it won't +be updated automatically. You can manually update it with <code>make +$(DOMAIN).pot-update</code>, and commit it at certain point. +</p> +<p>Special advices for particular version control systems: +</p> +<ul> +<li> +Recent version control systems, Git for instance, ignore file's +timestamp. In that case, PO files can be accidentally updated even if +a POT file is not updated. To prevent this, you can set +‘<samp>PO_DEPENDS_ON_POT</samp>’ variable to <code>no</code> in the ‘<tt>Makevars</tt>’ +file and do <code>make update-po</code> manually. + +</li><li> +Location comments such as <code>#: lib/error.c:116</code> are sometimes +annoying, since these comments are volatile and may introduce unwanted +change to the working copy when building. To mitigate this, you can +decide to omit those comments from the PO files in the repository. + +<p>This is possible with the <code>--no-location</code> option of the +<code>msgmerge</code> command <a name="DOCF6" href="gettext_fot.html#FOOT6">(6)</a>. The drawback is +that, if the location information is needed, translators have to +recover the location comments by running <code>msgmerge</code> again. +</p> +</li></ul> + + +<a name="autopoint-Invocation"></a> +<a name="SEC258"></a> +<h3 class="subsection"> <a href="gettext_toc.html#TOC251">13.6.4 Invoking the <code>autopoint</code> Program</a> </h3> + + +<table><tr><td> </td><td><pre class="example">autopoint [<var>option</var>]... +</pre></td></tr></table> + +<p>The <code>autopoint</code> program copies standard gettext infrastructure files +into a source package. It extracts from a macro call of the form +<code>AM_GNU_GETTEXT_VERSION(<var>version</var>)</code>, found in the package's +‘<tt>configure.in</tt>’ or ‘<tt>configure.ac</tt>’ file, the gettext version +used by the package, and copies the infrastructure files belonging to +this version into the package. +</p> +<p>To extract the latest available infrastructure which satisfies a version +requirement, then you can use the form +<code>AM_GNU_GETTEXT_REQUIRE_VERSION(<var>version</var>)</code> instead. For +example, if gettext 0.22.4 is installed on your system +and <code>0.19.1</code> is requested, then the infrastructure files of version +0.22.4 will be copied into a source package. +</p> + +<a name="SEC259"></a> +<h4 class="subsubsection"> <a href="gettext_toc.html#TOC252">13.6.4.1 Options</a> </h4> + +<dl compact="compact"> +<dt> ‘<samp>-f</samp>’</dt> +<dt> ‘<samp>--force</samp>’</dt> +<dd><a name="IDX1107"></a> +<a name="IDX1108"></a> +<p>Force overwriting of files that already exist. +</p> +</dd> +<dt> ‘<samp>-n</samp>’</dt> +<dt> ‘<samp>--dry-run</samp>’</dt> +<dd><a name="IDX1109"></a> +<a name="IDX1110"></a> +<p>Print modifications but don't perform them. All file copying actions that +<code>autopoint</code> would normally execute are inhibited and instead only +listed on standard output. +</p> +</dd> +</dl> + + +<a name="SEC260"></a> +<h4 class="subsubsection"> <a href="gettext_toc.html#TOC253">13.6.4.2 Informative output</a> </h4> + +<dl compact="compact"> +<dt> ‘<samp>--help</samp>’</dt> +<dd><a name="IDX1111"></a> +<p>Display this help and exit. +</p> +</dd> +<dt> ‘<samp>--version</samp>’</dt> +<dd><a name="IDX1112"></a> +<p>Output version information and exit. +</p> +</dd> +</dl> + +<p><code>autopoint</code> supports the GNU <code>gettext</code> versions from 0.10.35 +to the current one, 0.22.4. In order to apply +<code>autopoint</code> to a package using a <code>gettext</code> version newer than +0.22.4, you need to install this same version of GNU +<code>gettext</code> at least. +</p> +<p>In packages using GNU <code>automake</code>, an invocation of <code>autopoint</code> +should be followed by invocations of <code>aclocal</code> and then <code>autoconf</code> +and <code>autoheader</code>. The reason is that <code>autopoint</code> installs some +autoconf macro files, which are used by <code>aclocal</code> to create +‘<tt>aclocal.m4</tt>’, and the latter is used by <code>autoconf</code> to create the +package's ‘<tt>configure</tt>’ script and by <code>autoheader</code> to create the +package's ‘<tt>config.h.in</tt>’ include file template. +</p> +<p>The name ‘<samp>autopoint</samp>’ is an abbreviation of ‘<samp>auto-po-intl-m4</samp>’; +in earlier versions, the tool copied or updated mostly files in the ‘<tt>po</tt>’, +‘<tt>intl</tt>’, ‘<tt>m4</tt>’ directories. +</p> + +<a name="Release-Management"></a> +<a name="SEC261"></a> +<h2 class="section"> <a href="gettext_toc.html#TOC254">13.7 Creating a Distribution Tarball</a> </h2> + +<p>In projects that use GNU <code>automake</code>, the usual commands for creating +a distribution tarball, ‘<samp>make dist</samp>’ or ‘<samp>make distcheck</samp>’, +automatically update the PO files as needed. +</p> +<p>If GNU <code>automake</code> is not used, the maintainer needs to perform this +update before making a release: +</p> +<table><tr><td> </td><td><pre class="example">$ ./configure +$ (cd po; make update-po) +$ make distclean +</pre></td></tr></table> + + +<table cellpadding="1" cellspacing="1" border="0"> +<tr><td valign="middle" align="left">[<a href="#SEC230" title="Beginning of this chapter or previous chapter"> << </a>]</td> +<td valign="middle" align="left">[<a href="gettext_14.html#SEC262" title="Next chapter"> >> </a>]</td> +<td valign="middle" align="left"> </td> +<td valign="middle" align="left"> </td> +<td valign="middle" align="left"> </td> +<td valign="middle" align="left"> </td> +<td valign="middle" align="left"> </td> +<td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td> +<td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td> +<td valign="middle" align="left">[<a href="gettext_21.html#SEC389" title="Index">Index</a>]</td> +<td valign="middle" align="left">[<a href="gettext_abt.html#SEC_About" title="About (help)"> ? </a>]</td> +</tr></table> +<p> + <font size="-1"> + This document was generated by <em>Bruno Haible</em> on <em>February, 21 2024</em> using <a href="https://www.nongnu.org/texi2html/"><em>texi2html 1.78a</em></a>. + </font> + <br> + +</p> +</body> +</html>