Revision control
++ // Copyright (C) 2025 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example localizedclock
++ \ingroup examples-linguist
++ \examplecategory {User Interface Components}
++ \meta tags {qtquick,i18n,l10n,linguist,plurals}
++
++ \title Localized Clock Example
++
++ \brief The example shows best practices for using Qt's translation and
++ localization features in CMake and Qt Quick including the handling
++ of plurals in different languages, and localized time and date formats.
++
++ See the \l{Qt Linguist Manual} for more information about
++ translating Qt applications.
++
++ \section1 User Interface
++
++ The example shows the current time and date in the locale and language of
++ your system. The texts in the UI are furthermore localized for
++ the following languages:
++ English, German, French, Spanish, Italian, Japanese, Korean, Portuguese,
++ Arabic, and Chinese.
++ If your desktop is in another language, it falls back to English.
++
++ To test different languages and locales without altering your system, the
++ example also accepts a locale as command line argument. For example,
++ starting localizedClock from the command line with the option
++ \c{--locale de} shows the clock in German, with a date and time
++ format as it is common in Germany.
++
++ The screenshot shows the en_US version:
++ \image linguist-localizedclock_en_US.webp {Screenshot of digital clock
++ in English (US)}
++
++ \section2 Internationalization
++
++ In the application translation is used to set the main window
++ title and a few UI texts, including ones with placeholders
++ and plural forms. The application counts the seconds with
++ \e{plural forms} enabled (see \l{Handle Plural Forms}). As a
++ result, depending on the count of seconds, the translation function
++ returns a different translation, with the correct grammatical
++ number for the target language.
++ For instance, in English, if the count is larger
++ than \e one, the \e plural form is used, otherwise the \e singular
++ form is used. In \l{Translation Rules for Plural Forms} you find
++ the plural rules for different languages.
++
++ The locale also affects how dates and times are displayed.
++ These are formatted according to the country conventions of the current
++ locale. For example, a German locale results in 24-hour time and
++ the day written before the month, while a US locale
++ uses a 12-hour clock, and the month is written before the day.
++
++ This screenshot shows the en_GB version. Notice that the data format is
++ different than the en_US version above, while the same English plural
++ translation is loaded in both cases.
++
++ \image linguist-localizedclock_en_GB.webp {Screenshot of digital clock
++ in English (UK)}
++
++ Here is the screenshot of the de_DE version, which similar to GB has a
++ different date format than US. Notice that the German translation for
++ regular and plural forms is loaded accordingly.
++
++ \image linguist-localizedclock_de_DE.webp {Screenshot of digital clock
++ in German}
++
++ \section1 Implementation
++
++ The implementation has three parts:
++ \list
++ \li \l{CMakeLists.txt}
++ \li \l{main.cpp}
++ \li \l{Main.qml}
++ \endlist
++
++ \section2 CMakeLists.txt
++
++ The CMake file of the application enables Qt's translation and localization support.
++ Here are the relevant pieces:
++
++ \c find_package(Qt6 REQUIRED COMPONENTS Core Linguist Qml Quick):
++ Finds and links the required Qt 6 modules, including \c Linguist which
++ are essential for internationalization.
++
++ \c qt_standard_project_setup(...):
++ Sets up the internationalization system with support for the listed
++ locales. \c I18N_SOURCE_LANGUAGE is left at its default value (English),
++ since the source code contains English texts.
++ \quotefromfile localizedclock/CMakeLists.txt
++ \skipto qt_standard_project_setup
++ \printuntil I18N_TRANSLATED_LANGUAGES
++
++ \c qt_add_translations(...):
++ Bundles the functionality of \c lupdate and \c lrelease by generating the
++ translation source files (TS files) in the "i18n" directory using
++ \c clock as the base name, and compiling them into binary \c .qm files if
++ they contain translations. The following TS files are generated:
++ \list
++ \li "clock_{de, ar, ko, zh, ja, fr, it, es, pt}.ts": One TS file per language
++ listed in \c I18N_TRANSLATED_LANGUAGES of \c qt_standard_project_setup
++ containing the translations to that language.
++ \li "clock_en.ts": Contains English plural forms, since the source code
++ has plural form translation ("%n second(s)").
++ The function \c qt_add_translations writes only the plural forms here,
++ as we specified the language of the texts in the source code as English,
++ by leaving \c I18N_SOURCE_LANGUAGE with the default value. So the reglular
++ texts do not need translations.
++ \endlist
++ \quotefromfile localizedclock/CMakeLists.txt
++ \skipto qt_add_translations
++ \printuntil )
++
++ \c qt_add_qml_module(...):
++ Adds a QML module under the URI \c qtexamples.localizedclock, including
++ the \l Main.qml file.
++ \quotefromfile localizedclock/CMakeLists.txt
++ \skipto qt_add_qml_module
++ \printuntil )
++
++ \section2 main.cpp
++ The starting point of the application. This part is responsible
++ for setting the locale, installing required translations, and
++ loading UI. Below is an explanation of the relevant pieces of code:
++
++ Define the locale argument, e.g., \c {--locale en_US} or \c{--locale de_DE}:
++
++ \quotefromfile localizedclock/main.cpp
++ \skipto QCommandLineParser parser
++ \printuntil parser.process
++
++ Parse the arguments, fetch the provided locale, and set the input
++ locale as the default locale of the application:
++
++ \quotefromfile localizedclock/main.cpp
++ \skipto QLocale locale
++ \printuntil QLocale::setDefault
++
++
++ Install the English translation regardless of the locale, to allow incomplete
++ translations for other languages. QTranslator queries translations
++ for texts in the reversed order the translations are installed:
++
++ \quotefromfile localizedclock/main.cpp
++ \skipto QTranslator enPlurals
++ \printuntil app.installTranslator
++
++ Install a translation according to the given locale. As English translation
++ is already installed in the previous step, we might end
++ up with two installed translations here. Qt uses the most recently installed
++ translation for any overlapping keys. Therefore, the locale-specific
++ translation will take precedence over English, and in case of any missing
++ translations, QTranslator falls back to English.
++
++ \quotefromfile localizedclock/main.cpp
++ \skipto QTranslator translation
++ \printuntil }
++ \printuntil }
++ \printuntil }
++
++ \section2 Main.qml
++ This QML file defines the main UI window of the application, which
++ presents time, date, the used locale, and a counter for seconds.
++ Below is an explanation of the relevant pieces of code:
++
++ \b {Set the title of the Window using qsTr() for translation.} To
++ find the translation for this text QTranslator queries in the
++ TS file of the current language the text \e{"Digital Clock"}
++ within the context \e{"Main"} (the file name):
++
++ \qml
++ title: qsTr("Digital Clock")
++ \endqml
++
++ \b{Show the number of seconds using qsTr() with plural (numeral) support.}
++ The plural form is enabled by using the special notation "%n"
++ (see \l{Handle Plural Forms}).
++ Depending on the value of n, the translation function returns a
++ different translation, with the correct grammatical number for the
++ target language.
++ For instance in English, if the value of \c root.seconds is larger
++ than one, the plural form is used, otherwise the singular form is used.
++ In \l{Translation Rules for Plural Forms} you find the plural rules
++ for different languages.
++
++ \qml
++ text: qsTr("%n second(s)", "seconds", root.seconds)
++ \endqml
++
++ \b{Display the current locale and use qsTr() to translate
++ the source text "Locale: %1".} Also the translation needs
++ to contain the argument notation "%1". As a result, the
++ argument of the text (i.e. \c{Qt.locale().name}) can
++ correctly be used to format the text:
++
++ \qml
++ text: qsTr("Locale: %1").arg(Qt.locale().name)
++ \endqml
++
++ \b{Format the time and date according to the locale convensions.}
++ Different countires might have specific preferences on
++ how time and date should be presented.
++ For instance, the German locale uses a 24-hour clock and writes
++ the day before the month, whereas the US locale follows a
++ 12-hour clock and places the month before the day.
++ The method Date.toLocaleTimeString takes these considerations
++ into account and formats the time and date correctly based
++ on the given locale:
++
++ \quotefromfile localizedclock/Main.qml
++ \skipto const now
++ \printuntil root.date
++ */