gettext-runtime/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.19.7"
  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)