Uploaded image for project: 'Qt'
  1. Qt
  2. QTBUG-127411

Documentation improvement for i18n of Qt Quick App

    XMLWordPrintable

Details

    • 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:

      1. qt_add_translations
      2. QML: Use QQmlApplicationEngine

      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

          For Gerrit Dashboard: QTBUG-127411
          # Subject Branch Project Status CR V

          Activity

            People

              andreas.eliasson Andreas Eliasson
              mikio_hirai Mikio Hirai
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

                Created:
                Updated:

                Gerrit Reviews

                  There are 2 open Gerrit changes