mingw/share/doc/gettext/gettext.3.html

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