|
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 NGETTEXT 3 "May 2001" "GNU gettext 0.22.5"
|
|
jpayne@68
|
14 .SH NAME
|
|
jpayne@68
|
15 ngettext, dngettext, dcngettext \- translate message and choose plural form
|
|
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 * ngettext (const char * " msgid ", const char * " msgid_plural ,
|
|
jpayne@68
|
21 .BI " unsigned long int " n );
|
|
jpayne@68
|
22 .BI "char * dngettext (const char * " domainname ,
|
|
jpayne@68
|
23 .BI " const char * " msgid ", const char * " msgid_plural ,
|
|
jpayne@68
|
24 .BI " unsigned long int " n );
|
|
jpayne@68
|
25 .BI "char * dcngettext (const char * " domainname ,
|
|
jpayne@68
|
26 .BI " const char * " msgid ", const char * " msgid_plural ,
|
|
jpayne@68
|
27 .BI " unsigned long int " n ", int " category );
|
|
jpayne@68
|
28 .fi
|
|
jpayne@68
|
29 .SH DESCRIPTION
|
|
jpayne@68
|
30 The \fBngettext\fP, \fBdngettext\fP and \fBdcngettext\fP functions attempt to
|
|
jpayne@68
|
31 translate a text string into the user's native language, by looking up the
|
|
jpayne@68
|
32 appropriate plural form of the translation in a message catalog.
|
|
jpayne@68
|
33 .PP
|
|
jpayne@68
|
34 Plural forms are grammatical variants depending on the a number. Some languages
|
|
jpayne@68
|
35 have two forms, called singular and plural. Other languages have three forms,
|
|
jpayne@68
|
36 called singular, dual and plural. There are also languages with four forms.
|
|
jpayne@68
|
37 .PP
|
|
jpayne@68
|
38 The \fBngettext\fP, \fBdngettext\fP and \fBdcngettext\fP functions work like
|
|
jpayne@68
|
39 the \fBgettext\fP, \fBdgettext\fP and \fBdcgettext\fP functions, respectively.
|
|
jpayne@68
|
40 Additionally, they choose the appropriate plural form, which depends on the
|
|
jpayne@68
|
41 number \fIn\fP and the language of the message catalog where the translation
|
|
jpayne@68
|
42 was found.
|
|
jpayne@68
|
43 .PP
|
|
jpayne@68
|
44 In the "C" locale, or if none of the used catalogs contain a translation for
|
|
jpayne@68
|
45 \fImsgid\fP, the \fBngettext\fP, \fBdngettext\fP and \fBdcngettext\fP functions
|
|
jpayne@68
|
46 return \fImsgid\fP if \fIn\fP == 1, or \fImsgid_plural\fP if \fIn\fP != 1.
|
|
jpayne@68
|
47 .SH "RETURN VALUE"
|
|
jpayne@68
|
48 If a translation was found in one of the specified catalogs, the appropriate
|
|
jpayne@68
|
49 plural form is converted to the locale's codeset and returned. The resulting
|
|
jpayne@68
|
50 string is statically allocated and must not be modified or freed. Otherwise
|
|
jpayne@68
|
51 \fImsgid\fP or \fImsgid_plural\fP is returned, as described above.
|
|
jpayne@68
|
52 .SH ERRORS
|
|
jpayne@68
|
53 \fBerrno\fP is not modified.
|
|
jpayne@68
|
54 .SH BUGS
|
|
jpayne@68
|
55 The return type ought to be \fBconst char *\fP, but is \fBchar *\fP to avoid
|
|
jpayne@68
|
56 warnings in C code predating ANSI C.
|
|
jpayne@68
|
57 .SH "SEE ALSO"
|
|
jpayne@68
|
58 .BR gettext (3),
|
|
jpayne@68
|
59 .BR dgettext (3),
|
|
jpayne@68
|
60 .BR dcgettext (3)
|
