gettext, dgettext, dcgettext - translate message
#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);
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.
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.
errno is not modified.
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.
ngettext(3),
dngettext(3),
dcngettext(3),
setlocale(3),
textdomain(3),
bindtextdomain(3),
bind_textdomain_codeset(3),
msgfmt(1)