sam-t2/devtools/amd64/html/python/lib/node327.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="node328.html" />
<link rel="prev" href="module-gettext.html" />
<link rel="parent" href="module-gettext.html" />
<link rel="next" href="node328.html" />
<meta name='aesop' content='information' />
<title>6.28.1 GNU gettext API</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="6.28 gettext  "
  href="module-gettext.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="6.28 gettext  "
  href="module-gettext.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="6.28.2 Class-based API"
  href="node328.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-gettext.html">6.28 gettext  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-gettext.html">6.28 gettext  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node328.html">6.28.2 Class-based API</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION0082810000000000000000">
6.28.1 GNU <b class="program">gettext</b> API</A>
</H2>

<P>
The <tt class="module">gettext</tt> module defines the following API, which is very
similar to the GNU <b class="program">gettext</b> API.  If you use this API you
will affect the translation of your entire application globally.  Often
this is what you want if your application is monolingual, with the choice
of language dependent on the locale of your user.  If you are
localizing a Python module, or if your application needs to switch
languages on the fly, you probably want to use the class-based API
instead.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2412' xml:id='l2h-2412' class="function">bindtextdomain</tt></b>(</nobr></td>
  <td><var>domain</var><big>[</big><var>, localedir</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Bind the <var>domain</var> to the locale directory
<var>localedir</var>.  More concretely, <tt class="module">gettext</tt> will look for
binary <span class="file">.mo</span> files for the given domain using the path (on <span class="Unix">Unix</span>):
<span class="file"><var>localedir</var>/<var>language</var>/LC_MESSAGES/<var>domain</var>.mo</span>,
where <var>languages</var> is searched for in the environment variables
<a class="envvar" id='l2h-2423' xml:id='l2h-2423'>LANGUAGE</a>, <a class="envvar" id='l2h-2424' xml:id='l2h-2424'>LC_ALL</a>, <a class="envvar" id='l2h-2425' xml:id='l2h-2425'>LC_MESSAGES</a>, and
<a class="envvar" id='l2h-2426' xml:id='l2h-2426'>LANG</a> respectively.

<P>
If <var>localedir</var> is omitted or <code>None</code>, then the current binding
for <var>domain</var> is returned.<A NAME="tex2html42"
  HREF="#foot36716"><SUP>6.2</SUP></A></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2413' xml:id='l2h-2413' class="function">bind_textdomain_codeset</tt></b>(</nobr></td>
  <td><var>domain</var><big>[</big><var>, codeset</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Bind the <var>domain</var> to <var>codeset</var>, changing the encoding of
strings returned by the <tt class="function">gettext()</tt> family of functions.
If <var>codeset</var> is omitted, then the current binding is returned.

<P>

<span class="versionnote">New in version 2.4.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2414' xml:id='l2h-2414' class="function">textdomain</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>domain</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Change or query the current global domain.  If <var>domain</var> is
<code>None</code>, then the current global domain is returned, otherwise the
global domain is set to <var>domain</var>, which is returned.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2415' xml:id='l2h-2415' class="function">gettext</tt></b>(</nobr></td>
  <td><var>message</var>)</td></tr></table></dt>
<dd>
Return the localized translation of <var>message</var>, based on the
current global domain, language, and locale directory.  This function
is usually aliased as <tt class="function">_</tt> in the local namespace (see
examples below).
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2416' xml:id='l2h-2416' class="function">lgettext</tt></b>(</nobr></td>
  <td><var>message</var>)</td></tr></table></dt>
<dd>
Equivalent to <tt class="function">gettext()</tt>, but the translation is returned
in the preferred system encoding, if no other encoding was explicitly
set with <tt class="function">bind_textdomain_codeset()</tt>.

<P>

<span class="versionnote">New in version 2.4.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2417' xml:id='l2h-2417' class="function">dgettext</tt></b>(</nobr></td>
  <td><var>domain, message</var>)</td></tr></table></dt>
