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 textdomain 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 prefix/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 LANGUAGE 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)