File indexing completed on 2024-05-19 04:45:52

 // SPDX-FileCopyrightText: Lukas Sommer <sommerluk@gmail.com>
 // SPDX-License-Identifier: BSD-2-Clause OR MIT
 
 // Own headers
 // First the interface, which forces the header to be self-contained.
 #include "initializetranslation.h"
 
 #include "initializelibraryresources.h"
 #include <qcoreapplication.h>
 #include <qdebug.h>
 #include <qglobal.h>
 #include <qlocale.h>
 #include <qmutex.h>
 #include <qpointer.h>
 #include <qstring.h>
 #include <qstringliteral.h>
 #include <qthread.h>
 #include <qtranslator.h>
 
 #if (QT_VERSION >= QT_VERSION_CHECK(6, 0, 0))
 #include <qlist.h>
 #else
 #include <qstringlist.h>
 #endif
 
 /** @internal @file
  *
  * Provides the @ref PerceptualColor::initializeTranslation() function. */
 
 namespace PerceptualColor
 {
 
 /** @internal
  *
  * @brief Set the translation for the whole library.
  *
  * After calling this function, all objects of this library that are created
  * from now on are translated according to translation that was set.
  *
  * Objects that were yet existing when calling are <em>not always</em>
  * automatically updated: When calling this function, Qt sends
  * a <tt>QEvent::LanguageChange</tt> event only to top-level widgets,
  * and these will get updated then. You can send the event yourself
  * to non-top-level widgets to update those widgets also. Note that
  * also @ref RgbColorSpaceFactory generates objects that might have
  * localized properties; these objects do not support translation
  * updates.
  *
  * If you create objects that use translations <em>before</em> a translation
  * has been set explicitly, than automatically an environment-dependant
  * translation is loaded.
  *
  * It is safe to call this function multiple times.
  *
  * @pre There exists exactly <em>one</em> instance of <tt>QCoreApplication</tt>
  * to which the parameter points. This function is called from the same thread
  * in which the <tt>QCoreApplication</tt> instance lives.
  *
  * @param instance A pointer to the <tt>QCoreApplication</tt> instance for
  *        which the initialization will be done.
  *
  * @param newUiLanguages List of translations, ordered by priority, most
  *        important ones first, like in <tt>QLocale::uiLanguages()</tt>. If
  *        <tt>std::optional::has_value()</tt> than the translation is
  *        initialized for this value, and previously loaded translations are
  *        removed. If <tt>std::optional::has_value()</tt> is <tt>false</tt>,
  *        than it depends: If no translation has been initialized so far, than
  *        the translation is initialized to an environment-dependent default
  *        value; otherwise there last initialization is simply repeated.
  *
  * @post The translation is initialized, even if a previous initialization
  * had been destroyed by deleting the previous QCoreApplication object. */
 void initializeTranslation(QCoreApplication *instance, std::optional<QStringList> newUiLanguages)
 {
     // Mutex protection
     static QMutex mutex;
 #if (QT_VERSION >= QT_VERSION_CHECK(6, 0, 0))
     QMutexLocker<QMutex> mutexLocker(&mutex);
 #else
     QMutexLocker mutexLocker(&mutex);
 #endif
 
     // Check of pre-conditions
     // The mutex lowers the risk when using QCoreApplication::instance()
     // and QThread::currentThread(), which are not explicitly documented
     // as thread-safe.
     if (instance == nullptr) {
         qWarning() //
             << __func__ //
             << "must not be called without a QCoreApplication object.";
         throw 0;
     }
     if (QThread::currentThread() != QCoreApplication::instance()->thread()) {
         qWarning() //
             << __func__ //
             << "must not be called by any other thread "
                "except the QCoreApplication thread.";
         throw 0;
     }
 
     // Static variables
     static QTranslator translator;
     // The last UI language list that was loaded:
     static std::optional<QStringList> translatorUiLanguages;
     // A guarded pointer to the QCoreApplication object for which
     // the translation is initialized. In the (strange) use case
     // that a library user deletes his QCoreApplication (and maybe
     // create a new one), this guarded pointer is set to nullptr.
     // We provide support for this use case because Q_COREAPP_STARTUP_FUNCTION
     // also does, and we want to provide a full-featured alternative
     // to Q_COREAPP_STARTUP_FUNCTION.
     static QPointer<QCoreApplication> instanceWhereTranslationIsInstalled;
 
     // Actual function implementation…
 
     if (!newUiLanguages.has_value()) {
         if (translatorUiLanguages.has_value()) {
             newUiLanguages = translatorUiLanguages;
         } else {
             newUiLanguages = //
                 QLocale().uiLanguages() + QLocale::system().uiLanguages();
         }
     }
 
     // NOTE Currently, this library does not use any plural forms in the
     // original English user-visible strings of the form "%1 color(s)".
     // If it becomes necessary to have these strings later, we have to
     // adapt this function: It has to install unconditionally first a
     // QTranslator for English, which resolves to "1 color" or "2 colors"
     // and so on. Then, a further QTranslator is installed for the target
     // language (but only if the target language is not English?). A
     // QTranslator that is installed later has higher priority. This makes
     // sure that, if a string is not translated to the target language,
     // the user does not see something like "1 color(s)" in the English
     // fallback, but instead "1 color".
 
     // QTranslator::load() will generate a QEvent::LanguageChange event
     // even if it loads the same translation file that was loaded anyway.
     // To avoid unnecessary events, we check if the new locale is really
     // different from the old locale: only than, we try to load the new
     // locale.
     //
     // Still, this will generate unnecessary events if in the previous call
     // of this function, we had tried to load a non-existing translation, so
     // that the QTranslator has an empty file path now. If we try to load now
     // another non-existing translation, we get an unnecessary event. But
     // to try to filter this out would be overkill…
     if (translatorUiLanguages != newUiLanguages) {
         // Resources can be loaded, and they can also be unloaded. Therefore,
         // here we make sure that our resources are actually currently loaded.
         // It is safe to call this function various times, and the overhead
         // should not be big.
         initializeLibraryResources();
 
         if (newUiLanguages.value().count() <= 0) {
             // QTranslator::load() will always delete the currently loaded
             // translation. After that, it will try to load the new one.
             // With this trick, we can delete the existing translation:
             Q_UNUSED( // We expect load() to fail, so we discard return value.
                 translator.load(
                     // Filename of the binary translation file (.qm):
                     QStringLiteral("nonexistingfilename"),
                     // Directory within which filename is searched
                     // if filename is a relative path:
                     QStringLiteral(":/PerceptualColor/i18n")));
         } else {
             bool loaded = false;
             int i = 0;
             // NOTE We will load the first translation among the translation
             // list for which we can find an actual translation file (qm file).
             // Example: The list is "fr", "es", "de". The qm file for "fr" does
             // not exist, but the "qm" filed for "es" and "de" exist. Only the
             // "es" translation is loaded. If a specific string is missing in
             // "es", but exists in "de", than the system will nevertheless
             // fallback to the original source code language ("en"). Of course,
             // it would be better to fallback to "de", but this would require
             // to load various QTranslator and this might be a overkill. While
             // KDE’s internationalization library explicitly supports this use
             // case, Qt doesn’t. And we do not have too many strings to
             // translate anyway. If we find out later that we have many
             // incomplete translations, we can still implement this feature…
             while (!loaded && i < newUiLanguages.value().count()) {
                 loaded = translator.load(
                     // The locale. From this locale are generated BCP47 codes.
                     // Various versions (upper-case and lower-case) are tried
                     // to load. If for more specific codes like "en-US" it
                     // does not succeed, than less specific variants like
                     // "en" are also tried.
                     QLocale(newUiLanguages.value().value(i)),
                     // First part of the filename
                     QStringLiteral("localization"),
                     // Separator after the first part of the filename
                     // (Intentionally NOT "_" or "-" to avoid confusion
                     // with the separators in BCP47 codes
                     QStringLiteral("."),
                     // Directory within which filename is searched
                     // if filename is a relative path:
                     QStringLiteral(":/PerceptualColor/i18n"));
                 ++i;
             }
         }
         translatorUiLanguages = newUiLanguages;
     }
 
     // Make sure that the translator is installed into the current
     // QCoreApplication instance. The library user cannot uninstall it
     // because this is only possible when you have a pointer to the
     // QTranslator object, but the pointer is kept a private information
     // of this function. So we can be confident that, if once installed
     // on a QCoreApplication object, the QTranslation object will stay
     // available. However, the library user could delete the existing
     // QCoreApplication object and create a new one. In this case,
     // our guarded pointer instanceWhereTranslationIsInstalled will
     // be set to nullptr, so we can detect this case:
     if (instanceWhereTranslationIsInstalled != instance) {
         if (instance->installTranslator(&translator)) {
             instanceWhereTranslationIsInstalled = instance;
         } else {
             instanceWhereTranslationIsInstalled = nullptr;
         }
     }
 }
 
 } // namespace PerceptualColor