Adrien Leravat

Qt Internationalization – Create Your UI Using Non-Latin Characters

Published Friday February 23rd, 2018
8 Comments on Qt Internationalization – Create Your UI Using Non-Latin Characters
Posted in Contributors, Dev Loop, Guest Blog, Internationalization

People, ideas and data are moving all around the world nowadays, and so are your applications! Developing a UI in one language only, regardless of the platform is not an option anymore. Now if you are lucky enough to be using Qt, this is achievable with little effort, even when dealing with non-latin characters and “right to left” languages.

This tutorial will guide you towards this goal with your Qt Quick application and will hopefully give you some, useful tips!

Phase 1: Translation Files and Iupdate

1.1 Generate Your Translation File in Qt

The first thing to do is to translate your application. It means you have to take all the static strings in your application and replace them with the translated version at the right time.

In Qt, this is first done by declaring translations files and using translation methods (tr, qsTr, QT_TR_NOOP). Your application will require exactly one translation file per supported language.

This is how you have to modify your project file and QML files to enable extraction the strings to translate:

    translations/en-US.ts \
    translations/zh-CN.ts \
    translations/ar-MA.ts \

lupdate_only {
    SOURCES += \

Windows {
    width: 800; height: 480
    title: qsTr ("My Application Title")

If you are wondering about the “en-US” notation, it corresponds to IETF language tags ( It is the juxtaposition of the language and country code and is often used to identify languages and locale.

Also, note we used ‘lupdate_only’ conditional in order to add our QML files to SOURCES only for the lupdate step. The SOURCES variables are used to compile your .cpp files, but they also happen to be used by lupdate to extract the translations.

At this point you can manually generate the translation files in QtCreator using “Tools > External > Linguist > Update translations (linguist)”. This will regenerate .ts files after parsing all files from the SOURCE variable of your project. You will end up with three .ts files (XML format) in your project, containing your new untranslated string “My Application Title”, its context (i.e. file) and its line number.

1.2 Now Apply Your Translation

You can then apply a translation.

Instantiate a QTranslator class, and use the QCoreApplication::installTranslator() method.

QTranslator *arabicTranslator = new QTranslator (":/translation/ar-MA.ts");
qApp ->installTranslator (arabicTranslator);

More than one translator can be installed at the same time. Qt will translate your strings using the last applied translator, and sequentially the next ones until it succeeds… or not. If not your original string will be displayed as it is written in your code.

Window {
    width: 800; height: 480
    title: qsTr ("My Application Title")

Phase 2: Translation at Runtime

Another common request is to dynamically retranslate the user interface. Changing the translator at runtime is quite simple, but updating the strings to reflect that modification may be a bit more challenging.

Fortunately, Qt provides QEvent::LanguageChange event for that purpose.

It is generated when you apply a new translator. This is what you will use for Widget based applications, along with the retranslateUi method for Designer generated UIs.

However, this is not very convenient and I found there is another simple solution.

  • Expose an empty QString property, trTrigger in our case
  • Bind your texts with this property like ‘text:qsTr(“My text”) + app.trTrigger
  • Emit trTrigger “changed”signal every time the language changes

You will get the full expression being re-evaluated (hence retranslated) while keeping the text unaffected.

Window {
     width: 800; height: 480
     title: qsTr ("My Application Title") + app.trTrigger

Phase 3: Supporting Chinese, Arabic, and Others

This is where font and text encoding become important. You may already have stumbled upon related issues when copy-pasting special characters from another document, only to discover they were replaced by unreadable ones. The two usual suspects are the Font and the Encoding of your document.

  • An incorrect encoding won’t be able to store or translate the characters correctly
  • An incorrect font won’t be able to render the characters

For example, Ask Comic sans MS to tell you “你好!”, and it will just fail. If this happens (and it probably will), it simply means your system or software uses a different or fallback font. This fallback font is used to render Chinese, despite the fact the original font does not support Chinese characters. And this is exactly what Qt will do when possible, saving you some work!

That’s why for the best visual outcome you will need to include fonts that are compatible with the language you want to support. If you then package these fontswith your application, you can easily install them dynamically using the QFontDatabase, or FontLoader on QML side.

On Linux platform, just make sure you have a fontloader library installed and available otherwise it won’t work. The encoding is less explicit than the font. It applies to files and variables storing your text. As long as you stick with QString for display and Qt translation mechanism you should be fine. But when you manipulate non-ascii characters you will have to take a few precautions:

  1. In files, make sure that encoding supports the characters you use (UTF-8 is a good default choice)
  2. In variables, make sure that it supports such characters (e.g. std::wstring vs std::string).

As for classic Qt translation, you will have to provide the corresponding .ts file to the person in charge of translations (e.g. “translations/zh-CN.ts”), as well as the linguist application from your Qt folder (e.g. “C:\Qt\5.8\mingw53_32\bin”).

Yes, I used a Windows path as an example, because I doubt that people working on your translations will be able to run linguist from your custom Linux distribution Linguist is a standalone application, so translators won’t need to install Qt, don’t worry.

This standalone application allows loading and saving .ts files, once the translations are done.

Witekio Qt Linguist Chinese

Now ask your translator to send you the .ts file modified: you’re done!

Phase 4: Don’t Forget that Right to Left Is Not Only a Text Thing

User interface composing is where the biggest difference compared to Left-to-Right languages lies.

In Arabic and Hebrew, you read and write from the right side to the left, and this has a significant impact not only on the text but on your whole application including:

  • Text alignment (right aligned by default!)
  • Menus and components position
  • Writing direction
  • Lists direction

In a way, this is like flipping your entire UI layout horizontally. Qt will locally help you change text alignment based on the character set used, but you will have to anticipate and implement the global strategy.

At the application level, you have the “setLayoutDirection” method. It is typically set from the application language, but you can also do it manually with:

qApp->setLayoutDirection (Qt::RightToLeft);

Qt Quick application then provides different ways to deal with layout direction. QML Layouts have the layoutDirection property, Images have the mirror, and all Items have the very powerful LayoutMirroring attached property.

”LayoutMirroring” is a fast way to change the direction of layouts, positioners (Row, Grid, …), anchors and text alignments, of the item and its children with only two lines:

Page {
     LayoutMirroring.enabled: (Qt.application.layoutDirection === Qt.RightToLeft)
     LayoutMirroring.childrenInherit: true
     Row {
         // Row will use right-to-left order when LayoutMirror.enabled = true
         Text {
              id: songNumber
              text: "1."
              horizontalAlignment: Text.AlignLeft // Alignment will adjust too. But don't fail to mention it         
                                                  // or the text won't change its alignment
         Text {
              id: artistItem
              text: "Some Artist"
              horizontalAlignment: Text.AlignLeft
              // Manually change elide side
              elide: (Qt.application.layoutDirection === Qt.LeftToRight) ? 
Text.ElideRight : Text.ElideLeft

LayoutMirroring.childrenInherit will apply the mirroring to all the children, making it a very efficient way to apply it. However be careful as it will very likely break some parts of your UI if you have not built it from the beginning with “Right-to-Left” and “Left-to-Right” in mind.

The example below shows the difference between standard English version and Arabic right-to-left version. Note that not only the text alignment is changed, but also the layout and the “+” and “-” buttons. This may look odd to some of you, but remember that right-to-left languages are not only about the text, but also the way eyes scan the content of the application.

Witekio | qt-application-english et qt-application-arabic-rtl


How Can You Make Chinese, Arabic, and Left-To-Right Integration as Easy as Possible? Wrap Up!

  • Use Qt Linguist and QTranslators for translations
  • Pack the fonts you want to use in your application for Chinese, Arabic, etc and install them with QFontDatabase or Fontloader
  • Do not use absolute positioning (the default “x:O” does count as such!)
  • Do use Layouts and positioners
  • Do use anchors and anchors margins
  • Do set Text.horizontal Alignment property

Qt provides you with a good start for integrating a lot of languages. With a bit of work and anticipation, your application will be understood all over the world. The key to an efficient integration of Right to Left languages is simply to plan and test it early during application development, to ensure it is fully compatible.

On embedded devices, don’t forget that Chinese, Russian and Arabic, only to name a few, need more than a simple keyboard layout, but also a way to “compose” different words based on what was typed. This is critical if you created your own virtual keyboard.

People will not be able to write in these languages simply with a different keyboard layout. Hopefully, the Qt Virtual Keyboard (Commercial or LGPLv3 license) does provide such specific input method, if you are not willing to redevelop it for yourself.

Another way is to use a carefully selected iconography. Symbols may not have exactly the same meaning in all countries, but if carefully picked up, they can help you keep your UI simple and clear.

And guess what? Resources (like images), paths and names can be translated too!

website:  –  blog:

Do you like this? Share it
Share on LinkedInGoogle+Share on FacebookTweet about this on Twitter

Posted in Contributors, Dev Loop, Guest Blog, Internationalization


Pavel H says:

Qt 5.10 added support for retranslation in QML module. Method QQmlEngine::retranslate(). I didn’t use it by myself yet, but maybe you could also mention it in “Phase 2: Translation at Runtime” to avoid people will automatically follow that wayaround with dummy string property binding.

Adrien Leravat says:

Thank you for the remark, you are right! This is a nice addition since the time I wrote this article, and we should mention it.

Jason says:

“Note: Due to a limitation in the implementation, this function refreshes all the engine’s bindings, not only those that use strings marked for translation. This may be optimized in a future release.”

What does that exactly mean? Are function bindings re-evaluated too? That could cause unwanted side-effects, including UI lag/flicker. It’d be interesting to see how bad it is.

jason says:

I have used this approach to publish mobile apps in 14+ languages, including non-Latin languages like various Indian languages, Chinese and Arabic. I cannot stress enough getting a good professional translation service. Our “Oh, I know X language” translated the word for “exit” to “door to the morgue”. By the way, Chinese looks awesome, and is a great way to test your layouts.

Which brings me to my next comment. I found QtLinguist in need of rework, and translater user unfriendly.. Perhaps re-work is needed for 5.12? There is a non-qt standard that is widely supported by other platforms called “Gettext” it uses a PO file format. It should be supported in Qt, particularly if QtLinguist is to remain unfriendly. Contract Translaters do not want to need training on QtLinguist, they don’t want to install QtLinguist. I can see QtLinguist making sense from a developer MVP point of view. Also to handle the file exchange, we also just ended up buying a web service, which kinda exported to Qt’s ts, but there ARE ISSUES WITH THE TS SCHEMA.

In the end, handling just 1 app with 14 languages is like hearing cats, and Qt has a long way to go. I spent a lot of time writing code to merge translations (which you will have to do, and it’s not built in). The translation work is very asynchronous and the tools not a good fit.
Basically the laundry list is:
1a. Support a “what’s needed view”. We are charged by the translation, and it’s not clear when we hand a file over for translation if the old translations should be re-examined. Yes, there is the check mark, but there really needs to be a filter to just see what’s needed. Corrections are rare.
1b. The checkmark is not dynamic – if I change the source text, it should cascade through all the other languages as needing re-examination in case the meaning has changed.
2. Have some web service to expose to users so that we don’t have to email files. The file management becomes a problem and translators are not users of git. Have the users only see the languages they are assigned
3. Have a global translation database within the web service that can populate a new application’s translations from you existing set. I don’t want to pay a translator again for a translation we already have, and I shouldn’t have to muck about in XML files to transfer that intellectual property.
4. Integrate into google translate for first-pass translations.
5. Be able to tell me what translations are missing before I ship.
6. Make the lupdate step more invisible. Really, I should never need to run it.

Anyone shipping 14 languages in an app will find their days consumed by translation work (not even doing the translations!) But QtLingust is better than a Word document.

Prav says:

>images can be translated too!
Can you be more specific about what you mean by that?

Ralph says:

I assume he meant you could use
QIcon icon(tr(“:/en/iconfilename.png”)) ;

in the source code for the default language (assuming english here)
and for the translation for e.g. german translate to

and for e.g. french translate to

Dominik says:

For example you can have an image path: “:/flags/” + qsTrId(“country-code”) + “.png” – you can translate the “country-code” and the image path will be loaded based on the translation.

Nejatafshar says:

Thanks for the useful hints. It’ s also good to mention that if you add your qml files to resource, they would be parsed by lupdate and there is no need to use lupdate_only in pro file.

Commenting closed.

Get started today with Qt Download now