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> 9 for 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 17 releases.</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 22 error 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 25 named <span style="font-family: monospace;">rpath-<span 26 style="font-style: italic;">Nxyz</span></span> 27 fail: 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 35 reference to libintl_gettext</a></li> 36 <li><a href="#integrating_abuse_gettextize">gettextize adds multiple 37 references to the same directories/files 38 to <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, 42 but doesn't output translated 43 strings.</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 50 that uses the gettext() 51 function?</a><br> 52 </li> 53 <li><a href="#windows_setenv">Setting the <span 54 style="font-family: monospace;">LANG</span> 55 environment 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' 60 entries do not both 61 end with '\n'</a></li> 62 <li><a href="#translit">German umlauts are displayed like ge"andert 63 instead of 64 gendert</a></li> 65 <li><a href="#localename">The <span style="font-family: monospace;">LANGUAGE</span> 66 environment 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 69 source code. How do I tell the 70 C/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> 77 Three mailing lists are available: <br> 78 <ul> 79 <li><span style="font-family: monospace;">bug-gnu-gettext (a] gnu.org</span><br> 80 This mailing list is for discussion of features and bugs of the GNU 81 gettext <span style="font-style: italic;">software</span>, including 82 libintl, the gettext-tools, and its autoconf macros.</li> 83 <li><span style="font-family: monospace;">translation-i18n (a] lists.sourceforge.net</span><br> 84 This mailing list is for methodology questions around 85 internationalization, and for discussions of translator tools, 86 including but not limited to GNU gettext.</li> 87 <li><span style="font-family: monospace;">translation (a] iro.umontreal.ca</span><br> 88 This is the email address of the <a 89 href="http://www.iro.umontreal.ca/contrib/po/HTML/">Free Translation 90 Project</a>, that is the project which manages the translated message 91 catalogs for many free software packages. Note that KDE and GNOME 92 packages are not part of this project; they have their own translation 93 projects: <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> 97 The <span style="font-family: monospace;">bug-gnu-gettext</span> list 98 is 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 102 subscribed 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> 105 The 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> 109 Prereleases 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>. 112 Note that prereleases are meant for testing and not meant for use in 113 production environments. Please don't use the gettextize program of a 114 prerelease on projects which you share with other programmers via CVS.<br> 115 <br> 116 If you want to live on the bleeding edge, you can also use the 117 development sources. Instructions for retrieving the gettext CVS are 118 found <a href="http://savannah.gnu.org/projects/gettext">here</a>. 119 Note that building from CVS requires special tools (autoconf, automake, 120 m4, 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 124 releases.</h4> 125 If 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 128 is 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> 131 through <a href="http://www.gmane.org/"><span 132 style="font-family: monospace;">gmane.org</span></a>.<br> 133 <br> 134 You can also periodically check the download location.<br> 135 <br> 136 If you are interested in testing prereleases as well, you can subscribe 137 to the <a href="http://mail.gnu.org/pipermail/autotools-announce"><span 138 style="font-family: monospace;">autotools-announce</span> mailing 139 list</a>.<br> 140 <h3>Problems building GNU gettext</h3> 141 <h4><a name="building_solaris_libasprintf"></a>On Solaris, I get a 142 build error text relocations remain in the <span 143 style="font-family: monospace;">libasprintf</span> subdirectory</h4> 144 libtool (or more precisely, the version of libtool that was available 145 at the time the gettext release waas made) doesn't support linking C++ 146 libraries with some versions of GCC. As a workaround, you can configure 147 gettext 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 149 named <span style="font-family: monospace;">rpath-<span 150 style="font-style: italic;">Nxyz</span></span> 151 fail: ld: fatal error ... -lrpathz</h4> 152 If only a few among the many rpath tests fail, you can probably ignore 153 the problem. The rpath tests are sensitive to incomplete shared library 154 support in the system, and to bugs in libtool that creates the shared 155 libraries. Some known failures are listed in <span 156 style="font-family: monospace;">autoconf-lib-link/tests/rpath.README</span>.<br> 157 <br> 158 To 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 168 an error message relating to <span style="font-family: monospace;">libgettextlib</span> 169 or <span style="font-family: monospace;">libgettextsrc</span>, or can 170 silently fail to install <span style="font-family: monospace;">libgettextsrc</span>. 171 On some platforms, this is due to limitations of libtool regarding <span 172 style="font-family: monospace;">DESTDIR</span>. On other platforms, it 173 is due to the way the system handles shared libraries, and libtool 174 cannot work around it. Fortunately, on Linux and other glibc based 175 systems, <span style="font-family: monospace;">DESTDIR</span> is 176 supported if no different version of gettext is already installed (i.e. 177 it works if you uninstall the older gettext before building and 178 installing 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 182 systems, when <span style="font-family: monospace;">DESTDIR</span> 183 does not work, you can still do <span style="font-family: monospace;">make 184 install</span> and copy the installed files to <span 185 style="font-family: monospace;"><span style="font-style: italic;">/some/tempdir</span></span> 186 afterwards.<br> 187 <br> 188 If <span style="font-family: monospace;">make install</span> without <span 189 style="font-family: monospace;">DESTDIR</span> fails, it's a bug which 190 you 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> 194 It's not as difficult as it sounds. Here's the recipe for C or C++ 195 based packages.<br> 196 <ul> 197 <li>Add an invocation of <span style="font-family: monospace;">AM_GNU_GETTEXT([external])</span> 198 to the package's <span style="font-family: monospace;">configure.{ac,in}</span> 199 file.</li> 200 <li>Invoke <span style="font-family: monospace;">gettextize --copy</span>. 201 It will do most of the autoconf/automake related work for you.</li> 202 <li>Add the <span style="font-family: monospace;">gettext.h</span> 203 file to the package's source directory, and include it in all source 204 files 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, 208 add 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> 214 and 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, 219 LOCALEDIR);</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 225 doing this, try to turn the strings into good English, one entire 226 sentence per string, not more than one paragraph per string, and use 227 format strings instead of string concatenation. This is needed so that 228 the translators can provide accurate translations.</li> 229 <li>In every source file containing translatable strings, add these lines 230 to 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> 238 directory, set up the <span style="font-family: monospace;">POTFILES.in</span> 239 file, and do a <span style="font-family: monospace;">make update-po</span>. 240 Then distribute the generated <span style="font-family: monospace;">.pot</span> 241 file 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> 248 You find detailed descriptions of how this all works in the GNU gettext 249 manual, chapters The Maintainer's View and Preparing Program 250 Sources. 251 <h4><a name="integrating_undefined"></a>I get a linker error undefined 252 reference to libintl_gettext</h4> 253 This error means that the program uses the <span 254 style="font-family: monospace;">gettext()</span> function after having 255 included the <span style="font-family: monospace;"><libintl.h></span> 256 file from GNU gettext (which remaps it to <span 257 style="font-family: monospace;">libintl_gettext()</span>), however at 258 link time a function of this name could not be linked in. (It is 259 expected to come from the <span style="font-family: monospace;">libintl</span> 260 library, installed by GNU gettext.)<br> 261 <br> 262 There are many possible reasons for this error, but in any case you 263 should 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 266 compiler. In packages using <span style="font-family: monospace;">autoconf</span> 267 generated configure scripts, <span style="font-family: monospace;">-I</span> 268 options come from the <span style="font-family: monospace;">CFLAGS</span> 269 and <span style="font-family: monospace;">CPPFLAGS</span> variables 270 (in Makefiles also <span style="font-family: monospace;">DEFS</span> 271 and <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 276 you should check are the values of these variables in your environment 277 and in the package's <span style="font-family: monospace;">config.status</span> 278 autoconfiguration result.<br> 279 <br> 280 To find the cause of the error, a little analysis is needed. Does the 281 program's final link command contains the option -lintl?<br> 282 <ul> 283 <li>If yes:<br> 284 Find out where the <span style="font-family: monospace;">libintl</span> 285 comes 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 289 each directory given as a -L option, as well as in the compiler's 290 implicit search directories. (You get these implicit search directories 291 for gcc by using <span style="font-family: monospace;">gcc -v</span> 292 instead of <span style="font-family: monospace;">gcc</span> in the 293 final 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> 299 will show where the <span style="font-family: monospace;">libintl</span> 300 comes 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 304 causes of the error:<br> 305 <ul> 306 <li>Some older libintl is used instead of the newer one. The fix 307 is 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 309 libintl_gettext. This would be a bug in gettext. If this is the case, 310 please report it to the usual bug report address.</li> 311 <li>The used libintl is a static library (libintl.a), there are 312 no uses of gettext in .o files before the -lintl but there are some 313 after the -lintl. In this case the fix is to move the -lintl to the 314 end or near the end of the link command line. The only libintl 315 dependency that needs to be mentioned after -lintl is -liconv.</li> 316 </ul> 317 </li> 318 <li>If no:<br> 319 In this case it's likely a bug in the package you are building: The 320 package's Makefiles should make sure that -lintl is used where needed.<br> 321 Test 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> 325 and 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 328 use the value of this variable in the link command line. Does the 329 Makefile.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 335 deeper.</li> 336 </ul> 337 Note that <span style="font-family: monospace;">@INTLLIBS@</span> is 338 for <span style="font-family: monospace;">gettext.m4</span> versions 339 <= 0.10.40 and <span style="font-family: monospace;">@LIBINTL@</span> 340 is for <span style="font-family: monospace;">gettext.m4</span> 341 versions >= 0.11, depending on which <span 342 style="font-family: monospace;">gettext.m4</span> was used to build 343 the package's <span style="font-family: monospace;">configure</span> - 344 regardless of which gettext you have now installed.</li> 345 <li>If no: So libintl was not found.<br> 346 Take a look at the package's <span style="font-family: monospace;">configure.in/ac</span>. 347 Does it invoke AM_GNU_GETTEXT?<br> 348 <ul> 349 <li>If no: The gettext maintainers take no responsibilities for 350 lookalikes named CY_GNU_GETTEXT, AM_GLIB_GNU_GETTEXT, AM_GNOME_GETTEXT 351 and similar, or for homebrewn autoconf checks. Complain to the package 352 maintainer.</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. 356 You 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 360 also 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> 364 should contain a <span style="font-family: monospace;">libintl.h</span> 365 if 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> 368 This case can also happen if you have configured a GCC < 3.2 with 369 the same <span style="font-family: monospace;">--prefix</span> option 370 as you used for GNU libiconv or GNU gettext. This is fatal, because 371 these versions of GCC implicitly use <span 372 style="font-family: monospace;">-L<span style="font-style: italic;">prefix</span>/lib</span> 373 but <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 377 workaround is to use a different <span style="font-family: monospace;">--prefix</span> 378 for 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 386 references to the same directories/files 387 to <span style="font-family: monospace;">Makefile.am</span> and <span 388 style="font-family: monospace;">configure.ac</span></h4> 389 If <span style="font-family: monospace;">gettextize</span> is used on 390 a 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 393 are removed, and then <span style="font-family: monospace;">gettextize</span> 394 is 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 401 normal. The second use of <span style="font-family: monospace;">gettextize</span> 402 here is an abuse of the program. <span style="font-family: monospace;">gettextize</span> 403 is a wizard intended to transform a <span style="font-style: italic;">working 404 source package</span> into a <span style="font-style: italic;">working 405 source package</span> that uses the newest version of gettext. If you 406 start out from a nonfunctional source package (it is nonfunctional 407 since you have omitted some directories), you cannot expect that <span 408 style="font-family: monospace;">gettextize</span> corrects it.<br> 409 <br> 410 Often this question arises in packages that use CVS. See the section 411 CVS Issues / Integrating with CVS of the GNU gettext documentation. 412 This section mentions a program <span style="font-family: monospace;">autopoint</span> 413 which is designed to reconstruct those files and directories created by 414 <span style="font-family: monospace;">gettextize</span> that can be 415 omitted from a CVS repository.<br> 416 <h4><a name="integrating_noop"></a>My program compiles and links fine, 417 but doesn't output translated 418 strings.</h4> 419 There are several possible reasons. Here is a checklist that allows you 420 to determine the cause.<br> 421 <ol> 422 <li>Check that the environment variables LC_ALL, LC_MESSAGES, 423 LC_CTYPE, LANG, LANGUAGE together specify a valid locale and language.<br> 424 To 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> 428 You should see at least some output in your desired language. If not, 429 either<br> 430 <ul> 431 <li>You have chosen a too exotic language. <span 432 style="font-family: monospace;">gettext</span> is localized to 33 433 languages. Choose a less exotic language, such as Galician or 434 Ukrainian. Or<br> 435 </li> 436 <li>There is a problem with your environment variables. Possibly 437 LC_ALL points to a locale that is not installed, or LC_MESSAGES and 438 LC_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> 443 To 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> 450 If you have no ltrace, you can also do this check by running your 451 program 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 460 called.</code><br> 461 </div> 462 Either way, check that the return value of <span 463 style="font-family: monospace;">setlocale()</span> is non-NULL. A NULL 464 return 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 468 to 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> 472 To 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) = 479 0x4001721f</code><br> 480 </div> 481 If you have no ltrace, you can also do this check by running your 482 program 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> 499 Note that here <span style="font-family: monospace;">dcgettext()</span> 500 is called instead of the <span style="font-family: monospace;">gettext()</span> 501 function mentioned in the source code; this is due to an optimization 502 in <span style="font-family: monospace;"><libintl.h></span>.<br> 503 When 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 505 names mentioned here, because that's what the functions are really 506 named, under the hood.<br> 507 If <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, 510 the possible cause might be that some autoconf or Makefile macrology 511 has turned off internationalization entirely (like the <span 512 style="font-family: monospace;">--disable-nls</span> configuration 513 option usually does).<br> 514 </li> 515 <li>Check that the <span style="font-family: monospace;">.mo</span> 516 file that contains the translation is really there where the program 517 expects it.<br> 518 To 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 523 ENOENT (No such file or directory)</code><br> 524 <code>open("/etc/ld.so.cache", 525 O_RDONLY) = 5</code><br> 526 <code>open("/lib/libc.so.6", 527 O_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> 535 A nonnegative <span style="font-family: monospace;">open()</span> 536 return value means that the file has been found.<br> 537 If 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> 544 where <span style="font-style: italic;">domain</span> is the argument 545 passed to <span style="font-family: monospace;">textdomain()</span>, <span 546 style="font-style: italic;">localedir</span> is the second argument 547 passed to <span style="font-family: monospace;">bindtextdomain()</span>, 548 and <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>), 551 depending on the environment variables checked in step 1.</li> 552 <li>Check that the .mo file contains a translation for the string 553 that is being asked for.<br> 554 To do this, you need to convert the .mo file back to PO file format, 555 through 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> 561 and look for an <span style="font-family: monospace;">msgid</span> 562 that 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 568 NT/2000/XP and Windows 95/98/ME. Microsoft uses the term Win32 to 569 denote these; this is a psychological trick in order to make everyone 570 believe that these OSes are a win for the user. However, for most 571 users and developers, they are a source of woes, which is why I call 572 them Woe32.<br> 573 <h4><a name="windows_howto"></a>How do I compile, link and run a 574 program that uses the gettext() 575 function?</h4> 576 When 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> 579 option 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> 582 option to the link command line, so that the linker finds the <span 583 style="font-family: monospace;">libintl</span> library.</li> 584 </ul> 585 When you use the Mingw environment (either from within cygwin, with <span 586 style="font-family: monospace;">CC="gcc -mno-cygwin"</span>, or from 587 MSYS, with <span style="font-family: monospace;">CC="gcc"</span>), I 588 don't know the details.<br> 589 <br> 590 When you use the Microsoft Visual C/C++ (MSVC) compiler, you will 591 likely use the precompiled Woe32 binaries. For running a program that 592 uses gettext(), one needs the <span style="font-family: monospace;">.bin.woe32.zip</span> 593 packages of <span style="font-family: monospace;">gettext-runtime</span> 594 and <span style="font-family: monospace;">libiconv</span>. As a 595 developer, you'll also need the <span style="font-family: monospace;">xgettext</span> 596 and <span style="font-family: monospace;">msgfmt</span> programs that 597 are contained in the <span style="font-family: monospace;">.bin.woe32.zip</span> 598 package of <span style="font-family: monospace;">gettext-tools</span>. 599 Then<br> 600 <ul> 601 <li>You need to add an <span style="font-family: monospace;">-MD</span> 602 option to all compilation and link command lines. MSVC has six 603 different, 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>, <span 607 style="font-family: monospace;">-MLd</span>, <span 608 style="font-family: monospace;">-MTd</span>, <span 609 style="font-family: monospace;">-MDd</span>); the default is <span 610 style="font-family: monospace;">-ML</span>. <span 611 style="font-family: monospace;">intl.dll</span> uses the <span 612 style="font-family: monospace;">-MD</span> model, therefore the rest 613 of the program must use <span style="font-family: monospace;">-MD</span> 614 as well.<br> 615 </li> 616 <li>You need to add an <span style="font-family: monospace;">-I</span> 617 option to the compilation command line, so that the compiler finds the <span 618 style="font-family: monospace;">libintl.h</span> include file.<br> 619 </li> 620 <li>You need to add an <span style="font-family: monospace;">-L</span> 621 option to the link command line, so that the linker finds the <span 622 style="font-family: monospace;">intl.lib</span> library.</li> 623 <li>You need to copy the <span style="font-family: monospace;">intl.dll</span> 624 and <span style="font-family: monospace;">iconv.dll</span> to the 625 directory where your <span style="font-family: monospace;">.exe</span> 626 files are created, so that they will be found at runtime.<br> 627 </li> 628 </ul> 629 <h4><a name="windows_setenv"></a>Setting the <span 630 style="font-family: monospace;">LANG</span> 631 environment variable doesn't have any effect</h4> 632 If neither LC_ALL, LC_MESSAGES nor LANGUAGES is set, it's the LANG 633 environment variable which determines the language into which gettext() 634 translates the messages.<br> 635 <br> 636 You can test your program by setting the LANG environment variable from 637 outside the program. In a Windows command interpreter:<br> 638 <div style="margin-left: 40px;"><code>set LANG=de_DE</code><br> 639 <code>.\myprog.exe</code><br> 640 </div> 641 Or in a Cygwin shell:<br> 642 <div style="margin-left: 40px;"><code>$ env LANG=de_DE ./myprog.exe</code><br> 643 </div> 644 <br> 645 If this test fails, look at the question My program compiles and links 646 fine, but doesn't output translated 647 strings. above.<br> 648 <br> 649 If this test succeeds, the problem is related in the way you set the 650 environment variable. Here is a checklist:<br> 651 <ul> 652 <li>Check that you are using the <span 653 style="font-family: monospace;">-MD</span> option in all compilation 654 and link command lines. Otherwise you might end up calling the <span 655 style="font-family: monospace;">putenv()</span> function from 656 Microsoft's <span style="font-family: monospace;">libc.lib</span>, 657 whereas <span style="font-family: monospace;">intl.dll</span> is using 658 the <span style="font-family: monospace;">getenv()</span> function 659 from Mictosoft's <span style="font-family: monospace;">msvcrt.lib</span>.</li> 660 <li>Check that you set the environment variable using <span 661 style="font-style: italic;">both</span> <span 662 style="font-family: monospace;">SetEnvironmentVariable()</span> and <span 663 style="font-family: monospace;">putenv()</span>. A convenient way to 664 do so, and to deal with the fact that some Unix systems have <span 665 style="font-family: monospace;">setenv()</span> and some don't, is the 666 following function.<br> 667 <br> 668 <div style="margin-left: 40px;"><code>#include <string.h></code><br> 669 <code>#include <stdlib.h></code><br> 670 <code>#if defined _WIN32</code><br> 671 <code># include <windows.h></code><br> 672 <code>#endif</code><br> 673 <code></code><br> 674 <code>int my_setenv (const char * name, const char * value) {</code><br> 675 <code> size_t namelen = strlen(name);</code><br> 676 <code> size_t valuelen = (value==NULL ? 0 : strlen(value));</code><br> 677 <code>#if defined _WIN32</code><br> 678 <code> /* On Woe32, each process has two copies of the 679 environment variables,</code><br> 680 <code> one managed by the OS and one 681 managed by the C library. We set</code><br> 682 <code> the value in both locations, so that 683 other software that looks in</code><br> 684 <code> one place or the other is guaranteed 685 to see the value. Even if it's</code><br> 686 <code> a bit slow. See also</code><br> 687 <code> <<a 688 href="http://article.gmane.org/gmane.comp.gnu.mingw.user/8272">http://article.gmane.org/gmane.comp.gnu.mingw.user/8272</a>></code><br> 689 <code> <<a 690 href="http://article.gmane.org/gmane.comp.gnu.mingw.user/8273">http://article.gmane.org/gmane.comp.gnu.mingw.user/8273</a>></code><br> 691 <code> <<a 692 href="http://www.cygwin.com/ml/cygwin/1999-04/msg00478.html">http://www.cygwin.com/ml/cygwin/1999-04/msg00478.html</a>> 693 */</code><br> 694 <code> if (!SetEnvironmentVariableA(name,value))</code><br> 695 <code> return -1; </code><br> 696 <code>#endif</code><br> 697 <code>#if defined(HAVE_PUTENV)</code><br> 698 <code> char* buffer = (char*)malloc(namelen+1+valuelen+1);</code><br> 699 <code> if (!buffer)</code><br> 700 <code> return -1; /* no need to set errno = 701 ENOMEM */</code><br> 702 <code> memcpy(buffer,name,namelen);</code><br> 703 <code> if (value != NULL) {</code><br> 704 <code> buffer[namelen] = '=';</code><br> 705 <code> memcpy(buffer+namelen+1,value,valuelen);</code><br> 706 <code> buffer[namelen+1+valuelen] = 0;</code><br> 707 <code> } else</code><br> 708 <code> buffer[namelen] = 0;</code><br> 709 <code> return putenv(buffer);</code><br> 710 <code>#elif defined(HAVE_SETENV)</code><br> 711 <code> return setenv(name,value,1);</code><br> 712 <code>#else</code><br> 713 <code> /* Uh oh, neither putenv() nor setenv() ... */</code><br> 714 <code> return -1;</code><br> 715 <code>#endif</code><br> 716 <code>}</code><br> 717 <code></code></div> 718 <br> 719 </li> 720 </ul> 721 <h3>Other</h3> 722 <h4><a name="newline"></a>What does this mean: `msgid' and `msgstr' 723 entries do not both end 724 with '\n'</h4> 725 It means that when the original string ends in a newline, your 726 translation must also end in a newline. And if the original string does 727 not end in a newline, then your translation should likewise not have a 728 newline at the end.<br> 729 <h4><a name="translit"></a>German umlauts are displayed like 730 ge"andert instead of gendert</h4> 731 This symptom occurs when the <span style="font-family: monospace;">LC_CTYPE</span> 732 facet of the locale is not set; then gettext() doesn't know which 733 character set to use, and converts all messages to ASCII, as far as 734 possible.<br> 735 <br> 736 If the program is doing<br> 737 <code><br> 738 setlocale (LC_MESSAGES, "");<br> 739 <br> 740 </code>then change it to<br> 741 <code><br> 742 setlocale (LC_CTYPE, "");<br> 743 setlocale (LC_MESSAGES, "");<br> 744 </code><br> 745 or do both of these in a single call:<br> 746 <code><br> 747 setlocale (LC_ALL, "");<br> 748 </code><br> 749 If the program is already doing<br> 750 <code><br> 751 setlocale (LC_ALL, "");<br> 752 </code><br> 753 then the symptom can still occur if the user has not set <span 754 style="font-family: monospace;">LANG</span>, but instead has set <span 755 style="font-family: monospace;">LC_MESSAGES</span> to a valid locale 756 and has set <span style="font-family: monospace;">LC_CTYPE</span> to 757 nothing or an invalid locale. The fix for the user is then to set <span 758 style="font-family: monospace;">LANG</span> instead of <span 759 style="font-family: monospace;">LC_MESSAGES</span>.<br> 760 <h4><a name="localename"></a>The <span style="font-family: monospace;">LANGUAGE</span> 761 environment variable is ignored after I set <span 762 style="font-family: monospace;">LANG=en</span></h4> 763 This is because en is a language name, but not a valid locale name. 764 The <span style="font-family: monospace;">ABOUT-NLS</span> file 765 says:<br> 766 <blockquote> 767 In the <span style="font-family: monospace;">LANGUAGE</span> 768 environment variable, but not in the <span 769 style="font-family: monospace;">LANG</span> environment variable, <span 770 style="font-style: italic;">LL</span>_<span style="font-style: italic;">CC</span><span 771 style="font-family: monospace;"> </span>combinations can be 772 abbreviated as <span style="font-style: italic;">LL</span> to 773 denote the language's main dialect.</blockquote> 774 Why is <span style="font-family: monospace;">LANG=en</span> not 775 allowed? Because <span style="font-family: monospace;">LANG</span> is 776 a setting for the entire locale, including monetary information, and 777 this depends on the country: en_GB, en_AU, en_ZA all have different 778 currencies.<br> 779 <h4><a name="nonascii_strings"></a>I use accented characters in my 780 source code. How do I tell the 781 C/C++ compiler in which encoding it is (like <span 782 style="font-family: monospace;">xgettext</span>'s <span 783 style="font-family: monospace;">--from-code</span> option)?</h4> 784 Short answer: If you want your program to be useful to other people, 785 then <span style="font-style: italic;">don't use accented characters</span> 786 (or other non-ASCII characters) in string literals <span 787 style="font-style: italic;">in the source code</span>. Instead, use 788 only ASCII for string literals, and use <span 789 style="font-family: monospace;">gettext()</span> to retrieve their 790 display-ready form.<br> 791 <br> 792 Long explanation:<br> 793 The reason is that the ISO C standard specifies that the character set 794 at compilation time can be different from the character set at 795 execution time.<br> 796 The character encoding at compilation time is the one which determines 797 how the source files are interpreted and also how string literals are 798 stored in the compiled code. This character encoding is generally 799 unspecified; for recent versions of GCC, it depends on the LC_CTYPE 800 locale in effect during the compilation process.<br> 801 The character encoding at execution time is the one which determines 802 how standard functions like <span style="font-family: monospace;">isprint()</span>, 803 <span style="font-family: monospace;">wcwidth()</span> etc. work and 804 how strings written to standard output should be encoded. This 805 character encoding is specified by POSIX to depend on the LC_CTYPE 806 locale in effect when the program is executed; see also the description 807 in the <span style="font-family: monospace;">ABOUT-NLS</span> file.<br> 808 Strings in the compiled code are not magically converted between the 809 time the program is compiled and the time it is run.<br> 810 <br> 811 Therefore what could you do to get accented characters to work?<br> 812 <br> 813 Can you ensure that the execution character set is the same as the 814 compilation character set? Even if your program is to be used only in a 815 single country, this is not realistically possible. For example, in 816 Germany there are currently three character encodings in use: UTF-8, 817 ISO-8859-15 and ISO-8859-1. Therefore you would have to explicitly 818 convert the accented strings from the compilation character set to the 819 execution character set at runtime, for example through iconv().<br> 820 <br> 821 Can you ensure that the compilation character set is the one in which 822 your source files are stored? This is not realistically possible 823 either: For compilers other than GCC, there is no way to specify the 824 compilation character set. So let's assume for a moment that everyone 825 uses GCC; then you will specify the LC_CTYPE or LC_ALL environment 826 variable in the Makefile. But for this you have to assume that everyone 827 has a locale in a given encoding. Be it UTF-8 or ISO-8859-1 - this is 828 not realistic. People often have no locale installed besides the one 829 they use.<br> 830 <br> 831 Use of wide strings <span style="font-family: monospace;">L"..."</span> 832 doesn't help solving the problem, because on systems like FreeBSD or 833 Solaris, the way how wide string literals are stored in compiled code 834 depends on the compilation character set, just as it does for 835 narrow strings <span style="font-family: monospace;">"..."</span>. 836 Moreover, wide strings have problems of their own.<br> 837 <br> 838 Use of ISO C 99 Unicode escapes "\u<span style="font-style: italic;">xxxx</span>" 839 doesn't help either because these characters are converted to the 840 compilation character set at compile time; so again, since you can't 841 guarantee that the compilation character set is not ASCII, you're 842 risking compilation errors just as if the real character had been used 843 in the source instead of the Unicode escape.<br> 844 <br> 845 So, in summary, there is no way to make accented characters in string 846 literals work in C/C++.<br> 847 <br> 848 You might then wonder what <span style="font-family: monospace;">xgettext</span>'s 849 <span style="font-family: monospace;">--from-code</span> option is good 850 for. The answer is<br> 851 <ol> 852 <li>For the comments in C/C++ source code. The compiler ignores them.<br> 853 </li> 854 <li>For other programming languages like Java, for which the compiler 855 converts all string literals to UTF-8.</li> 856 </ol> 857 <br> 858 <hr style="width: 100%; height: 2px;"> 859 <address>GNU gettext FAQ<br> 860 Bruno Haible <<a href="mailto:bruno (a] clisp.org">bruno (a] clisp.org</a>></address> 861 <p>Last modified: 24 February 2004 862 </p> 863 </body> 864 </html> 865
Indexes created Sun Sep 20 00:26:38 UTC 2026