Mercurial > repos > rliterman > csp2
diff CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/gettext/FAQ.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/FAQ.html Tue Mar 18 16:23:26 2025 -0400 @@ -0,0 +1,864 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<!-- + Copyright (C) 2004-2005, 2007-2008, 2010, 2012, 2014, 2019-2020 Free Software Foundation, Inc. + Written by Bruno Haible <bruno@clisp.org>, 2004. + + This manual is free documentation. It is dually licensed under the + GNU FDL and the GNU GPL. This means that you can redistribute this + manual under either of these two licenses, at your choice. + + This manual is covered by the GNU FDL. Permission is granted to copy, + distribute and/or modify this document under the terms of the + GNU Free Documentation License (FDL), either version 1.2 of the + License, or (at your option) any later version published by the + Free Software Foundation (FSF); with no Invariant Sections, with no + Front-Cover Text, and with no Back-Cover Texts. + A copy of the license is at + <https://www.gnu.org/licenses/old-licenses/fdl-1.2>. + + This manual is covered by the GNU GPL. You can redistribute it and/or + modify it under the terms of the GNU General Public License (GPL), either + version 2 of the License, or (at your option) any later version published + by the Free Software Foundation (FSF). + A copy of the license is at + <https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. +--> +<head> + <meta http-equiv="content-type" content="text/html; charset=UTF-8"> + <title>GNU gettext FAQ</title> +</head> +<body> +<h1 style="text-align: center;">Frequently Asked Questions<br> +for GNU gettext +</h1> +<h1 style="text-align: center;">Questions</h1> +<h3>General</h3> +<ul> + <li><a href="#general_mailinglist">Where is the mailing list?</a></li> + <li><a href="#general_source">Where is the newest gettext source?</a></li> + <li><a href="#general_announce">I want to be notified of new gettext +releases.</a></li> +</ul> +<h3>Problems building GNU gettext</h3> +<ul> + <li><a href="#building_solaris_libasprintf">On Solaris, I get a build +error “text relocations remain” in the <span + style="font-family: monospace;">libasprintf</span> subdirectory</a></li> + <li><a href="#building_install">“make install” fails</a></li> +</ul> +<h3>Problems integrating GNU gettext</h3> +<ul> + <li><a href="#integrating_howto">How do I make use of <span + style="font-family: monospace;">gettext()</span> in my package?</a></li> + <li><a href="#integrating_undefined">I get a linker error “undefined +reference to libintl_gettext”</a></li> + <li><a href="#integrating_abuse_gettextize">gettextize adds multiple +references to the same directories/files +to <span style="font-family: monospace;">Makefile.am</span> and </a><span + style="font-family: monospace;"><a href="#integrating_abuse_gettextize">configure.ac</a><br> + </span></li> + <li><a href="#integrating_noop">My program compiles and links fine, +but doesn't output translated +strings.</a><br> + </li> +</ul> +<h3>GNU gettext on Windows</h3> +<ul> + <li><a href="#windows_woe32">What does Woe32 mean?</a></li> + <li><a href="#windows_howto">How do I compile, link and run a program +that uses the gettext() +function?</a><br> + </li> + <li><a href="#windows_setenv">Setting the <span + style="font-family: monospace;">LANG</span> +environment variable doesn't have any effect</a></li> +</ul> +<h3>Other</h3> +<ul> + <li><a href="#newline">What does this mean: “'msgid' and 'msgstr' +entries do not both +end with '\n'”</a></li> + <li><a href="#translit">German umlauts are displayed like “ge"andert” +instead of +“geändert”</a></li> + <li><a href="#localename">The <span style="font-family: monospace;">LANGUAGE</span> +environment variable is ignored after I set <span + style="font-family: monospace;">LANG=en</span></a></li> + <li><a href="#nonascii_strings">I use accented characters in my +source code. How do I tell the +C/C++ compiler in which encoding it is (like <span + style="font-family: monospace;">xgettext</span>'s <span + style="font-family: monospace;">--from-code</span> option)?</a></li> +</ul> +<h1 style="text-align: center;">Answers</h1> +<h3>General</h3> +<h4><a name="general_mailinglist"></a>Where is the mailing list?</h4> +Three mailing lists are available: <br> +<ul> + <li><span style="font-family: monospace;">bug-gettext@gnu.org</span><br> +This mailing list is for discussion of features and bugs of the GNU +gettext <span style="font-style: italic;">software</span>, including +libintl, the gettext-tools, and its autoconf macros. The archive and subscription instructions can be found at <a href="https://lists.gnu.org/mailman/listinfo/bug-gettext">the information page</a>.</li> + <li><span style="font-family: monospace;">translation-i18n@lists.sourceforge.net</span><br> +This mailing list is for methodology questions around +internationalization, and for discussions of translator tools, +including but not limited to GNU gettext.</li> + <li><span style="font-family: monospace;">coordinator@translationproject.org</span><br> +This is the email address of the <a + href="https://translationproject.org/">Translation Project</a>, +that is the project which manages the translated message +catalogs for many free software packages. Note that KDE and GNOME +packages are not part of this project; they have their own translation +projects: <a href="https://l10n.kde.org/">l10n.kde.org</a> and <a + href="https://wiki.gnome.org/TranslationProject/">GNOME Translation Project</a>.<br> + </li> +</ul> +The <span style="font-family: monospace;">bug-gettext</span> list +is archived <a href="https://lists.gnu.org/archive/html/bug-gettext/">here</a>. +You may occasionally also see +<span style="font-family: monospace;">bug-gnu-gettext</span>; this is an alias +of <span style="font-family: monospace;">bug-gettext</span>.<br> +<h4><a name="general_source"></a>Where is the newest gettext source?</h4> +The newest gettext release is available on <span + style="font-family: monospace;">ftp.gnu.org</span> and its mirrors, in +<a href="https://ftp.gnu.org/gnu/gettext/">https://ftp.gnu.org/gnu/gettext/</a>.<br> +<br> +Prereleases are announced on the <a + href="https://lists.gnu.org/mailman/listinfo/autotools-announce"><span + style="font-family: monospace;">autotools-announce</span> mailing list</a>. +Note that prereleases are meant for testing and not meant for use in +production environments. Please don't use the “gettextize” program of a +prerelease on projects which you share with other programmers via CVS.<br> +<br> +If you want to live on the bleeding edge, you can also use the +development sources. Instructions for retrieving the gettext CVS are +found <a href="https://savannah.gnu.org/projects/gettext">here</a>. +Note that building from CVS requires special tools (autoconf, automake, +m4, groff, bison, etc.) and requires that you pay attention to the <span + style="font-family: monospace;">README-alpha</span> and <span + style="font-family: monospace;">autogen.sh</span> files in the CVS.<br> +<h4><a name="general_announce"></a>I want to be notified of new gettext +releases.</h4> +If you are interested in stable gettext releases, you can follow the <a + href="https://lists.gnu.org/mailman/listinfo/info-gnu"><span + style="font-family: monospace;">info-gnu</span> mailing list</a>. It +is also available as a newsgroup <a + href="nntp://news.gmane.org/gmane.org.fsf.announce"><span + style="font-family: monospace;">gmane.org.fsf.announce</span></a> +through <a href="https://www.gmane.org/"><span + style="font-family: monospace;">gmane.org</span></a>.<br> +<br> +You can also periodically check the download location.<br> +<br> +If you are interested in testing prereleases as well, you can subscribe +to the <a href="://lists.gnu.org/mailman/listinfo/autotools-announce"><span + style="font-family: monospace;">autotools-announce</span> mailing +list</a>.<br> +<h3>Problems building GNU gettext</h3> +<h4><a name="building_solaris_libasprintf"></a>On Solaris, I get a +build error “text relocations remain” in the <span + style="font-family: monospace;">libasprintf</span> subdirectory</h4> +libtool (or more precisely, the version of libtool that was available +at the time the gettext release waas made) doesn't support linking C++ +libraries with some versions of GCC. As a workaround, you can configure +gettext with the option <span style="font-family: monospace;">--disable-libasprintf</span>.<br> +<h4><a name="building_install"></a>“make install” fails</h4> +“<span style="font-family: monospace;">make install DESTDIR=<span + style="font-style: italic;">/some/tempdir</span></span>” can fail with +an error message relating to <span style="font-family: monospace;">libgettextlib</span> +or <span style="font-family: monospace;">libgettextsrc</span>, or can +silently fail to install <span style="font-family: monospace;">libgettextsrc</span>. +On some platforms, this is due to limitations of libtool regarding <span + style="font-family: monospace;">DESTDIR</span>. On other platforms, it +is due to the way the system handles shared libraries, and libtool +cannot work around it. Fortunately, on Linux and other glibc based +systems, <span style="font-family: monospace;">DESTDIR</span> is +supported if no different version of gettext is already installed (i.e. +it works if you uninstall the older gettext before building and +installing the newer one, or if you do a plain “<span + style="font-family: monospace;">make install</span>” before “<span + style="font-family: monospace;">make install DESTDIR=<span + style="font-style: italic;">/some/tempdir</span></span>”). On other +systems, when <span style="font-family: monospace;">DESTDIR</span> +does not work, you can still do “<span style="font-family: monospace;">make +install</span>” and copy the installed files to <span + style="font-family: monospace;"><span style="font-style: italic;">/some/tempdir</span></span> +afterwards.<br> +<br> +If “<span style="font-family: monospace;">make install</span>” without <span + style="font-family: monospace;">DESTDIR</span> fails, it's a bug which +you are welcome to report to the usual bug report address. +<h3>Problems integrating GNU gettext</h3> +<h4><a name="integrating_howto"></a>How do I make use of <span + style="font-family: monospace;">gettext()</span> in my package?</h4> +It's not as difficult as it sounds. Here's the recipe for C or C++ +based packages.<br> +<ul> + <li>Add an invocation of <span style="font-family: monospace;">AM_GNU_GETTEXT([external])</span> +to the package's <span style="font-family: monospace;">configure.{ac,in}</span> +file.</li> + <li>Invoke “<span style="font-family: monospace;">gettextize --copy</span>”. +It will do most of the autoconf/automake related work for you.</li> + <li>Add the <span style="font-family: monospace;">gettext.h</span> +file to the package's source directory, and include it in all source +files that contain translatable strings or do output via <span + style="font-family: monospace;">printf</span> or <span + style="font-family: monospace;">fprintf</span>.</li> + <li>In the source file defining the main() function of the program, +add these lines to the header<br> + <div style="margin-left: 40px;"><code><span + style="font-family: monospace;">#include <locale.h></span><br + style="font-family: monospace;"> + <span style="font-family: monospace;">#include "gettext.h"</span></code><br> + </div> +and these lines near the beginning of the main() function:<br> + <div style="margin-left: 40px;"><code><span + style="font-family: monospace;">setlocale (LC_ALL, "");</span><br + style="font-family: monospace;"> + <span style="font-family: monospace;">bindtextdomain (PACKAGE, +LOCALEDIR);</span><br style="font-family: monospace;"> + <span style="font-family: monospace;">textdomain (PACKAGE);</span></code><br> + </div> + </li> + <li>Mark all strings that should be translated with _(), like this: <span + style="font-family: monospace;">_("No errors found.")</span>. While +doing this, try to turn the strings into good English, one entire +sentence per string, not more than one paragraph per string, and use +format strings instead of string concatenation. This is needed so that +the translators can provide accurate translations.</li> + <li>In every source file containing translatable strings, add these lines +to the header:<br> + <div style="margin-left: 40px;"><code><span + style="font-family: monospace;">#include "gettext.h"</span><br + style="font-family: monospace;"> + <span style="font-family: monospace;">#define _(string) gettext (string)</span></code><br> + </div> + </li> + <li>In the freshly created <span style="font-family: monospace;">po/</span> +directory, set up the <span style="font-family: monospace;">POTFILES.in</span> +file, and do a “<span style="font-family: monospace;">make update-po</span>”. +Then distribute the generated <span style="font-family: monospace;">.pot</span> +file to your nearest translation project.</li> + <li>Shortly before a release, integrate the translators' <span + style="font-family: monospace;">.po</span> files into the <span + style="font-family: monospace;">po/</span> directory and do “<span + style="font-family: monospace;">make update-po</span>” again.<br> + </li> +</ul> +You find detailed descriptions of how this all works in the GNU gettext +manual, chapters “The Maintainer's View” and “Preparing Program +Sources”. +<h4><a name="integrating_undefined"></a>I get a linker error “undefined +reference to libintl_gettext”</h4> +This error means that the program uses the <span + style="font-family: monospace;">gettext()</span> function after having +included the <span style="font-family: monospace;"><libintl.h></span> +file from GNU gettext (which remaps it to <span + style="font-family: monospace;">libintl_gettext()</span>), however at +link time a function of this name could not be linked in. (It is +expected to come from the <span style="font-family: monospace;">libintl</span> +library, installed by GNU gettext.)<br> +<br> +There are many possible reasons for this error, but in any case you +should consider the <span style="font-family: monospace;">-I</span>, <span + style="font-family: monospace;">-L</span> and <span + style="font-family: monospace;">-l</span> options passed to the +compiler. In packages using <span style="font-family: monospace;">autoconf</span> +generated configure scripts, <span style="font-family: monospace;">-I</span> +options come from the <span style="font-family: monospace;">CFLAGS</span> +and <span style="font-family: monospace;">CPPFLAGS</span> variables +(in Makefiles also <span style="font-family: monospace;">DEFS</span> +and <span style="font-family: monospace;">INCLUDES</span>), <span + style="font-family: monospace;">-L</span> options come from the <span + style="font-family: monospace;">LDFLAGS</span> variable, and <span + style="font-family: monospace;">-l</span> options come from the <span + style="font-family: monospace;">LIBS</span> variable. The first thing +you should check are the values of these variables in your environment +and in the package's <span style="font-family: monospace;">config.status</span> +autoconfiguration result.<br> +<br> +To find the cause of the error, a little analysis is needed. Does the +program's final link command contains the option “-lintl”?<br> +<ul> + <li>If yes:<br> +Find out where the <span style="font-family: monospace;">libintl</span> +comes from. To do this, you have to check for <span + style="font-family: monospace;">libintl.a</span> and <span + style="font-family: monospace;">libintl.so*</span> (<span + style="font-family: monospace;">libintl.dylib</span> on MacOS X) in +each directory given as a -L option, as well as in the compiler's +implicit search directories. (You get these implicit search directories +for gcc by using “<span style="font-family: monospace;">gcc -v</span>” +instead of “<span style="font-family: monospace;">gcc</span>” in the +final link command line; compilers other than GCC usually look in <span + style="font-family: monospace;">/usr/lib</span> and <span + style="font-family: monospace;">/lib</span>.) A shell command like<br> + <div style="margin-left: 40px;"><code>$ for d in /usr/local/lib +/usr/lib /lib; do ls -l $d/libintl.*; done</code><br> + </div> +will show where the <span style="font-family: monospace;">libintl</span> +comes from. By looking at the dates and whether each library defines <span + style="font-family: monospace;">libintl_gettext</span> (via “<span + style="font-family: monospace;">nm <span style="font-style: italic;">path</span>/libintl.so +| grep libintl_gettext</span>”) you can now distinguish three possible +causes of the error:<br> + <ul> + <li>Some older libintl is used instead of the newer one. The fix +is to remove the old library or to reorganize your -L options.</li> + <li>The used libintl is the new one, and it doesn't contain +libintl_gettext. This would be a bug in gettext. If this is the case, +please report it to the usual bug report address.</li> + <li>The used libintl is a static library (libintl.a), there are +no uses of gettext in .o files before the “-lintl” but there are some +after the “-lintl”. In this case the fix is to move the “-lintl” to the +end or near the end of the link command line. The only libintl +dependency that needs to be mentioned after “-lintl” is “-liconv”.</li> + </ul> + </li> + <li>If no:<br> +In this case it's likely a bug in the package you are building: The +package's Makefiles should make sure that “-lintl” is used where needed.<br> +Test whether libintl was found by configure. You can check this by doing<br> + <div style="margin-left: 40px;"><code>$ grep +'\(INTLLIBS\|LIBINTL\)' config.status</code><br> + </div> +and looking whether the value of this autoconf variable is non-empty.<br> + <ul> + <li>If yes: It should be the responsibility of the Makefile to +use the value of this variable in the link command line. Does the +Makefile.in rule for linking the program use <span + style="font-family: monospace;">@INTLLIBS@</span> or <span + style="font-family: monospace;">@LIBINTL@</span>?<br> + <ul> + <li>If no: It's a Makefile.am/in bug.</li> + <li>If yes: Something strange is going on. You need to dig +deeper.</li> + </ul> +Note that <span style="font-family: monospace;">@INTLLIBS@</span> is +for <span style="font-family: monospace;">gettext.m4</span> versions +<= 0.10.40 and <span style="font-family: monospace;">@LIBINTL@</span> +is for <span style="font-family: monospace;">gettext.m4</span> +versions >= 0.11, depending on which <span + style="font-family: monospace;">gettext.m4</span> was used to build +the package's <span style="font-family: monospace;">configure</span> - +regardless of which gettext you have now installed.</li> + <li>If no: So libintl was not found.<br> +Take a look at the package's <span style="font-family: monospace;">configure.in/ac</span>. +Does it invoke AM_GNU_GETTEXT?<br> + <ul> + <li>If no: The gettext maintainers take no responsibilities for +lookalikes named CY_GNU_GETTEXT, AM_GLIB_GNU_GETTEXT, AM_GNOME_GETTEXT +and similar, or for homebrewn autoconf checks. Complain to the package +maintainer.</li> + <li>If yes: It looks like the <span + style="font-family: monospace;">-I</span> and <span + style="font-family: monospace;">-L</span> options were inconsistent. +You should have a <span style="font-family: monospace;">-I<span + style="font-style: italic;">somedir</span>/include</span> in the <span + style="font-family: monospace;">CFLAGS</span> or <span + style="font-family: monospace;">CPPFLAGS</span> if and only if you +also have a <span style="font-family: monospace;">-L<span + style="font-style: italic;">somedir</span>/lib</span> in the <span + style="font-family: monospace;">LDFLAGS</span>. And <span + style="font-family: monospace;"><span style="font-style: italic;">somedir</span>/include</span> +should contain a <span style="font-family: monospace;">libintl.h</span> +if and only if <span style="font-family: monospace;"><span + style="font-style: italic;">somedir</span>/lib</span> contains <span + style="font-family: monospace;">libintl.{a,so}</span>.<br> +This case can also happen if you have configured a GCC < 3.2 with +the same <span style="font-family: monospace;">--prefix</span> option +as you used for GNU libiconv or GNU gettext. This is fatal, because +these versions of GCC implicitly use <span + style="font-family: monospace;">-L<span style="font-style: italic;">prefix</span>/lib</span> +but <span style="font-weight: bold; font-style: italic;">not</span><br + style="font-weight: bold; font-style: italic;"> + <span style="font-family: monospace;">-I<span + style="font-style: italic;">prefix</span>/include</span>. The +workaround is to use a different <span style="font-family: monospace;">--prefix</span> +for GCC.<br> + </li> + </ul> + </li> + </ul> + </li> +</ul> +<h4><a name="integrating_abuse_gettextize"></a>gettextize adds multiple +references to the same directories/files +to <span style="font-family: monospace;">Makefile.am</span> and <span + style="font-family: monospace;">configure.ac</span></h4> +If <span style="font-family: monospace;">gettextize</span> is used on +a package, then the <span style="font-family: monospace;">po/</span>, <span + style="font-family: monospace;">intl/</span>, <span + style="font-family: monospace;">m4/</span> directories of the package +are removed, and then <span style="font-family: monospace;">gettextize</span> +is invoked on the package again, it will re-add the <span + style="font-family: monospace;">po/</span>, <span + style="font-family: monospace;">intl/</span>, <span + style="font-family: monospace;">m4/</span> directories and change <span + style="font-family: monospace;">Makefile.am</span>, <span + style="font-family: monospace;">configure.ac</span> and <span + style="font-family: monospace;">ChangeLog</span> accordingly. This is +normal. The second use of <span style="font-family: monospace;">gettextize</span> +here is an abuse of the program. <span style="font-family: monospace;">gettextize</span> +is a wizard intended to transform a <span style="font-style: italic;">working +source package</span> into a <span style="font-style: italic;">working +source package</span> that uses the newest version of gettext. If you +start out from a nonfunctional source package (it is nonfunctional +since you have omitted some directories), you cannot expect that <span + style="font-family: monospace;">gettextize</span> corrects it.<br> +<br> +Often this question arises in packages that use CVS. See the section +“CVS Issues / Integrating with CVS” of the GNU gettext documentation. +This section mentions a program <span style="font-family: monospace;">autopoint</span> +which is designed to reconstruct those files and directories created by +<span style="font-family: monospace;">gettextize</span> that can be +omitted from a CVS repository.<br> +<h4><a name="integrating_noop"></a>My program compiles and links fine, +but doesn't output translated +strings.</h4> +There are several possible reasons. Here is a checklist that allows you +to determine the cause.<br> +<ol> + <li>Check that the environment variables LC_ALL, LC_MESSAGES, +LC_CTYPE, LANG, LANGUAGE together specify a valid locale and language.<br> +To check this, run the commands<br> + <div style="margin-left: 40px;"><code>$ gettext --version</code><br> + <code>$ gettext --help</code><br> + </div> +You should see at least some output in your desired language. If not, +either<br> + <ul> + <li>You have chosen a too exotic language. <span + style="font-family: monospace;">gettext</span> is localized to 33 +languages. Choose a less exotic language, such as Galician or +Ukrainian. Or<br> + </li> + <li>There is a problem with your environment variables. Possibly +LC_ALL points to a locale that is not installed, or LC_MESSAGES and +LC_CTYPE are inconsistent.</li> + </ul> + </li> + <li>Check that your program contains a <span + style="font-family: monospace;">setlocale</span> call.<br> +To check this, run your program under ltrace. For example,<br> + <div style="margin-left: 40px;"><code>$ ltrace ./myprog</code><br> + <code>...</code><br> + <code>setlocale(6, +"") += "de_DE.UTF-8"</code><br> + </div> +If you have no ltrace, you can also do this check by running your +program under the debugger. For example,<br> + <div style="margin-left: 40px;"><code>$ gdb ./myprog</code><br> + <code>(gdb) break main</code><br> + <code>(gdb) run</code><br> + <code>Breakpoint 1, main ()</code><br> + <code>(gdb) break setlocale</code><br> + <code>(gdb) continue</code><br> + <code>Breakpoint 2, setlocale ()</code><br> + <code>;; OK, the breakpoint has been hit, setlocale() is being +called.</code><br> + </div> +Either way, check that the return value of <span + style="font-family: monospace;">setlocale()</span> is non-NULL. A NULL +return value indicates a failure. </li> + <li>Check that your program contains a <span + style="font-family: monospace;">textdomain</span> call, a <span + style="font-family: monospace;">bindtextdomain</span> call referring +to the same message domain, and then really calls the <span + style="font-family: monospace;">gettext</span>, <span + style="font-family: monospace;">dgettext</span> or <span + style="font-family: monospace;">dcgettext</span> function.<br> +To check this, run the program under ltrace. For example,<br> + <div style="margin-left: 40px;"><code>$ ltrace ./myprog</code><br> + <code>...</code><br> + <code>textdomain("hello-c") += "hello-c"</code><br> + <code>bindtextdomain("hello-c", "/opt/share"...) = "/opt/share"...</code><br> + <code>dcgettext(0, 0x08048691, 5, 0x0804a200, 0x08048689) = +0x4001721f</code><br> + </div> +If you have no ltrace, you can also do this check by running your +program under the debugger. For example,<br> + <div style="margin-left: 40px;"><code>$ gdb ./myprog</code><br> + <code>(gdb) break main</code><br> + <code>(gdb) run</code><br> + <code>Breakpoint 1, main ()</code><br> + <code>(gdb) break textdomain</code><br> + <code>(gdb) break bindtextdomain</code><br> + <code>(gdb) break gettext</code><br> + <code>(gdb) break dgettext</code><br> + <code>(gdb) break dcgettext</code><br> + <code>(gdb) continue</code><br> + <code>Breakpoint 2, textdomain ()</code><br> + <code>(gdb) continue</code><br> + <code>Breakpoint 3, bindtextdomain ()</code><br> + <code>(gdb) continue</code><br> + <code>Breakpoint 6, dcgettext ()</code><br> + </div> +Note that here <span style="font-family: monospace;">dcgettext()</span> +is called instead of the <span style="font-family: monospace;">gettext()</span> +function mentioned in the source code; this is due to an optimization +in <span style="font-family: monospace;"><libintl.h></span>.<br> +When using libintl on a non-glibc system, you have to add a prefix “<span + style="font-family: monospace;">libintl_</span>” to all the function +names mentioned here, because that's what the functions are really +named, under the hood.<br> +If <span style="font-family: monospace;">gettext</span>/<span + style="font-family: monospace;">dgettext</span>/<span + style="font-family: monospace;">dcgettext</span> is not called at all, +the possible cause might be that some autoconf or Makefile macrology +has turned off internationalization entirely (like the <span + style="font-family: monospace;">--disable-nls</span> configuration +option usually does).<br> + </li> + <li>Check that the <span style="font-family: monospace;">.mo</span> +file that contains the translation is really there where the program +expects it.<br> +To check this, run the program under strace and look at the <span + style="font-family: monospace;">open()</span> calls. For example,<br> + <div style="margin-left: 40px;"><code>$ strace ./myprog 2>&1 +| grep '^open('</code><br> + <code>open("/etc/ld.so.preload", O_RDONLY) = -1 +ENOENT (No such file or directory)</code><br> + <code>open("/etc/ld.so.cache", +O_RDONLY) = 5</code><br> + <code>open("/lib/libc.so.6", +O_RDONLY) = 5</code><br> + <code>open("/usr/lib/locale/locale-archive", O_RDONLY|O_LARGEFILE) += 5</code><br> + <code>open("/usr/share/locale/locale.alias", O_RDONLY) = 5</code><br> + <code>open("/opt/share/locale/de/LC_MESSAGES/hello-c.mo", O_RDONLY) += 5</code><br> + <code>...</code><br> + </div> +A nonnegative <span style="font-family: monospace;">open()</span> +return value means that the file has been found.<br> +If you have no strace, you can also guess the <span + style="font-family: monospace;">.mo</span> file's location: it is<br> + <div style="margin-left: 40px;"><span + style="font-family: monospace;"><span style="font-style: italic;">localedir</span>/<span + style="font-style: italic;">lang</span>/LC_MESSAGES/<span + style="font-style: italic;">domain</span>.mo</span><br> + </div> +where <span style="font-style: italic;">domain</span> is the argument +passed to <span style="font-family: monospace;">textdomain()</span>, <span + style="font-style: italic;">localedir</span> is the second argument +passed to <span style="font-family: monospace;">bindtextdomain()</span>, +and <span style="font-style: italic;">lang</span> is the language (<span + style="font-style: italic;">LL</span>) or language and territory (<span + style="font-style: italic;">LL</span>_<span style="font-style: italic;">CC</span>), +depending on the environment variables checked in step 1.</li> + <li>Check that the .mo file contains a translation for the string +that is being asked for.<br> +To do this, you need to convert the .mo file back to PO file format, +through the command<br> + <div style="margin-left: 40px;"><code>$ msgunfmt </code><span + style="font-family: monospace;"><span style="font-style: italic;">localedir</span>/<span + style="font-style: italic;">lang</span>/LC_MESSAGES/<span + style="font-style: italic;">domain</span>.mo</span><br> + <code></code></div> +and look for an <span style="font-family: monospace;">msgid</span> +that matches the given string.<br> + </li> +</ol> +<h3>GNU gettext on Windows</h3> +<h4><a name="windows_woe32"></a>What does Woe32 mean?</h4> +“Woe32” denotes the Windows 32-bit operating systems for x86: Windows +NT/2000/XP/Vista and Windows 95/98/ME. Microsoft uses the term “Win32” to +denote these; this is a psychological trick in order to make everyone +believe that these OSes are a “win” for the user. However, for most +users and developers, they are a source of woes, which is why I call +them “Woe32”.<br> +<h4><a name="windows_howto"></a>How do I compile, link and run a +program that uses the gettext() +function?</h4> +When you use RedHat's cygwin environment, it's as on Unix:<br> +<ul> + <li>You need to add an <span style="font-family: monospace;">-I</span> +option to the compilation command line, so that the compiler finds the <span + style="font-family: monospace;">libintl.h</span> include file, and</li> + <li>You need to add an <span style="font-family: monospace;">-L</span> +option to the link command line, so that the linker finds the <span + style="font-family: monospace;">libintl</span> library.</li> +</ul> +When you use the Mingw environment (either from within cygwin, with <span + style="font-family: monospace;">CC="gcc -mno-cygwin"</span>, or from +MSYS, with <span style="font-family: monospace;">CC="gcc"</span>), I +don't know the details.<br> +<br> +When you use the Microsoft Visual C/C++ (MSVC) compiler, you will +likely use the precompiled Woe32 binaries. For running a program that +uses gettext(), one needs the <span style="font-family: monospace;">.bin.woe32.zip</span> +packages of <span style="font-family: monospace;">gettext-runtime</span> +and <span style="font-family: monospace;">libiconv</span>. As a +developer, you'll also need the <span style="font-family: monospace;">xgettext</span> +and <span style="font-family: monospace;">msgfmt</span> programs that +are contained in the <span style="font-family: monospace;">.bin.woe32.zip</span> +package of <span style="font-family: monospace;">gettext-tools</span>. +Then<br> +<ul> + <li>You need to add an <span style="font-family: monospace;">-MD</span> +option to all compilation and link command lines. MSVC has six +different, mutually incompatible, compilation models (<span + style="font-family: monospace;">-ML</span>, <span + style="font-family: monospace;">-MT</span>, <span + style="font-family: monospace;">-MD</span>, <span + style="font-family: monospace;">-MLd</span>, <span + style="font-family: monospace;">-MTd</span>, <span + style="font-family: monospace;">-MDd</span>); the default is <span + style="font-family: monospace;">-ML</span>. <span + style="font-family: monospace;">intl.dll</span> uses the <span + style="font-family: monospace;">-MD</span> model, therefore the rest +of the program must use <span style="font-family: monospace;">-MD</span> +as well.<br> + </li> + <li>You need to add an <span style="font-family: monospace;">-I</span> +option to the compilation command line, so that the compiler finds the <span + style="font-family: monospace;">libintl.h</span> include file.<br> + </li> + <li>You need to add an <span style="font-family: monospace;">-L</span> +option to the link command line, so that the linker finds the <span + style="font-family: monospace;">intl.lib</span> library.</li> + <li>You need to copy the <span style="font-family: monospace;">intl.dll</span> +and <span style="font-family: monospace;">iconv.dll</span> to the +directory where your <span style="font-family: monospace;">.exe</span> +files are created, so that they will be found at runtime.<br> + </li> +</ul> +<h4><a name="windows_setenv"></a>Setting the <span + style="font-family: monospace;">LANG</span> +environment variable doesn't have any effect</h4> +If neither LC_ALL, LC_MESSAGES nor LANGUAGES is set, it's the LANG +environment variable which determines the language into which gettext() +translates the messages.<br> +<br> +You can test your program by setting the LANG environment variable from +outside the program. In a Windows command interpreter:<br> +<div style="margin-left: 40px;"><code>set LANG=de_DE</code><br> +<code>.\myprog.exe</code><br> +</div> +Or in a Cygwin shell:<br> +<div style="margin-left: 40px;"><code>$ env LANG=de_DE ./myprog.exe</code><br> +</div> +<br> +If this test fails, look at the question “My program compiles and links +fine, but doesn't output translated +strings.” above.<br> +<br> +If this test succeeds, the problem is related in the way you set the +environment variable. Here is a checklist:<br> +<ul> + <li>Check that you are using the <span + style="font-family: monospace;">-MD</span> option in all compilation +and link command lines. Otherwise you might end up calling the <span + style="font-family: monospace;">putenv()</span> function from +Microsoft's <span style="font-family: monospace;">libc.lib</span>, +whereas <span style="font-family: monospace;">intl.dll</span> is using +the <span style="font-family: monospace;">getenv()</span> function +from Mictosoft's <span style="font-family: monospace;">msvcrt.lib</span>.</li> + <li>Check that you set the environment variable using <span + style="font-style: italic;">both</span> <span + style="font-family: monospace;">SetEnvironmentVariable()</span> and <span + style="font-family: monospace;">putenv()</span>. A convenient way to +do so, and to deal with the fact that some Unix systems have <span + style="font-family: monospace;">setenv()</span> and some don't, is the +following function.<br> + <br> + <div style="margin-left: 40px;"><code>#include <string.h></code><br> + <code>#include <stdlib.h></code><br> + <code>#if defined _WIN32</code><br> + <code># include <windows.h></code><br> + <code>#endif</code><br> + <code></code><br> + <code>int my_setenv (const char * name, const char * value) {</code><br> + <code> size_t namelen = strlen(name);</code><br> + <code> size_t valuelen = (value==NULL ? 0 : strlen(value));</code><br> + <code>#if defined _WIN32</code><br> + <code> /* On Woe32, each process has two copies of the +environment variables,</code><br> + <code> one managed by the OS and one +managed by the C library. We set</code><br> + <code> the value in both locations, so that +other software that looks in</code><br> + <code> one place or the other is guaranteed +to see the value. Even if it's</code><br> + <code> a bit slow. See also</code><br> + <code> <<a + href="https://article.gmane.org/gmane.comp.gnu.mingw.user/8272">https://article.gmane.org/gmane.comp.gnu.mingw.user/8272</a>></code><br> + <code> <<a + href="https://article.gmane.org/gmane.comp.gnu.mingw.user/8273">https://article.gmane.org/gmane.comp.gnu.mingw.user/8273</a>></code><br> + <code> <<a + href="https://www.cygwin.com/ml/cygwin/1999-04/msg00478.html">https://www.cygwin.com/ml/cygwin/1999-04/msg00478.html</a>> +*/</code><br> + <code> if (!SetEnvironmentVariableA(name,value))</code><br> + <code> return -1; </code><br> + <code>#endif</code><br> + <code>#if defined(HAVE_PUTENV)</code><br> + <code> char* buffer = (char*)malloc(namelen+1+valuelen+1);</code><br> + <code> if (!buffer)</code><br> + <code> return -1; /* no need to set errno = +ENOMEM */</code><br> + <code> memcpy(buffer,name,namelen);</code><br> + <code> if (value != NULL) {</code><br> + <code> buffer[namelen] = '=';</code><br> + <code> memcpy(buffer+namelen+1,value,valuelen);</code><br> + <code> buffer[namelen+1+valuelen] = 0;</code><br> + <code> } else</code><br> + <code> buffer[namelen] = 0;</code><br> + <code> return putenv(buffer);</code><br> + <code>#elif defined(HAVE_SETENV)</code><br> + <code> return setenv(name,value,1);</code><br> + <code>#else</code><br> + <code> /* Uh oh, neither putenv() nor setenv() ... */</code><br> + <code> return -1;</code><br> + <code>#endif</code><br> + <code>}</code><br> + <code></code></div> + <br> + </li> +</ul> +<h3>Other</h3> +<h4><a name="newline"></a>What does this mean: “'msgid' and 'msgstr' +entries do not both end +with '\n'”</h4> +It means that when the original string ends in a newline, your +translation must also end in a newline. And if the original string does +not end in a newline, then your translation should likewise not have a +newline at the end.<br> +<h4><a name="translit"></a>German umlauts are displayed like +“ge"andert” instead of “geändert”</h4> +This symptom occurs when the <span style="font-family: monospace;">LC_CTYPE</span> +facet of the locale is not set; then gettext() doesn't know which +character set to use, and converts all messages to ASCII, as far as +possible.<br> +<br> +If the program is doing<br> +<code><br> +setlocale (LC_MESSAGES, "");<br> +<br> +</code>then change it to<br> +<code><br> +setlocale (LC_CTYPE, "");<br> +setlocale (LC_MESSAGES, "");<br> +</code><br> +or do both of these in a single call:<br> +<code><br> +setlocale (LC_ALL, "");<br> +</code><br> +If the program is already doing<br> +<code><br> +setlocale (LC_ALL, "");<br> +</code><br> +then the symptom can still occur if the user has not set <span + style="font-family: monospace;">LANG</span>, but instead has set <span + style="font-family: monospace;">LC_MESSAGES</span> to a valid locale +and has set <span style="font-family: monospace;">LC_CTYPE</span> to +nothing or an invalid locale. The fix for the user is then to set <span + style="font-family: monospace;">LANG</span> instead of <span + style="font-family: monospace;">LC_MESSAGES</span>.<br> +<h4><a name="localename"></a>The <span style="font-family: monospace;">LANGUAGE</span> +environment variable is ignored after I set <span + style="font-family: monospace;">LANG=en</span></h4> +This is because “en” is a language name, but not a valid locale name. +The <a href="https://www.gnu.org/software/gettext/manual/html_node/The-LANGUAGE-variable.html">documentation</a> says:<br> +<blockquote> +In the <span style="font-family: monospace;">LANGUAGE</span> +environment variable, but not in the <span + style="font-family: monospace;">LANG</span> environment variable, <span + style="font-style: italic;">LL</span>_<span style="font-style: italic;">CC</span><span + style="font-family: monospace;"> </span>combinations can be +abbreviated as <span style="font-style: italic;">LL</span> to +denote the language's main dialect.</blockquote> +Why is <span style="font-family: monospace;">LANG=en</span> not +allowed? Because <span style="font-family: monospace;">LANG</span> is +a setting for the entire locale, including monetary information, and +this depends on the country: en_GB, en_AU, en_ZA all have different +currencies.<br> +<h4><a name="nonascii_strings"></a>I use accented characters in my +source code. How do I tell the +C/C++ compiler in which encoding it is (like <span + style="font-family: monospace;">xgettext</span>'s <span + style="font-family: monospace;">--from-code</span> option)?</h4> +Short answer: If you want your program to be useful to other people, +then <span style="font-style: italic;">don't use accented characters</span> +(or other non-ASCII characters) in string literals <span + style="font-style: italic;">in the source code</span>. Instead, use +only ASCII for string literals, and use <span + style="font-family: monospace;">gettext()</span> to retrieve their +display-ready form.<br> +<br> +Long explanation:<br> +The reason is that the ISO C standard specifies that the character set +at compilation time can be different from the character set at +execution time.<br> +The character encoding at compilation time is the one which determines +how the source files are interpreted and also how string literals are +stored in the compiled code. This character encoding is generally +unspecified; for recent versions of GCC, it depends on the LC_CTYPE +locale in effect during the compilation process.<br> +The character encoding at execution time is the one which determines +how standard functions like <span style="font-family: monospace;">isprint()</span>, +<span style="font-family: monospace;">wcwidth()</span> etc. work and +how strings written to standard output should be encoded. This +character encoding is specified by POSIX to depend on the LC_CTYPE +locale in effect when the program is executed; see also the description +in the <a href="https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html">documentation</a>.<br> +Strings in the compiled code are not magically converted between the +time the program is compiled and the time it is run.<br> +<br> +Therefore what could you do to get accented characters to work?<br> +<br> +Can you ensure that the execution character set is the same as the +compilation character set? Even if your program is to be used only in a +single country, this is not realistically possible. For example, in +Germany there are currently three character encodings in use: UTF-8, +ISO-8859-15 and ISO-8859-1. Therefore you would have to explicitly +convert the accented strings from the compilation character set to the +execution character set at runtime, for example through iconv().<br> +<br> +Can you ensure that the compilation character set is the one in which +your source files are stored? This is not realistically possible +either: For compilers other than GCC, there is no way to specify the +compilation character set. So let's assume for a moment that everyone +uses GCC; then you will specify the LC_CTYPE or LC_ALL environment +variable in the Makefile. But for this you have to assume that everyone +has a locale in a given encoding. Be it UTF-8 or ISO-8859-1 - this is +not realistic. People often have no locale installed besides the one +they use.<br> +<br> +Use of wide strings <span style="font-family: monospace;">L"..."</span> +doesn't help solving the problem, because on systems like FreeBSD or +Solaris, the way how wide string literals are stored in compiled code +depends on the compilation character set, just as it does for +narrow strings <span style="font-family: monospace;">"..."</span>. +Moreover, wide strings have problems of their own.<br> +<br> +Use of ISO C 99 Unicode escapes "\u<span style="font-style: italic;">xxxx</span>" +doesn't help either because these characters are converted to the +compilation character set at compile time; so again, since you can't +guarantee that the compilation character set is not ASCII, you're +risking compilation errors just as if the real character had been used +in the source instead of the Unicode escape.<br> +<br> +So, in summary, there is no way to make accented characters in string +literals work in C/C++.<br> +<br> +You might then wonder what <span style="font-family: monospace;">xgettext</span>'s +<span style="font-family: monospace;">--from-code</span> option is good +for. The answer is<br> +<ol> + <li>For the comments in C/C++ source code. The compiler ignores them.<br> + </li> + <li>For other programming languages like Java, for which the compiler +converts all string literals to UTF-8.</li> +</ol> +<br> +<hr style="width: 100%; height: 2px;"> +<address>GNU gettext FAQ<br> +Bruno Haible <<a href="mailto:bruno@clisp.org">bruno@clisp.org</a>></address> +<p>Last modified: 6 June 2020 +</p> +</body> +</html>