GETTEXT
#NAMENAME #SYNOPSISSYNOPSIS #DESCRIPTIONDESCRIPTION #RETURN VALUERETURN VALUE #ERRORSERRORS #BUGSBUGS #SEE ALSOSEE ALSO 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 dcgettextfunctions 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 
msgfmtutility.
A message domain is a set of translatable 
msgidmessages. 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 dgettextfunctions, the 
LC_MESSAGES locale facet is used. It
is determined by a preceding call to the 
setlocalefunction. 
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
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) 