Doc: Document the new CMake translation API

Fixes: QTBUG-95566
Change-Id: Ic3bdaf4c3880a007f549a667d66de9942e83ec07
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
(cherry picked from commit b634173e78b594e95d172feddf6be9e83c3a5648)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

3 files changed, 310 insertions, 1 deletions

diff --git a/src/linguist/linguist/doc/cmake-macros.qdoc b/src/linguist/linguist/doc/cmake-macros.qdoc
index b82739b07..384704931 100644
--- a/src/linguist/linguist/doc/cmake-macros.qdoc
+++ b/src/linguist/linguist/doc/cmake-macros.qdoc
@@ -34,6 +34,9 @@
 
 \brief Compiles Qt Linguist .ts files into .qm files.
 
+\warning This function is deprecated. Consider using the target-based
+functions \l{qt6_add_lrelease} or \l{qt6_add_translations} instead.
+
 \section1 Synopsis
 
 \badcode
@@ -58,6 +61,11 @@ By default, the \c{qm} files will be placed in the root level of the build
 directory. To change this, you can set \c{OUTPUT_LOCATION} as a property
 of the source \c{.ts} file.
 
+For example, with the following code, the \c{.qm} files are generated
+in a \c{translations} directory below the build directory.
+
+\snippet cmake-macros/examples.cmake set_output_location_on_ts_file
+
 \section1 Examples
 
 Generating \c{helloworld_en.qm}, \c{helloworld_de.qm} in the build
@@ -78,6 +86,9 @@ sub-directory:
 \title qt_create_translation
 \target qt6_create_translation
 
+\warning This function is deprecated. Consider using the target-based
+functions \l{qt6_add_lupdate} or \l{qt6_add_translations} instead.
+
 \brief Sets up the Qt Linguist translation toolchain.
 
 \section1 Synopsis
@@ -117,3 +128,254 @@ files in the build directory:
 
 \snippet cmake-macros/examples.cmake qt_create_translation
 */
