Skip to content

Fixing a common antipattern when loading translations in Qt

TL;DR: If you choose a default translation in your Qt application based on a locale name like this:

QTranslator myappTranslator;
myappTranslator.load("myapp_" + QLocale::system().name());

then please change it to:

QTranslator myappTranslator;
myappTranslator.load(QLocale(), "myapp", "_");

Some of your users (me!) will be thankful that your application appears in the same language as the rest of their system.

Background

I’m a Polish guy working with computers, mostly on Windows. However, the lingua franca of the IT industry is English, so every time I see a tutorial for some dev tool, it’s in that language. To lessen the burden of decoding which menu entry in the tutorial corresponds to which menu entry on my PC I decided to run the system with an English display language. I still want the rest of the i18n-related stuff (date format, keyboard, currency etc.) to be in Polish however.

That’s why my system has Polish locale and English display language. This leads to a problem:

As you can see, Thunderbird and Windows Settings show up in English but Qt Linguist is encrypted with some overengineered Slavic cipher (aka Polish language). What I further noticed, is that this incorrect language selection is particularly prevalent in Qt-based applications. Subsequent digging revealed that this antipattern is widespread in Qt world, see the relevant GitHub search (requires login).

The Root Cause

My investigation made me think: Why do Qt users keep doing this wrong?

It turns out that it’s what the documentation tells them to do! See, the first time a Qt user wants to do i18n they are led to the Internationalization landing page which contained the following section in the middle:

Which in case of my system is unfortunately incorrect. QLocale::system().name() will return "pl_PL" which is not what I want. You should use the other overload of QTranslator::load() that consults the list of user’s preferred display languages (yes, it’s a list) and chooses the correct one.

To be fair to Qt’s docs, they actually tell you to use it but you need to navigate to the QTranslator docs and scroll to the bottom of the section about the first QTranslator::load() overload:

Not very discoverable

I personally believe that we shouldn’t blame the developers if they use the first thing they see prominently featured on the subsystem landing page. They don’t want to delve into intricacies of Qt’s i18n support, they have other problems to solve with their application (also, developers are lazy, at least, I am).

That’s why it’s so important to make sure that users are taught best practice the first time they are dealing with a concept. Or at least they are explicitly warned that they should do things differently in a real-world code (with examples).

The Fix

The obvious fix is to change the offending line as I show in the beginning of the post. This won’t however prevent new users from making this mistake again. The real fix is thus to fix the Qt documentation. And I did just that:

https://codereview.qt-project.org/c/qt/qtdoc/+/297560

Oh, and I fixed some applications too:

https://codereview.qt-project.org/c/qt/qttools/+/299827

The Call

If you are a maintainer of Qt-based application, please take a look in your codebase and see whether you use this antipattern. If you won’t fix it, and I happen to use your application, be prepared to deal with a change request at some point. 🙂

About KDAB

If you like this article and want to read similar material, consider subscribing via our RSS feed.

Subscribe to KDAB TV for similar informative short video content.

KDAB provides market leading software consulting and development services and training in Qt, C++ and 3D/OpenGL. Contact us.

FacebookTwitterLinkedInEmail

8 thoughts on “Fixing a common antipattern when loading translations in Qt”

  1. Thank you so much! I have the same problem! I live and work in Germany and must use the same date/number format as my colleagues (so that we can share spreadsheets, etc.), but as a native English speaker, I want the GUI to display in English. The application I develop is in English, but some Qt elements such as the FileDialog and the ColorDialog were always appearing in German on my machine! I finally renamed Qt’s german translation files (added a tilde to the extension — a good way to temporarily disable files!) so that they wouldn’t be found. So annoying! Now I finally know where the problem is coming from!

      1. BTW, we just updated to 5.15 (we were using 5.6 before!) and the problem is fixed there, so I no longer have to rename the translation files! Hurrah!

  2. Hi,

    IMHO, there is a huge pitfall because the documentation is wrong regarding the order of locales it loads.
    If you look at https://doc.qt.io/qt-5/qtranslator.html#load-1 the order for (fr-CA, de) is

    1. fr_CA
    2. fr
    3. de

    But in reality and according to the source comments at https://github.com/qt/qtbase/blame/40143c189b7c1bf3c2058b77d00ea5c4e3be8b28/src/corelib/kernel/qtranslator.cpp#L757 the order is:

    1. fr_CA
    2. de
    3. fr

    This was a huge pitfall for me because on a fresh Windows 10 Education installation for Germany, QLocale::system().uiLanguages() returns (“de-DE”, “en-US”). And my application had “App_de.qm” and “App_en_US.qm” files. The English version was loaded _all_ the time!

    Is there anyway to first try to load all German versions and only then use the second UI Language?

    Regards,
    Andre

    1. Hello Andre.

      I believe that what you described is a bug: https://bugreports.qt.io/browse/QTBUG-86179

      This bug seems to be fixed in 6.0.1 and onward.

      Unfortunately, if you’re still on 5.x that’s more involved. Fix for this didn’t land till 5.15.3 which is not yet available as LGPL version.
      Recently, KDE announced that they’re hosting a set of backported patches for the 5.15 series, so you may need to build your own Qt:

      https://dot.kde.org/2021/04/06/announcing-kdes-qt-5-patch-collection

      The patch seems to be there:
      https://invent.kde.org/qt/qt/qtbase/-/commit/e6e23d061cb8ac81007119603f8e7c64fc572e04

Leave a Reply

Your email address will not be published. Required fields are marked *