Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man3/gettext.3 @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 68:5028fdace37b
1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
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 "May 2001" "GNU gettext 0.22.5"
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)