+
+/*!
+\page qtlinguist-cmake-qt-add-lupdate.html
+\ingroup cmake-macros-qtlinguisttools
+
+\title qt_add_lupdate
+\target qt6_add_lupdate
+
+\brief Add targets to generate or update Qt Linguist .ts files.
+
+\section1 Synopsis
+
+\badcode
+qt_add_lupdate(target TS_FILES file1.ts [file2.ts ...]
+               [SOURCES source1.cpp [sources2.cpp ...]]
+               [INCLUDE_DIRECTORIES directory1 [directory2 ...]]
+               [NO_GLOBAL_TARGET]
+               [OPTIONS ...])
+\endcode
+
+\versionlessNote qt6_add_lupdate()
+
+\section1 Description
+
+Creates a target \c{${target}_lupdate} to generate or update Qt Linguist \c{.ts}
+files with \l{lupdate}.
+
+The parameter \c{target} is an existing executable or library target that
+contains sources with translatable strings.
+
+The \c{.ts} files must be specified with the argument \c{TS_FILES}.
+
+This function is designed to be used in conjunction with
+\l{qt6_add_lrelease}{qt_add_lrelease}.  See also the convenience wrapper
+\l{qt6_add_translations}{qt_add_translations}.
+
+\section1 Sources and Include Directories
+
+By default, \c{qt_add_lupdate} extracts the source files and include directories
+from the given target and passes them to \c{lupdate}.
+
+With \c{SOURCES} one may explicitly specify source files that contain
+translatable strings. This turns off the automatic extraction of source files
+from the target.
+
+\c{INCLUDE_DIRECTORIES} can be used to explicitly specify include directories.
+This turns off the automatic extraction of include directories from the target.
+
+\section1 Options
+
+You can set additional \c{OPTIONS} that should be passed when \c{lupdate} is
+invoked. You can find possible options in the \l{lupdate}{lupdate
+documentation}.
+
+\section1 Umbrella Target
+
+In addition to the target \c{${target}_lupdate}, an umbrella target
+\c{update_translations} is created. This target will build all
+\c{${target}_lupdate} targets that were created with \c{qt_add_lupdate}.
+
+Pass \c{NO_GLOBAL_TARGET} to \c{qt_add_lupdate} to prevent this behavior.
+
+The name of this target can be overridden by setting the variable
+\c{QT_GLOBAL_LUPDATE_TARGET} before calling \c{qt_add_lupdate}.
+
+\section1 Examples
+
+Add the targets \c{myapp_lupdate} and \c{update_translations} for updating the
+\c{.ts} file of an application \c{myapp}.
+
+\snippet cmake-macros/examples.cmake qt_add_lupdate
+*/
+
+/*!
+\page qtlinguist-cmake-qt-add-lrelease.html
+\ingroup cmake-macros-qtlinguisttools
+
+\title qt_add_lrelease
+\target qt6_add_lrelease
+
+\brief Add targets to transform Qt Linguist .ts files into .qm files.
+
+\section1 Synopsis
+
+\badcode
+qt_add_lrelease(target TS_FILES file1.ts [file2.ts ...]
+                [NO_TARGET_DEPENDENCY]
+                [NO_GLOBAL_TARGET]
+                [QM_FILES_OUTPUT_VARIABLE variable-name]
+                [OPTIONS ...])
+\endcode
+
+\versionlessNote qt6_add_lrelease()
+
+\section1 Description
+
+Creates a target \c{${target}_lrelease} to transform \c{.ts} files into \c{.qm}
+files with \l{lrelease}.
+
+The parameter \c{target} is an existing executable or library target that
+contains sources with translatable strings.
+
+The \c{.ts} files must be specified with the argument \c{TS_FILES}.
+
+This function is designed to be used in conjunction with
+\l{qt6_add_lupdate}{qt_add_lupdate}.  See also the convenience wrapper
+\l{qt6_add_translations}{qt_add_translations}.
+
+\section1 Options
+
+You can set additional \c{OPTIONS} that should be passed when \c{lrelease} is
+invoked. You can find possible options in the \l{lrelease}{lrelease
+documentation}.
+
+By default, the \c{.qm} files will be placed in the root level of the build
+directory. To change this, you can set \c{OUTPUT_LOCATION} as a property
+of the source \c{.ts} file.
+
+For example, with the following code, the \c{.qm} files are generated
+in a \c{translations} directory below the build directory.
+
+\snippet cmake-macros/examples.cmake set_output_location_on_ts_file
+
+\section1 Processing Generated .qm Files
+
+To further process the generated \c{.qm} files, for example to create install
+rules, \c{qt_add_lrelease} can store the paths of the \c{.qm} files in a
+variable. Pass \c{QM_FILES_OUTPUT_VARIABLE <variable-name>} to the function for
+that.
+
+\section1 Build by Default
+
+By default, the command makes \c{${target}} depend on \c{${target}_lrelease}.
+This ensures that the \c{.qm} files are always up-to-date when \c{${target}} is
+built. This behavior can be turned off with \c{NO_TARGET_DEPENDENCY}. In this
+case, the user must build the \c{${target}_lrelease} target manually.
+
+\section1 Umbrella Target
+
+In addition to the target \c{${target}_lrelease}, an umbrella target
+\c{release_translations} is created. This target will build all
+\c{${target}_lrelease} targets that were created with \c{qt_add_lrelease}.
+
+Pass \c{NO_GLOBAL_TARGET} to \c{qt_add_lrelease} to prevent this behavior.
+
+The name of this target can be overridden by setting the variable
+\c{QT_GLOBAL_LRELEASE_TARGET} before calling \c{qt_add_lrelease}.
+
+\section1 Examples
+
+Add the targets \c{myapp_lrelease} and \c{update_translations} for updating the
+\c{.ts} file of an application \c{myapp}. Also, install the generated \c{.qm}
+files.
+
+\snippet cmake-macros/examples.cmake qt_add_lrelease_install
+*/
+
+/*!
+\page qtlinguist-cmake-qt-add-translations.html
+\ingroup cmake-macros-qtlinguisttools
+
+\title qt_add_translations
+\target qt6_add_translations
+
+\brief Add targets to update and transform Qt Linguist .ts files into .qm files.
+
+\section1 Synopsis
+
+\badcode
+qt_add_translations(target TS_FILES file1.ts [file2.ts ...]
+                    [RESOURCE_PREFIX [OUTPUT_TARGETS variable-name]]
+                    [QM_FILES_OUTPUT_VARIABLE variable-name]
+                    [SOURCES]
+                    [INCLUDE_DIRECTORIES]
+                    [LUPDATE_OPTIONS]
+                    [LRELEASE_OPTIONS])
+\endcode
+
+\versionlessNote qt6_add_translations()
+
+\preliminarycmakecommand
+
+\section1 Description
+
+Creates targets for updating Qt Linguist \c{.ts} files and for transforming them
+into \c{.qm} files. This function is a convenience wrapper around
+\l{qt6_add_lupdate}{qt_add_lupdate} and \l{qt6_add_lrelease}{qt_add_lrelease}
+and aims to offer the most common usage of both functions with one call.
+
+The parameter \c{target} is an existing executable or library target that
+contains sources with translatable strings. This function will create the
+targets \c{${target}_lupdate}, \c{${target}_lrelease}, \c{update_translations}
+and \c{release_translations}. The latter targets are umbrella targets that build
+all \c{${target}_lupdate} and \c{${target}}_lrelease targets.
+
+\c{${target}_lrelease} is built automatically whenever \c{${target}} needs to be
+built.
+
+The \c{.ts} files must be specified with the argument \c{TS_FILES}.
+
+\section1 Options
+
+You can set additional options for \l{lupdate} and \l{lrelease} with
+\c{LUPDATE_OPTIONS} and \c{LRELEASE_OPTIONS}. You can find possible options in
+the \l{translations}{translations documentation}.
+
+By default, the \c{.qm} files will be placed in the root level of the build
+directory. To change this, you can set \c{OUTPUT_LOCATION} as a property
+of the source \c{.ts} file.
+
+For example, with the following code, the \c{.qm} files are generated
+in a \c{translations} directory below the build directory.
+
+\snippet cmake-macros/examples.cmake set_output_location_on_ts_file
+
+\section1 Embedding Generated .qm Files in Resources
+
+By default, the generated \c{.qm} files are embedded in a Qt resource that will
+be linked into \c{${target}}. The files in the resource are accessible under the
+resource prefix \c{"/i18n"}.
+
+You can set the resource prefix with \c{RESOURCE_PREFIX}.
+
+In a static Qt build, when a resource target is created, additional targets can
+be created. You can instruct \c{qt_add_translations} to store these targets in a
+variable, by passing \c{OUTPUT_TARGETS <variable-name>}.
+
+The automatic resource embedding can be turned off by giving the
+\c{QM_FILES_OUTPUT_VARIABLE} option, followed by the name of a variable in which
+the command should store the list of generated \c{.qm} files.
+
+\section1 Examples
+
+Add a German translation to a target \c{super_calc} using
+\c{qt_add_translations}.
+
+\snippet cmake-macros/examples.cmake qt_add_translations_default
+
+This is roughly equivalent to the following.
+
+\snippet cmake-macros/examples.cmake qt_lupdate_lrelease
+
+Add a Norwegian translation to \c{frogger_game} with a custom resource prefix.
+
+\snippet cmake-macros/examples.cmake qt_add_translations_resource_prefix
+
+Add a Finnish translation to \c{business_logic}, and install the generated
+\c{.qm} files.
+
+\snippet cmake-macros/examples.cmake qt_add_translations_install
+*/
diff --git a/src/linguist/linguist/doc/qtlinguist.qdocconf b/src/linguist/linguist/doc/qtlinguist.qdocconf
index 595471aa1..ead0e5f9c 100644
--- a/src/linguist/linguist/doc/qtlinguist.qdocconf
+++ b/src/linguist/linguist/doc/qtlinguist.qdocconf
@@ -34,8 +34,11 @@ exampledirs             = ../../../../examples/linguist \
 
 imagedirs               = images
 
