// Copyright (C) 2020 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
\group cmake-commands-qtlinguisttools
\title CMake Commands in Qt6 LinguistTools

The following CMake commands are defined when Qt6::LinguistTools is loaded, for instance
with

\code
find_package(Qt6 REQUIRED COMPONENTS LinguistTools)
\endcode

\sa{CMake Command Reference}
*/

/*!
\page qtlinguist-cmake-qt-add-translation.html
\ingroup cmake-commands-qtlinguisttools

\title qt_add_translation
\target qt6_add_translation

\summary {Compiles Qt Linguist .ts files into .qm files.}

\include cmake-find-package-linguisttools.qdocinc

\warning This function is deprecated. Consider using the target-based
functions \l{qt6_add_lrelease} or \l{qt6_add_translations} instead.

\section1 Synopsis

\badcode
qt_add_translation(<VAR> file1.ts [file2.ts ...]
                    [OPTIONS ...])
\endcode

\versionlessCMakeCommandsNote qt6_add_translation

\section1 Description

Calls \c{lrelease} on each \c{.ts} file passed as an argument, generating
\c{.qm} files. The paths of the generated files are added to \c{<VAR>}.

\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 current build directory
(\c{CMAKE_CURRENT_BINARY_DIR}). 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 current 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
directory:

\snippet cmake-macros/examples.cmake qt_add_translation

Generating \c{helloworld_en.qm}, \c{helloworld_de.qm} in a \c{l10n}
sub-directory:

\snippet cmake-macros/examples.cmake qt_add_translation_output_location
*/

/*!
\page qtlinguist-cmake-qt-create-translation.html
\ingroup cmake-commands-qtlinguisttools

\title qt_create_translation
\target qt6_create_translation

\summary {Sets up the Qt Linguist translation toolchain.}

\include cmake-find-package-linguisttools.qdocinc

\warning This function is deprecated. Consider using the target-based
functions \l{qt6_add_lupdate} or \l{qt6_add_translations} instead.

\section1 Synopsis

\badcode
qt_create_translation(<VAR> ts-file-or-sources [ts-file-or-sources2 ...]
                      [OPTIONS ...])
\endcode

\versionlessCMakeCommandsNote qt6_create_translation

\section1 Description

Processes given sources (directories or individual files) to generate
Qt Linguist \c{.ts} files. The \c{.ts} files are in turn compiled into \c{.qm}
files of the same base name that are stored in the build
directory. Paths to the generated \c{.qm} files are added to \c{<VAR>}.

The translation files to create or update need to have a \c{.ts} suffix. If
the given file path is not absolute it is resolved relative to the current
source directory. If no \c{.ts} file is passed as an argument, the macro
does nothing.

Any arguments that do not have a \c{.ts} suffix are passed as input to the
\c{lupdate}. \c{lupdate} accepts directories and source files as input.
See also the \l{lupdate}{lupdate documentation} on further details.

\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 Examples

Recursively look up Qt translations from source files in current directory and
generate or update \c{helloworld_en.ts} and \c{helloworld_de.ts} file using
\c{lupdate}. Compile said files into \c{helloworld_en.qm} and \c{helloworld.de.qm}
files in the build directory:

\snippet cmake-macros/examples.cmake qt_create_translation
*/

/*!
\page qtlinguist-cmake-qt-add-lupdate.html
\ingroup cmake-commands-qtlinguisttools

\title qt_add_lupdate
\target qt6_add_lupdate

\summary {Add targets to generate or update Qt Linguist .ts files.}

\include cmake-find-package-linguisttools.qdocinc

\cmakecommandsince 6.2

\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

\versionlessCMakeCommandsNote 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}.

//! [sources-and-include-dirs]
\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} you can explicitly specify source files that contain
translatable strings. This turns off the automatic extraction of source files
from the target.

You can use \c{INCLUDE_DIRECTORIES} to explicitly specify include directories.
This turns off the automatic extraction of include directories from the target.
//! [sources-and-include-dirs]

\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-commands-qtlinguisttools

\title qt_add_lrelease
\target qt6_add_lrelease

\summary {Add targets to transform Qt Linguist .ts files into .qm files.}

\include cmake-find-package-linguisttools.qdocinc

\cmakecommandsince 6.2

\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

\versionlessCMakeCommandsNote qt6_add_lrelease()

\warning Calling \c qt_add_lrelease in a directory scope different than the
target directory scope requires at least CMake version 3.18.

\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 current build directory
(\c{CMAKE_CURRENT_BINARY_DIR}). 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 current 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-commands-qtlinguisttools

\title qt_add_translations
\target qt6_add_translations

\summary {Add targets to update and transform Qt Linguist .ts files into .qm files.}

\include cmake-find-package-linguisttools.qdocinc

\cmakecommandsince 6.2

\section1 Synopsis

\badcode
qt_add_translations(target TS_FILES file1.ts [file2.ts ...]
                    [RESOURCE_PREFIX prefix]
                    [OUTPUT_TARGETS variable-name]
                    [QM_FILES_OUTPUT_VARIABLE variable-name]
                    [SOURCES source1.cpp [sources2.cpp ...]]
                    [INCLUDE_DIRECTORIES directory1 [directory2 ...]]
                    [LUPDATE_OPTIONS ...]
                    [LRELEASE_OPTIONS ...])
\endcode

\versionlessCMakeCommandsNote qt6_add_translations()

\preliminarycmakecommand

\warning Calling \c qt_add_translations in a directory scope different than the
target directory scope requires at least CMake version 3.18.

\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}.

\include cmake-macros.qdoc sources-and-include-dirs

\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{lupdate options} and \l{lrelease options}.

By default, the \c{.qm} files will be placed in the current build directory
(\c{CMAKE_CURRENT_BINARY_DIR}). 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 current 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
*/
