jpayne@68: .\" Copyright (c) Bruno Haible jpayne@68: .\" jpayne@68: .\" This is free documentation; you can redistribute it and/or jpayne@68: .\" modify it under the terms of the GNU General Public License as jpayne@68: .\" published by the Free Software Foundation; either version 2 of jpayne@68: .\" the License, or (at your option) any later version. jpayne@68: .\" jpayne@68: .\" References consulted: jpayne@68: .\" GNU glibc-2 source code and manual jpayne@68: .\" GNU gettext source code and manual jpayne@68: .\" LI18NUX 2000 Globalization Specification jpayne@68: .\" jpayne@68: .TH GETTEXT 3 "May 2001" "GNU gettext 0.22.5" jpayne@68: .SH NAME jpayne@68: gettext, dgettext, dcgettext \- translate message jpayne@68: .SH SYNOPSIS jpayne@68: .nf jpayne@68: .B #include jpayne@68: .sp jpayne@68: .BI "char * gettext (const char * " msgid ); jpayne@68: .BI "char * dgettext (const char * " domainname ", const char * " msgid ); jpayne@68: .BI "char * dcgettext (const char * " domainname ", const char * " msgid , jpayne@68: .BI " int " category ); jpayne@68: .fi jpayne@68: .SH DESCRIPTION jpayne@68: The \fBgettext\fP, \fBdgettext\fP and \fBdcgettext\fP functions attempt to jpayne@68: translate a text string into the user's native language, by looking up the jpayne@68: translation in a message catalog. jpayne@68: .PP jpayne@68: The \fImsgid\fP argument identifies the message to be translated. By jpayne@68: convention, it is the English version of the message, with non-ASCII jpayne@68: characters replaced by ASCII approximations. This choice allows the jpayne@68: translators to work with message catalogs, called PO files, that contain jpayne@68: both the English and the translated versions of each message, and can be jpayne@68: installed using the \fBmsgfmt\fP utility. jpayne@68: .PP jpayne@68: A message domain is a set of translatable \fImsgid\fP messages. Usually, jpayne@68: every software package has its own message domain. The domain name is used jpayne@68: to determine the message catalog where the translation is looked up; it must jpayne@68: be a non-empty string. For the \fBgettext\fP function, it is specified through jpayne@68: a preceding \fBtextdomain\fP call. For the \fBdgettext\fP and \fBdcgettext\fP jpayne@68: functions, it is passed as the \fIdomainname\fP argument; if this argument is jpayne@68: NULL, the domain name specified through a preceding \fBtextdomain\fP call is jpayne@68: used instead. jpayne@68: .PP jpayne@68: Translation lookup operates in the context of the current locale. For the jpayne@68: \fBgettext\fP and \fBdgettext\fP functions, the \fBLC_MESSAGES\fP locale jpayne@68: facet is used. It is determined by a preceding call to the \fBsetlocale\fP jpayne@68: function. \fBsetlocale(LC_ALL,"")\fP initializes the \fBLC_MESSAGES\fP locale jpayne@68: based on the first nonempty value of the three environment variables jpayne@68: \fBLC_ALL\fP, \fBLC_MESSAGES\fP, \fBLANG\fP; see \fBsetlocale\fP(3). For the jpayne@68: \fBdcgettext\fP function, the locale facet is determined by the \fIcategory\fP jpayne@68: argument, which should be one of the \fBLC_xxx\fP constants defined in the jpayne@68: header, excluding \fBLC_ALL\fP. In both cases, the functions also jpayne@68: use the \fBLC_CTYPE\fP locale facet in order to convert the translated message jpayne@68: from the translator's codeset to the current locale's codeset, unless jpayne@68: overridden by a prior call to the \fBbind_textdomain_codeset\fP function. jpayne@68: .PP jpayne@68: The message catalog used by the functions is at the pathname jpayne@68: \fIdirname\fP/\fIlocale\fP/\fIcategory\fP/\fIdomainname\fP.mo. Here jpayne@68: \fIdirname\fP is the directory specified through \fBbindtextdomain\fP. Its jpayne@68: default is system and configuration dependent; typically it is jpayne@68: \fIprefix\fP/share/locale, where \fIprefix\fP is the installation prefix of the jpayne@68: package. \fIlocale\fP is the name of the current locale facet; the GNU jpayne@68: implementation also tries generalizations, such as the language name without jpayne@68: the territory name. \fIcategory\fP is \fBLC_MESSAGES\fP for the \fBgettext\fP jpayne@68: and \fBdgettext\fP functions, or the argument passed to the \fBdcgettext\fP jpayne@68: function. jpayne@68: .PP jpayne@68: If the \fBLANGUAGE\fP environment variable is set to a nonempty value, and the jpayne@68: locale is not the "C" locale, the value of \fBLANGUAGE\fP is assumed to contain jpayne@68: a colon separated list of locale names. The functions will attempt to look up jpayne@68: a translation of \fImsgid\fP in each of the locales in turn. This is a GNU jpayne@68: extension. jpayne@68: .PP jpayne@68: In the "C" locale, or if none of the used catalogs contain a translation for jpayne@68: \fImsgid\fP, the \fBgettext\fP, \fBdgettext\fP and \fBdcgettext\fP functions jpayne@68: return \fImsgid\fP. jpayne@68: .SH "RETURN VALUE" jpayne@68: If a translation was found in one of the specified catalogs, it is converted jpayne@68: to the locale's codeset and returned. The resulting string is statically jpayne@68: allocated and must not be modified or freed. Otherwise \fImsgid\fP is returned. jpayne@68: .SH ERRORS jpayne@68: \fBerrno\fP is not modified. jpayne@68: .SH BUGS jpayne@68: The return type ought to be \fBconst char *\fP, but is \fBchar *\fP to avoid jpayne@68: warnings in C code predating ANSI C. jpayne@68: .PP jpayne@68: When an empty string is used for \fImsgid\fP, the functions may return a jpayne@68: nonempty string. jpayne@68: .SH "SEE ALSO" jpayne@68: .BR ngettext (3), jpayne@68: .BR dngettext (3), jpayne@68: .BR dcngettext (3), jpayne@68: .BR setlocale (3), jpayne@68: .BR textdomain (3), jpayne@68: .BR bindtextdomain (3), jpayne@68: .BR bind_textdomain_codeset (3), jpayne@68: .BR msgfmt (1)