QQmlEngine: Introduce markCurrentFunctionAsTranslationBinding

The general recommendation to handle language changes in QML is to
handle the LanguageChange event. However, if one is willing to tie
themselves to the QQmlEngine, we can offer a way to ensure that calling
a function will result in a traslation binding.

This might also be helpful for anyone implementing a translation system
different from Qt's, e.g. KDE's i18n.

Fixes: QTBUG-102393
Change-Id: Id4d7a401e0be9d65e1769c8471b26689f44bf66a
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>

2 files changed, 41 insertions, 0 deletions

diff --git a/src/qml/qml/qqmlengine.cpp b/src/qml/qml/qqmlengine.cpp
index 285da1a4e4..9c7d9f302e 100644
--- a/src/qml/qml/qqmlengine.cpp
+++ b/src/qml/qml/qqmlengine.cpp
@@ -927,6 +927,45 @@ void QQmlEngine::setOutputWarningsToStandardError(bool enabled)
     d->outputWarningsToMsgLog = enabled;
 }
 
+
+/*!
+  \since 6.6
+  If this method is called inside of a function that is part of
+  a binding in QML, the binding will be treated as a translation binding.
+
+  \code
+  class I18nAwareClass : public QObject {
+
+    //...
+
+     QString text() const
+     {
+          if (auto engine = qmlEngine(this))
+              engine->markCurrentFunctionAsTranslationBinding();
+          return tr("Hello, world!");
+     }
+  };
+  \endcode
+
+  \note This function is mostly useful if you wish to provide your
+  own alternative to the qsTr function. To ensure that properties
+  exposed from C++ classes are updated on language changes, it is
+  instead recommended to react to \c LanguageChange events. That
+  is a more general mechanism which also works when the class is
+  used in a non-QML context, and has slightly less overhead. However,
+  using \c markCurrentFunctionAsTranslationBinding can be acceptable
+  when the class is already closely tied to the QML engine.
+  For more details, see \l {Prepare for Dynamic Language Changes}
+
+  \sa QQmlEngine::retranslate
+*/
+void QQmlEngine::markCurrentFunctionAsTranslationBinding()
+{
+    Q_D(QQmlEngine);
+    if (auto propertyCapture = d->propertyCapture)
+        propertyCapture->captureTranslation();
+}
+
 /*!
   \internal
 
diff --git a/src/qml/qml/qqmlengine.h b/src/qml/qml/qqmlengine.h
index a8b19e41c6..9c20090613 100644
--- a/src/qml/qml/qqmlengine.h
+++ b/src/qml/qml/qqmlengine.h
@@ -123,6 +123,8 @@ public:
     bool outputWarningsToStandardError() const;
     void setOutputWarningsToStandardError(bool);
 
+    void markCurrentFunctionAsTranslationBinding();
+
     template<typename T>
     T singletonInstance(int qmlTypeId);