gettext-tools/doc/FAQ.html

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