<dd>
Like <tt class="function">gettext()</tt>, but look the message up in the specified
<var>domain</var>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2418' xml:id='l2h-2418' class="function">ldgettext</tt></b>(</nobr></td>
  <td><var>domain, message</var>)</td></tr></table></dt>
<dd>
Equivalent to <tt class="function">dgettext()</tt>, but the translation is returned
in the preferred system encoding, if no other encoding was explicitly
set with <tt class="function">bind_textdomain_codeset()</tt>.

<P>

<span class="versionnote">New in version 2.4.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2419' xml:id='l2h-2419' class="function">ngettext</tt></b>(</nobr></td>
  <td><var>singular, plural, n</var>)</td></tr></table></dt>
<dd>

<P>
Like <tt class="function">gettext()</tt>, but consider plural forms. If a translation
is found, apply the plural formula to <var>n</var>, and return the
resulting message (some languages have more than two plural forms).
If no translation is found, return <var>singular</var> if <var>n</var> is 1;
return <var>plural</var> otherwise.

<P>
The Plural formula is taken from the catalog header. It is a C or
Python expression that has a free variable n; the expression evaluates
to the index of the plural in the catalog. See the GNU gettext
documentation for the precise syntax to be used in .po files, and the
formulas for a variety of languages.

<P>

<span class="versionnote">New in version 2.3.</span>

<P>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2420' xml:id='l2h-2420' class="function">lngettext</tt></b>(</nobr></td>
  <td><var>singular, plural, n</var>)</td></tr></table></dt>
<dd>
Equivalent to <tt class="function">ngettext()</tt>, but the translation is returned
in the preferred system encoding, if no other encoding was explicitly
set with <tt class="function">bind_textdomain_codeset()</tt>.

<P>

<span class="versionnote">New in version 2.4.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2421' xml:id='l2h-2421' class="function">dngettext</tt></b>(</nobr></td>
  <td><var>domain, singular, plural, n</var>)</td></tr></table></dt>
<dd>
Like <tt class="function">ngettext()</tt>, but look the message up in the specified
<var>domain</var>.

<P>

<span class="versionnote">New in version 2.3.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2422' xml:id='l2h-2422' class="function">ldngettext</tt></b>(</nobr></td>
  <td><var>domain, singular, plural, n</var>)</td></tr></table></dt>
<dd>
Equivalent to <tt class="function">dngettext()</tt>, but the translation is returned
in the preferred system encoding, if no other encoding was explicitly
set with <tt class="function">bind_textdomain_codeset()</tt>.

<P>

<span class="versionnote">New in version 2.4.</span>

</dl>

<P>
Note that GNU <b class="program">gettext</b> also defines a <tt class="function">dcgettext()</tt>
method, but this was deemed not useful and so it is currently
unimplemented.

<P>
Here's an example of typical usage for this API:

<P>
<div class="verbatim"><pre>
import gettext
gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
gettext.textdomain('myapplication')
_ = gettext.gettext
# ...
print _('This is a translatable string.')
</pre></div>

<P>
<BR><HR><H4>Footnotes</H4>
<DL>
<DT><A NAME="foot36716">... returned.</A><A
 HREF="node327.html#tex2html42"><SUP>6.2</SUP></A></DT>
<DD>
        The default locale directory is system dependent; for example,
        on RedHat Linux it is <span class="file">/usr/share/locale</span>, but on Solaris
        it is <span class="file">/usr/lib/locale</span>.  The <tt class="module">gettext</tt> module
        does not try to support these system dependent defaults;
        instead its default is <span class="file"><code>sys.prefix</code>/share/locale</span>.
        For this reason, it is always best to call
        <tt class="function">bindtextdomain()</tt> with an explicit absolute path at
        the start of your application.

</DD>
</DL>
<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="6.28 gettext  "
  href="module-gettext.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="6.28 gettext  "
  href="module-gettext.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="6.28.2 Class-based API"
  href="node328.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-gettext.html">6.28 gettext  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-gettext.html">6.28 gettext  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node328.html">6.28.2 Class-based API</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>