Internationalisation of PyQt5 Applications
==========================================
PyQt5 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.
The process of internationalising an application comprises the following
steps.
- The programmer uses :program:`pylupdate5` to create or update a ``.ts``
translation file for each language that the application is to be translated
into. A ``.ts`` file is an XML file that contains the strings to be
translated and the corresponding translations that have already been made.
:program:`pylupdate5` can be run any number of times during development to
update the ``.ts`` files with the latest strings for translation.
- The translator uses Qt Linguist to update the ``.ts`` files with translations
of the strings.
- The release manager then uses Qt's :program:`lrelease` utility to convert the
``.ts`` files to ``.qm`` files which are compact binary equivalents used by
the application. If an application cannot find an appropriate ``.qm`` file,
or a particular string hasn't been translated, then the strings used in the
original source code are used instead.
- The release manage may optionally use :program:`pyrcc5` to embed the ``.qm``
files, along with other application resources such as icons, in a Python
module. This may make packaging and distribution of the application easier.
:program:`pylupdate5`
---------------------
.. program:: pylupdate5
:program:`pylupdate5` is PyQt5's equivalent to Qt's :program:`lupdate` utility
and is used in exactly the same way. A Qt ``.pro`` 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 ``.pro`` file also
specifies the ``.ts`` translation files that :program:`pylupdate5` updates (or
creates if necessary) and are subsequently used by Qt Linguist.
Differences Between PyQt5 and Qt
--------------------------------
Qt implements internationalisation support through the
:class:`~PyQt5.QtCore.QTranslator` class, and the
:meth:`~PyQt5.QtCore.QCoreApplication.translate` and
:meth:`~PyQt5.QtCore.QObject.tr` methods. Usually
:meth:`~PyQt5.QtCore.QObject.tr` 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. In Qt :meth:`~PyQt5.QtCore.QObject.tr`
is actually generated by ``moc`` and uses the hardcoded class name as the
context. On the other hand, :meth:`~PyQt5.QtCore.QApplication.translate`
allows the context to be specified explicitly.
Unfortunately, because of the way Qt implements
:meth:`~PyQt5.QtCore.QObject.tr` it is not possible for PyQt5 to exactly
reproduce its behaviour. The PyQt5 implementation of
:meth:`~PyQt5.QtCore.QObject.tr` 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 PyQt5, but is hardcoded in Qt. In other
words, the context of a translation may change depending on an instance's class
hierarchy. For example::
class A(QObject):
def hello(self):
return self.tr("Hello")
class B(A):
pass
a = A()
a.hello()
b = B()
b.hello()
In the above the message is translated by ``a.hello()`` using a context of
``A``, and by ``b.hello()`` using a context of ``B``. In the equivalent C++
version the context would be ``A`` in both cases.
The PyQt5 behaviour is unsatisfactory and may be changed in the future. It is
recommended that :meth:`~PyQt5.QtCore.QCoreApplication.translate` be used in
preference to :meth:`~PyQt5.QtCore.QObject.tr`. This is guaranteed to work
with current and future versions of PyQt5 and makes it much easier to share
message files between Python and C++ code. Below is the alternative
implementation of ``A`` that uses
:meth:`~PyQt5.QtCore.QCoreApplication.translate`::
class A(QObject):
def hello(self):
return QCoreApplication.translate('A', "Hello")
