Fixing a common antipattern when loading translations in Qt

09.07.2020 Miłosz Kosobucki 8 comments

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. 🙂