Qt

Qt Localization

Localize a Qt application: mark the strings with tr, extract them into a .ts file with lupdate, translate the file in Soluling, and compile the localized files into the .qm files that your application loads.

Qt Widgets and Qt Quick both keep their strings in Qt Linguist .ts files. Soluling reads the file or your .pro project, shows plurals in a pattern editor, checks the placeholders, and writes a localized .ts file for each language. Translate in Soluling Desktop or in a browser with Soluling Cloud. The guide follows the Driving sample, a small driving time window built with Qt Widgets.

Try Soluling

Resources TS strings.ts Soluling Original (English) Translation (Finnish) Driving Time Driving distance: Speed: Calculate Driving time is %1 hours %2 min %n file Ajoaika Ajomatka: Nopeus: Laske Ajoaika on %1 tuntia %2 min %n tiedosto The strings in strings.ts have been translated Localized resources TS strings.ts fi strings_fi.ts de strings_de.ts ja strings_ja.ts Localized .ts files, or Driving.exe with the .qm files embedded Resources TS strings.ts Soluling Original (English) Translation (Finnish) Driving Time Driving distance: Speed: Calculate Driving time is %1 hours %2 min %n file Ajoaika Ajomatka: Nopeus: Laske Ajoaika on %1 tuntia %2 min %n tiedosto The strings in strings.ts have been translated Localized resources TS strings.ts fi strings_fi.ts de strings_de.ts ja strings_ja.ts Localized .ts files, or Driving.exe with the .qm files embedded
You deploy Driving.exe; the .ts files stay in your project. The Driving sample embeds the .qm files in the application, and you can also deploy them as separate files.
Input
The Qt project (.pro) or the extracted file (strings.ts)
Output
Localized .ts files (strings_fi.ts), and .qm files compiled by Soluling or your build
Runtime
QTranslator loads the .qm file of the user's language
Cloud
Upload strings.ts to Soluling Cloud directly; no desktop step needed

On this page

Tutorial

Localize a Qt application, step by step

Six steps take a Qt application from English only to a multilingual one.

01

Prepare: mark the strings

Texts that you enter in Qt Designer are ready for localization: the .ui file marks them as translatable. Strings in the code are not. A typical problem looks like this:

ui->resultLabel->setText(QString("Driving time is %1 hours %2 minutes").arg(hours).arg(minutes));

Internationalizing the application takes three changes:

  1. Wrap the strings in tr. Use it in every class that has the Q_OBJECT macro. Elsewhere, use QCoreApplication::translate.
  2. Use numbered placeholders. Qt's %1 and %2 are filled by arg, so a translator can move them. Validation checks that the translation keeps every placeholder.
  3. Leave out texts that are not for translation. In Qt Designer, uncheck translatable for a placeholder text that the code replaces.
Marking a string in the code Before, the result is a hard-coded English QString. After, tr marks it, so lupdate extracts it, and Soluling shows it with its Finnish translation and numbered placeholders. Before QString("Driving time is %1 hours %2 minutes") .arg(hours).arg(minutes); ✕ Stays English, lupdate doesn't see it Internationalize After tr("Driving time is %1 hours %2 minutes") .arg(hours).arg(minutes); strings.ts in Soluling MainWindow English Driving time is %1 hours %2 minutes Finnish Ajoaika on %1 tuntia %2 minuuttia ✓ Extracted and translated, and the translator can reorder the values
02

Extract: create the .ts file and a Soluling project

Add the original .ts file to your .pro file, and run lupdate from Qt's bin directory:

TRANSLATIONS += strings.ts

lupdate Driving.pro

lupdate reads the .ui files and the code, and writes the marked strings to strings.ts. Then drag and drop Driving.pro or strings.ts on Soluling.

  • If you add strings.ts, the Select File Type dialog appears, because .ts also means a TypeScript file. Soluling detects it as a Qt translation file; click OK.
  • On the Options sheet, select the context method. The default suits most projects.
  • On the Select Languages page, select the original language and the target languages, and click Finish.
