man > gettext(3)

GETTEXT(3)                            Library Functions Manual                            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  dget‐
       text 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 setlo‐
       cale(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/domain‐
       name.mo. Here dirname is the directory specified through bindtextdomain. Its default is  sys‐
       tem and configuration dependent; typically it is prefix/share/locale, where prefix is the in‐
       stallation prefix of the package. locale is the name of the current locale facet; the GNU im‐
       plementation  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 get‐
       text, 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.20.1.124-32cf                   May 2001                                    GETTEXT(3)