Revision control
++ // Copyright (C) 2025 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example localizedclock-switchlocale
++ \ingroup examples-linguist
++ \examplecategory {User Interface Components}
++ \meta tags {qtquick,i18n,l10n,linguist,runtime,switch}
++
++ \title Localized Clock with Runtime Language Switch
++
++ \brief The example demonstrates best practices for using
++ Qt's translation and localization features in \l{Build with CMake}{CMake}
++ and \l{Qt Quick}, in particular changing the language of an application during
++ runtime. It extends the simpler \l{Localized Clock Example}.
++
++ 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 your system's locale
++ and language. The UI texts are also localized for the following languages:
++ English, German, French, Spanish, Italian, Japanese, Korean, Portuguese,
++ Arabic, and Chinese. Users can also use a menu button to select different
++ languages and locales.
++
++ The English version of the application:
++ \image linguist-localizedclock_switchlang_en.webp {Screenshot of a digital
++ clock in English}
++
++ The German version after changing the language at runtime:
++ \image linguist-localizedclock_switchlang_de.webp {Screenshot of a digital
++ clock in German}
++
++
++ \section1 Implementation
++
++ The application has four parts:
++ \list
++ \li \l {CMakeLists.txt}
++ \li \l main.cpp
++ \li \l {Translator Manager (translator.h, translator.cpp)}
++ \li \l{localizedclock-switchlocale#Main.qml}{Main.qml}
++ \endlist
++
++ \section2 CMakeLists.txt
++ The CMake integration is the same as the
++ \l{localizedclock#CMakeLists.txt}{CMake integration} of
++ the \l{localizedclock}{Localized Clock} example.
++ Please refer to that page for more details.
++
++ \section2 main.cpp
++ The starting point of the application, responsible for loading the
++ QML module.
++
++ \quotefromfile localizedclock-switchlocale/main.cpp
++ \skipto main
++ \printuntil }
++ \printuntil }
++
++ \section2 Translator Manager (translator.h, translator.cpp)
++
++ \c TranslatorManager is a QML singleton class that manages language and
++ locale switching at runtime. The central method of the class is
++ \c TranslatorManager::switchLanguage(), which accepts a string
++ representing a language code.
++
++ While the method is marked with \l Q_INVOKABLE, the TranslatorManager
++ class is declared with \l QML_ELEMENT and \l QML_SINGLETON.
++ This allows the method to be directly accessed from QML; also, see
++ \l{localizedclock-switchlocale#Main.qml}{Main.qml}.
++
++ \quotefromfile localizedclock-switchlocale/translatormanager.cpp
++ \skipto TranslatorManager::switchLanguage
++ \printuntil }
++ \printuntil }
++ \printuntil }
++
++ \section3 Updating Translations at Runtime
++
++ Upon switching language, the previous translation
++ is removed (QCoreApplication::removeTranslator()) and a
++ new translation for the selected language is
++ loaded (QTranslator::load()) and installed
++ (QCoreApplication::installTranslator()).
++ \l QQmlEngine::retranslate() then triggers the retranslation of
++ the strings in the QML document.
++
++ \section3 Updating Date and Time Formats
++
++ Changing language could also affect how dates and times are displayed.
++ For instance, if QLocale on your system prefers locale "en_US" for
++ "en", and "de_DE" for "de":
++ \list
++ \li The application is initially loaded with "US" as the country code.
++ \li Due to the US locale conventions, the date is presented in \e MM/DD/YYYY
++ format, and the time uses a 12-hour clock.
++ \li After changing the language to German, "de_DE" is the first preferred
++ locale for the German language, so the country changes to Germany.
++ \li The German conventions bring the date in \e DD.MM.YYYY format and
++ use a 24-hour clock.
++ \endlist
++
++ Upon switching the language, the application updates its QLocale
++ according to the selected language using \l QLocale::setDefault().
++ When representing time, the function
++ \l[QML]{Date::toLocaleTimeString()}{Date.toLocaleTimeString()} takes care of localizing the time and date
++ according to the locale of the application (see \l{localizedclock-switchlocale#Main.qml}{Main.qml}).
++
++
++ \section2 Main.qml
++ The main QML file defines the application's user interface.
++ The UI presents time, date, and a counter for seconds. For the basic
++ translation (window title) and plural handling (number of seconds),
++ please refer to the \l{localizedclock#Main.qml}{Localized Clock} example.
++
++ Upon selecting an item from the \c Menu \c TranslatorManager.switchLanguage()
++ is called with the respective language code. This call also takes care of
++ retranslating the translatable texts (see
++ \l{Translator Manager (translator.h, translator.cpp)}{Translator Manager}).
++ However, we still need to invoke \c updateClock() to
++ update the time representation in the new localization format
++ when the language is changed.
++
++ \quotefromfile localizedclock-switchlocale/Main.qml
++ \skipto ListModel
++ \printuntil root.updateClock()
++ \printuntil /^ {8}\}/
++ */