dcgettext

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 transla-
       tion in a message catalog.

       The  msgid argument identifies the message to be translated. By conven-
       tion, it is the English version of the message, with non-ASCII  charac-
       ters  replaced by ASCII approximations. This choice allows the transla-
       tors 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_MES-
       SAGES, 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  code-
       set  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  configura-
       tion  dependent;  typically  it is prefix/share/locale, where prefix is
       the installation prefix of the package. locale is the name of the  cur-
       rent  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
       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 warn-
       ings 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.17                   May 2001                         GETTEXT(3)