← Back to branch summary

~ubuntu-branches/ubuntu/breezy/gettext/breezy

« back to all changes in this revision

Viewing changes to gettext-runtime/man/gettext.3.in

  • Committer: Bazaar Package Importer
  • Author(s): Santiago Vila
  • Date: 2004-03-14 17:40:02 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20040314174002-p1ad5ldve1hqzhye
Tags: 0.14.1-2
* Added libexpat1-dev to Build-Depends, for glade support.
* Added libc0.1-dev to Build-Depends, for GNU/kFreeBSD.
* Removed special-casing of knetbsd-gnu in debian/rules.

Show diffs side-by-side

added added

removed removed

Lines of Context:
gettext-runtime/man/gettext.3.in
 
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 @VERSION@"
 
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)