dgettext(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 trans-
lated. 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 speci-
fied 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 speci-
fied 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. setlo-
cale(LC_ALL,"") initializes the LC_MESSAGES locale based
on the first nonempty value of the three environment vari-
ables 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 con-
stants 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_textdo-
main_codeset function.
The message catalog used by the functions is at the path-
name 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 installa-
tion prefix of the package. locale is the name of the cur-
rent locale facet; the GNU implementation also tries gen-
eralizations, such as the language name without the terri-
tory 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 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 dcget-
text functions return msgid.
RETURN VALUE
If a translation was found in one of the specified cata-
logs, 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_code-
set(3), msgfmt(1)
GNU gettext 0.16.1 May 2001 GETTEXT(3)
Man(1) output converted with
man2html