gettext: lib/gettext.h

1 
1 13.4.13 ‘gettext.h’ in ‘lib/’
1 -----------------------------
1 
1    Internationalization of packages, as provided by GNU ‘gettext’, is
1 optional.  It can be turned off in two situations:
1 
1    • When the installer has specified ‘./configure --disable-nls’.  This
1      can be useful when small binaries are more important than features,
1      for example when building utilities for boot diskettes.  It can
1      also be useful in order to get some specific C compiler warnings
1      about code quality with some older versions of GCC (older than
1      3.0).
1 
1    • When the package does not include the ‘intl/’ subdirectory, and the
1      libintl.h header (with its associated libintl library, if any) is
1      not already installed on the system, it is preferable that the
1      package builds without internationalization support, rather than to
1      give a compilation error.
1 
1    A C preprocessor macro can be used to detect these two cases.
1 Usually, when ‘libintl.h’ was found and not explicitly disabled, the
1 ‘ENABLE_NLS’ macro will be defined to 1 in the autoconf generated
1 configuration file (usually called ‘config.h’).  In the two negative
1 situations, however, this macro will not be defined, thus it will
1 evaluate to 0 in C preprocessor expressions.
1 
1    ‘gettext.h’ is a convenience header file for conditional use of
1 ‘<libintl.h>’, depending on the ‘ENABLE_NLS’ macro.  If ‘ENABLE_NLS’ is
1 set, it includes ‘<libintl.h>’; otherwise it defines no-op substitutes
1 for the libintl.h functions.  We recommend the use of ‘"gettext.h"’ over
1 direct use of ‘<libintl.h>’, so that portability to older systems is
1 guaranteed and installers can turn off internationalization if they want
1 to.  In the C code, you will then write
1 
1      #include "gettext.h"
1 
1 instead of
1 
1      #include <libintl.h>
1 
1    The location of ‘gettext.h’ is usually in a directory containing
1 auxiliary include files.  In many GNU packages, there is a directory
1 ‘lib/’ containing helper functions; ‘gettext.h’ fits there.  In other
1 packages, it can go into the ‘src’ directory.
1 
1    Do not install the ‘gettext.h’ file in public locations.  Every
1 package that needs it should contain a copy of it on its own.
1