Details
-
Suggestion
-
Resolution: Unresolved
-
P3: Somewhat important
-
None
-
6.7.1
-
framework-content 5, framework-content 6
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 QTBUG-133657 instead
Attachments
Issue Links
- split to
-
QTBUG-133657 Improve Qt Quick I18N example
-
- Reported
-
Gerrit Reviews
For Gerrit Dashboard: QTBUG-127411 | ||||||
---|---|---|---|---|---|---|
# | Subject | Branch | Project | Status | CR | V |
622378,3 | WIP: Doc: Improve i18n docs | dev | qt/qttools | Status: NEW | -2 | 0 |
625719,2 | Doc: Add supportive code snippets to QQmlApplicationEngine section | dev | qt/qtdoc | Status: NEW | 0 | 0 |