-depends                 += qtdoc qtqml qtquick qtcore qtgui qmake
+depends                 += qtdoc qtqml qtquick qtcore qtgui qmake qtcmake
 
 navigation.landingpage = "Qt Linguist Manual"
 
 warninglimit = 0
+
+# QTBUG-95796: Remove, once this macro is defined in qtbase.
+macro.versionlessNote = "If \\l{Versionless commands}{versionless commands} are disabled, use \\c{\1} instead. It supports the same set of arguments as this command."
diff --git a/src/linguist/linguist/doc/snippets/cmake-macros/examples.cmake b/src/linguist/linguist/doc/snippets/cmake-macros/examples.cmake
index c91fe5536..02ecd53d0 100644
--- a/src/linguist/linguist/doc/snippets/cmake-macros/examples.cmake
+++ b/src/linguist/linguist/doc/snippets/cmake-macros/examples.cmake
@@ -11,3 +11,47 @@ qt_add_translation(qmFiles ${TS_FILES})
 #! [qt_create_translation]
 qt_create_translation(QM_FILES ${CMAKE_SOURCE_DIR} helloworld_en.ts helloworld_de.ts)
 #! [qt_create_translation]
+
+#! [set_output_location_on_ts_file]
+set_source_files_properties(app_en.ts app_de.ts
+    PROPERTIES OUTPUT_LOCATION "${CMAKE_CURRENT_BINARY_DIR}/translations")
+#! [set_output_location_on_ts_file]
+
+#! [qt_add_lupdate]
+qt6_add_lupdate(myapp TS_FILES myapp_de.ts)
+#! [qt_add_lupdate]
+
+#! [qt_add_lrelease_install]
+qt6_add_lrelease(myapp
+    TS_FILES myapp_de.ts
+    QM_FILES_OUTPUT_VARIABLE qm_files)
+install(FILES ${qm_files} DESTINATION "translations")
+#! [qt_add_lrelease_install]
+
+#! [qt_add_translations_default]
+qt6_add_translations(super_calc TS_FILES super_calc_de.ts)
+#! [qt_add_translations_default]
+
+#! [qt_lupdate_lrelease]
+qt6_add_lupdate(super_calc TS_FILES super_calc_de.ts)
+qt6_add_lrelease(super_calc
+    TS_FILES super_calc_de.ts
+    QM_FILES_OUTPUT_VARIABLE qm_files)
+qt6_add_resource(super_calc "translations"
+    PREFIX "/i18n"
+    BASE "${CMAKE_CURRENT_BINARY_DIR}"
+    FILES "${qm_files}")
+#! [qt_lupdate_lrelease]
+
+#! [qt_add_translations_resource_prefix]
+qt6_add_translations(frogger_game
+    TS_FILES frogger_game_no.ts
+    RESOURCE_PREFIX "/translations")
+#! [qt_add_translations_resource_prefix]
+
+#! [qt_add_translations_install]
+qt6_add_translations(business_logic
+    TS_FILES myapp_fi.ts
+    QM_FILES_OUTPUT_VARIABLE qm_files)
+install(FILES ${qm_files} DESTINATION "translations")
+#! [qt_add_translations_install]