Internationalisation of PyQt4 Applications — PyQt 4.11.4 Reference Guide

# Internationalisation of PyQt4 Applications

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.

The process of internationalising an application comprises the following steps.

- The programmer uses pylupdate4 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. pylupdate4 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 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 pyrcc4 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.

## pylupdate4

pylupdate4 is PyQt4’s equivalent to Qt’s 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 pylupdate4 updates (or creates if necessary) and are subsequently used by Qt Linguist.

pylupdate4 will only be included if your copy of Qt includes the XML module.

## Differences Between PyQt4 and Qt

Qt implements internationalisation support through the `QTranslator` class, and the `QCoreApplication::translate()`, `QObject::tr()` and `QObject::trUtf8()` methods. Usually the `tr()` 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. `tr()` is actually generated by `moc` and uses the hardcoded class name as the context. On the other hand, `QApplication::translate()` allows the context to be explicitly stated.

Unfortunately, because of the way Qt implements `tr()` (and `trUtf8()`) it is not possible for PyQt4 to exactly reproduce its behaviour. The PyQt4 implementation of `tr()` (and `trUtf8()`) 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:

    class A(QtCore.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 PyQt4 behaviour is unsatisfactory and may be changed in the future. It is recommended that `QCoreApplication.translate()` be used in preference to `tr()` (and `trUtf8()`). 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 `A` that uses `QCoreApplication.translate()`:

    class A(QtCore.QObject):
        def hello(self):
            return QtCore.QCoreApplication.translate("A", "Hello")