Introduction to Library Functions                      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 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

GNU gettext 0.11.5    Last change: May 2001                     1

Introduction to Library Functions                      GETTEXT(3)

     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  func-
     tions, 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 trans-
     lation 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.11.5    Last change: May 2001                     2