Extracting and creating the project lupdate writes strings.ts. Driving.pro or strings.ts goes through Project Wizard's Options sheet (context method) and Select Languages page (Finnish, German, Japanese). Extract lupdate Driving.pro strings.ts Options Context method: Original value Languages Finnish (fi) German (de) Japanese (ja) Adding strings.ts also shows a dialog: confirm that it is a Qt translation file.
03

Translate: texts, placeholders, and plurals

The project tree shows a node for each context of the .ts file, usually one for each class, such as MainWindow. Each string is a row in the grid. The file has only the strings and not the forms, so you translate Qt in the grid, without a visual editor. The same text in the same class is one row: in the Driving sample, &Calculate is both the button and the menu item. Plurals open in the pattern editor; see Plurals.

  • Machine translation and translation memory. Click Use Machine Translation to translate with Amazon, Claude, DeepL, Google, Microsoft, ModernMT, or MyMemory, and reuse earlier translations from translation memory and terminology.
  • External translators. Send a translation package, an Excel file, or XLIFF to a translator, and import the results back. See teamwork.
  • Translators in a browser. Upload the project to Soluling Cloud and let translators work in Translate.
04

Check: find problems before release

Pseudo translation. Click Translate | Pseudo Translations | Fill, build, and run the application. Pseudo translations are longer and use accented characters, so texts that don't fit and strings still in the code (shown in plain English) stand out. See pseudo translation.

Pseudo-translated build

[Ðŕîvîñĝ Ţîɱé ___] PS ✕ [Ƒîļé __] [Ĥéļþ __] [Ðŕîvîñĝ ðîšţåñçé: ____________________] 220 [Šþééð: __________] 88 [Çåļçûļåţé ___] 2 hour(s) 30 minute(s) PS Too long and still English (hard-coded)

Validation. Soluling validates translations while you type and in batch (Validation | Validate Translations): missing translations, inconsistent placeholders and patterns, duplicate hotkeys, and more. See validation.

Validation: German

⚠ Inconsistent format string MainWindow The original has %1 and %2; the translation has only %1: Fahrzeit: %1 Stunden ⚠ Duplicate hotkey &Berechnen / &Beenden Both use Alt+B in the File menu, so change one of them.
05

Build: create the localized files and load them

Choose Home | Build All. Soluling writes strings_fi.ts, strings_de.ts, and strings_ja.ts next to strings.ts. Qt uses binary .qm files at runtime, and there are two ways to compile them:

  • In your Qt build. Add the localized files to the .pro file, as the Driving sample does. lrelease compiles them, and embed_translations puts them in the application under :/i18n. lupdate doesn't touch EXTRA_TRANSLATIONS, so it leaves your translations alone.
  • In Soluling. When you add a .ts file, Soluling also compiles the localized files with lrelease.exe by default. Set the Qt tools directory in the Qt options. See the Qt write options for this and for compressing the .qm files.
CONFIG += c++11 lrelease embed_translations

TRANSLATIONS += strings.ts
EXTRA_TRANSLATIONS = strings_fi.ts strings_de.ts strings_ja.ts

Then load the file of the user's language in main.cpp, before you create the windows:

QApplication a(argc, argv);

// Create translator object and load translations
QTranslator translator;
bool ok = translator.load(":/i18n/strings_" + QLocale::system().name());

if (ok)
  a.installTranslator(&translator);

MainWindow w;
w.show();
Resource files and the built application The project folder has the extracted strings.ts and the localized strings_fi.ts, strings_de.ts, and strings_ja.ts. The Qt build compiles them into .qm files and embeds them in Driving.exe. Soluling: Build All DIR Driving\ TS strings.ts extracted by lupdate TS strings_fi.ts TS strings_de.ts TS strings_ja.ts Qt: your build DIR release\ QM strings_fi.qm and the other languages EXE Driving.exe the .qm files embedded
06

