GETTEXT(3)                                                                                                            GETTEXT(3)



NAME
       gettext, dgettext, dcgettext - translate message

SYNOPSIS
       #include <libintl.h>

       char * gettext (const char * msgid);
       char * dgettext (const char * domainname, const char * msgid);
       char * dcgettext (const char * domainname, const char * msgid,
                         int category);

DESCRIPTION
       The  gettext,  dgettext  and  dcgettext  functions attempt to translate a text string into the user's native language, by
       looking up the translation in a message catalog.

       The msgid argument identifies the message to be translated. By convention, it is the English version of the message, with
       non-ASCII  characters replaced by ASCII approximations. This choice allows the translators to work with message catalogs,
       called PO files, that contain both the English and the translated versions of each message, and can  be  installed  using
       the msgfmt utility.

       A message domain is a set of translatable msgid messages. Usually, every software package has its own message domain. The
       domain name is used to determine the message catalog where the translation is looked up; it must be a  non-empty  string.
       For  the gettext function, it is specified through a preceding textdomain call. For the dgettext and dcgettext functions,
       it is passed as the domainname argument; if this argument is NULL, the domain name specified through a preceding  textdo-
       main call is used instead.

       Translation lookup operates in the context of the current locale. For the gettext and dgettext functions, the LC_MESSAGES
       locale facet is used. It is determined by a preceding call to the setlocale  function.  setlocale(LC_ALL,"")  initializes
       the  LC_MESSAGES  locale  based on the first nonempty value of the three environment variables LC_ALL, LC_MESSAGES, LANG;
       see setlocale(3). For the dcgettext function, the locale facet is determined by the category argument,  which  should  be
       one of the LC_xxx constants defined in the <locale.h> header, excluding LC_ALL. In both cases, the functions also use the
       LC_CTYPE locale facet in order to convert the translated message from the translator's codeset to  the  current  locale's
       codeset, unless overridden by a prior call to the bind_textdomain_codeset function.

       The  message  catalog used by the functions is at the pathname dirname/locale/category/domainname.mo. Here dirname is the
       directory specified through bindtextdomain. Its default is system and  configuration  dependent;  typically  it  is  pre-
       fix/share/locale, where prefix is the installation prefix of the package. locale is the name of the current locale facet;
       the GNU implementation also tries generalizations, such as the language name without  the  territory  name.  category  is
       LC_MESSAGES for the gettext and dgettext functions, or the argument passed to the dcgettext function.

       If  the LANGUAGE environment variable is set to a nonempty value, and the locale is not the "C" locale, the value of LAN-
       GUAGE is assumed to contain a colon separated list of locale names. The functions will attempt to look up  a  translation
       of msgid in each of the locales in turn. This is a GNU extension.

       In  the  "C" locale, or if none of the used catalogs contain a translation for msgid, the gettext, dgettext and dcgettext
       functions return msgid.

RETURN VALUE
       If a translation was found in one of the specified catalogs, it is converted to the locale's codeset  and  returned.  The
       resulting string is statically allocated and must not be modified or freed. Otherwise msgid is returned.

ERRORS
       errno is not modified.

BUGS
       The return type ought to be const char *, but is char * to avoid warnings in C code predating ANSI C.

       When an empty string is used for msgid, the functions may return a nonempty string.

SEE ALSO
       ngettext(3),  dngettext(3),  dcngettext(3),  setlocale(3),  textdomain(3), bindtextdomain(3), bind_textdomain_codeset(3),
       msgfmt(1)



GNU gettext 0.18.1                                          May 2001                                                  GETTEXT(3)