1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3<head> 4 <meta http-equiv="content-type" content="text/html; charset=UTF-8"> 5 <title>GNU gettext FAQ</title> 6</head> 7<body> 8<h1 style="text-align: center;">Frequently Asked Questions<br> 9for GNU gettext 10</h1> 11<h1 style="text-align: center;">Questions</h1> 12<h3>General</h3> 13<ul> 14 <li><a href="#general_mailinglist">Where is the mailing list?</a></li> 15 <li><a href="#general_source">Where is the newest gettext source?</a></li> 16 <li><a href="#general_announce">I want to be notified of new gettext 17releases.</a></li> 18</ul> 19<h3>Problems building GNU gettext</h3> 20<ul> 21 <li><a href="#building_solaris_libasprintf">On Solaris, I get a build 22error “text relocations remain” in the <span 23 style="font-family: monospace;">libasprintf</span> subdirectory</a></li> 24 <li><a href="#building_rpath_check">During “make check”, some tests 25named <span style="font-family: monospace;">rpath-<span 26 style="font-style: italic;">Nxyz</span></span> 27fail: “ld: fatal error ... -lrpathz”</a></li> 28 <li><a href="#building_install">“make install” fails</a></li> 29</ul> 30<h3>Problems integrating GNU gettext</h3> 31<ul> 32 <li><a href="#integrating_howto">How do I make use of <span 33 style="font-family: monospace;">gettext()</span> in my package?</a></li> 34 <li><a href="#integrating_undefined">I get a linker error “undefined 35reference to libintl_gettext”</a></li> 36 <li><a href="#integrating_abuse_gettextize">gettextize adds multiple 37references to the same directories/files 38to <span style="font-family: monospace;">Makefile.am</span> and </a><span 39 style="font-family: monospace;"><a href="#integrating_abuse_gettextize">configure.ac</a><br> 40 </span></li> 41 <li><a href="#integrating_noop">My program compiles and links fine, 42but doesn't output translated 43strings.</a><br> 44 </li> 45</ul> 46<h3>GNU gettext on Windows</h3> 47<ul> 48 <li><a href="#windows_woe32">What does Woe32 mean?</a></li> 49 <li><a href="#windows_howto">How do I compile, link and run a program 50that uses the gettext() 51function?</a><br> 52 </li> 53 <li><a href="#windows_setenv">Setting the <span 54 style="font-family: monospace;">LANG</span> 55environment variable doesn't have any effect</a></li> 56</ul> 57<h3>Other</h3> 58<ul> 59 <li><a href="#newline">What does this mean: “`msgid' and `msgstr' 60entries do not both 61end with '\n'”</a></li> 62 <li><a href="#translit">German umlauts are displayed like “ge"andert” 63instead of 64“geändert”</a></li> 65 <li><a href="#localename">The <span style="font-family: monospace;">LANGUAGE</span> 66environment variable is ignored after I set <span 67 style="font-family: monospace;">LANG=en</span></a></li> 68 <li><a href="#nonascii_strings">I use accented characters in my 69source code. How do I tell the 70C/C++ compiler in which encoding it is (like <span 71 style="font-family: monospace;">xgettext</span>'s <span 72 style="font-family: monospace;">--from-code</span> option)?</a></li> 73</ul> 74<h1 style="text-align: center;">Answers</h1> 75<h3>General</h3> 76<h4><a name="general_mailinglist"></a>Where is the mailing list?</h4> 77Three mailing lists are available: <br> 78<ul> 79 <li><span style="font-family: monospace;">bug-gnu-gettext@gnu.org</span><br> 80This mailing list is for discussion of features and bugs of the GNU 81gettext <span style="font-style: italic;">software</span>, including 82libintl, the gettext-tools, and its autoconf macros.</li> 83 <li><span style="font-family: monospace;">translation-i18n@lists.sourceforge.net</span><br> 84This mailing list is for methodology questions around 85internationalization, and for discussions of translator tools, 86including but not limited to GNU gettext.</li> 87 <li><span style="font-family: monospace;">translation@iro.umontreal.ca</span><br> 88This is the email address of the <a 89 href="http://www.iro.umontreal.ca/contrib/po/HTML/">Free Translation 90Project</a>, that is the project which manages the translated message 91catalogs for many free software packages. Note that KDE and GNOME 92packages are not part of this project; they have their own translation 93projects: <a href="http://i18n.kde.org/">i18n.kde.org</a> and <a 94 href="http://developer.gnome.org/projects/gtp/">gtp</a>.<br> 95 </li> 96</ul> 97The <span style="font-family: monospace;">bug-gnu-gettext</span> list 98is archived as part of the <a 99 href="http://mail.gnu.org/archive/html/bug-gnu-utils/"><span 100 style="font-family: monospace;">bug-gnu-utils</span></a> archives. <span 101 style="font-family: monospace;">bug-gnu-gettext</span> cannot be 102subscribed on its own; to receive its contents by mail, subscribe to <span 103 style="font-family: monospace;">bug-gnu-utils</span>.<br> 104<h4><a name="general_source"></a>Where is the newest gettext source?</h4> 105The newest gettext release is available on <span 106 style="font-family: monospace;">ftp.gnu.org</span> and its mirrors, in 107<a href="http://ftp.gnu.org/gnu/gettext/">http://ftp.gnu.org/gnu/gettext/</a>.<br> 108<br> 109Prereleases are announced on the <a 110 href="http://mail.gnu.org/pipermail/autotools-announce"><span 111 style="font-family: monospace;">autotools-announce</span> mailing list</a>. 112Note that prereleases are meant for testing and not meant for use in 113production environments. Please don't use the “gettextize” program of a 114prerelease on projects which you share with other programmers via CVS.<br> 115<br> 116If you want to live on the bleeding edge, you can also use the 117development sources. Instructions for retrieving the gettext CVS are 118found <a href="http://savannah.gnu.org/projects/gettext">here</a>. 119Note that building from CVS requires special tools (autoconf, automake, 120m4, groff, bison, etc.) and requires that you pay attention to the <span 121 style="font-family: monospace;">README-alpha</span> and <span 122 style="font-family: monospace;">autogen.sh</span> files in the CVS.<br> 123<h4><a name="general_announce"></a>I want to be notified of new gettext 124releases.</h4> 125If you are interested in stable gettext releases, you can follow the <a 126 href="http://mail.gnu.org/pipermail/info-gnu"><span 127 style="font-family: monospace;">info-gnu</span> mailing list</a>. It 128is also available as a newsgroup <a 129 href="nntp://news.gmane.org/gmane.org.fsf.announce"><span 130 style="font-family: monospace;">gmane.org.fsf.announce</span></a> 131through <a href="http://www.gmane.org/"><span 132 style="font-family: monospace;">gmane.org</span></a>.<br> 133<br> 134You can also periodically check the download location.<br> 135<br> 136If you are interested in testing prereleases as well, you can subscribe 137to the <a href="http://mail.gnu.org/pipermail/autotools-announce"><span 138 style="font-family: monospace;">autotools-announce</span> mailing 139list</a>.<br> 140<h3>Problems building GNU gettext</h3> 141<h4><a name="building_solaris_libasprintf"></a>On Solaris, I get a 142build error “text relocations remain” in the <span 143 style="font-family: monospace;">libasprintf</span> subdirectory</h4> 144libtool (or more precisely, the version of libtool that was available 145at the time the gettext release waas made) doesn't support linking C++ 146libraries with some versions of GCC. As a workaround, you can configure 147gettext with the option <span style="font-family: monospace;">--disable-libasprintf</span>.<br> 148<h4><a name="building_rpath_check"></a>During “make check”, some tests 149named <span style="font-family: monospace;">rpath-<span 150 style="font-style: italic;">Nxyz</span></span> 151fail: “ld: fatal error ... -lrpathz”</h4> 152If only a few among the many rpath tests fail, you can probably ignore 153the problem. The rpath tests are sensitive to incomplete shared library 154support in the system, and to bugs in libtool that creates the shared 155libraries. Some known failures are listed in <span 156 style="font-family: monospace;">autoconf-lib-link/tests/rpath.README</span>.<br> 157<br> 158To ignore the problem, just proceed with<br> 159<br> 160<div style="margin-left: 40px;"><code>cd gettext-tools</code><br> 161<code>make check</code><br> 162<code>cd ..</code><br> 163</div> 164<br> 165<h4><a name="building_install"></a>“make install” fails</h4> 166“<span style="font-family: monospace;">make install DESTDIR=<span 167 style="font-style: italic;">/some/tempdir</span></span>” can fail with 168an error message relating to <span style="font-family: monospace;">libgettextlib</span> 169or <span style="font-family: monospace;">libgettextsrc</span>, or can 170silently fail to install <span style="font-family: monospace;">libgettextsrc</span>. 171On some platforms, this is due to limitations of libtool regarding <span 172 style="font-family: monospace;">DESTDIR</span>. On other platforms, it 173is due to the way the system handles shared libraries, and libtool 174cannot work around it. Fortunately, on Linux and other glibc based 175systems, <span style="font-family: monospace;">DESTDIR</span> is 176supported if no different version of gettext is already installed (i.e. 177it works if you uninstall the older gettext before building and 178installing the newer one, or if you do a plain “<span 179 style="font-family: monospace;">make install</span>” before “<span 180 style="font-family: monospace;">make install DESTDIR=<span 181 style="font-style: italic;">/some/tempdir</span></span>”). On other 182systems, when <span style="font-family: monospace;">DESTDIR</span> 183does not work, you can still do “<span style="font-family: monospace;">make 184install</span>” and copy the installed files to <span 185 style="font-family: monospace;"><span style="font-style: italic;">/some/tempdir</span></span> 186afterwards.<br> 187<br> 188If “<span style="font-family: monospace;">make install</span>” without <span 189 style="font-family: monospace;">DESTDIR</span> fails, it's a bug which 190you are welcome to report to the usual bug report address. 191<h3>Problems integrating GNU gettext</h3> 192<h4><a name="integrating_howto"></a>How do I make use of <span 193 style="font-family: monospace;">gettext()</span> in my package?</h4> 194It's not as difficult as it sounds. Here's the recipe for C or C++ 195based packages.<br> 196<ul> 197 <li>Add an invocation of <span style="font-family: monospace;">AM_GNU_GETTEXT([external])</span> 198to the package's <span style="font-family: monospace;">configure.{ac,in}</span> 199file.</li> 200 <li>Invoke “<span style="font-family: monospace;">gettextize --copy</span>”. 201It will do most of the autoconf/automake related work for you.</li> 202 <li>Add the <span style="font-family: monospace;">gettext.h</span> 203file to the package's source directory, and include it in all source 204files that contain translatable strings or do output via <span 205 style="font-family: monospace;">printf</span> or <span 206 style="font-family: monospace;">fprintf</span>.</li> 207 <li>In the source file defining the main() function of the program, 208add these lines to the header<br> 209 <div style="margin-left: 40px;"><code><span 210 style="font-family: monospace;">#include <locale.h></span><br 211 style="font-family: monospace;"> 212 <span style="font-family: monospace;">#include "gettext.h"</span></code><br> 213 </div> 214and these lines near the beginning of the main() function:<br> 215 <div style="margin-left: 40px;"><code><span 216 style="font-family: monospace;">setlocale (LC_ALL, "");</span><br 217 style="font-family: monospace;"> 218 <span style="font-family: monospace;">bindtextdomain (PACKAGE, 219LOCALEDIR);</span><br style="font-family: monospace;"> 220 <span style="font-family: monospace;">textdomain (PACKAGE);</span></code><br> 221 </div> 222 </li> 223 <li>Mark all strings that should be translated with _(), like this: <span 224 style="font-family: monospace;">_("No errors found.")</span>. While 225doing this, try to turn the strings into good English, one entire 226sentence per string, not more than one paragraph per string, and use 227format strings instead of string concatenation. This is needed so that 228the translators can provide accurate translations.</li> 229 <li>In every source file containing translatable strings, add these lines 230to the header:<br> 231 <div style="margin-left: 40px;"><code><span 232 style="font-family: monospace;">#include "gettext.h"</span><br 233 style="font-family: monospace;"> 234 <span style="font-family: monospace;">#define _(string) gettext (string)</span></code><br> 235 </div> 236 </li> 237 <li>In the freshly created <span style="font-family: monospace;">po/</span> 238directory, set up the <span style="font-family: monospace;">POTFILES.in</span> 239file, and do a “<span style="font-family: monospace;">make update-po</span>”. 240Then distribute the generated <span style="font-family: monospace;">.pot</span> 241file to your nearest translation project.</li> 242 <li>Shortly before a release, integrate the translators' <span 243 style="font-family: monospace;">.po</span> files into the <span 244 style="font-family: monospace;">po/</span> directory and do “<span 245 style="font-family: monospace;">make update-po</span>” again.<br> 246 </li> 247</ul> 248You find detailed descriptions of how this all works in the GNU gettext 249manual, chapters “The Maintainer's View” and “Preparing Program 250Sources”. 251<h4><a name="integrating_undefined"></a>I get a linker error “undefined 252reference to libintl_gettext”</h4> 253This error means that the program uses the <span 254 style="font-family: monospace;">gettext()</span> function after having 255included the <span style="font-family: monospace;"><libintl.h></span> 256file from GNU gettext (which remaps it to <span 257 style="font-family: monospace;">libintl_gettext()</span>), however at 258link time a function of this name could not be linked in. (It is 259expected to come from the <span style="font-family: monospace;">libintl</span> 260library, installed by GNU gettext.)<br> 261<br> 262There are many possible reasons for this error, but in any case you 263should consider the <span style="font-family: monospace;">-I</span>, <span 264 style="font-family: monospace;">-L</span> and <span 265 style="font-family: monospace;">-l</span> options passed to the 266compiler. In packages using <span style="font-family: monospace;">autoconf</span> 267generated configure scripts, <span style="font-family: monospace;">-I</span> 268options come from the <span style="font-family: monospace;">CFLAGS</span> 269and <span style="font-family: monospace;">CPPFLAGS</span> variables 270(in Makefiles also <span style="font-family: monospace;">DEFS</span> 271and <span style="font-family: monospace;">INCLUDES</span>), <span 272 style="font-family: monospace;">-L</span> options come from the <span 273 style="font-family: monospace;">LDFLAGS</span> variable, and <span 274 style="font-family: monospace;">-l</span> options come from the <span 275 style="font-family: monospace;">LIBS</span> variable. The first thing 276you should check are the values of these variables in your environment 277and in the package's <span style="font-family: monospace;">config.status</span> 278autoconfiguration result.<br> 279<br> 280To find the cause of the error, a little analysis is needed. Does the 281program's final link command contains the option “-lintl”?<br> 282<ul> 283 <li>If yes:<br> 284Find out where the <span style="font-family: monospace;">libintl</span> 285comes from. To do this, you have to check for <span 286 style="font-family: monospace;">libintl.a</span> and <span 287 style="font-family: monospace;">libintl.so*</span> (<span 288 style="font-family: monospace;">libintl.dylib</span> on MacOS X) in 289each directory given as a -L option, as well as in the compiler's 290implicit search directories. (You get these implicit search directories 291for gcc by using “<span style="font-family: monospace;">gcc -v</span>” 292instead of “<span style="font-family: monospace;">gcc</span>” in the 293final link command line; compilers other than GCC usually look in <span 294 style="font-family: monospace;">/usr/lib</span> and <span 295 style="font-family: monospace;">/lib</span>.) A shell command like<br> 296 <div style="margin-left: 40px;"><code>$ for d in /usr/local/lib 297/usr/lib /lib; do ls -l $d/libintl.*; done</code><br> 298 </div> 299will show where the <span style="font-family: monospace;">libintl</span> 300comes from. By looking at the dates and whether each library defines <span 301 style="font-family: monospace;">libintl_gettext</span> (via “<span 302 style="font-family: monospace;">nm <span style="font-style: italic;">path</span>/libintl.so 303| grep libintl_gettext</span>”) you can now distinguish three possible 304causes of the error:<br> 305 <ul> 306 <li>Some older libintl is used instead of the newer one. The fix 307is to remove the old library or to reorganize your -L options.</li> 308 <li>The used libintl is the new one, and it doesn't contain 309libintl_gettext. This would be a bug in gettext. If this is the case, 310please report it to the usual bug report address.</li> 311 <li>The used libintl is a static library (libintl.a), there are 312no uses of gettext in .o files before the “-lintl” but there are some 313after the “-lintl”. In this case the fix is to move the “-lintl” to the 314end or near the end of the link command line. The only libintl 315dependency that needs to be mentioned after “-lintl” is “-liconv”.</li> 316 </ul> 317 </li> 318 <li>If no:<br> 319In this case it's likely a bug in the package you are building: The 320package's Makefiles should make sure that “-lintl” is used where needed.<br> 321Test whether libintl was found by configure. You can check this by doing<br> 322 <div style="margin-left: 40px;"><code>$ grep 323'\(INTLLIBS\|LIBINTL\)' config.status</code><br> 324 </div> 325and looking whether the value of this autoconf variable is non-empty.<br> 326 <ul> 327 <li>If yes: It should be the responsibility of the Makefile to 328use the value of this variable in the link command line. Does the 329Makefile.in rule for linking the program use <span 330 style="font-family: monospace;">@INTLLIBS@</span> or <span 331 style="font-family: monospace;">@LIBINTL@</span>?<br> 332 <ul> 333 <li>If no: It's a Makefile.am/in bug.</li> 334 <li>If yes: Something strange is going on. You need to dig 335deeper.</li> 336 </ul> 337Note that <span style="font-family: monospace;">@INTLLIBS@</span> is 338for <span style="font-family: monospace;">gettext.m4</span> versions 339<= 0.10.40 and <span style="font-family: monospace;">@LIBINTL@</span> 340is for <span style="font-family: monospace;">gettext.m4</span> 341versions >= 0.11, depending on which <span 342 style="font-family: monospace;">gettext.m4</span> was used to build 343the package's <span style="font-family: monospace;">configure</span> - 344regardless of which gettext you have now installed.</li> 345 <li>If no: So libintl was not found.<br> 346Take a look at the package's <span style="font-family: monospace;">configure.in/ac</span>. 347Does it invoke AM_GNU_GETTEXT?<br> 348 <ul> 349 <li>If no: The gettext maintainers take no responsibilities for 350lookalikes named CY_GNU_GETTEXT, AM_GLIB_GNU_GETTEXT, AM_GNOME_GETTEXT 351and similar, or for homebrewn autoconf checks. Complain to the package 352maintainer.</li> 353 <li>If yes: It looks like the <span 354 style="font-family: monospace;">-I</span> and <span 355 style="font-family: monospace;">-L</span> options were inconsistent. 356You should have a <span style="font-family: monospace;">-I<span 357 style="font-style: italic;">somedir</span>/include</span> in the <span 358 style="font-family: monospace;">CFLAGS</span> or <span 359 style="font-family: monospace;">CPPFLAGS</span> if and only if you 360also have a <span style="font-family: monospace;">-L<span 361 style="font-style: italic;">somedir</span>/lib</span> in the <span 362 style="font-family: monospace;">LDFLAGS</span>. And <span 363 style="font-family: monospace;"><span style="font-style: italic;">somedir</span>/include</span> 364should contain a <span style="font-family: monospace;">libintl.h</span> 365if and only if <span style="font-family: monospace;"><span 366 style="font-style: italic;">somedir</span>/lib</span> contains <span 367 style="font-family: monospace;">libintl.{a,so}</span>.<br> 368This case can also happen if you have configured a GCC < 3.2 with 369the same <span style="font-family: monospace;">--prefix</span> option 370as you used for GNU libiconv or GNU gettext. This is fatal, because 371these versions of GCC implicitly use <span 372 style="font-family: monospace;">-L<span style="font-style: italic;">prefix</span>/lib</span> 373but <span style="font-weight: bold; font-style: italic;">not</span><br 374 style="font-weight: bold; font-style: italic;"> 375 <span style="font-family: monospace;">-I<span 376 style="font-style: italic;">prefix</span>/include</span>. The 377workaround is to use a different <span style="font-family: monospace;">--prefix</span> 378for GCC.<br> 379 </li> 380 </ul> 381 </li> 382 </ul> 383 </li> 384</ul> 385<h4><a name="integrating_abuse_gettextize"></a>gettextize adds multiple 386references to the same directories/files 387to <span style="font-family: monospace;">Makefile.am</span> and <span 388 style="font-family: monospace;">configure.ac</span></h4> 389If <span style="font-family: monospace;">gettextize</span> is used on 390a package, then the <span style="font-family: monospace;">po/</span>, <span 391 style="font-family: monospace;">intl/</span>, <span 392 style="font-family: monospace;">m4/</span> directories of the package 393are removed, and then <span style="font-family: monospace;">gettextize</span> 394is invoked on the package again, it will re-add the <span 395 style="font-family: monospace;">po/</span>, <span 396 style="font-family: monospace;">intl/</span>, <span 397 style="font-family: monospace;">m4/</span> directories and change <span 398 style="font-family: monospace;">Makefile.am</span>, <span 399 style="font-family: monospace;">configure.ac</span> and <span 400 style="font-family: monospace;">ChangeLog</span> accordingly. This is 401normal. The second use of <span style="font-family: monospace;">gettextize</span> 402here is an abuse of the program. <span style="font-family: monospace;">gettextize</span> 403is a wizard intended to transform a <span style="font-style: italic;">working 404source package</span> into a <span style="font-style: italic;">working 405source package</span> that uses the newest version of gettext. If you 406start out from a nonfunctional source package (it is nonfunctional 407since you have omitted some directories), you cannot expect that <span 408 style="font-family: monospace;">gettextize</span> corrects it.<br> 409<br> 410Often this question arises in packages that use CVS. See the section 411“CVS Issues / Integrating with CVS” of the GNU gettext documentation. 412This section mentions a program <span style="font-family: monospace;">autopoint</span> 413which is designed to reconstruct those files and directories created by 414<span style="font-family: monospace;">gettextize</span> that can be 415omitted from a CVS repository.<br> 416<h4><a name="integrating_noop"></a>My program compiles and links fine, 417but doesn't output translated 418strings.</h4> 419There are several possible reasons. Here is a checklist that allows you 420to determine the cause.<br> 421<ol> 422 <li>Check that the environment variables LC_ALL, LC_MESSAGES, 423LC_CTYPE, LANG, LANGUAGE together specify a valid locale and language.<br> 424To check this, run the commands<br> 425 <div style="margin-left: 40px;"><code>$ gettext --version</code><br> 426 <code>$ gettext --help</code><br> 427 </div> 428You should see at least some output in your desired language. If not, 429either<br> 430 <ul> 431 <li>You have chosen a too exotic language. <span 432 style="font-family: monospace;">gettext</span> is localized to 33 433languages. Choose a less exotic language, such as Galician or 434Ukrainian. Or<br> 435 </li> 436 <li>There is a problem with your environment variables. Possibly 437LC_ALL points to a locale that is not installed, or LC_MESSAGES and 438LC_CTYPE are inconsistent.</li> 439 </ul> 440 </li> 441 <li>Check that your program contains a <span 442 style="font-family: monospace;">setlocale</span> call.<br> 443To check this, run your program under ltrace. For example,<br> 444 <div style="margin-left: 40px;"><code>$ ltrace ./myprog</code><br> 445 <code>...</code><br> 446 <code>setlocale(6, 447"") 448= "de_DE.UTF-8"</code><br> 449 </div> 450If you have no ltrace, you can also do this check by running your 451program under the debugger. For example,<br> 452 <div style="margin-left: 40px;"><code>$ gdb ./myprog</code><br> 453 <code>(gdb) break main</code><br> 454 <code>(gdb) run</code><br> 455 <code>Breakpoint 1, main ()</code><br> 456 <code>(gdb) break setlocale</code><br> 457 <code>(gdb) continue</code><br> 458 <code>Breakpoint 2, setlocale ()</code><br> 459 <code>;; OK, the breakpoint has been hit, setlocale() is being 460called.</code><br> 461 </div> 462Either way, check that the return value of <span 463 style="font-family: monospace;">setlocale()</span> is non-NULL. A NULL 464return value indicates a failure. </li> 465 <li>Check that your program contains a <span 466 style="font-family: monospace;">textdomain</span> call, a <span 467 style="font-family: monospace;">bindtextdomain</span> call referring 468to the same message domain, and then really calls the <span 469 style="font-family: monospace;">gettext</span>, <span 470 style="font-family: monospace;">dgettext</span> or <span 471 style="font-family: monospace;">dcgettext</span> function.<br> 472To check this, run the program under ltrace. For example,<br> 473 <div style="margin-left: 40px;"><code>$ ltrace ./myprog</code><br> 474 <code>...</code><br> 475 <code>textdomain("hello-c") 476= "hello-c"</code><br> 477 <code>bindtextdomain("hello-c", "/opt/share"...) = "/opt/share"...</code><br> 478 <code>dcgettext(0, 0x08048691, 5, 0x0804a200, 0x08048689) = 4790x4001721f</code><br> 480 </div> 481If you have no ltrace, you can also do this check by running your 482program under the debugger. For example,<br> 483 <div style="margin-left: 40px;"><code>$ gdb ./myprog</code><br> 484 <code>(gdb) break main</code><br> 485 <code>(gdb) run</code><br> 486 <code>Breakpoint 1, main ()</code><br> 487 <code>(gdb) break textdomain</code><br> 488 <code>(gdb) break bindtextdomain</code><br> 489 <code>(gdb) break gettext</code><br> 490 <code>(gdb) break dgettext</code><br> 491 <code>(gdb) break dcgettext</code><br> 492 <code>(gdb) continue</code><br> 493 <code>Breakpoint 2, textdomain ()</code><br> 494 <code>(gdb) continue</code><br> 495 <code>Breakpoint 3, bindtextdomain ()</code><br> 496 <code>(gdb) continue</code><br> 497 <code>Breakpoint 6, dcgettext ()</code><br> 498 </div> 499Note that here <span style="font-family: monospace;">dcgettext()</span> 500is called instead of the <span style="font-family: monospace;">gettext()</span> 501function mentioned in the source code; this is due to an optimization 502in <span style="font-family: monospace;"><libintl.h></span>.<br> 503When using libintl on a non-glibc system, you have to add a prefix “<span 504 style="font-family: monospace;">libintl_</span>” to all the function 505names mentioned here, because that's what the functions are really 506named, under the hood.<br> 507If <span style="font-family: monospace;">gettext</span>/<span 508 style="font-family: monospace;">dgettext</span>/<span 509 style="font-family: monospace;">dcgettext</span> is not called at all, 510the possible cause might be that some autoconf or Makefile macrology 511has turned off internationalization entirely (like the <span 512 style="font-family: monospace;">--disable-nls</span> configuration 513option usually does).<br> 514 </li> 515 <li>Check that the <span style="font-family: monospace;">.mo</span> 516file that contains the translation is really there where the program 517expects it.<br> 518To check this, run the program under strace and look at the <span 519 style="font-family: monospace;">open()</span> calls. For example,<br> 520 <div style="margin-left: 40px;"><code>$ strace ./myprog 2>&1 521| grep '^open('</code><br> 522 <code>open("/etc/ld.so.preload", O_RDONLY) = -1 523ENOENT (No such file or directory)</code><br> 524 <code>open("/etc/ld.so.cache", 525O_RDONLY) = 5</code><br> 526 <code>open("/lib/libc.so.6", 527O_RDONLY) = 5</code><br> 528 <code>open("/usr/lib/locale/locale-archive", O_RDONLY|O_LARGEFILE) 529= 5</code><br> 530 <code>open("/usr/share/locale/locale.alias", O_RDONLY) = 5</code><br> 531 <code>open("/opt/share/locale/de/LC_MESSAGES/hello-c.mo", O_RDONLY) 532= 5</code><br> 533 <code>...</code><br> 534 </div> 535A nonnegative <span style="font-family: monospace;">open()</span> 536return value means that the file has been found.<br> 537If you have no strace, you can also guess the <span 538 style="font-family: monospace;">.mo</span> file's location: it is<br> 539 <div style="margin-left: 40px;"><span 540 style="font-family: monospace;"><span style="font-style: italic;">localedir</span>/<span 541 style="font-style: italic;">lang</span>/LC_MESSAGES/<span 542 style="font-style: italic;">domain</span>.mo</span><br> 543 </div> 544where <span style="font-style: italic;">domain</span> is the argument 545passed to <span style="font-family: monospace;">textdomain()</span>, <span 546 style="font-style: italic;">localedir</span> is the second argument 547passed to <span style="font-family: monospace;">bindtextdomain()</span>, 548and <span style="font-style: italic;">lang</span> is the language (<span 549 style="font-style: italic;">LL</span>) or language and territory (<span 550 style="font-style: italic;">LL</span>_<span style="font-style: italic;">CC</span>), 551depending on the environment variables checked in step 1.</li> 552 <li>Check that the .mo file contains a translation for the string 553that is being asked for.<br> 554To do this, you need to convert the .mo file back to PO file format, 555through the command<br> 556 <div style="margin-left: 40px;"><code>$ msgunfmt </code><span 557 style="font-family: monospace;"><span style="font-style: italic;">localedir</span>/<span 558 style="font-style: italic;">lang</span>/LC_MESSAGES/<span 559 style="font-style: italic;">domain</span>.mo</span><br> 560 <code></code></div> 561and look for an <span style="font-family: monospace;">msgid</span> 562that matches the given string.<br> 563 </li> 564</ol> 565<h3>GNU gettext on Windows</h3> 566<h4><a name="windows_woe32"></a>What does Woe32 mean?</h4> 567“Woe32” denotes the Windows 32-bit operating systems for x86: Windows 568NT/2000/XP and Windows 95/98/ME. Microsoft uses the term “Win32” to 569denote these; this is a psychological trick in order to make everyone 570believe that these OSes are a “win” for the user. However, for most 571users and developers, they are a source of woes, which is why I call 572them “Woe32”.<br> 573<h4><a name="windows_howto"></a>How do I compile, link and run a 574program that uses the gettext() 575function?</h4> 576When you use RedHat's cygwin environment, it's as on Unix:<br> 577<ul> 578 <li>You need to add an <span style="font-family: monospace;">-I</span> 579option to the compilation command line, so that the compiler finds the <span 580 style="font-family: monospace;">libintl.h</span> include file, and</li> 581 <li>You need to add an <span style="font-family: monospace;">-L</span> 582option to the link command line, so that the linker finds the <span 583 style="font-family: monospace;">libintl</span> library.</li> 584</ul> 585When you use the Mingw environment (either from within cygwin, with <span 586 style="font-family: monospace;">CC="gcc -mno-cygwin"</span>, or from 587MSYS, with <span style="font-family: monospace;">CC="gcc"</span>), I 588don't know the details.<br> 589<br> 590When you use the Microsoft Visual C/C++ (MSVC) compiler, you will 591likely use the precompiled Woe32 binaries. For running a program that 592uses gettext(), one needs the <span style="font-family: monospace;">.bin.woe32.zip</span> 593packages of <span style="font-family: monospace;">gettext-runtime</span> 594and <span style="font-family: monospace;">libiconv</span>. As a 595developer, you'll also need the <span style="font-family: monospace;">xgettext</span> 596and <span style="font-family: monospace;">msgfmt</span> programs that 597are contained in the <span style="font-family: monospace;">.bin.woe32.zip</span> 598package of <span style="font-family: monospace;">gettext-tools</span>. 599Then<br> 600<ul> 601 <li>You need to add an <span style="font-family: monospace;">-MD</span> 602option to all compilation and link command lines. MSVC has three 603different, mutually incompatible, compilation models (<span 604 style="font-family: monospace;">-ML</span>, <span 605 style="font-family: monospace;">-MT</span>, <span 606 style="font-family: monospace;">-MD</span>); the default is <span 607 style="font-family: monospace;">-ML</span>. <span 608 style="font-family: monospace;">intl.dll</span> uses the <span 609 style="font-family: monospace;">-MD</span> model, therefore the rest 610of the program must use <span style="font-family: monospace;">-MD</span> 611as well.<br> 612 </li> 613 <li>You need to add an <span style="font-family: monospace;">-I</span> 614option to the compilation command line, so that the compiler finds the <span 615 style="font-family: monospace;">libintl.h</span> include file.<br> 616 </li> 617 <li>You need to add an <span style="font-family: monospace;">-L</span> 618option to the link command line, so that the linker finds the <span 619 style="font-family: monospace;">intl.lib</span> library.</li> 620 <li>You need to copy the <span style="font-family: monospace;">intl.dll</span> 621and <span style="font-family: monospace;">iconv.dll</span> to the 622directory where your <span style="font-family: monospace;">.exe</span> 623files are created, so that they will be found at runtime.<br> 624 </li> 625</ul> 626<h4><a name="windows_setenv"></a>Setting the <span 627 style="font-family: monospace;">LANG</span> 628environment variable doesn't have any effect</h4> 629If neither LC_ALL, LC_MESSAGES nor LANGUAGES is set, it's the LANG 630environment variable which determines the language into which gettext() 631translates the messages.<br> 632<br> 633You can test your program by setting the LANG environment variable from 634outside the program. In a Windows command interpreter:<br> 635<div style="margin-left: 40px;"><code>set LANG=de_DE</code><br> 636<code>.\myprog.exe</code><br> 637</div> 638Or in a Cygwin shell:<br> 639<div style="margin-left: 40px;"><code>$ env LANG=de_DE ./myprog.exe</code><br> 640</div> 641<br> 642If this test fails, look at the question “My program compiles and links 643fine, but doesn't output translated 644strings.” above.<br> 645<br> 646If this test succeeds, the problem is related in the way you set the 647environment variable. Here is a checklist:<br> 648<ul> 649 <li>Check that you are using the <span 650 style="font-family: monospace;">-MD</span> option in all compilation 651and link command lines. Otherwise you might end up calling the <span 652 style="font-family: monospace;">putenv()</span> function from 653Microsoft's <span style="font-family: monospace;">libc.lib</span>, 654whereas <span style="font-family: monospace;">intl.dll</span> is using 655the <span style="font-family: monospace;">getenv()</span> function 656from Mictosoft's <span style="font-family: monospace;">msvcrt.lib</span>.</li> 657 <li>Check that you set the environment variable using <span 658 style="font-style: italic;">both</span> <span 659 style="font-family: monospace;">SetEnvironmentVariable()</span> and <span 660 style="font-family: monospace;">putenv()</span>. A convenient way to 661do so, and to deal with the fact that some Unix systems have <span 662 style="font-family: monospace;">setenv()</span> and some don't, is the 663following function.<br> 664 <br> 665 <div style="margin-left: 40px;"><code>#include <string.h></code><br> 666 <code>#include <stdlib.h></code><br> 667 <code>#if defined _WIN32</code><br> 668 <code># include <windows.h></code><br> 669 <code>#endif</code><br> 670 <code></code><br> 671 <code>int my_setenv (const char * name, const char * value) {</code><br> 672 <code> size_t namelen = strlen(name);</code><br> 673 <code> size_t valuelen = (value==NULL ? 0 : strlen(value));</code><br> 674 <code>#if defined _WIN32</code><br> 675 <code> /* On Woe32, each process has two copies of the 676environment variables,</code><br> 677 <code> one managed by the OS and one 678managed by the C library. We set</code><br> 679 <code> the value in both locations, so that 680other software that looks in</code><br> 681 <code> one place or the other is guaranteed 682to see the value. Even if it's</code><br> 683 <code> a bit slow. See also</code><br> 684 <code> <<a 685 href="http://article.gmane.org/gmane.comp.gnu.mingw.user/8272">http://article.gmane.org/gmane.comp.gnu.mingw.user/8272</a>></code><br> 686 <code> <<a 687 href="http://article.gmane.org/gmane.comp.gnu.mingw.user/8273">http://article.gmane.org/gmane.comp.gnu.mingw.user/8273</a>></code><br> 688 <code> <<a 689 href="http://www.cygwin.com/ml/cygwin/1999-04/msg00478.html">http://www.cygwin.com/ml/cygwin/1999-04/msg00478.html</a>> 690*/</code><br> 691 <code> if (!SetEnvironmentVariableA(name,value))</code><br> 692 <code> return -1; </code><br> 693 <code>#endif</code><br> 694 <code>#if defined(HAVE_PUTENV)</code><br> 695 <code> char* buffer = (char*)malloc(namelen+1+valuelen+1);</code><br> 696 <code> if (!buffer)</code><br> 697 <code> return -1; /* no need to set errno = 698ENOMEM */</code><br> 699 <code> memcpy(buffer,name,namelen);</code><br> 700 <code> if (value != NULL) {</code><br> 701 <code> buffer[namelen] = '=';</code><br> 702 <code> memcpy(buffer+namelen+1,value,valuelen);</code><br> 703 <code> buffer[namelen+1+valuelen] = 0;</code><br> 704 <code> } else</code><br> 705 <code> buffer[namelen] = 0;</code><br> 706 <code> return putenv(buffer);</code><br> 707 <code>#elif defined(HAVE_SETENV)</code><br> 708 <code> return setenv(name,value,1);</code><br> 709 <code>#else</code><br> 710 <code> /* Uh oh, neither putenv() nor setenv() ... */</code><br> 711 <code> return -1;</code><br> 712 <code>#endif</code><br> 713 <code>}</code><br> 714 <code></code></div> 715 <br> 716 </li> 717</ul> 718<h3>Other</h3> 719<h4><a name="newline"></a>What does this mean: “`msgid' and `msgstr' 720entries do not both end 721with '\n'”</h4> 722It means that when the original string ends in a newline, your 723translation must also end in a newline. And if the original string does 724not end in a newline, then your translation should likewise not have a 725newline at the end.<br> 726<h4><a name="translit"></a>German umlauts are displayed like 727“ge"andert” instead of “geändert”</h4> 728This symptom occurs when the <span style="font-family: monospace;">LC_CTYPE</span> 729facet of the locale is not set; then gettext() doesn't know which 730character set to use, and converts all messages to ASCII, as far as 731possible.<br> 732<br> 733If the program is doing<br> 734<code><br> 735setlocale (LC_MESSAGES, "");<br> 736<br> 737</code>then change it to<br> 738<code><br> 739setlocale (LC_CTYPE, "");<br> 740setlocale (LC_MESSAGES, "");<br> 741</code><br> 742or do both of these in a single call:<br> 743<code><br> 744setlocale (LC_ALL, "");<br> 745</code><br> 746If the program is already doing<br> 747<code><br> 748setlocale (LC_ALL, "");<br> 749</code><br> 750then the symptom can still occur if the user has not set <span 751 style="font-family: monospace;">LANG</span>, but instead has set <span 752 style="font-family: monospace;">LC_MESSAGES</span> to a valid locale 753and has set <span style="font-family: monospace;">LC_CTYPE</span> to 754nothing or an invalid locale. The fix for the user is then to set <span 755 style="font-family: monospace;">LANG</span> instead of <span 756 style="font-family: monospace;">LC_MESSAGES</span>.<br> 757<h4><a name="localename"></a>The <span style="font-family: monospace;">LANGUAGE</span> 758environment variable is ignored after I set <span 759 style="font-family: monospace;">LANG=en</span></h4> 760This is because “en” is a language name, but not a valid locale name. 761The <span style="font-family: monospace;">ABOUT-NLS</span> file 762says:<br> 763<blockquote> 764In the <span style="font-family: monospace;">LANGUAGE</span> 765environment variable, but not in the <span 766 style="font-family: monospace;">LANG</span> environment variable, <span 767 style="font-style: italic;">LL</span>_<span style="font-style: italic;">CC</span><span 768 style="font-family: monospace;"> </span>combinations can be 769abbreviated as <span style="font-style: italic;">LL</span> to 770denote the language's main dialect.</blockquote> 771Why is <span style="font-family: monospace;">LANG=en</span> not 772allowed? Because <span style="font-family: monospace;">LANG</span> is 773a setting for the entire locale, including monetary information, and 774this depends on the country: en_GB, en_AU, en_ZA all have different 775currencies.<br> 776<h4><a name="nonascii_strings"></a>I use accented characters in my 777source code. How do I tell the 778C/C++ compiler in which encoding it is (like <span 779 style="font-family: monospace;">xgettext</span>'s <span 780 style="font-family: monospace;">--from-code</span> option)?</h4> 781Short answer: If you want your program to be useful to other people, 782then <span style="font-style: italic;">don't use accented characters</span> 783(or other non-ASCII characters) in string literals <span 784 style="font-style: italic;">in the source code</span>. Instead, use 785only ASCII for string literals, and use <span 786 style="font-family: monospace;">gettext()</span> to retrieve their 787display-ready form.<br> 788<br> 789Long explanation:<br> 790The reason is that the ISO C standard specifies that the character set 791at compilation time can be different from the character set at 792execution time.<br> 793The character encoding at compilation time is the one which determines 794how the source files are interpreted and also how string literals are 795stored in the compiled code. This character encoding is generally 796unspecified; for recent versions of GCC, it depends on the LC_CTYPE 797locale in effect during the compilation process.<br> 798The character encoding at execution time is the one which determines 799how standard functions like <span style="font-family: monospace;">isprint()</span>, 800<span style="font-family: monospace;">wcwidth()</span> etc. work and 801how strings written to standard output should be encoded. This 802character encoding is specified by POSIX to depend on the LC_CTYPE 803locale in effect when the program is executed; see also the description 804in the <span style="font-family: monospace;">ABOUT-NLS</span> file.<br> 805Strings in the compiled code are not magically converted between the 806time the program is compiled and the time it is run.<br> 807<br> 808Therefore what could you do to get accented characters to work?<br> 809<br> 810Can you ensure that the execution character set is the same as the 811compilation character set? Even if your program is to be used only in a 812single country, this is not realistically possible. For example, in 813Germany there are currently three character encodings in use: UTF-8, 814ISO-8859-15 and ISO-8859-1. Therefore you would have to explicitly 815convert the accented strings from the compilation character set to the 816execution character set at runtime, for example through iconv().<br> 817<br> 818Can you ensure that the compilation character set is the one in which 819your source files are stored? This is not realistically possible 820either: For compilers other than GCC, there is no way to specify the 821compilation character set. So let's assume for a moment that everyone 822uses GCC; then you will specify the LC_CTYPE or LC_ALL environment 823variable in the Makefile. But for this you have to assume that everyone 824has a locale in a given encoding. Be it UTF-8 or ISO-8859-1 - this is 825not realistic. People often have no locale installed besides the one 826they use.<br> 827<br> 828Use of wide strings <span style="font-family: monospace;">L"..."</span> 829doesn't help solving the problem, because on systems like FreeBSD or 830Solaris, the way how wide string literals are stored in compiled code 831depends on the compilation character set, just as it does for 832narrow strings <span style="font-family: monospace;">"..."</span>. 833Moreover, wide strings have problems of their own.<br> 834<br> 835Use of ISO C 99 Unicode escapes "\u<span style="font-style: italic;">xxxx</span>" 836doesn't help either because these characters are converted to the 837compilation character set at compile time; so again, since you can't 838guarantee that the compilation character set is not ASCII, you're 839risking compilation errors just as if the real character had been used 840in the source instead of the Unicode escape.<br> 841<br> 842So, in summary, there is no way to make accented characters in string 843literals work in C/C++.<br> 844<br> 845You might then wonder what <span style="font-family: monospace;">xgettext</span>'s 846<span style="font-family: monospace;">--from-code</span> option is good 847for. The answer is<br> 848<ol> 849 <li>For the comments in C/C++ source code. The compiler ignores them.<br> 850 </li> 851 <li>For other programming languages like Java, for which the compiler 852converts all string literals to UTF-8.</li> 853</ol> 854<br> 855<hr style="width: 100%; height: 2px;"> 856<address>GNU gettext FAQ<br> 857Bruno Haible <<a href="mailto:bruno@clisp.org">bruno@clisp.org</a>></address> 858<p>Last modified: 24 February 2004 859</p> 860</body> 861</html> 862