← Back to branch summary

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

« back to all changes in this revision

Viewing changes to man/gettext.3

  • 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:
man/gettext.3
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.10.40"
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)