C
Internationalization and localization with Qt Quick Ultralite
Based on Qt
The functionality in Qt Quick Ultralite is based on Internationalization and localization in Qt and Qt Linguist. This document describes the differences, enhancements, and limitations compared to Qt.
Translation
Use either the qsTr()
or qsTrId()
function in QML files to mark string literals for translation. All such marked string literals are found by the tooling, which updates the translation source (.ts
) files registered in a TranslationFiles node in the same QmlProject as the QML file(s) containing those strings.
Important: Use one of these two alternatives in an application. Using both of them in the same application may lead to unexpected behavior.
Add a .ts
file for each language to each of the QmlProject files containing QML files with translatable strings. Make sure that all QmlProject files include a .ts
files for each language the application will support, to avoid missing translations in parts of the application.
The .ts
files are compiled to translation release files (.qm
) and passed to the QML compiler, which replaces the qsTr()
or qsTrId()
calls with a lookup of the correct string based on the Qt.uiLanguage
property.
The Qt.uiLanguage
property can also be used in other bindings to make decisions based on the active language.
Each .ts
file introduces a translated language that can be switched to at runtime by setting the Qt.uiLanguage
property. The name of the language is derived from the name of the .ts
file. For example, the "app_nb_NO.ts" file defines the translations for nb_NO
, which is the ISO language code for Norwegian Bokmål.
When the Qt.uiLanguage
is empty, no translation is applied and the strings used in the source code are shown.
By default, the application will also include the source strings (or IDs) given to qsTr()
or qsTrId()
in QML. To omit the source strings and only include declared translations, set TranslationFiles.MCU.omitSourceLanguage to false
.
The translation example shows how to use qsTr()
and the Qt.uiLanguage
property.
Note: If at least one declared .ts
file does not exist, qmlprojectexporter
will run lupdate
to create them when configuring the application build.
Building with CMake
Listing the translation source files for the target languages in the QmlProject and using the containing QmlProject file in qul_add_target
with QML_PROJECT specified will have the following effects:
- It creates a
update_translations
CMake target which is not included in the default build. Trigger a build of this target to create or update the.ts
files with new and changed translatable strings from the source code. - It sets up the build system to embed the translations from the
.ts
files in the program binary. - If at least one of the declared translation source files does not exist, all translation source files will be created (if not already present), and updated with the source strings currently present in the declared QML source files.
Standalone qmlprojectexporter
When developing using a build system other than CMake, qmlprojectexporter
can be run solely to update the translations, refer to qmlprojectexporter's update translation argument for more details.
Text ID-based translations
The text ID translation mechanism is an industrial strength system for internationalization and localization. Each text in the application has a unique identifier (text ID) that you use in the source code instead of text. This makes it much easier to manage large numbers of translated texts.
If you set the idBasedTranslations to true in the .qmlproject
file, it will enable text ID based translations for your project. Use the qsTrId()
function instead of qsTr()
in QML files to mark strings for text ID based translations.
Note: You must use only plain text based or only text ID based functions in one application. If you mix them, you will end up with an incomplete set of texts to be translated. If QML modules in your application have QML files to be translated, the QML modules should follow the same translation mechanism as the main project.
Memory optimization
When using ID-based translations, the application is not expected to display the source strings. It is highly recommended to set the TranslationFiles.MCU.omitSourceLanguage flag to true
to reduce ROM footprints when idBasedTranslations is enabled.
Qt Design Studio translations
Qt Design Studio can create and maintain translations using the Translations view. When using this feature, Qt Design Studio will automatically update the .qmlproject
file to include the translations in the application.
Limitations
The following functionality is not currently supported:
- Translation of strings in C++ files
- Text ID based translations with non-QmlProject based CMake APIs
- Translation functions other than
qsTr()
orqsTrId()
, such asqsTranslate()
,QT_TR_NOOP()
,QT_TRANSLATE_NOOP()
andQT_TRID_NOOP()
- The plural disambiguation argument in
qsTr()
orqsTrId()
Available under certain Qt licenses.
Find out more.