support for id-based translations

unlike in an earlier attempt, ids are textual this time.

the developer is able to provide a template for the string. when lupdate
and lrelease are integrated into the build process, this makes it
possible to avoid a round-trip to a dedicated string designer during the
early development stage.

Requirement-id: QT-435

3 files changed, 74 insertions, 0 deletions

diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp
index f7a97e1..ad4868d 100644
--- a/src/corelib/global/qglobal.cpp
+++ b/src/corelib/global/qglobal.cpp
@@ -2459,6 +2459,62 @@ int qrand()
 */
 
 /*!
+    \fn QString qtTrId(const char *id, int n = -1)
+    \relates <QtGlobal>
+    \reentrant
+    \since 4.6
+
+    Returns a translated string identified by \a id.
+    If no matching string is found, the id itself is returned. This
+    should not happen under normal conditions.
+
+    If \a n >= 0, all occurrences of \c %n in the resulting string
+    are replaced with a decimal representation of \a n. In addition,
+    depending on \a n's value, the translation text may vary.
+
+    Meta data and comments can be passed as documented for QObject::tr().
+    In addition, it is possible to supply a source string template like that:
+
+    \tt{//% <C string>}
+
+    or
+
+    \tt{\begincomment% <C string> \endcomment}
+
+    Example:
+
+    \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp qttrid
+
+    Creating QM files suitable for use with this function requires passing
+    the \c -idbased option to the \c lrelease tool.
+
+    \warning This method is reentrant only if all translators are
+    installed \e before calling this method. Installing or removing
+    translators while performing translations is not supported. Doing
+    so will probably result in crashes or other undesirable behavior.
+
+    \sa QObject::tr(), QCoreApplication::translate(), {Internationalization with Qt}
+*/
+
+/*!
+    \macro QT_TRID_NOOP(id)
+    \relates <QtGlobal>
+    \since 4.6
+
+    Marks \a id for dynamic translation.
+    The only purpose of this macro is to provide an anchor for attaching
+    meta data like to qtTrId().
+
+    The macro expands to \a id.
+
+    Example:
+
+    \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp qttrid_noop
+
+    \sa qtTrId(), {Internationalization with Qt}
+*/
+
+/*!
     \macro QT_POINTER_SIZE
     \relates <QtGlobal>
 
diff --git a/src/corelib/global/qglobal.h b/src/corelib/global/qglobal.h
index a522bcf..a139a55 100644
--- a/src/corelib/global/qglobal.h
+++ b/src/corelib/global/qglobal.h
@@ -2198,6 +2198,18 @@ inline const QForeachContainer<T> *qForeachContainer(const QForeachContainerBase
 #define QT_TRANSLATE_NOOP_UTF8(scope, x) (x)
 #define QT_TRANSLATE_NOOP3(scope, x, comment) {x, comment}
 #define QT_TRANSLATE_NOOP3_UTF8(scope, x, comment) {x, comment}
+
+#ifndef QT_NO_TRANSLATION // ### This should enclose the NOOPs above
+
+// Defined in qcoreapplication.cpp
+// The better name qTrId() is reserved for an upcoming function which would
+// return a much more powerful QStringFormatter instead of a QString.
+Q_CORE_EXPORT QString qtTrId(const char *id, int n = -1);
+
+#define QT_TRID_NOOP(id) id
+
+#endif // QT_NO_TRANSLATION
+
 #define QDOC_PROPERTY(text)
 
 /*
diff --git a/src/corelib/kernel/qcoreapplication.cpp b/src/corelib/kernel/qcoreapplication.cpp
index e2708c3..054be70 100644
--- a/src/corelib/kernel/qcoreapplication.cpp
+++ b/src/corelib/kernel/qcoreapplication.cpp
@@ -1675,6 +1675,12 @@ QString QCoreApplication::translate(const char *context, const char *sourceText,
     return result;
 }
 
+// Declared in qglobal.h
+QString qtTrId(const char *id, int n)
+{
+    return QCoreApplication::translate(0, id, 0, QCoreApplication::UnicodeUTF8, n);
+}
+
 bool QCoreApplicationPrivate::isTranslatorInstalled(QTranslator *translator)
 {
     return QCoreApplication::self