// 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( 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{}. \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( 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{}. 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 } 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 }. 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 */