Notes on i18n localization of Qt5 using PyQt

These are brief notes about localization of PyQt (or C++) programs using Qt5.  Use with caution, I’m learning too, and this could be wrong.

Localization is also known as:

  • i18n
  • internationalization
  • l10n (common on Qt sites)

The state of Qt translations

Briefly, they are haphazard.  Because of the transition from Qt4 to Qt5, many translations files are waiting to be ‘blessed’ by a third party translator.  You might need to use a mix of files from Qt4 and Qt5.

This page discusses how to contribute translations to Qt.  If you go there, this link takes you to the current translation files and shows you their percentage completion (whether they have been blessed by a person who knows the native language.)  That link also lets you download the current (or future) translation files.

Note that the ‘future’ translation files  (for Qt 5.4 as of the time of this writing) are full of translations, but all are marked ‘unfinished’  (until someone blesses them, sometime during the release of Qt5.4?)

Differences between Qt4 and Qt5 translation files

In Qt4, all translations were in one monolithic file but in Qt5 they are split up into a file per Qt module.  For example, in Qt4 translations were all in qt_xx.ts but in Qt5 translations for QtCore and QtGui are now in qtbase_xx.ts.  This applies both to the templates (.ts) and compiled translations (.qm).

In Qt5, there still exists a translation file having the same name as the Qt4 monolithic file (qt_xx.ts or qt_xx.qm) but it ‘includes’ (in other words references) the split files (e.g. qtbase_xx.ts and qtdeclarative_xx.ts).  In Qt5, that file is called a ‘meta catalog file.’  (Such a .ts file will not open in Linguist; Linguist says it is empty.)

So in your app code, you can still load a translator for the one name.  As discussed here, for C++ it recommends to concatenate .qm files into one file having that same name.

However, for a PyQt app that only uses one module, it might make sense to load a translator with only one file, e.g. qtbase_xx.ts.  But because of the transition from Qt4 to Qt5, a ‘blessed’ qtbase_xx.ts file may not exist.  You might just rename the Qt4 monolithic file qt_xx.ts to qtbase_xx.ts.

It is part of your build process to compile the template files (.ts => .qm) and to concatenate them into one file (or not.)  Your buld process may include a step of downloading the template files (.ts) for Qt library.

In the files at that link for Qt5.3, there are some files such as qt_pt.ts that are the ‘meta catalog file’ but the included split files are not present!  So you must be careful where you get your files: sometimes qt_xx.ts is a Qt4 file of translations, and sometimes it is a Qt5 ‘meta catlog’ that Linguist says is empty.

Understanding the gitorious Qt website

Warning: I don’t really understand it yet.  If you open the qt/qt5 repository, it doesn’t have much in it.  If you read the Qt Wiki about building Qt5 from source, it says you first clone that repository, and then run a script that clones other repositories.  That’s probably the best way to get Qt5 source. (But for example, the web site says the repository will have all branches, but I found that it only has the 5.3 branch (the stable branch), and is missing the ‘dev’ branch described by the Qt Wiki about Qt’s branching model ?)

At the gitorious qt website, if you open the qt/qtranslations repository, it appears to contain Qt4 translations files.  I could be wrong.  As evidence, the files there seem to be missing the ‘QPlatformTheme’ context, which is a Qt5 innovation.

Reiterating, you must be careful where you get your translations files (.ts).

What worked for me

I downloaded qtbase_xx.ts files from this link (an ftp site) under the ‘5.4’ section (which are ‘future’.)  The files seems to be complete in that they have all the user-facing texts from the Qt5 source code.  However, they are all (?) marked unfinished.  As mentioned earlier, they are awaiting the 5.4 release and ‘blessing.’

But I ran an awk script to mark “finished” all translations that have non-empty translated text.  Its not politically correct, since no human has reviewed the status of the translations.  Some of the translated texts may themselves have been generated by a program (by the conversion from Qt4 to Qt5) and might not be correct.  But I found that at least for my app, which uses a minimal but critical subset of the strings, it is better than the alternatives.  The critical set that I need are the strings in the context ‘QPlatformTheme’, which makes standard buttons in dialogs use the platform’s theme.  (This also very much depends on what language you choose, for example German may already be blessed and complete, but Portuguese not.)

The awk script:

# gawk script to mark translations finished in a .ts file

# Usage: gawk -f finish.nawk foo.ts > tmp.ts

# unfinished translations with non-empty text become finished
# Note .+ matches at least one character
/"unfinished">.+<\/translation/ { 
    sub("unfin", "fin")

# print every line (some modified by earlier pattern)
{ print }


Cut and paste can garble a template file!

I found the hard way that you must be careful: you can’t browse to a ‘raw blob’ template file at the gitorious qt website and cut and paste it to your computer.  Somehow it garbles the Unicode encoding.  You are better off downloading the files (say using the link above.)

The relationship between KDE and Qt

KDE (an alternative desktop to Gnome) is alive and well in Europe.  It uses Qt instead of GTK as its windowing framework.

Unfortunately, KDE does their own translations of Qt user-facing strings.  They use their own i18n system, including another format (.po) file.   I don’t think they base their translations on Qt translations, and have little interest in updating the Qt translations.  There doesn’t appear to be much flow of translations from KDE back into Qt.  (Its another case of duplication of effort, and difficulty of coordination?)

Japanese still is not well supported on Ubuntu

I especially had trouble with Japanese language on Ubuntu. For example, in Linguist, many characters in translated texts don’t display properly.  I think it is mostly to do with fonts.  It might depend on many factors, such as whether you have exported LANGUAGE=ja in your shell environment, whether you have used System Settings>Language to set the language, whether you have rebooted, and what fonts you have installed.  I struggled to find a combination that was stable.

Bottom line: use something other than Linux/Ubuntu (a Mac?) to use Linguist to translate Japanese (until the mess is straightened out.)


One thought on “Notes on i18n localization of Qt5 using PyQt

  1. Pingback: Deploying PyQt Python Qt apps cross platform using pyqtdeploy | plashless

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s