Man Linux: Main Page and Category List

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)