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.
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
.tsfiles (strings_fi.ts), and.qmfiles compiled by Soluling or your build - Runtime
QTranslatorloads the.qmfile of the user's language- Cloud
- Upload
strings.tsto Soluling Cloud directly; no desktop step needed
On this page
- Tutorial: localize a Qt application step by step
- How Qt localization works
- Context: how rows are identified
- Plurals
- Fallback
- Change the language at runtime
- Qt Quick and CMake
- Translate in Soluling Cloud
- Do and don't
- Typical localizability problems
- Troubleshooting
- Samples
- FAQ
Localize a Qt application, step by step
Six steps take a Qt application from English only to a multilingual one.
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:
-
Wrap the strings in
tr. Use it in every class that has theQ_OBJECTmacro. Elsewhere, useQCoreApplication::translate. -
Use numbered placeholders. Qt's
%1and%2are filled byarg, so a translator can move them. Validation checks that the translation keeps every placeholder. - Leave out texts that are not for translation. In Qt Designer, uncheck translatable for a placeholder text that the code replaces.
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.tsalso 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.
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.
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
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
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
.profile, as the Driving sample does.lreleasecompiles them, andembed_translationsputs them in the application under:/i18n.lupdatedoesn't touchEXTRA_TRANSLATIONS, so it leaves your translations alone. -
In Soluling. When you add a
.tsfile, Soluling also compiles the localized files withlrelease.exeby default. Set the Qt tools directory in the Qt options. See the Qt write options for this and for compressing the.qmfiles.
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();
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.
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.
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 astitle: qsTr("Hello World"). They go to the same.tsfile, so the rest of the process is the same. To change the language at runtime, callQQmlEngine::retranslate. -
CMake. Soluling reads the
.profile but notCMakeLists.txt, so addstrings.tsto Soluling. Qt's CMake commands, such asqt_add_translations, create the.tsand.qmfiles. Keep the localized files out of thelupdatestep. 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, selectstrings.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 tostrings.ts. Your Qt build compiles them into.qmfiles. When the application changes, runlupdateand upload the newstrings.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
trorqsTr. - Use numbered placeholders and
arg. - Use the count parameter of
trand%nfor 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;lupdatecan't read it. - List the localized files in
TRANSLATIONS; useEXTRA_TRANSLATIONS. - Choose TypeScript when you add a Qt
.tsfile. - Deploy
.tsfiles; the application needs the.qmfiles.
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
qsTrand a.tsfile.
See Qt localization in the Desktop documentation for all the details.
FAQ
.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.strings.ts to Soluling Cloud, translate in Translate, and download the localized files. See Translate in Soluling Cloud..ts files, so you can keep using lupdate and lrelease and leave out Qt Linguist..qm file you embed, and it chooses at runtime..qm file, install the translator again, and handle the LanguageChange event. See Change the language at runtime.Related
- Qt localization - the full Desktop documentation
- Qt write options - compiling and compressing the
.qmfiles - Patterns - plurals, genders, and selects
- Supported formats - everything else Soluling localizes