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