GETTEXT
Section: C Library Functions (3)
Updated: May 2001
Index
Return to Main Contents
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)
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- RETURN VALUE
-
- ERRORS
-
- BUGS
-
- SEE ALSO
-
|
|
- Running on 
-
:
: 