Spaces:
Running
Running
| <html> | |
| <!-- | |
| Copyright (C) 2004-2005, 2007-2008, 2010, 2012, 2014, 2019-2020 Free Software Foundation, Inc. | |
| Written by Bruno Haible <[email protected]>, 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;">[email protected]</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;">[email protected]</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;">[email protected]</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:[email protected]">[email protected]</a>></address> | |
| <p>Last modified: 6 June 2020 | |
| </p> | |
| </body> | |
| </html> | |