<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Internationalisation of PyQt4 Applications — PyQt 4.10.3 Reference Guide</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '4.10.3',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="shortcut icon" href="_static/logo_tn.ico"/>
<link rel="top" title="PyQt 4.10.3 Reference Guide" href="index.html" />
<link rel="next" title="DBus Support" href="dbus.html" />
<link rel="prev" title="Using PyQt4 from the Python Shell" href="python_shell.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="dbus.html" title="DBus Support"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="python_shell.html" title="Using PyQt4 from the Python Shell"
accesskey="P">previous</a> |</li>
<li><a href="index.html">PyQt 4.10.3 Reference Guide</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="internationalisation-of-pyqt4-applications">
<h1>Internationalisation of PyQt4 Applications<a class="headerlink" href="#internationalisation-of-pyqt4-applications" title="Permalink to this headline">¶</a></h1>
<p>PyQt4 and Qt include a comprehensive set of tools for translating applications
into local languages. For a full description, see the Qt Linguist Manual in
the Qt documentation.</p>
<p>The process of internationalising an application comprises the following
steps.</p>
<ul class="simple">
<li>The programmer uses <strong class="program">pylupdate4</strong> to create or update a <tt class="docutils literal"><span class="pre">.ts</span></tt>
translation file for each language that the application is to be translated
into. A <tt class="docutils literal"><span class="pre">.ts</span></tt> file is an XML file that contains the strings to be
translated and the corresponding translations that have already been made.
<strong class="program">pylupdate4</strong> can be run any number of times during development to
update the <tt class="docutils literal"><span class="pre">.ts</span></tt> files with the latest strings for translation.</li>
<li>The translator uses Qt Linguist to update the <tt class="docutils literal"><span class="pre">.ts</span></tt> files with translations
of the strings.</li>
<li>The release manager then uses Qt’s <strong class="program">lrelease</strong> utility to convert the
<tt class="docutils literal"><span class="pre">.ts</span></tt> files to <tt class="docutils literal"><span class="pre">.qm</span></tt> files which are compact binary equivalents used by
the application. If an application cannot find an appropriate <tt class="docutils literal"><span class="pre">.qm</span></tt> file,
or a particular string hasn’t been translated, then the strings used in the
original source code are used instead.</li>
<li>The release manage may optionally use <strong class="program">pyrcc4</strong> to embed the <tt class="docutils literal"><span class="pre">.qm</span></tt>
files, along with other application resources such as icons, in a Python
module. This may make packaging and distribution of the application easier.</li>
</ul>
<div class="section" id="pylupdate4">
<h2><strong class="program">pylupdate4</strong><a class="headerlink" href="#pylupdate4" title="Permalink to this headline">¶</a></h2>
<p><strong class="program">pylupdate4</strong> is PyQt4’s equivalent to Qt’s <strong class="program">lupdate</strong> utility
and is used in exactly the same way. A Qt <tt class="docutils literal"><span class="pre">.pro</span></tt> project file is read that
specifies the Python source files and Qt Designer interface files from which
the text that needs to be translated is extracted. The <tt class="docutils literal"><span class="pre">.pro</span></tt> file also
specifies the <tt class="docutils literal"><span class="pre">.ts</span></tt> translation files that <strong class="program">pylupdate4</strong> updates (or
creates if necessary) and are subsequently used by Qt Linguist.</p>
<p><strong class="program">pylupdate4</strong> will only be included if your copy of Qt includes the XML
module.</p>
</div>
<div class="section" id="differences-between-pyqt4-and-qt">
<h2>Differences Between PyQt4 and Qt<a class="headerlink" href="#differences-between-pyqt4-and-qt" title="Permalink to this headline">¶</a></h2>
<p>Qt implements internationalisation support through the <tt class="docutils literal"><span class="pre">QTranslator</span></tt> class,
and the <tt class="docutils literal"><span class="pre">QCoreApplication::translate()</span></tt>, <tt class="docutils literal"><span class="pre">QObject::tr()</span></tt> and
<tt class="docutils literal"><span class="pre">QObject::trUtf8()</span></tt> methods. Usually the <tt class="docutils literal"><span class="pre">tr()</span></tt> method is used to obtain
the correct translation of a message. The translation process uses a message
context to allow the same message to be translated differently. <tt class="docutils literal"><span class="pre">tr()</span></tt> is
actually generated by <tt class="docutils literal"><span class="pre">moc</span></tt> and uses the hardcoded class name as the context.
On the other hand, <tt class="docutils literal"><span class="pre">QApplication::translate()</span></tt> allows the context to be
explicitly stated.</p>
<p>Unfortunately, because of the way Qt implements <tt class="docutils literal"><span class="pre">tr()</span></tt> (and <tt class="docutils literal"><span class="pre">trUtf8()</span></tt>) it
is not possible for PyQt4 to exactly reproduce its behaviour. The PyQt4
implementation of <tt class="docutils literal"><span class="pre">tr()</span></tt> (and <tt class="docutils literal"><span class="pre">trUtf8()</span></tt>) uses the class name of the
instance as the context. The key difference, and the source of potential
problems, is that the context is determined dynamically in PyQt4, but is
hardcoded in Qt. In other words, the context of a translation may change
depending on an instance’s class hierarchy. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">A</span><span class="p">(</span><span class="n">QtCore</span><span class="o">.</span><span class="n">QObject</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">hello</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">tr</span><span class="p">(</span><span class="s">"Hello"</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">B</span><span class="p">(</span><span class="n">A</span><span class="p">):</span>
<span class="k">pass</span>
<span class="n">a</span> <span class="o">=</span> <span class="n">A</span><span class="p">()</span>
<span class="n">a</span><span class="o">.</span><span class="n">hello</span><span class="p">()</span>
<span class="n">b</span> <span class="o">=</span> <span class="n">B</span><span class="p">()</span>
<span class="n">b</span><span class="o">.</span><span class="n">hello</span><span class="p">()</span>
</pre></div>
</div>
<p>In the above the message is translated by <tt class="docutils literal"><span class="pre">a.hello()</span></tt> using a context of
<tt class="docutils literal"><span class="pre">A</span></tt>, and by <tt class="docutils literal"><span class="pre">b.hello()</span></tt> using a context of <tt class="docutils literal"><span class="pre">B</span></tt>. In the equivalent C++
version the context would be <tt class="docutils literal"><span class="pre">A</span></tt> in both cases.</p>
<p>The PyQt4 behaviour is unsatisfactory and may be changed in the future. It is
recommended that <tt class="docutils literal"><span class="pre">QCoreApplication.translate()</span></tt> be used in preference to
<tt class="docutils literal"><span class="pre">tr()</span></tt> (and <tt class="docutils literal"><span class="pre">trUtf8()</span></tt>). This is guaranteed to work with current and
future versions of PyQt4 and makes it much easier to share message files
between Python and C++ code. Below is the alternative implementation of <tt class="docutils literal"><span class="pre">A</span></tt>
that uses <tt class="docutils literal"><span class="pre">QCoreApplication.translate()</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">A</span><span class="p">(</span><span class="n">QtCore</span><span class="o">.</span><span class="n">QObject</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">hello</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">QCoreApplication</span><span class="o">.</span><span class="n">translate</span><span class="p">(</span><span class="s">"A"</span><span class="p">,</span> <span class="s">"Hello"</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html">
<img class="logo" src="_static/logo.png" alt="Logo"/>
</a></p>
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Internationalisation of PyQt4 Applications</a><ul>
<li><a class="reference internal" href="#pylupdate4"><strong class="program">pylupdate4</strong></a></li>
<li><a class="reference internal" href="#differences-between-pyqt4-and-qt">Differences Between PyQt4 and Qt</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="python_shell.html"
title="previous chapter">Using PyQt4 from the Python Shell</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="dbus.html"
title="next chapter">DBus Support</a></p>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="dbus.html" title="DBus Support"
>next</a> |</li>
<li class="right" >
<a href="python_shell.html" title="Using PyQt4 from the Python Shell"
>previous</a> |</li>
<li><a href="index.html">PyQt 4.10.3 Reference Guide</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2013 Riverbank Computing Limited.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
