Details
-
Suggestion
-
Resolution: Unresolved
-
P3: Somewhat important
-
None
-
6.7.1
-
None
Description
I had a chance to work on some i18n and found out that it must be difficult for new Qt users to find out how exactly they should set up their project so that the translation takes place properly.
Currently, as far as I know, there are two documentations to look for when it comes to this topic:
Here are some improvements I propose. I may be wrong or missing something though, in that case, please feel free to make the proposed fix based on the correct understanding the R&D has.
(1) We should clearly state that, for QtQuick app, the resource prefix must be "qt/qml/<the directory name where the qml file with translatable texts resides>/i18n" otherwise the QQmlApplicationEngine fails to load the .qm files and the translation won't take place, to this section: https://doc.qt.io/qt-6/qtlinguist-cmake-qt-add-translations.html#embedding-generated-qm-files-in-resources
(2) We should clearly state that, for QtQuick app, TS_FILE_BASE option must exactly be "qml" otherwise the QQmlAppliationEngine fails to load the .qml files and the translation won't take place, to this section: https://doc.qt.io/qt-6/qtlinguist-cmake-qt-add-translations.html#influencing-the-names-of-the-ts-files.
Although this is written in the different documentation, "QML: Use QQmlApplicationEngine" ...well, this is a different documentation and hard to find, and it just says "The translation file names must have the prefix qml. For example, qml_en_US.qm."_ which still leaves a room for the user to think it would be okay to make it like "qml_myApp_en_US.qml," just like I did.
(3) We should mention that for SOURCE_TARGETS, it can realistically be different from the first argument of qt_add_translations(). I attached the sample project for this case(tested with Qt 6.7.1 msvc desktop), where the root CMakeLists.txt has this:
qt_add_translations(ClocksApp TS_FILE_BASE qml # must be qml TS_FILE_DIR i18n # optional RESOURCE_PREFIX qt/qml/ClocksContent/i18n # must be SOURCE_TARGETS ClocksContent # the target LRELEASE_OPTIONS -idbased)
This project also has a sub module called "ClocksContents" which contains qml files with translatable texts. This sub module was automatically generated by QDS, therefore many commercial users who have been told about QDS by the pre-sales team would likely end up with this project structure. In this case, like above, the SOURCE_TARGETS should be this submodule which contains the qml files. There's another reason to have qt_add_translations() at the root CMakeLists.txt, which is that the CMakeLists.txt inside ClockContents has this sentence at the top:
### This file is automatically generated by Qt Design Studio. ### Do not change
Which means we cannot directly modify this CMakeList.txt.
The documentation may need to mention the situation where there are multiple submodules with bunch of QML files with translatable texts, and tell to the readers that they can have multiple qt_add_translations() in the root CMakeLists.txt for each submodule. (Although I haven't verified if this use case really works or not)
(4) We should state that the language name such as de and fr are the keywords the user should assign to Qt.uiLanguage when they are to dynamically translate the texts in the app during runtime, to this section: https://doc.qt.io/qt-6/qtlinguist-cmake-qt-add-translations.html#influencing-the-names-of-the-ts-files
The reason was, it was confusing what exactly the keyword I should've assigned to Qt.uiLanguage in QML files, such that "is it ja? jp? or ja_JP, etc? I've figured this out by debugging the Qt's source itself and I don't want every Qt commercial user to go through this process. Therefore, this point should be made clearer in my opinion.
(5) We should make https://doc.qt.io/qt-6/i18n-source-translation.html#qml-use-qqmlapplicationengine more elaborate, with some code snippets on how to do this in the app, including the snippet of .qml file and CMakeLists.txt. or, if this enhancement isn't appropriate for this section, we can work on the proposal (6) instead.
(6) We should improve the [Qt Quick I18N example|https://doc.qt.io/qt-6/qtqml-qml-i18n-example.html.]
What I have in mind is to make this example much like Qt for MCUs' thermo demo, where it uses Qt.uiLanguage to dynamically change the languages of the texts. The issue in the current Qt Quick I18N example is that it doesn't use Qt.uiLanguage to dynamically translate the texts, which is the basic usecase of any realistic i18n app. The enhanced example should show how the users can dynamically translate, how they should write CMakeLists.txt for it and most importantly, they should enable "<target_name>_lrelease" and "<target_name>_lupdate" targets in Build setting for the Kit they use on Qt Creator to update the .ts and .qm files(Of course, we need a lot of screenshots to avoid any possible misunderstanding and confusion). Ideally, we should add an internationalization & localization tutorial documentation which is based on this enhanced example. The tutorial should also contain how to use Linguist on this particular app, meaning, a user can just read and work on this tutorial to fully understand the basics on how they can make their own i18n app. This example may contain other use cases too, such as plural translation.