NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | BUGS | SEE ALSO | COLOPHON

GETTEXT(3)                Library Functions Manual                GETTEXT(3)

NAME         top

       gettext, dgettext, dcgettext - translate message

SYNOPSIS         top

       #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         top

       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         top

       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         top

       errno is not modified.

BUGS         top

       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         top

       ngettext(3), dngettext(3), dcngettext(3), setlocale(3),
       textdomain(3), bindtextdomain(3), bind_textdomain_codeset(3),
       msgfmt(1)

COLOPHON         top

       This page is part of the gettext (message translation) project.
       Information about the project can be found at 
       ⟨http://www.gnu.org/software/gettext/⟩.  If you have a bug report for
       this manual page, see ⟨http://savannah.gnu.org/projects/gettext/⟩.
       This page was obtained from the project's upstream Git repository 
       ⟨git://git.savannah.gnu.org/gettext.git⟩ on 2017-05-03.  If you dis‐
       cover any rendering problems in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the page, or
       you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a mail
       to man-pages@man7.org

GNU gettext 0.19.8.1.6-c77646     May 2001                        GETTEXT(3)

Pages that refer to this page: bindtextdomain(3)bind_textdomain_codeset(3)ngettext(3)textdomain(3)wprintf(3)environ(7)locale(7)