Update: translate only what changed

When the application changes, run lupdate again and click Home | Scan. Soluling keeps the existing translations and adds the new strings. With the default context method, the original text identifies the row, so changing a text makes it a new row that needs a translation. Translate the new rows, build, and build the application. Add the steps to your build pipeline with SoluMake or, with Soluling Cloud, SoluCLI.

Reference

Three file types: .ui, .ts, and .qm

You write the texts in .ui files and in the code. lupdate collects them into a .ts file, an XML file with one context element for each class and one message for each string. Soluling writes the translations into a copy of it for each language. lrelease compiles a .ts file into a binary .qm file, the only one your application needs at runtime.

<!-- strings_fi.ts, written by Soluling -->
<TS version="2.1" language="fi">
<context>
    <name>MainWindow</name>
    <message>
        <location filename="mainwindow.ui" line="14"/>
        <source>Driving Time</source>
        <translation>Ajoaika</translation>
    </message>
</context>
</TS>

Context: how rows are identified

A message has no ID, so Soluling uses another of its elements to identify the row. Select the method on the Options sheet of the source. Once you have translations, keep the same method.

Context method Identifies a row by When a text changes
Original value (default) The original text The row is new, and it needs a translation.
Comment value The comment, or the original text if there is no comment The row keeps its translation. Use this only if the comments in a class are unique.
Line attribute value The line number in the source file The row keeps its translation, but any edit above the string can move it. Avoid this.

Plurals

Pass the count as the third parameter of tr, and use %n for the number. lupdate marks the message as plural, and Soluling shows it in the pattern editor, with the forms that each target language needs. The Widget\Plural sample does this:

label->setText(tr("%n file", "", count));

<!-- strings_fi.ts -->
<message numerus="yes">
    <source>%n file</source>
    <translation>
        <numerusform>%n tiedosto</numerusform>
        <numerusform>%n tiedostoa</numerusform>
    </translation>
</message>

The original has only one form, so an English application shows "2 file" until the text is translated to English too. See patterns.

Fallback

QLocale::system().name() returns a name with a region, such as fi_FI. If that file doesn't exist, QTranslator::load removes the end of the name and tries again, so fi_FI finds strings_fi.qm. If a string isn't translated, Qt shows the source text in the code.

Message lookup on a system in fi_FI On a system in fi_FI, there is no strings_fi_FI.qm, so QTranslator loads strings_fi.qm. Driving Time and Calculate are found there as Ajoaika and Laske. A string that was not translated uses the source text in the code. UI culture: fi_FI strings_fi_FI.qm no such file strings_fi.qm Source text the original text in the code Driving Time – ✓ Ajoaika &Calculate – ✓ &Laske A new string – not translated ✓ A new string

Change the language at runtime

Load another .qm file and install the translator again. Qt then sends a LanguageChange event to every widget, and the code that Qt Designer generated sets the texts again. Set again any texts that your own code sets. The samples don't include this.

void MainWindow::setLanguage(const QString &language)
{
  qApp->removeTranslator(&translator);

  if (translator.load(":/i18n/strings_" + language))
    qApp->installTranslator(&translator);
}

void MainWindow::changeEvent(QEvent *event)
{
  if (event->type() == QEvent::LanguageChange)
    ui->retranslateUi(this);

  QMainWindow::changeEvent(event);
}

Qt Quick and CMake

  • Qt Quick. Mark the strings in QML with qsTr, such as title: qsTr("Hello World"). They go to the same .ts file, so the rest of the process is the same. To change the language at runtime, call QQmlEngine::retranslate.
  • CMake. Soluling reads the .pro file but not CMakeLists.txt, so add strings.ts to Soluling. Qt's CMake commands, such as qt_add_translations, create the .ts and .qm files. Keep the localized files out of the lupdate step. See Qt's documentation for the commands of your Qt version.

