GETTEXT
#NAME
NAME
#SYNOPSIS
SYNOPSIS
#DESCRIPTION
DESCRIPTION
#RETURN VALUE
RETURN VALUE
#ERRORS
ERRORS
#BUGS
BUGS
#SEE ALSO
SEE 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
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
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)
