From 2ecbaa7c29de2350486c6e83375ba8c83fee6cda Mon Sep 17 00:00:00 2001 From: Kai Koehne Date: Thu, 16 May 2019 17:15:01 +0200 Subject: Qt Linguist: Document CMake macros Task-number: QTBUG-72159 Change-Id: I817e1d562675c0aa462706a1e90e758030ce7d1e Reviewed-by: Leena Miettinen --- src/linguist/linguist/doc/cmake-macros.qdoc | 114 +++++++++++++++++++++ .../doc/snippets/cmake-macros/examples.cmake | 13 +++ 2 files changed, 127 insertions(+) create mode 100644 src/linguist/linguist/doc/cmake-macros.qdoc create mode 100644 src/linguist/linguist/doc/snippets/cmake-macros/examples.cmake diff --git a/src/linguist/linguist/doc/cmake-macros.qdoc b/src/linguist/linguist/doc/cmake-macros.qdoc new file mode 100644 index 000000000..68eb849f5 --- /dev/null +++ b/src/linguist/linguist/doc/cmake-macros.qdoc @@ -0,0 +1,114 @@ +/**************************************************************************** +** +** Copyright (C) 2019 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qtlinguist-cmake-qt5-add-translation.html +\ingroup cmake-macros-qtlinguisttools + +\title qt5_add_translation + +\brief Compiles Qt Linguist .ts files into .qm files. + +\section1 Synopsis + +\badcode +qt5_add_translation( file1.ts [file2.ts ...] + [OPTIONS ...]) +\endcode + +\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 root level of the build +directory. To change this, you can set \c{OUTPUT_LOCATION} as a property +of the source \c{.ts} file. + +\section1 Examples + +Generating \c{helloworld_en.qm}, \c{helloworld_de.qm} in the build +directory: + +\snippet cmake-macros/examples.cmake qt5_add_translation + +Generating \c{helloworld_en.qm}, \c{helloworld_de.qm} in a \c{l10n} +sub-directory: + +\snippet cmake-macros/examples.cmake qt5_add_translation_output_location +*/ + +/*! +\page qtlinguist-cmake-qt5-create-translation.html +\ingroup cmake-macros-qtlinguisttools + +\title qt5_create_translation + +\brief Sets up the Qt Linguist translation toolchain. + +\section1 Synopsis + +\badcode +qt5_create_translation( ts-file-or-sources [ts-file-or-sources2 ...] + [OPTIONS ...]) +\endcode + +\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 qt5_create_translation +*/ diff --git a/src/linguist/linguist/doc/snippets/cmake-macros/examples.cmake b/src/linguist/linguist/doc/snippets/cmake-macros/examples.cmake new file mode 100644 index 000000000..542ba7a6f --- /dev/null +++ b/src/linguist/linguist/doc/snippets/cmake-macros/examples.cmake @@ -0,0 +1,13 @@ +#! [qt5_add_translation] +qt5_add_translation(qmFiles helloworld_en.ts helloworld_de.ts) +#! [qt5_add_translation] + +#! [qt5_add_translation_output_location] +set(TS_FILES helloworld_en.ts helloworld_de.ts) +set_source_files_properties(${TS_FILES} PROPERTIES OUTPUT_LOCATION "l10n") +qt5_add_translation(qmFiles ${TS_FILES}) +#! [qt5_add_translation_output_location] + +#! [qt5_create_translation] +qt5_create_translation(QM_FILES ${CMAKE_SOURCE_DIR} helloworld_en.ts helloworld_de.ts) +#! [qt5_create_translation] -- cgit v1.2.3