Soluling home   Document home

Qt Localization and Internationalization

Qt Localization and Internationalization

Qt (Wikipedia) is a popular cross-platform application framework that is used to develop desktop applications (e.g., Windows, Mac, Linux), embedded software (e.g. automobile and machine industry), and mobile applications (e.g., Sailfish). Qt has two frameworks. The traditional framework uses the widget-based API. The new framework is called Qt Quick, and it uses declarative language, QML. Both technologies use Qt Linguist files, .ts, to store localized strings. Use Soluling localization tool or service to create localized .ts files.

Qt's online documentation contains several useful topics. Read them first.

If you want to implement a runtime language switch, read this.

Process

Create a new Qt Widgets application that uses QDialog as a base class. Name the project Tutorial.

Create a dialog based Qt project

Complete New Project wizard. Then add two labels on the dialog. Set the first text to "Hello world" and the second text to "dummy." The first label is static, and the value is defined on design time. However, the second one is dynamic, and we will set the value on run time. This is why we set the value to "dummy." You can also set the value to empty, but having a value makes it easier to see in the designer.

A minimal Qt dialog

Because we don't want to extract the value of dummy, we need to turn the translatable property to false. Select the second label, expand text property, and uncheck translatable.

Select property to be translatable

This will prevent "dummy" to appear in the translation file. Now we can enable creating the .ts file. Add the following line to Tutorial.pro

TRANSLATIONS = strings.ts

This will tell Qt that we want to have all the strings (from .ui and .cpp) of the application stored into strings.ts file. To scan the source code and to create the ts file, we need to call lupdate.exe from Qt's bin directory.

lupdate Tutorial.pro

This scans the project files and creates strings.ts. The next step is to localize strings.ts. You can do it either in Soluling Cloud or in Soluling Desktop.

Cloud process Cloud

With Soluling Cloud, you localize the Qt translation file in your browser: upload the file, translate it in Translate, and download the localized files. You need a Soluling account. See the available Cloud plans.

Create a project

  1. Sign in at www.soluling.com and open Cloud > Dashboard for Projects, Users and Terminology.
  2. Click Add a new project, then Select files and pick strings.ts, or drag and drop the file onto the page. Click Create.
  3. On the next page, check the project's Name. It defaults to the file's name.
  4. Set the Original language to the language of your application's strings, for example, English.
  5. Under Target languages, check the languages you want to translate to, for example, Finnish, German, and Japanese.
  6. Under Source type, select Qt translation file (.ts). The .ts file extension is also used by TypeScript source code files, so make sure you pick the Qt parser.
  7. Click Create. The project appears on the dashboard, and its status changes to Ready once the file has been processed.

Translate the project

Click the project's green Translate button on the dashboard. Translate opens the project, and you can type the translations into the grid. Machine translation suggestions, translation memory, and spell checking are available there. You do not have to finish every language before moving on to the next step.

Get the localized files

  1. In Translate's top bar, click the project's name. It opens the project's Manage page, the same page that the project's Manage button on the dashboard opens.
  2. If you have translated something since the localized files were last built, the page says Localized files need to be built. Click Build localized files and wait until it finishes.
  3. The Files section lists strings.ts with a download button for each target language. Save the localized .ts files to your Qt project directory, next to strings.ts.

Update the project

When you add or change strings in your application, run lupdate again, upload the new strings.ts, translate what is new or changed, and download the localized files again. On the dashboard, click the project's Update file button (the upload arrow), select the new strings.ts or drop it onto the page, and click Update. Existing translations are kept, so you only translate the strings that were added or changed.

The dashboard is one of four ways to use Soluling Cloud. You can also use the SoluCLI command-line tool, Soluling Desktop, or SoluMake, which can run the update and build steps in your build pipeline. See the Cloud tutorial for all of them.

Desktop process Desktop

Create a Soluling project for the Qt project.

  1. Start Soluling
  2. Drag strings.ts or Tutorial.pro on Soluling or click the New from File or Files button and select either of the files.
  3. If you selected .ts file the following dialog appears.
    Select a Qt source file
    This is because the .ts file extension can either mean Qt translation file or TypeScript source code file. Soluling correctly detects it as a Qt translation file. Click OK.
  4. Project Wizard appears showing first the Options sheet. This lets you select the context method you want to use. Click Next.
  5. Select Languages appears. Select the original languages and the target languages, for example, Finnish.
  6. The new project gets created. Translate the project and finally build the project by choosing Home | Build All ribbon menu.

Use the localized files