Translate in Soluling Cloud

With Soluling Cloud, translators use Translate in a browser. How you start depends on what you localize:

  • Qt translation files (.ts). On the dashboard, add a project, select strings.ts, and choose Qt translation file (.ts) as the source type, not TypeScript. Translators work in Translate; click Build localized files, and save the downloads next to strings.ts. Your Qt build compiles them into .qm files. When the application changes, run lupdate and upload the new strings.ts; the existing translations are kept. No desktop step is needed.

To run the scan, upload, import, and build steps in your build pipeline, use SoluMake. See the Cloud tutorial and workflows.

Do and don't

Do

  • Wrap every string the user sees in tr or qsTr.
  • Use numbered placeholders and arg.
  • Use the count parameter of tr and %n for plurals.
  • Use layouts, so that forms grow with longer text.
  • Install the translator before you create the windows.
  • Pseudo-translate before the first real translation.

Don't

  • Build sentences from pieces.
  • Pass a variable to tr; lupdate can't read it.
  • List the localized files in TRANSLATIONS; use EXTRA_TRANSLATIONS.
  • Choose TypeScript when you add a Qt .ts file.
  • Deploy .ts files; the application needs the .qm files.

Typical localizability problems

See also internationalization and pseudo translation.

Problem How it shows Find and fix
Strings in code English text in a pseudo-translated build Wrap the strings in tr, and run lupdate.
Sentences built from pieces Word order and grammar are wrong in the translation Use one string with %1 and %2.
Fixed geometry Clipped text in the pseudo or German build Use Qt layouts instead of fixed positions.
Plural forms in code Grammar is wrong for some counts Use %n and the count parameter of tr.
Hotkeys collide Alt+letter selects the wrong item Validation finds duplicate hotkeys.

Troubleshooting

Symptom Likely cause What to do
The application stays in English No .qm file matches the name, or the translator was installed after the windows were created Check the name and the :/i18n prefix, and install the translator first.
Soluling doesn't create .qm files The Qt tools directory isn't set Set it in the Qt options, or compile in your Qt build.
A text is missing from strings.ts It isn't marked with tr, or lupdate wasn't run Mark it, and run lupdate again.
A translation is lost after a text change The default context method identifies a row by its original text Translate the row again, or use the comment value as the context.
Soluling asks for the file type .ts also means a TypeScript file Select the Qt translation file.
Your translations disappear from the localized files They are in TRANSLATIONS, so lupdate updates them Move them to EXTRA_TRANSLATIONS.

Samples

The samples are in Samples\Qt of the Soluling installation and on GitHub:

  • Widget\Driving: the driving time window of this guide, with the Soluling project Driving.ntp, Finnish translations, and German and Japanese files ready to translate. The window has the texts, but the Calculate button has no code, so the result text in the figures is an example.
  • Widget\Simple: a simple localized application. Try this first.
  • Widget\Hello: a localized Hello World application.
  • Widget\Tutorial: the application of the tutorial in the Desktop documentation.
  • Widget\Plural: grammatically correct plural messages.
  • Quick\Sample: a small Qt Quick application with qsTr and a .ts file.

See Qt localization in the Desktop documentation for all the details.

FAQ

Either works. The .pro file brings every file listed in TRANSLATIONS. Add the .ts file if you use CMake, or if you want Soluling to compile the .qm files.

Yes. Upload strings.ts to Soluling Cloud, translate in Translate, and download the localized files. See Translate in Soluling Cloud.

No. Soluling and Soluling Cloud read and write the same .ts files, so you can keep using lupdate and lrelease and leave out Qt Linguist.

No. One application holds every .qm file you embed, and it chooses at runtime.

Yes. Load another .qm file, install the translator again, and handle the LanguageChange event. See Change the language at runtime.

Yes. QML strings marked with qsTr go to the same .ts file. See Qt Quick and CMake.

Related

All guides