22

✏️ Editing: gettext.3.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
 p { margin-top: 0; margin-bottom: 0; vertical-align: top }
 pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
 table { margin-top: 0; margin-bottom: 0; vertical-align: top }
 h1 { text-align: center }
</style>
<title>GETTEXT</title>

</head>
<body>

<h1 align="center">GETTEXT</h1>

<a href="#NAME">NAME</a> 
<a href="#SYNOPSIS">SYNOPSIS</a> 
<a href="#DESCRIPTION">DESCRIPTION</a> 
<a href="#RETURN VALUE">RETURN VALUE</a> 
<a href="#ERRORS">ERRORS</a> 
<a href="#BUGS">BUGS</a> 
<a href="#SEE ALSO">SEE ALSO</a>

<hr>

gettext,
dgettext, dcgettext &minus; translate message

<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>

#include
&lt;libintl.h&gt;

char *
gettext (const char * msgid); 
char * dgettext (const char * domainname,
const char * msgid); 
char * dcgettext (const char * domainname,
const char * msgid, 
int category);

<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>

The
gettext, dgettext and dcgettext
functions attempt to translate a text string into the
user&rsquo;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,&quot;&quot;) 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
&lt;locale.h&gt; 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&rsquo;s codeset to the current locale&rsquo;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 &quot;C&quot; 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
&quot;C&quot; locale, or if none of the used catalogs
contain a translation for msgid, the gettext,
dgettext and dcgettext functions return
msgid.

<h2>RETURN VALUE
<a name="RETURN VALUE"></a>
</h2>

If a
translation was found in one of the specified catalogs, it
is converted to the locale&rsquo;s codeset and returned. The
resulting string is statically allocated and must not be
modified or freed. Otherwise msgid is returned.

<h2>ERRORS
<a name="ERRORS"></a>
</h2>

errno is
not modified.

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.

ngettext(3),
dngettext(3), dcngettext(3),
setlocale(3), textdomain(3),
bindtextdomain(3), bind_textdomain_codeset(3),
msgfmt(1)
<hr>
</body>
</html>

MR SKB