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%"> 26gettext, 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 <libintl.h> 35 36char * gettext (const char *</b> <i>msgid</i><b>); 37char * dgettext (const char *</b> <i>domainname</i><b>, const char *</b> <i>msgid</i><b>); 38char * 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%"> 48The <b>gettext</b>, <b>dgettext</b> and <b>dcgettext</b> 49functions attempt to translate a text string into the user's 50native language, by looking up the translation in a message 51catalog.</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%"> 57The <i>msgid</i> argument identifies the message to be 58translated. By convention, it is the English version of the 59message, with non-ASCII characters replaced by ASCII 60approximations. This choice allows the translators to work 61with message catalogs, called PO files, that contain both 62the English and the translated versions of each message, and 63can be installed using the <b>msgfmt</b> 64utility.</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%"> 70A message domain is a set of translatable <i>msgid</i> 71messages. Usually, every software package has its own 72message domain. The domain name is used to determine the 73message catalog where the translation is looked up; it must 74be a non-empty string. For the <b>gettext</b> function, it 75is specified through a preceding <b>textdomain</b> call. For 76the <b>dgettext</b> and <b>dcgettext</b> functions, it is 77passed as the <i>domainname</i> argument; if this argument 78is 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%"> 85Translation lookup operates in the context of the current 86locale. For the <b>gettext</b> and <b>dgettext</b> 87functions, the <b>LC_MESSAGES</b> locale facet is used. It 88is determined by a preceding call to the <b>setlocale</b> 89function. <b>setlocale(LC_ALL,"")</b> initializes 90the <b>LC_MESSAGES</b> locale based on the first nonempty 91value of the three environment variables <b>LC_ALL</b>, 92<b>LC_MESSAGES</b>, <b>LANG</b>; see <b>setlocale</b>(3). 93For the <b>dcgettext</b> function, the locale facet is 94determined by the <i>category</i> argument, which should be 95one of the <b>LC_xxx</b> constants defined in the 96<locale.h> header, excluding <b>LC_ALL</b>. In both 97cases, the functions also use the <b>LC_CTYPE</b> locale 98facet in order to convert the translated message from the 99translator's codeset to the current locale's codeset, unless 100overridden 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%"> 107The message catalog used by the functions is at the pathname 108<i>dirname</i>/<i>locale</i>/<i>category</i>/<i>domainname</i>.mo. 109Here <i>dirname</i> is the directory specified through 110<b>bindtextdomain</b>. Its default is system and 111configuration dependent; typically it is 112<i>prefix</i>/share/locale, where <i>prefix</i> is the 113installation prefix of the package. <i>locale</i> is the 114name of the current locale facet; the GNU implementation 115also tries generalizations, such as the language name 116without 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%"> 125If the <b>LANGUAGE</b> environment variable is set to a 126nonempty value, and the locale is not the "C" 127locale, the value of <b>LANGUAGE</b> is assumed to contain a 128colon separated list of locale names. The functions will 129attempt to look up a translation of <i>msgid</i> in each of 130the 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%"> 136In the "C" locale, or if none of the used catalogs 137contain 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%"> 147If a translation was found in one of the specified catalogs, 148it is converted to the locale's codeset and returned. The 149resulting string is statically allocated and must not be 150modified or freed. Otherwise <i>msgid</i> is 151returned.</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%"> 167The return type ought to be <b>const char *</b>, but is 168<b>char *</b> to avoid warnings in C code predating ANSI 169C.</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%"> 175When an empty string is used for <i>msgid</i>, the functions 176may 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> 192