Doc: Update QML I18N example docs

Describe the use of qsTr() and QQmlApplicationEngine, as well
as the CMake qt_add_translations command.

Task-number: QTBUG-110009
Change-Id: I7d2244a772fdb132acdb5f9f66294a7d772e0d36
Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io>

1 files changed, 47 insertions, 19 deletions

diff --git a/examples/qml/qml-i18n/doc/src/i18n.qdoc b/examples/qml/qml-i18n/doc/src/i18n.qdoc
index c523151662..3ea56f6518 100644
--- a/examples/qml/qml-i18n/doc/src/i18n.qdoc
+++ b/examples/qml/qml-i18n/doc/src/i18n.qdoc
@@ -1,33 +1,61 @@
-// Copyright (C) 2017 The Qt Company Ltd.
+// Copyright (C) 2023 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 /*!
-    \title QML Examples - Internationalization
+    \title Qt Quick I18N
     \example qml-i18n
     \image qml-i18n-example.png
-    \brief This is an internationalization example.
+    \ingroup examples-linguist
+    \brief Generating translation files (TS and QM) for a Qt Quick application.
 
- The QML runtime automatically loads a translation from the i18n subdirectory of the root
- QML file, based on the system language.
+    When you run the example application, the QML runtime automatically loads a
+    translation from the \c i18n subdirectory of the directory that contains the
+    main .qml file, based on the system language.
 
- The files are created or updated by running:
+    \section1 Marking Text as Translatable
 
-\code
-   lupdate qml-i18n.qml -ts i18n/base.ts
-\endcode
+    In the \c qml-i18n.qml file, use the \c qsTr command to mark UI text as
+    translatable:
 
- Translations for new languages are created by copying \e i18n/base.ts to \e i18n/qml_<lang>.ts
- The .ts files can then be edited with \l{Qt Linguist}:
+    \quotefromfile qml-i18n/qml-i18n.qml
+    \skipto }
+    \skipto Text
+    \printuntil )
 
-\code
-   linguist i18n/qml_fr.ts
-\endcode
+    \section1 Enabling Translation
 
- The run-time translation files are then generated by running:
+    In the \c main.cpp file, use \l QQmlApplicationEngine to automatically load
+    translation files from a subdirectory called \c i18n in the directory that
+    contains the main QML file:
 
-\code
-   lrelease i18n/*.ts
-\endcode
+    \quotefromfile qml-i18n/main.cpp
+    \skipto <QQmlApplicationEngine>
+    \printuntil engine;
 
-\note On Android, please make sure to include the generated *.qm files as resources.
+    The translation file names in the \c i18n subdirectory must have the prefix
+    \c qml_. For example, \c qml_en_AU.ts.
 
+    \section1 Creating Translation Files
+
+    Add the \c LinguistTools module as a value of the \c find_package command in
+    the \c CMakeLists.txt file:
+
+    \quotefromfile qml-i18n/CMakeLists.txt
+    \skipto find_package(
+    \printuntil )
+
+    Define the translation files to generate in the \l qt_add_translations
+    command:
+
+    \skipto qt_add_translations
+    \printuntil )
+
+    Build the application to generate TS and QM files.
+
+    \note On Android, make sure to include the QM files as resources.
+
+    \section1 Adding Translations
+
+    To create translations for new languages, copy \e {i18n/base.ts} to
+    \e {i18n/qml_<lang>.ts}. You can use \l{Qt Linguist} to translate the
+    strings.
 */