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 transla-
tion in a message catalog.
The msgid argument identifies the message to be translated. By conven-
tion, it is the English version of the message, with non-ASCII charac-
ters replaced by ASCII approximations. This choice allows the transla-
tors to work with message catalogs, called PO files, that contain both
the English and the translated versions of each message, and can be in-
stalled 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_MES-
SAGES, 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 cur-
rent 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/lo-
cale/category/domainname.mo. Here dirname is the directory specified
through bindtextdomain. Its default is system and configuration depen-
dent; typically it is prefix/share/locale, where prefix is the installa-
tion 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 dcget-
text 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 con-
tain 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 con-
verted 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 warn-
ings in C code predating ANSI C.
When an empty string is used for msgid, the functions may return a non-
empty string.
SEE ALSO
ngettext(3), dngettext(3), dcngettext(3), setlocale(3), textdomain(3),
bindtextdomain(3), bind_textdomain_codeset(3), msgfmt(1)
GNU gettext 0.23.1 November 2024 GETTEXT(3)
Generated by dwww version 1.16 on Tue Dec 16 04:44:04 CET 2025.