gettext-runtime/man/gettext.3.html

   1 <!-- Creator     : groff version 1.22.3 -->
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   3 "http://www.w3.org/TR/html4/loose.dtd">
   4 <html>
   5 <head>
   6 <meta name="generator" content="groff -Thtml, see www.gnu.org">
   7 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   8 <meta name="Content-Style" content="text/css">
   9 <style type="text/css">
  10        p       { margin-top: 0; margin-bottom: 0; vertical-align: top }
  11        pre     { margin-top: 0; margin-bottom: 0; vertical-align: top }
  12        table   { margin-top: 0; margin-bottom: 0; vertical-align: top }
  13        h1      { text-align: center }
  14 </style>
  15 <title>GETTEXT</title>
  16
  17 </head>
  18 <body>
  19
  20 <h1 align="center">GETTEXT</h1>
  21
  22 <a href="#NAME">NAME</a><br>
  23 <a href="#SYNOPSIS">SYNOPSIS</a><br>
  24 <a href="#DESCRIPTION">DESCRIPTION</a><br>
  25 <a href="#RETURN VALUE">RETURN VALUE</a><br>
  26 <a href="#ERRORS">ERRORS</a><br>
  27 <a href="#BUGS">BUGS</a><br>
  28 <a href="#SEE ALSO">SEE ALSO</a><br>
  29
  30 <hr>
  31
  32
  33 <h2>NAME
  34 <a name="NAME"></a>
  35 </h2>
  36
  37
  38 <p style="margin-left:11%; margin-top: 1em">gettext,
  39 dgettext, dcgettext &minus; translate message</p>
  40
  41 <h2>SYNOPSIS
  42 <a name="SYNOPSIS"></a>
  43 </h2>
  44
  45
  46 <p style="margin-left:11%; margin-top: 1em"><b>#include
  47 &lt;libintl.h&gt;</b></p>
  48
  49 <p style="margin-left:11%; margin-top: 1em"><b>char *
  50 gettext (const char *</b> <i>msgid</i><b>); <br>
  51 char * dgettext (const char *</b> <i>domainname</i><b>,
  52 const char *</b> <i>msgid</i><b>); <br>
  53 char * dcgettext (const char *</b> <i>domainname</i><b>,
  54 const char *</b> <i>msgid</i><b>, <br>
  55 int</b> <i>category</i><b>);</b></p>
  56
  57 <h2>DESCRIPTION
  58 <a name="DESCRIPTION"></a>
  59 </h2>
  60
  61
  62 <p style="margin-left:11%; margin-top: 1em">The
  63 <b>gettext</b>, <b>dgettext</b> and <b>dcgettext</b>
  64 functions attempt to translate a text string into the
  65 user&rsquo;s native language, by looking up the translation
  66 in a message catalog.</p>
  67
  68 <p style="margin-left:11%; margin-top: 1em">The
  69 <i>msgid</i> argument identifies the message to be
  70 translated. By convention, it is the English version of the
  71 message, with non-ASCII characters replaced by ASCII
  72 approximations. This choice allows the translators to work
  73 with message catalogs, called PO files, that contain both
  74 the English and the translated versions of each message, and
  75 can be installed using the <b>msgfmt</b> utility.</p>
  76
  77 <p style="margin-left:11%; margin-top: 1em">A message
  78 domain is a set of translatable <i>msgid</i> messages.
  79 Usually, every software package has its own message domain.
  80 The domain name is used to determine the message catalog
  81 where the translation is looked up; it must be a non-empty
  82 string. For the <b>gettext</b> function, it is specified
  83 through a preceding <b>textdomain</b> call. For the
  84 <b>dgettext</b> and <b>dcgettext</b> functions, it is passed
  85 as the <i>domainname</i> argument; if this argument is NULL,
  86 the domain name specified through a preceding
  87 <b>textdomain</b> call is used instead.</p>
  88
  89 <p style="margin-left:11%; margin-top: 1em">Translation
  90 lookup operates in the context of the current locale. For
  91 the <b>gettext</b> and <b>dgettext</b> functions, the
  92 <b>LC_MESSAGES</b> locale facet is used. It is determined by
  93 a preceding call to the <b>setlocale</b> function.
  94 <b>setlocale(LC_ALL,&quot;&quot;)</b> initializes the
  95 <b>LC_MESSAGES</b> locale based on the first nonempty value
  96 of the three environment variables <b>LC_ALL</b>,
  97 <b>LC_MESSAGES</b>, <b>LANG</b>; see <b>setlocale</b>(3).
  98 For the <b>dcgettext</b> function, the locale facet is
  99 determined by the <i>category</i> argument, which should be
 100 one of the <b>LC_xxx</b> constants defined in the
 101 &lt;locale.h&gt; header, excluding <b>LC_ALL</b>. In both
 102 cases, the functions also use the <b>LC_CTYPE</b> locale
 103 facet in order to convert the translated message from the
 104 translator&rsquo;s codeset to the current locale&rsquo;s
 105 codeset, unless overridden by a prior call to the
 106 <b>bind_textdomain_codeset</b> function.</p>
 107
 108 <p style="margin-left:11%; margin-top: 1em">The message
 109 catalog used by the functions is at the pathname
 110 <i>dirname</i>/<i>locale</i>/<i>category</i>/<i>domainname</i>.mo.
 111 Here <i>dirname</i> is the directory specified through
 112 <b>bindtextdomain</b>. Its default is system and
 113 configuration dependent; typically it is
 114 <i>prefix</i>/share/locale, where <i>prefix</i> is the
 115 installation prefix of the package. <i>locale</i> is the
 116 name of the current locale facet; the GNU implementation
 117 also tries generalizations, such as the language name
 118 without the territory name. <i>category</i> is
 119 <b>LC_MESSAGES</b> for the <b>gettext</b> and
 120 <b>dgettext</b> functions, or the argument passed to the
 121 <b>dcgettext</b> function.</p>
 122
 123 <p style="margin-left:11%; margin-top: 1em">If the
 124 <b>LANGUAGE</b> environment variable is set to a nonempty
 125 value, and the locale is not the &quot;C&quot; locale, the
 126 value of <b>LANGUAGE</b> is assumed to contain a colon
 127 separated list of locale names. The functions will attempt
 128 to look up a translation of <i>msgid</i> in each of the
 129 locales in turn. This is a GNU extension.</p>
 130
 131 <p style="margin-left:11%; margin-top: 1em">In the
 132 &quot;C&quot; locale, or if none of the used catalogs
 133 contain a translation for <i>msgid</i>, the <b>gettext</b>,
 134 <b>dgettext</b> and <b>dcgettext</b> functions return
 135 <i>msgid</i>.</p>
 136
 137 <h2>RETURN VALUE
 138 <a name="RETURN VALUE"></a>
 139 </h2>
 140
 141
 142 <p style="margin-left:11%; margin-top: 1em">If a
 143 translation was found in one of the specified catalogs, it
 144 is converted to the locale&rsquo;s codeset and returned. The
 145 resulting string is statically allocated and must not be
 146 modified or freed. Otherwise <i>msgid</i> is returned.</p>
 147
 148 <h2>ERRORS
 149 <a name="ERRORS"></a>
 150 </h2>
 151
 152
 153 <p style="margin-left:11%; margin-top: 1em"><b>errno</b> is
 154 not modified.</p>
 155
 156 <h2>BUGS
 157 <a name="BUGS"></a>
 158 </h2>
 159
 160
 161 <p style="margin-left:11%; margin-top: 1em">The return type
 162 ought to be <b>const char *</b>, but is <b>char *</b> to
 163 avoid warnings in C code predating ANSI C.</p>
 164
 165 <p style="margin-left:11%; margin-top: 1em">When an empty
 166 string is used for <i>msgid</i>, the functions may return a
 167 nonempty string.</p>
 168
 169 <h2>SEE ALSO
 170 <a name="SEE ALSO"></a>
 171 </h2>
 172
 173
 174
 175 <p style="margin-left:11%; margin-top: 1em"><b>ngettext</b>(3),
 176 <b>dngettext</b>(3), <b>dcngettext</b>(3),
 177 <b>setlocale</b>(3), <b>textdomain</b>(3),
 178 <b>bindtextdomain</b>(3), <b>bind_textdomain_codeset</b>(3),
 179 <b>msgfmt</b>(1)</p>
 180 <hr>
 181 </body>
 182 </html>