Frequently Asked Questions
for GNU gettext

Questions

General

• Where is the mailing list?
• Where is the newest gettext source?
• I want to be notified of new gettext releases.

Problems building GNU gettext

• On Solaris, I get a build error “text relocations remain” in the libasprintf subdirectory
• “make install” fails

Problems integrating GNU gettext

• How do I make use of gettext() in my package?
• I get a linker error “undefined reference to libintl_gettext”
• gettextize adds multiple references to the same directories/files to Makefile.am and configure.ac
  
• My program compiles and links fine, but doesn't output translated strings.
  

GNU gettext on Windows

• What does Woe32 mean?
• How do I compile, link and run a program that uses the gettext() function?
  
• Setting the LANG environment variable doesn't have any effect

Other

• What does this mean: “'msgid' and 'msgstr' entries do not both end with '\n'”
• German umlauts are displayed like “ge"andert” instead of “geändert”
• The LANGUAGE environment variable is ignored after I set LANG=en
• I use accented characters in my source code. How do I tell the C/C++ compiler in which encoding it is (like xgettext's --from-code option)?

Answers

General

Where is the mailing list?

• bug-gettext@gnu.org
  This mailing list is for discussion of features and bugs of the GNU gettext software, including libintl, the gettext-tools, and its autoconf macros. The archive and subscription instructions can be found at the information page.
• translation-i18n@lists.sourceforge.net
  This mailing list is for methodology questions around internationalization, and for discussions of translator tools, including but not limited to GNU gettext.
• coordinator@translationproject.org
  This is the email address of the Translation Project, that is the project which manages the translated message catalogs for many free software packages. Note that KDE and GNOME packages are not part of this project; they have their own translation projects: l10n.kde.org and GNOME Translation Project.
  

Where is the newest gettext source?

I want to be notified of new gettext releases.

Problems building GNU gettext

On Solaris, I get a build error “text relocations remain” in the libasprintf subdirectory

“make install” fails

Problems integrating GNU gettext

How do I make use of gettext() in my package?

• Add an invocation of AM_GNU_GETTEXT([external]) to the package's configure.{ac,in} file.
• Invoke “gettextize --copy”. It will do most of the autoconf/automake related work for you.
• Add the gettext.h file to the package's source directory, and include it in all source files that contain translatable strings or do output via printf or fprintf.
• In the source file defining the main() function of the program, add these lines to the header
  
  #include <locale.h>
#include "gettext.h"
  
  and these lines near the beginning of the main() function:
  
  setlocale (LC_ALL, "");
bindtextdomain (PACKAGE, LOCALEDIR);
textdomain (PACKAGE);
  
• Mark all strings that should be translated with _(), like this: _("No errors found."). While doing this, try to turn the strings into good English, one entire sentence per string, not more than one paragraph per string, and use format strings instead of string concatenation. This is needed so that the translators can provide accurate translations.
• In every source file containing translatable strings, add these lines to the header:
  
  #include "gettext.h"
#define _(string) gettext (string)
  
• In the freshly created po/ directory, set up the POTFILES.in file, and do a “make update-po”. Then distribute the generated .pot file to your nearest translation project.
• Shortly before a release, integrate the translators' .po files into the po/ directory and do “make update-po” again.
  

I get a linker error “undefined reference to libintl_gettext”

• If yes:
  Find out where the libintl comes from. To do this, you have to check for libintl.a and libintl.so* (libintl.dylib on MacOS X) in each directory given as a -L option, as well as in the compiler's implicit search directories. (You get these implicit search directories for gcc by using “gcc -v” instead of “gcc” in the final link command line; compilers other than GCC usually look in /usr/lib and /lib.) A shell command like
  
  $ for d in /usr/local/lib /usr/lib /lib; do ls -l $d/libintl.*; done
  
  will show where the libintl comes from. By looking at the dates and whether each library defines libintl_gettext (via “nm path/libintl.so | grep libintl_gettext”) you can now distinguish three possible causes of the error:
  
  • Some older libintl is used instead of the newer one. The fix is to remove the old library or to reorganize your -L options.
  • The used libintl is the new one, and it doesn't contain libintl_gettext. This would be a bug in gettext. If this is the case, please report it to the usual bug report address.
  • The used libintl is a static library (libintl.a), there are no uses of gettext in .o files before the “-lintl” but there are some after the “-lintl”. In this case the fix is to move the “-lintl” to the end or near the end of the link command line. The only libintl dependency that needs to be mentioned after “-lintl” is “-liconv”.
• If no:
  In this case it's likely a bug in the package you are building: The package's Makefiles should make sure that “-lintl” is used where needed.
  Test whether libintl was found by configure. You can check this by doing
  
  $ grep '\(INTLLIBS\|LIBINTL\)' config.status
  
  and looking whether the value of this autoconf variable is non-empty.
  
  • If yes: It should be the responsibility of the Makefile to use the value of this variable in the link command line. Does the Makefile.in rule for linking the program use @INTLLIBS@ or @LIBINTL@?
    
    • If no: It's a Makefile.am/in bug.
    • If yes: Something strange is going on. You need to dig deeper.
    Note that @INTLLIBS@ is for gettext.m4 versions <= 0.10.40 and @LIBINTL@ is for gettext.m4 versions >= 0.11, depending on which gettext.m4 was used to build the package's configure - regardless of which gettext you have now installed.
  • If no: So libintl was not found.
    Take a look at the package's configure.in/ac. Does it invoke AM_GNU_GETTEXT?
    
    • If no: The gettext maintainers take no responsibilities for lookalikes named CY_GNU_GETTEXT, AM_GLIB_GNU_GETTEXT, AM_GNOME_GETTEXT and similar, or for homebrewn autoconf checks. Complain to the package maintainer.
    • If yes: It looks like the -I and -L options were inconsistent. You should have a -Isomedir/include in the CFLAGS or CPPFLAGS if and only if you also have a -Lsomedir/lib in the LDFLAGS. And somedir/include should contain a libintl.h if and only if somedir/lib contains libintl.{a,so}.
      This case can also happen if you have configured a GCC < 3.2 with the same --prefix option as you used for GNU libiconv or GNU gettext. This is fatal, because these versions of GCC implicitly use -Lprefix/lib but not
      -Iprefix/include. The workaround is to use a different --prefix for GCC.
      

gettextize adds multiple references to the same directories/files to Makefile.am and configure.ac

My program compiles and links fine, but doesn't output translated strings.

1. Check that the environment variables LC_ALL, LC_MESSAGES, LC_CTYPE, LANG, LANGUAGE together specify a valid locale and language.
   To check this, run the commands
   
   $ gettext --version
$ gettext --help
   
   You should see at least some output in your desired language. If not, either
   
   • You have chosen a too exotic language. gettext is localized to 33 languages. Choose a less exotic language, such as Galician or Ukrainian. Or
     
   • There is a problem with your environment variables. Possibly LC_ALL points to a locale that is not installed, or LC_MESSAGES and LC_CTYPE are inconsistent.
2. Check that your program contains a setlocale call.
   To check this, run your program under ltrace. For example,
   
   $ ltrace ./myprog
...
setlocale(6, "")                  = "de_DE.UTF-8"
   
   If you have no ltrace, you can also do this check by running your program under the debugger. For example,
   
   $ gdb ./myprog
(gdb) break main
(gdb) run
Breakpoint 1, main ()
(gdb) break setlocale
(gdb) continue
Breakpoint 2, setlocale ()
;; OK, the breakpoint has been hit, setlocale() is being called.
   
   Either way, check that the return value of setlocale() is non-NULL. A NULL return value indicates a failure. 
3. Check that your program contains a textdomain call, a bindtextdomain call referring to the same message domain, and then really calls the gettext, dgettext or dcgettext function.
   To check this, run the program under ltrace. For example,
   
   $ ltrace ./myprog
...
textdomain("hello-c")                             = "hello-c"
bindtextdomain("hello-c", "/opt/share"...) = "/opt/share"...
dcgettext(0, 0x08048691, 5, 0x0804a200, 0x08048689) = 0x4001721f
   
   If you have no ltrace, you can also do this check by running your program under the debugger. For example,
   
   $ gdb ./myprog
(gdb) break main
(gdb) run
Breakpoint 1, main ()
(gdb) break textdomain
(gdb) break bindtextdomain
(gdb) break gettext
(gdb) break dgettext
(gdb) break dcgettext
(gdb) continue
Breakpoint 2, textdomain ()
(gdb) continue
Breakpoint 3, bindtextdomain ()
(gdb) continue
Breakpoint 6, dcgettext ()
   
   Note that here dcgettext() is called instead of the gettext() function mentioned in the source code; this is due to an optimization in <libintl.h>.
   When using libintl on a non-glibc system, you have to add a prefix “libintl_” to all the function names mentioned here, because that's what the functions are really named, under the hood.
   If gettext/dgettext/dcgettext is not called at all, the possible cause might be that some autoconf or Makefile macrology has turned off internationalization entirely (like the --disable-nls configuration option usually does).
   
4. Check that the .mo file that contains the translation is really there where the program expects it.
   To check this, run the program under strace and look at the open() calls. For example,
   
   $ strace ./myprog 2>&1 | grep '^open('
open("/etc/ld.so.preload", O_RDONLY)    = -1 ENOENT (No such file or directory)
open("/etc/ld.so.cache", O_RDONLY)      = 5
open("/lib/libc.so.6", O_RDONLY)        = 5
open("/usr/lib/locale/locale-archive", O_RDONLY|O_LARGEFILE) = 5
open("/usr/share/locale/locale.alias", O_RDONLY) = 5
open("/opt/share/locale/de/LC_MESSAGES/hello-c.mo", O_RDONLY) = 5
...
   
   A nonnegative open() return value means that the file has been found.
   If you have no strace, you can also guess the .mo file's location: it is
   
   localedir/lang/LC_MESSAGES/domain.mo
   
   where domain is the argument passed to textdomain(), localedir is the second argument passed to bindtextdomain(), and lang is the language (LL) or language and territory (LL_CC), depending on the environment variables checked in step 1.
5. Check that the .mo file contains a translation for the string that is being asked for.
   To do this, you need to convert the .mo file back to PO file format, through the command
   
   $ msgunfmt localedir/lang/LC_MESSAGES/domain.mo
   
   and look for an msgid that matches the given string.
   

GNU gettext on Windows

What does Woe32 mean?

How do I compile, link and run a program that uses the gettext() function?

• You need to add an -I option to the compilation command line, so that the compiler finds the libintl.h include file, and
• You need to add an -L option to the link command line, so that the linker finds the libintl library.

• You need to add an -MD option to all compilation and link command lines. MSVC has six different, mutually incompatible, compilation models (-ML, -MT, -MD, -MLd, -MTd, -MDd); the default is -ML. intl.dll uses the -MD model, therefore the rest of the program must use -MD as well.
  
• You need to add an -I option to the compilation command line, so that the compiler finds the libintl.h include file.
  
• You need to add an -L option to the link command line, so that the linker finds the intl.lib library.
• You need to copy the intl.dll and iconv.dll to the directory where your .exe files are created, so that they will be found at runtime.
  

Setting the LANG environment variable doesn't have any effect

• Check that you are using the -MD option in all compilation and link command lines. Otherwise you might end up calling the putenv() function from Microsoft's libc.lib, whereas intl.dll is using the getenv() function from Mictosoft's msvcrt.lib.
• Check that you set the environment variable using both SetEnvironmentVariable() and putenv(). A convenient way to do so, and to deal with the fact that some Unix systems have setenv() and some don't, is the following function.
  
  
  #include <string.h>
#include <stdlib.h>
#if defined _WIN32
# include <windows.h>
#endif

int my_setenv (const char * name, const char * value) {
  size_t namelen = strlen(name);
  size_t valuelen = (value==NULL ? 0 : strlen(value));
#if defined _WIN32
  /* On Woe32, each process has two copies of the environment variables,
     one managed by the OS and one managed by the C library. We set
     the value in both locations, so that other software that looks in
     one place or the other is guaranteed to see the value. Even if it's
     a bit slow. See also
     <https://article.gmane.org/gmane.comp.gnu.mingw.user/8272>
     <https://article.gmane.org/gmane.comp.gnu.mingw.user/8273>
     <https://www.cygwin.com/ml/cygwin/1999-04/msg00478.html> */
  if (!SetEnvironmentVariableA(name,value))
    return -1;
#endif
#if defined(HAVE_PUTENV)
  char* buffer = (char*)malloc(namelen+1+valuelen+1);
  if (!buffer)
    return -1; /* no need to set errno = ENOMEM */
  memcpy(buffer,name,namelen);
  if (value != NULL) {
    buffer[namelen] = '=';
    memcpy(buffer+namelen+1,value,valuelen);
    buffer[namelen+1+valuelen] = 0;
  } else
    buffer[namelen] = 0;
  return putenv(buffer);
#elif defined(HAVE_SETENV)
  return setenv(name,value,1);
#else
  /* Uh oh, neither putenv() nor setenv() ... */
  return -1;
#endif
}
  
  
  

Other

What does this mean: “'msgid' and 'msgstr' entries do not both end with '\n'”

German umlauts are displayed like “ge"andert” instead of “geändert”

The LANGUAGE environment variable is ignored after I set LANG=en

In the LANGUAGE environment variable, but not in the LANG environment variable, LL_CC combinations can be abbreviated as LL to denote the language's main dialect.

I use accented characters in my source code. How do I tell the C/C++ compiler in which encoding it is (like xgettext's --from-code option)?

1. For the comments in C/C++ source code. The compiler ignores them.
   
2. For other programming languages like Java, for which the compiler converts all string literals to UTF-8.

Last modified: 6 June 2020