CMake: Introduce qt_deploy_translations

Add the command qt_deploy_translations to the CMake deployment API.
This can be used to deploy a set of Qt translations.

This command is supposed to be called by the generic deployment tool in
a future commit.

[ChangeLog][CMake] Added qt_deploy_translations for deploying Qt
translation catalogs in user projects.

Change-Id: I4492a5042970cf89b2be2ed0c34521c7af904771
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>

2 files changed, 114 insertions, 5 deletions

diff --git a/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc b/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc
index b10de9dc3b..8182dd74e4 100644
--- a/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc
+++ b/src/corelib/doc/src/cmake/cmake-deploy-variables.qdoc
@@ -49,7 +49,7 @@ install location and just use the prefix-relative \c{QT_DEPLOY_..._DIR}
 variables.
 
 \sa QT_DEPLOY_SUPPORT, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR,
-    QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR
+    QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, QT_DEPLOY_TRANSLATIONS_DIR
 */
 
 /*!
@@ -90,7 +90,7 @@ should not be used for that scenario.
 \include cmake-deploy-runtime-dependencies.qdocinc
 
 \sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_LIB_DIR,
-    QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR
+    QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, QT_DEPLOY_TRANSLATIONS_DIR
 */
 
 /*!
@@ -132,7 +132,7 @@ should not be used for that scenario.
 \include cmake-deploy-modified-variable-values.qdocinc
 
 \sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR,
-    QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR
+    QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR, QT_DEPLOY_TRANSLATIONS_DIR
 */
 
 /*!
@@ -168,7 +168,7 @@ bundle contents.
 \include cmake-deploy-modified-variable-values.qdocinc
 
 \sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR,
-    QT_DEPLOY_QML_DIR
+    QT_DEPLOY_QML_DIR, QT_DEPLOY_TRANSLATIONS_DIR
 */
 
 /*!
@@ -206,5 +206,38 @@ to be deployed to different locations within the app bundle.
 \include cmake-deploy-modified-variable-values.qdocinc
 
 \sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR,
-    QT_DEPLOY_PLUGINS_DIR
+    QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_TRANSLATIONS_DIR
+*/
+
+/*!
+\page cmake-variable-QT_DEPLOY_TRANSLATIONS_DIR.html
+\ingroup cmake-variables-qtcore
+
+\title QT_DEPLOY_TRANSLATIONS_DIR
+\target cmake-variable-QT_DEPLOY_TRANSLATIONS_DIR
+
+\summary {Prefix-relative subdirectory for deploying Qt translations on some target platforms.}
+
+\include cmake-deploy-var-usage.qdocinc
+
+\cmakevariablesince 6.5
+\preliminarycmakevariable
+
+Projects should use \c QT_DEPLOY_TRANSLATIONS_DIR in their deploy scripts to
+avoid hard-coding a particular directory under which to deploy translations.
+
+\c QT_DEPLOY_TRANSLATIONS_DIR defaults to the value \c{translations}. To change
+the value of \c QT_DEPLOY_TRANSLATIONS_DIR, set it in the project deployment
+script before \c QT_DEPLOY_SUPPORT is included.
+
+The \c QT_DEPLOY_TRANSLATIONS_DIR path is relative to \l{QT_DEPLOY_PREFIX}.
+
+This variable is not meaningful when deploying on macOS or Windows.
+
+\section1 Example
+
+\include cmake-deploy-modified-variable-values.qdocinc
+
+\sa QT_DEPLOY_SUPPORT, QT_DEPLOY_PREFIX, QT_DEPLOY_BIN_DIR, QT_DEPLOY_LIB_DIR,
+    QT_DEPLOY_PLUGINS_DIR, QT_DEPLOY_QML_DIR
 */
diff --git a/src/corelib/doc/src/cmake/qt_deploy_translations.qdoc b/src/corelib/doc/src/cmake/qt_deploy_translations.qdoc
new file mode 100644
index 0000000000..87ef7cd2fc
--- /dev/null
+++ b/src/corelib/doc/src/cmake/qt_deploy_translations.qdoc
@@ -0,0 +1,76 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+\page qt_deploy_translations.html
+\ingroup cmake-commands-qtcore
+
+\title qt_deploy_translations
+\target qt_deploy_translations
+
+\summary {Deploy Qt translations needed by an executable.}
+
+\include cmake-find-package-core.qdocinc
+
+Unlike most other CMake commands provided by Qt, \c{qt_deploy_translations()}
+can only be called from a deployment script. It cannot be called directly by the
+project during the configure stage.
+
+\cmakecommandsince 6.5
+\preliminarycmakecommand
+\note This command does not usually need to be called directly. It is used
+      internally by other higher level commands, but projects wishing to
+      implement more customized deployment logic may find it useful.
+
+\section1 Synopsis
+
+\badcode
+qt_deploy_translations(
+    [CATALOGS catalogs]
+    [LOCALES locales]
+    [LCONVERT lconvert_executable]
+    [VERBOSE]
+)
+\endcode
+
+\section1 Description
+
+When installing an application, it may be desirable to also install the
+translations that belong to the used Qt modules. The \c qt_deploy_translations
+command collects the necessary \c{.qm} file from the Qt installation and
+compiles them into one \c{qt_${language}.qm} file per language. The \c{.qm}
+files are installed into \c{QT_DEPLOY_TRANSLATIONS_DIR}.
+
+\section1 Arguments
+
+The \c LOCALES argument specifies for which locales translations should be
+deployed. This is a list of language/region combinations as described in
+\l{Changing the Target Locale}{Qt Linguist's manual for translators}. Examples
+for valid locales are: \c{de}, \c{pl}, or \c{pt_BR}.
+
+If \c LOCALES is omitted, then all available locales are deployed.
+
+The \c CATALOGS argument specifies a list of \l{Available
+Catalogs}{translation catalogs} to be deployed. If this argument is
+omitted, then all catalogs are deployed that belong to any Qt module
+that is used in the project via \c{find_package}.
+
+The \c LCONVERT argument specifies the \c lconvert executable that is used to
+combine the catalogs. By default, the Qt installation's \c lconvert is used.
+
+For debugging purposed, the \c VERBOSE argument can be set to turn on diagnostic
+messages.
+
+\sa QT_DEPLOY_TRANSLATIONS_DIR
+
+\section1 Example
+
+The following example deploys Danish and German translations of the Qt
+libraries.
+
+\badcode
+qt_deploy_translations(
+    LOCALES da de
+)
+\endcode
+*/