| 1 |
.\" Copyright (c) Bruno Haible <[email protected]> |
| 2 |
.\" |
| 3 |
.\" This is free documentation; you can redistribute it and/or |
| 4 |
.\" modify it under the terms of the GNU General Public License as |
| 5 |
.\" published by the Free Software Foundation; either version 2 of |
| 6 |
.\" the License, or (at your option) any later version. |
| 7 |
.\" |
| 8 |
.\" References consulted: |
| 9 |
.\" GNU glibc-2 source code and manual |
| 10 |
.\" GNU gettext source code and manual |
| 11 |
.\" LI18NUX 2000 Globalization Specification |
| 12 |
.\" |
| 13 |
.TH GETTEXT 3 "November 2024" "GNU gettext 0.26" |
| 14 |
.SH NAME |
| 15 |
gettext, dgettext, dcgettext \- translate message |
| 16 |
.SH SYNOPSIS |
| 17 |
.nf |
| 18 |
.B #include <libintl.h> |
| 19 |
.sp |
| 20 |
.BI "char * gettext (const char * " msgid ); |
| 21 |
.BI "char * dgettext (const char * " domainname ", const char * " msgid ); |
| 22 |
.BI "char * dcgettext (const char * " domainname ", const char * " msgid , |
| 23 |
.BI " int " category ); |
| 24 |
.fi |
| 25 |
.SH DESCRIPTION |
| 26 |
The \fBgettext\fP, \fBdgettext\fP and \fBdcgettext\fP functions attempt to |
| 27 |
translate a text string into the user's native language, by looking up the |
| 28 |
translation in a message catalog. |
| 29 |
.PP |
| 30 |
The \fImsgid\fP argument identifies the message to be translated. By |
| 31 |
convention, it is the English version of the message, with non-ASCII |
| 32 |
characters replaced by ASCII approximations. This choice allows the |
| 33 |
translators to work with message catalogs, called PO files, that contain |
| 34 |
both the English and the translated versions of each message, and can be |
| 35 |
installed using the \fBmsgfmt\fP utility. |
| 36 |
.PP |
| 37 |
A message domain is a set of translatable \fImsgid\fP messages. Usually, |
| 38 |
every software package has its own message domain. The domain name is used |
| 39 |
to determine the message catalog where the translation is looked up; it must |
| 40 |
be a non-empty string. For the \fBgettext\fP function, it is specified through |
| 41 |
a preceding \fBtextdomain\fP call. For the \fBdgettext\fP and \fBdcgettext\fP |
| 42 |
functions, it is passed as the \fIdomainname\fP argument; if this argument is |
| 43 |
NULL, the domain name specified through a preceding \fBtextdomain\fP call is |
| 44 |
used instead. |
| 45 |
.PP |
| 46 |
Translation lookup operates in the context of the current locale. For the |
| 47 |
\fBgettext\fP and \fBdgettext\fP functions, the \fBLC_MESSAGES\fP locale |
| 48 |
facet is used. It is determined by a preceding call to the \fBsetlocale\fP |
| 49 |
function. \fBsetlocale (LC_ALL, "")\fP initializes the \fBLC_MESSAGES\fP locale |
| 50 |
based on the first nonempty value of the three environment variables |
| 51 |
\fBLC_ALL\fP, \fBLC_MESSAGES\fP, \fBLANG\fP; see \fBsetlocale\fP(3). For the |
| 52 |
\fBdcgettext\fP function, the locale facet is determined by the \fIcategory\fP |
| 53 |
argument, which should be one of the \fBLC_xxx\fP constants defined in the |
| 54 |
<locale.h> header, excluding \fBLC_ALL\fP. In both cases, the functions also |
| 55 |
use the \fBLC_CTYPE\fP locale facet in order to convert the translated message |
| 56 |
from the translator's codeset to the current locale's codeset, unless |
| 57 |
overridden by a prior call to the \fBbind_textdomain_codeset\fP function. |
| 58 |
.PP |
| 59 |
The message catalog used by the functions is at the pathname |
| 60 |
\fIdirname\fP/\fIlocale\fP/\fIcategory\fP/\fIdomainname\fP.mo. Here |
| 61 |
\fIdirname\fP is the directory specified through \fBbindtextdomain\fP. Its |
| 62 |
default is system and configuration dependent; typically it is |
| 63 |
\fIprefix\fP/share/locale, where \fIprefix\fP is the installation prefix of the |
| 64 |
package. \fIlocale\fP is the name of the current locale facet; the GNU |
| 65 |
implementation also tries generalizations, such as the language name without |
| 66 |
the territory name. \fIcategory\fP is \fBLC_MESSAGES\fP for the \fBgettext\fP |
| 67 |
and \fBdgettext\fP functions, or the argument passed to the \fBdcgettext\fP |
| 68 |
function. |
| 69 |
.PP |
| 70 |
If the \fBLANGUAGE\fP environment variable is set to a nonempty value, and the |
| 71 |
locale is not the "C" locale, the value of \fBLANGUAGE\fP is assumed to contain |
| 72 |
a colon separated list of locale names. The functions will attempt to look up |
| 73 |
a translation of \fImsgid\fP in each of the locales in turn. This is a GNU |
| 74 |
extension. |
| 75 |
.PP |
| 76 |
In the "C" locale, or if none of the used catalogs contain a translation for |
| 77 |
\fImsgid\fP, the \fBgettext\fP, \fBdgettext\fP and \fBdcgettext\fP functions |
| 78 |
return \fImsgid\fP. |
| 79 |
.SH "RETURN VALUE" |
| 80 |
If a translation was found in one of the specified catalogs, it is converted |
| 81 |
to the locale's codeset and returned. The resulting string is statically |
| 82 |
allocated and must not be modified or freed. Otherwise \fImsgid\fP is returned. |
| 83 |
.SH ERRORS |
| 84 |
\fBerrno\fP is not modified. |
| 85 |
.SH BUGS |
| 86 |
The return type ought to be \fBconst char *\fP, but is \fBchar *\fP to avoid |
| 87 |
warnings in C code predating ANSI C. |
| 88 |
.PP |
| 89 |
When an empty string is used for \fImsgid\fP, the functions may return a |
| 90 |
nonempty string. |
| 91 |
.SH "SEE ALSO" |
| 92 |
.BR ngettext (3), |
| 93 |
.BR dngettext (3), |
| 94 |
.BR dcngettext (3), |
| 95 |
.BR setlocale (3), |
| 96 |
.BR textdomain (3), |
| 97 |
.BR bindtextdomain (3), |
| 98 |
.BR bind_textdomain_codeset (3), |
| 99 |
.BR msgfmt (1) |