gnu/dist/gettext/gettext-runtime/man/gettext.3.html

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