Support for multiple languages is extremely simple in Qt applications, and adds little overhead to the developer's workload.
Qt minimizes the performance cost of using translations by translating the phrases for each window as they are created. In most applications the main window is created just once. Dialogs are often created once and then shown and hidden as required. Once the initial translation has taken place there is no further runtime overhead for the translated windows. Only those windows that are created, destroyed and subsequently created will have a translation performance cost.
Creating applications that can switch language at runtime is possible with Qt, but requires a certain amount of developer intervention and will of course incur some runtime performance cost.
To enable release managers to use lupdate and lrelease, specify a .pro
Qt project file. There must be an entry in the TRANSLATIONS
section of the project file for each language that is additional to
the native language. A typical entry looks like this:
TRANSLATIONS = arrowpad_fr.ts \ arrowpad_nl.ts
Using a locale within the translation file name is useful for determining which language to load at runtime. For more information, see QLocale.
The lupdate
tool extracts user interface strings from your application. It reads the application .pro file to identify which source files contain text to be translated. This means your source files must be
listed in the SOURCES
or HEADERS
entry in the .pro file, or in resource files listed in the RESOURCE
entry. If your files are not listed, the text in them will not be found.
An example of a complete .pro
file with four translation source files:
HEADERS = main-dlg.h \ options-dlg.h SOURCES = main-dlg.cpp \ options-dlg.cpp \ main.cpp FORMS = search-dlg.ui TRANSLATIONS = superapp_dk.ts \ superapp_fi.ts \ superapp_no.ts \ superapp_se.ts
If your compiler uses a different encoding for its runtime system than for its source code and you want to use non-ASCII characters in string literals, you will need to set the CODECFORSRC
. For example:
CODECFORSRC = UTF-8
Microsoft Visual Studio 2005 .NET appears to be the only compiler for which this is necessary. However, if you want to write portable code, we recommend that you avoid non-ASCII characters in your source files. You can still specify non-ASCII characters portably using escape sequences, for example:
label->setText(tr("F\374r \310lise"));
Design your application so that it can be adapted to various languages and regions without engineering changes. Qt tries to make internationalization as painless as possible for you. All input controls and text drawing methods in Qt offer built-in support for all supported languages. But you still need to keep the following things in mind when writing source code for your application:
You can develop applications that use both C++ and QML sources in the same application and even have user interface strings in both sources. The tools create a single combined translation file and the strings are accessible from C++ and QML.
The classes that support internationalizing of Qt applications are described in Internationalization with Qt. The process of making source code translatable is described in Writing Source Code for Translation and in Internationalization and Localization with Qt Quick.
Each piece of text that requires translating requires context to help the translator identify where in the program the text appears. In the case of multiple identical texts that require different translations, the translator also requires some information to disambiguate the source texts. Marking text for translation will automatically cause the class name to be used as basic context information. In some cases the developer may be required to add additional information to help the translator.
The .qm
files required for the application should be placed in a location where the loader code using QTranslator can locate them. Typically, this is done by specifying a path
relative to QCoreApplication::applicationDirPath().
Usually, there are .qm
files for the application, and, if a version of Qt is used that is not installed on the system, Qt's .qm files need to be deployed as well.
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.
In Qt 5, the .qm
files were split up by module and there is a so-called meta catalog file which includes the .qm
files of all modules. The name of the meta catalog file is identical to the name of
Qt 4's monolithic .qm
file so that existing loader code works as before provided all included .qm
files are found.
However, it is not necessary to always deploy all of Qt 5's .qm
files. We recommend concatenating the .qm
files of the modules required to one file matching the meta catalog file name using the tool
lconvert
in the deploy step. For example, to create a German translation file for an application using the modules Qt Core, Qt GUI, and
Qt Quick, run:
lconvert -o installation_folder/qt_de.qm qtbase_de.qm qtdeclarative_de.qm
The following tutorials illustrate how to prepare Qt applications for translation:
tr()
function to mark user-visible source text for translation.
tr()
which provides additional information to the translator.