Localizing Applications

The steps to localize applications include creating translatable applications, preparing them for translation, translating the strings, and creating runtime translation files for the released application.

Qt Quick and Qt C++ applications use the same underlying localization system: lupdate, lrelease, and the translation source (TS) files and QM files that they generate. You use the same tools for both QML and C++ code, as described in the Qt Linguist Manual.

You can even have user interface strings in QML and C++ source files in the same application. The system will create a single combined translation file and the strings are accessible from QML and C++ code.

To localize internationalized applications:

• Specify Translation Sources in Qt Project Files
• Deploy Translations
• Use Qt Module Translations

Specify Translation Sources in Qt Project Files

To enable lupdate and lrelease to generate TS and QM files, update the application project file to specify the source files that contain text to be translated.

Use ISO language and country codes in the TS file name to determine the language to load at runtime. For more information, see Enable Translation.

The lupdate tool extracts user interface strings from your application. It expects all source code to be encoded in UTF-8 by default. For more information, see Encoding.

Using CMake

Make Qt's CMake commands for internationalization available by loading the Qt6LinguistTools package.

 cmake_minimum_required(VERSION 3.16)
 project(myproject)
 find_package(Qt6 COMPONENTS Core LinguistTools)

Declare the supported languages with the I18N_TRANSLATED_LANGUAGES argument of qt_standard_project_setup.

 # Declare that the project will have a German and a French translation.
 qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES de fr)

The source code is assumed to have translatable strings in English. You can adjust the language of the strings in the source code with the qt_standard_project_setup parameter I18N_SOURCE_LANGUAGE.

Call the qt_add_translations command on the target that is supposed to load the .qm files at runtime.

 qt_add_translations(myapplication)

If they're not yet existing, this will create the files myproject_de.ts and myproject_fr.ts. See Automatic Determination of .ts File Paths on how those file names are constructed.

This command also creates myproject_en.ts, which is the plurals-only translation file. See Handle Plural Forms for more details. The generation of the plurals-only file can be turned off with the NO_GENERATE_PLURALS_TS_FILE argument.

All source files of all targets in the project are considered inputs for the generation of the .ts files. See the qt_add_translations reference documentation on more information how the project's targets are collected and how to exclude targets and single sources.

Using qmake

When using qmake, set a conditional statement to hide the QML source from the compiler that you list in the SOURCES or HEADERS entry in the .pro file.

The SOURCES variable is intended for C++ source files. If you list QML or JavaScript source files there, the compiler tries to build them as though they are C++ files. As a workaround, you can use an lupdate_only{...} conditional statement so the lupdate tool sees the .qml files but the C++ compiler ignores them.

For example, the following .pro file snippet specifies two .qml files in the application.

 lupdate_only{
 SOURCES = main.qml \
           MainPage.qml
 }

You can also specify the .qml source files with a wildcard match. The search is not recursive, so you need to specify each directory that contains source files that contain UI strings:

 lupdate_only{
 SOURCES = *.qml \
           *.js \
           content/*.qml \
           content/*.js
 }
 

Deploy Translations

The easiest way to deploy .qm files is by embedding them into Qt resources. The qt_add_translations CMake command automatically takes care of that. The .qm files are accessible under the ":/i18n" resource prefix.

 # Automatically embed generated .qm files.
 qt_add_translations(myapplication)

Alternatively, the .qm files can be deployed into a directory in the file system. This is desirable for larger applications that don't want to hold all available translations in memory. Pass the QM_FILES_OUTPUT_VARIABLE argument to qt_add_translations. The command stores the list of generated .qm files in the specified variable. Use CMake's regular installation commands on the file names in that list.

 # Do not embed generated .qm files.
 qt_add_translations(myapplication
     QM_FILES_OUTPUT_VARIABLE qm_files
 )

 # Install generated .qm files.
 install(FILES ${qm_files} DESTINATION translations)

Place the .qm files required for the application in a location where the loader code using QTranslator can find them. Typically, you specify a path relative to QCoreApplication::applicationDirPath().

In addition to the application's QM files, you need to deploy the QM files for the Qt modules that you use in the application, unless they are installed on the system.

The QM files are split up by module and there is a so-called meta catalog file which includes the QM files of all modules. However, you only need to deploy the QM files for the modules that you use in the application.

You can use the lconvert tool in the deploy step to concatenate the required QM files into one file that matches the meta catalog file. For example, to create a German translation file for an application that uses the Qt Core, Qt GUI, and Qt Quick modules, run:

 lconvert -o installation_folder/qt_de.qm qtbase_de.qm qtdeclarative_de.qm

Use Qt Module Translations

Qt modules contain several thousands of strings that also need to be translated into the languages that you are targeting. You can find a number of TS files in the qttranslations repository. Before you start translating Qt, read the wiki page Translating Qt Into Other Languages.

Locating Qt Translations

You can use QLibraryInfo::path() to locate the translations for the Qt modules that your application uses. You can request the path to the translations at run-time by passing QLibraryInfo::TranslationsPath to this function.

Available Catalogs

The Qt translation catalogs are located in the qttranslations repository.

In Qt 4, there is one big, monolithic .qm file per locale. For example, the file qt_de.qm contains the German translation of all libraries.

The qt_ meta catalog contains the still-existing Qt translations that were included in the qt_ catalog in Qt 4. It was created to make porting applications from Qt 4 to Qt 5 easier. The meta catalog depends on translations that might be absent, because they belong to unnecessary or deprecated modules, which might cause the loading of the translations to fail. If you use modules that are new in Qt 5 or later in your application, you must specify the names of the catalogs for those modules even if you use the meta catalog.

The following table lists the translation catalogs available for the Qt modules and tools in Qt.

Example: Essential Qt Modules

For example, to locate translations for essential Qt modules, such as Qt Core, Qt GUI, Qt Network, and Qt Widgets, add the following code to the main() function:

     QTranslator qtTranslator;
     if (qtTranslator.load(QLocale::system(), u"qtbase"_s, u"_"_s,
                           QLibraryInfo::path(QLibraryInfo::TranslationsPath))) {
         app.installTranslator(&qtTranslator);
     }