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