Now we have the localized ts files. Let's use them. First add lrelease into CONFIG of Tutorial.pro file.

CONFIG += c++11 lrelease

Then add the following line into Tutorial.pro file

EXTRA_TRANSLATONS strings_fi.ts strings_de.ts strings_ja.ts

You have to add all the .ts files you have. In the above line, we added Finnish, German, and Japanese translation files. These two lines make the build process to compile .ts files to .qm files that are the binary version of .ts files. Qt runtime uses .qm files instead of .ts files.

If you added a .ts file to Soluling instead of a .pro file, when Soluling creates localized .ts file, it by default also compiles them into binary .qm file that you can deploy with your application. Use the Write options sheet to configure how to create the localized .ts files and select if to compile the .qm files. Another way to compile .ts files is to use Qt's lrelease.exe command-line tool.

lrelease strings_fi.ts
Next, modify main.pas to use a .qm file. Your original main.cpp looks like this. 
#include "dialog.h"
#include <QApplication>

int main(int argc, char *argv[])
{
  QApplication a(argc, argv);
  Dialog w;
  w.show();
    
  return a.exec();
}

Change it to

#include "dialog.h"
#include <QApplication>
#include <QLocale>
#include <QTranslator>

int main(int argc, char *argv[])
{
  QApplication a(argc, argv);
    
  QTranslator translator;
  bool ok = translator.load("strings_" + QLocale::system().name());

  if (ok)
    a.installTranslator(&translator);
    
  Dialog w;
  w.show();

  return a.exec();
}

The new code creates a translator, loads a .qm file, and installs the translator. Now when you run the application and if there exists a .qm file matching your system locale, Qt will use translations of from the .qm file.

Our current application uses a standalone .qm file. If you want to add the .qm file inside your application as a resource, you can do that. Add embed_translations into CONFIG.

CONFIG += c++11 lrelease embed_translations

Finally, you need to modify main.pas to use resources translations instead of standalone translation files.

bool ok = translator.load(":/i18n/strings_" + QLocale::system().name());

Context

A ts file contains one or more context elements. Each context element contains one or more message elements that each contain one string. The context element has a name that Soluling uses as a context. However, the message element does not contain any specific ID or name that could be used as a context. This is why Soluling has to figure out the context using other elements and attributes. Let's see what they are. The following sample shows a message element.

<message>
  <location filename="mainwindow.ui" line="14"/>
  <source>Driving Time</source>
  <comment>This is a comment</comment>
  <translation type="unfinished"></translation>
</message>

The comment element is optional, so it exists if you have specified comments in your source code. There are three elements we could use as a context: source, location, and comment. Each method has its pros and cons.

By default, Soluling uses the source element as a context. This means the original value sets a part of the context. The pro is that the value always exists. The cons are that your ts file might have the same source value more than twice. If the duplicate values are in the same context element, there is a conflict. In that case, Soluling adds a comment value (if it exists) or a running index. If you change the original string value, your context will also change, and you will lose the existing translations. It is recommended to use the original value as a context.

Another method to specify the context is to use the comment value. The pro is that you, as a developer, can control the value, and it does not change even if you change the string value. The cons are that the context element is meant for a string describing the string, not giving a context. Also, if two message elements have the same comment value, then they are mapped as one. The source element is used if this method is set and the message element has no comment. Use this method only if you know that comment values contain context data, and every comment in the same context element is unique.

The last method is to use the location element. The pro is that it is automatically provided, and you do not have to perform any extra action to set it. The con is that the value is also very volatile. Any change in your source code will most likely cause a change in location values.

Plurals

Qt has a plural enabled format function: tr. The 3rd parameter of tr is the count parameter that is used to select the right grammatical number. What is missing in Qt's pluralization support is the ability to give a correct grammatical number for the original language. You can only pass one pattern for tr function. However, the localized .ts file will have the correct amount of patterns.

See GitHub or <data-dir>\Samples\Qt\Widget\Plural sample.

Samples

See GitHub and <data-dir>\Samples\Qt contains following Qt samples:

Directory Description Notes
Widget\Simple Simple localized Qt application.
 Try this first!
Widget\Hello Localized Hello World application for Qt  
Widget\Driving Shows how to localize a Qt application.  
Widget\Plural Shows how to create grammatically correct plural enabled messages.  
Widget\Tutorial The above tutorial sample.  

Configuring Qt Localization

You can configure how to localize your Qt application by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.

Soluling logo  Copyright © 2016-2026 Soluling Oy