projects / OpenSPARC-T2-DV / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 design and verification files.
[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / lib / node328.html
CommitLineData
86530b38
AT		 1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<link rel="STYLESHEET" href="lib.css" type='text/css' />
5<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
6<link rel='start' href='../index.html' title='Python Documentation Index' />
7<link rel="first" href="lib.html" title='Python Library Reference' />
8<link rel='contents' href='contents.html' title="Contents" />
9<link rel='index' href='genindex.html' title='Index' />
10<link rel='last' href='about.html' title='About this document...' />
11<link rel='help' href='about.html' title='About this document...' />
12<link rel="next" href="node333.html" />
13<link rel="prev" href="node327.html" />
14<link rel="parent" href="module-gettext.html" />
15<link rel="next" href="node329.html" />
16<meta name='aesop' content='information' />
17<title>6.28.2 Class-based API</title>
18</head>
19<body>
20<DIV CLASS="navigation">
21<div id='top-navigation-panel' xml:id='top-navigation-panel'>
22<table align="center" width="100%" cellpadding="0" cellspacing="2">
23<tr>
24<td class='online-navigation'><a rel="prev" title="6.28.1 GNU gettext API"
25 href="node327.html"><img src='../icons/previous.png'
26 border='0' height='32' alt='Previous Page' width='32' /></A></td>
27<td class='online-navigation'><a rel="parent" title="6.28 gettext "
28 href="module-gettext.html"><img src='../icons/up.png'
29 border='0' height='32' alt='Up One Level' width='32' /></A></td>
30<td class='online-navigation'><a rel="next" title="6.28.2.1 The NullTranslations class"
31 href="node329.html"><img src='../icons/next.png'
32 border='0' height='32' alt='Next Page' width='32' /></A></td>
33<td align="center" width="100%">Python Library Reference</td>
34<td class='online-navigation'><a rel="contents" title="Table of Contents"
35 href="contents.html"><img src='../icons/contents.png'
36 border='0' height='32' alt='Contents' width='32' /></A></td>
37<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
38 border='0' height='32' alt='Module Index' width='32' /></a></td>
39<td class='online-navigation'><a rel="index" title="Index"
40 href="genindex.html"><img src='../icons/index.png'
41 border='0' height='32' alt='Index' width='32' /></A></td>
42</tr></table>
43<div class='online-navigation'>
44<b class="navlabel">Previous:</b>
45<a class="sectref" rel="prev" href="node327.html">6.28.1 GNU gettext API</A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="module-gettext.html">6.28 gettext </A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="node329.html">6.28.2.1 The NullTranslations class</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H2><A NAME="SECTION0082820000000000000000">
566.28.2 Class-based API</A>
57</H2>
58
59<P>
60The class-based API of the <tt class="module">gettext</tt> module gives you more
61flexibility and greater convenience than the GNU <b class="program">gettext</b>
62API. It is the recommended way of localizing your Python applications and
63modules. <tt class="module">gettext</tt> defines a ``translations'' class which
64implements the parsing of GNU <span class="file">.mo</span> format files, and has methods
65for returning either standard 8-bit strings or Unicode strings.
66Instances of this ``translations'' class can also install themselves
67in the built-in namespace as the function <tt class="function">_()</tt>.
68
69<P>
70<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
71 <td><nobr><b><tt id='l2h-2427' xml:id='l2h-2427' class="function">find</tt></b>(</nobr></td>
72 <td><var>domain</var><big>[</big><var>, localedir</var><big>[</big><var>,
73 languages</var><big>[</big><var>, all</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
74<dd>
75This function implements the standard <span class="file">.mo</span> file search
76algorithm. It takes a <var>domain</var>, identical to what
77<tt class="function">textdomain()</tt> takes. Optional <var>localedir</var> is as in
78<tt class="function">bindtextdomain()</tt> Optional <var>languages</var> is a list of
79strings, where each string is a language code.
80
81<P>
82If <var>localedir</var> is not given, then the default system locale
83directory is used.<A NAME="tex2html43"
84 HREF="#foot36704"><SUP>6.3</SUP></A> If <var>languages</var> is not given,
85then the following environment variables are searched: <a class="envvar" id='l2h-2430' xml:id='l2h-2430'>LANGUAGE</a>,
86<a class="envvar" id='l2h-2431' xml:id='l2h-2431'>LC_ALL</a>, <a class="envvar" id='l2h-2432' xml:id='l2h-2432'>LC_MESSAGES</a>, and <a class="envvar" id='l2h-2433' xml:id='l2h-2433'>LANG</a>. The first one
87returning a non-empty value is used for the <var>languages</var> variable.
88The environment variables should contain a colon separated list of
89languages, which will be split on the colon to produce the expected
90list of language code strings.
91
92<P>
93<tt class="function">find()</tt> then expands and normalizes the languages, and then
94iterates through them, searching for an existing file built of these
95components:
96
97<P>
98<span class="file"><var>localedir</var>/<var>language</var>/LC_MESSAGES/<var>domain</var>.mo</span>
99
100<P>
101The first such file name that exists is returned by <tt class="function">find()</tt>.
102If no such file is found, then <code>None</code> is returned. If <var>all</var>
103is given, it returns a list of all file names, in the order in which
104they appear in the languages list or the environment variables.
105</dl>
106
107<P>
108<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
109 <td><nobr><b><tt id='l2h-2428' xml:id='l2h-2428' class="function">translation</tt></b>(</nobr></td>
110 <td><var>domain</var><big>[</big><var>, localedir</var><big>[</big><var>,
111 languages</var><big>[</big><var>, class_</var><big>[</big><var>,
112 fallback</var><big>[</big><var>, codeset</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
113<dd>
114Return a <tt class="class">Translations</tt> instance based on the <var>domain</var>,
115<var>localedir</var>, and <var>languages</var>, which are first passed to
116<tt class="function">find()</tt> to get a list of the
117associated <span class="file">.mo</span> file paths. Instances with
118identical <span class="file">.mo</span> file names are cached. The actual class instantiated
119is either <var>class_</var> if provided, otherwise
120<tt class="class">GNUTranslations</tt>. The class's constructor must take a single
121file object argument. If provided, <var>codeset</var> will change the
122charset used to encode translated strings.
123
124<P>
125If multiple files are found, later files are used as fallbacks for
126earlier ones. To allow setting the fallback, <tt class="function">copy.copy</tt>
127is used to clone each translation object from the cache; the actual
128instance data is still shared with the cache.
129
130<P>
131If no <span class="file">.mo</span> file is found, this function raises
132<tt class="exception">IOError</tt> if <var>fallback</var> is false (which is the default),
133and returns a <tt class="class">NullTranslations</tt> instance if <var>fallback</var> is
134true.
135
136<P>
137
138<span class="versionnote">Changed in version 2.4:
139Added the <var>codeset</var> parameter.</span>
140
141</dl>
142
143<P>
144<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
145 <td><nobr><b><tt id='l2h-2429' xml:id='l2h-2429' class="function">install</tt></b>(</nobr></td>
146 <td><var>domain</var><big>[</big><var>, localedir</var><big>[</big><var>, unicode
147 </var><big>[</big><var>, codeset</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
148<dd>
149This installs the function <tt class="function">_</tt> in Python's builtin namespace,
150based on <var>domain</var>, <var>localedir</var>, and <var>codeset</var> which are
151passed to the function <tt class="function">translation()</tt>. The <var>unicode</var>
152flag is passed to the resulting translation object's <tt class="method">install</tt>
153method.
154
155<P>
156As seen below, you usually mark the strings in your application that are
157candidates for translation, by wrapping them in a call to the
158<tt class="function">_()</tt> function, like this:
159
160<P>
161<div class="verbatim"><pre>
162print _('This string will be translated.')
163</pre></div>
164
165<P>
166For convenience, you want the <tt class="function">_()</tt> function to be installed in
167Python's builtin namespace, so it is easily accessible in all modules
168of your application.
169
170<P>
171
172<span class="versionnote">Changed in version 2.4:
173Added the <var>codeset</var> parameter.</span>
174
175</dl>
176
177<P>
178<BR><HR><H4>Footnotes</H4>
179<DL>
180<DT><A NAME="foot36704">... used.</A><A
181 HREF="node328.html#tex2html43"><SUP>6.3</SUP></A></DT>
182<DD>See the footnote for
183<tt class="function">bindtextdomain()</tt> above.
184
185</DD>
186</DL>
187<p><br /></p><hr class='online-navigation' />
188<div class='online-navigation'>
189<!--Table of Child-Links-->
190<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
191
192<UL CLASS="ChildLinks">
193<LI><A href="node329.html">6.28.2.1 The <tt class="class">NullTranslations</tt> class</a>
194<LI><A href="node330.html">6.28.2.2 The <tt class="class">GNUTranslations</tt> class</a>
195<LI><A href="node331.html">6.28.2.3 Solaris message catalog support</a>
196<LI><A href="node332.html">6.28.2.4 The Catalog constructor</a>
197</ul>
198<!--End of Table of Child-Links-->
199</div>
200
201<DIV CLASS="navigation">
202<div class='online-navigation'>
203<p></p><hr />
204<table align="center" width="100%" cellpadding="0" cellspacing="2">
205<tr>
206<td class='online-navigation'><a rel="prev" title="6.28.1 GNU gettext API"
207 href="node327.html"><img src='../icons/previous.png'
208 border='0' height='32' alt='Previous Page' width='32' /></A></td>
209<td class='online-navigation'><a rel="parent" title="6.28 gettext "
210 href="module-gettext.html"><img src='../icons/up.png'
211 border='0' height='32' alt='Up One Level' width='32' /></A></td>
212<td class='online-navigation'><a rel="next" title="6.28.2.1 The NullTranslations class"
213 href="node329.html"><img src='../icons/next.png'
214 border='0' height='32' alt='Next Page' width='32' /></A></td>
215<td align="center" width="100%">Python Library Reference</td>
216<td class='online-navigation'><a rel="contents" title="Table of Contents"
217 href="contents.html"><img src='../icons/contents.png'
218 border='0' height='32' alt='Contents' width='32' /></A></td>
219<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
220 border='0' height='32' alt='Module Index' width='32' /></a></td>
221<td class='online-navigation'><a rel="index" title="Index"
222 href="genindex.html"><img src='../icons/index.png'
223 border='0' height='32' alt='Index' width='32' /></A></td>
224</tr></table>
225<div class='online-navigation'>
226<b class="navlabel">Previous:</b>
227<a class="sectref" rel="prev" href="node327.html">6.28.1 GNU gettext API</A>
228<b class="navlabel">Up:</b>
229<a class="sectref" rel="parent" href="module-gettext.html">6.28 gettext </A>
230<b class="navlabel">Next:</b>
231<a class="sectref" rel="next" href="node329.html">6.28.2.1 The NullTranslations class</A>
232</div>
233</div>
234<hr />
235<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
236</DIV>
237<!--End of Navigation Panel-->
238<ADDRESS>
239See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
240</ADDRESS>
241</BODY>
242</HTML>
Full OpenSPARC design & verification tarball including full HDL.