linguist-manual.qdoc

Go to the documentation of this file.

// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
    \page qtlinguist-index.html
    \title Qt Linguist Manual
    \ingroup qttools
    \ingroup internationalization
    \brief Using Qt translation tools: lupdate, lrelease, and \QL.
 
    \startpage {index.html}{Qt Reference Documentation}
    \nextpage Release managers
 
    \keyword Qt Linguist
 
    Release managers, translators, and developers can use Qt tools to translate
    Qt C++ and Qt Quick applications into local languages.
 
    In addition to the Qt translation file (TS) format, \QL and \c lupdate
    support XML Localization Interchange File Format (XLIFF).
 
    \table
    \row
        \li \inlineimage front-publishing.png {Icon showing an publishing action}
        \li \inlineimage front-ui.png {UI illustration showing Start buttons,
                         toggle controls, and a circular selector on a dark
                         screen}
        \li \inlineimage front-coding.png {Illustration showing a code}
    \row
        \li \l{Release managers}
        \li \l{Translators}
        \li \l{Developers}
    \row
        \li
            \list
                \li \l {Creating translation files}
                \li \l {Using lupdate}
                \li \l {Using lrelease}
                \li \l {Using lconvert}
                \li \l {Using lcheck}
            \endlist
        \li
            \list
                \li \l {Qt Linguist user interface}
                \li \l {Translating strings}
                \li \l {Selecting context or label to translate}
                \li \l {Selecting strings to translate}
                \li \l {Viewing strings in context}
                \li \l {Reusing translations}
                \li \l {Validating translations}
                \li \l {Translating multiple languages simultaneously}
            \endlist
        \li
            \list
                \li \l{TS file format}
                \li \l{Text ID based translations}
                \li \l{Meta strings reference}
                \li \l{CMake Commands in Qt6 LinguistTools}{CMake commands}
                \li \l{Examples}
            \endlist
    \endtable
 
    The following video shows how to internationalize and localize a simple
    example application:
 
    \youtube xNIz78IPBu0
*/
 
/*!
    \page linguist-toc.html
    \title All topics
 
    \list
        \li \l{Release managers}
            \list
                \li \l {Creating translation files}
                \li \l {Using lupdate}
                \li \l {Using lrelease}
            \endlist
        \li \l{Translators}
            \list
                \li \l {Qt Linguist user interface}
                \li \l {Translating strings}
                \li \l {Selecting context or label to translate}
                \li \l {Selecting strings to translate}
                \li \l {Viewing strings in context}
                \li \l {Reusing translations}
                \li \l {Validating translations}
                \li \l {Translating multiple languages simultaneously}
            \endlist
        \li \l{Developers}
            \list
                \li \l{TS file format}
                \li \l{Text ID based translations}
                \li \l{Meta strings reference}
                \li \l{CMake Commands in Qt6 LinguistTools}{CMake commands}
                \li \l{Examples}
            \endlist
    \endlist
 */
 
/*!
    \page linguist-manager.html
    \title Release managers
 
    \previouspage Qt Linguist Manual
    \nextpage Creating translation files
 
    \image front-publishing.png {Icon showing an publishing action}
 
    Release managers use \c lupdate to generate a set of translation source (TS)
    files from the application source files (QML and C++) and pass them to
    translators. The translators use \QL to translate the strings and pass the
    TS files back to the release managers. They use \c lrelease to generate
    compact versions of the TS files, called Qt message (QM) files, that are
    ready for use by the application.
 
    \list
        \li \l {Creating translation files}
        \li \l {Using lupdate}
        \li \l {Using lrelease}
    \endlist
 
    You can use the tools in repeated cycles as applications change and evolve.
    They preserve existing translations and make it easy to identify new strings.
    In addition, you can use the \QL phrase books to consistently translate
    multiple applications and projects.
 
    You can configure CMake projects to automatically run \c lupdate and
    \c lrelease when you build a project and generate TS and QM files for you.
 
    You can use the Qt Design Studio
    \l{https://doc-snapshots.qt.io/qtdesignstudio/studio-translations.html}
    {Translations} view to test and manage \l {Text ID based translations}
    {ID-based translations}.
*/
 
/*!
    \page linguist-creating-ts-files.html
 
    \previouspage Release managers
    \nextpage Using lupdate
 
    \title Creating translation files
 
    Most of the text to translate in an application consists of either single
    words or short phrases. These typically appear as window titles, menu
    items, tooltips, and labels to buttons, check boxes, and radio buttons.
 
    Developers mark the phrases as translatable in the QML and C++ source code.
    The Qt tools provide context information for each of the phrases to help the
    translator understand their meaning. The developer can add comments to the
    phrases.
 
    Translation files consist of all the user-visible text and \key Ctrl key
    shortcuts in an application and translations of that text.
 
    To create translation files:
 
    \list 1
 
        \li Run \c lupdate to generate the first set of translation source (TS)
            files with all the user-visible text but no translations.
 
        \li Give the TS files to translators who add translations using \QL.
            \QL indicates changed and deleted source text.
 
        \li Run \c lupdate to incorporate any new text added to the application.
            \c lupdate synchronizes the user-visible text from the application
            with the translations. Existing translations in the TS file are
            preserved.
 
        \li Run \c lrelease to read the TS files and produce the QM files used
            by the application at runtime.
 
    \endlist
 
    For \c lupdate to work successfully, it must know which translation files to
    produce. Specify the files in the application's Qt project file.
 
    When building with CMake, you use \l{CMake Commands in Qt6 LinguistTools}
    {CMake commands} to add targets that create or update TS files and transform
    them into QM files. The translation files are generated when you build the
    targets.
*/
 
/*!
    \page linguist-lupdate.html
    \target lupdate
 
    \previouspage Release managers
    \nextpage Using lrelease
 
    \title Using lupdate
 
    The \c lupdate command line tool finds translatable strings in C++ source,
    C++ header, Java, Python, QML, and UI files and generates or updates TS
    files.
 
    When building with qmake, specify the files to process at the command line
    or in a .pro file.
 
    When building with CMake, use \l{CMake Commands in Qt6 LinguistTools}
    {CMake commands} to add targets that create or update TS files and transform
    them into QM files. The \c lupdate tool is run with the \l {lupdate options}
    {options} you pass to the commands when you build the target.
 
    For more information about specifying translations in project files, see
    \l{Localizing Applications}.
 
    \section1 lupdate syntax
 
    \badcode
    lupdate [options] [project-file]...
    lupdate [options] [source-file|path|@lst-file]... -ts ts-files|@lst-file
    \endcode
 
    Where:
 
    \list
        \li \c options means one or several \l {lupdate options}.
        \li \c project-file is the project configuration file.
        \li \c source-file is a file that contains translatable strings.
        \li \c path is the path to a folder that contains translation
            source files.
        \li \c @lst-file reads additional file names (one per line) or
            includepaths (one per line and prefixed with \c -I) from \e lst-file.
        \li \c ts-files are the TS files to generate or update.
    \endlist
 
    To view the latest help, enter:
 
    \badcode
    lupdate -help
    \endcode
 
    \section2 lupdate options
 
    \table
    \header
        \li Option
        \li Action
    \row
        \li \c {-help}
        \li Display up-to-date help information and exit.
    \row
        \li \c {-no-obsolete}
        \li Drop all obsolete and vanished strings.
    \row
        \li \c {-extensions <ext>[,<ext>]...}
        \li Process files with the given extensions, only. Use commas to
            separate extensions in the list. Do not use whitespace. The default
            value is:
            \c {java,jui,ui,c,c++,cc,cpp,cxx,ch,h,h++,hh,hpp,hxx,js,qs,qml,qrc}.
    \row
        \li \c {-pluralonly}
        \li Only include plural form messages.
    \row
        \li \c {-silent}
        \li Do not explain what is being done.
    \row
        \li \c {-no-sort}
        \li Do not sort contexts in TS files.
    \row
        \li \c {-sort-messages}
        \li Sort messages in a context alphabetically in TS files.
    \row
        \li \c {-no-recursive}
        \li Do not recursively scan directories.
    \row
        \li \c {-recursive}
        \li Recursively scan directories (default).
    \row
        \li \c {-warnings-are-errors}
        \li Treat warnings as errors.
    \row
        \li \c {-I <includepath> or -I<includepath>}
        \li Look for include files in this additional location. You can specify
            multiple paths.
    \row
        \li \c {-locations {absolute|relative|none}}
        \li Specify or override the way to save source code references in TS
            files.
            \list
                \li \c absolute means that the source file path is relative to
                    the target file, but the line number is absolute.
                \li \c relative means that the source file path is relative to
                    the target file. The line number is relative to other
                    entries in the same source file.
                \li \c none stores no information about source location.
            \endlist
            If you do not specify the location, \c lupdate determines it from
            existing TS files. The default value for new files is \c absolute.
    \row
        \li \c {-no-ui-lines}
        \li Do not record line numbers in references to UI files.
    \row
        \li \c {-disable-heuristic {sametext|similartext}}
        \li Disable the named merge heuristic. Can be specified multiple times.
    \row
        \li \c {-project <filename>}
        \li Name of a file containing the project's description in JSON format.
            You can use the \c lprodump tool to generate the file from a .pro
            file.
    \row
        \li \c {-pro <filename>}
        \li Name of a .pro file. Useful for files with the .pro file syntax but
            some other file suffix. Projects are recursed into and merged.
            This option is deprecated. Use the \c lupdate-pro tool instead.
    \row
        \li \c {-pro-out <directory>}
        \li Virtual output directory for processing subsequent .pro files.
    \row
        \li \c {-pro-debug}
        \li Trace processing .pro files. Specify twice for more verbosity.
    \row
        \li \c {-source-language <language>[_<region>]}
        \li Specify the language of the source strings for new files.
            Defaults to POSIX if not specified.
    \row
        \li \c {-target-language <language>[_<region>]}
        \li Specify the language of the translations for new files.
            If you do not specify the language, \c lupdate determines it from
            the file name.
    \row
        \li \c {-tr-function-alias <function>{+=,=}<alias>[,<function>{+=,=}<alias>]...}
        \li With \c {+=}, recognize \c <alias> as an alternative spelling of
            \c <function>.
            With \c {=,} recognize \c <alias> as the only spelling of
            \c <function>.
 
            Available \c <function> values (with their currently defined aliases)
            are:
            \list
                \li \c {Q_DECLARE_TR_FUNCTIONS} (\c {=Q_DECLARE_TR_FUNCTIONS})
                \li \c {QT_TR_N_NOOP} (\c {=QT_TR_N_NOOP})
                \li \c {QT_TRID_N_NOOP} (\c {=QT_TRID_N_NOOP})
                \li \c {QT_TRANSLATE_N_NOOP} (\c {=QT_TRANSLATE_N_NOOP})
                \li \c {QT_TRANSLATE_N_NOOP3} (\c {=QT_TRANSLATE_N_NOOP3})
                \li \c {QT_TR_NOOP} (\c {=QT_TR_NOOP})
                \li \c {QT_TRID_NOOP} (\c {=QT_TRID_NOOP})
                \li \c {QT_TRANSLATE_NOOP} (\c {=QT_TRANSLATE_NOOP})
                \li \c {QT_TRANSLATE_NOOP3} (\c {=QT_TRANSLATE_NOOP3})
                \li \c {QT_TR_NOOP_UTF8} (\c {=QT_TR_NOOP_UTF8})
                \li \c {QT_TRANSLATE_NOOP_UTF8} (\c {=QT_TRANSLATE_NOOP_UTF8})
                \li \c {QT_TRANSLATE_NOOP3_UTF8} (\c {=QT_TRANSLATE_NOOP3_UTF8})
                \li \c {findMessage} (\c {=findMessage})
                \li \c {qtTrId} (\c {=qtTrId})
                \li \c {tr} (\c {=tr})
                \li \c {trUtf8} (\c {=trUtf8})
                \li \c {translate} (\c {=translate})
                \li \c {qsTr} (\c {=qsTr})
                \li \c {qsTrId} (\c {=qsTrId})
                \li \c {qsTranslate} (\c {=qsTranslate})
            \endlist
    \row
        \li \c {-ts <ts-file>...}
        \li Specify the output files. This overrides \c TRANSLATIONS.
    \row
        \li \c {-version}
        \li Display the version of \c lupdate and exit.
    \endtable
 
    \section1 Examples
 
    \section2 Using lupdate with CMake
 
    When building with CMake, use \l{CMake Commands in Qt6 LinguistTools}
    {CMake commands} to add translations on targets to the CMakeLists.txt
    file, and then build the targets.
 
    Select one of the following options:
 
    \list
        \li Use \l qt_add_translations on a target, such as \e app.
            This calls \l qt_add_lupdate and \l qt_add_lrelease.
        \li Use \c qt_add_lupdate on a target.
    \endlist
 
    Build a target (for example, \c app_lupdate) to update the .ts
    files for it. To update the .ts files for all targets, build the
    target \c {update_translations}.
 
    \section2 Using lupdate with qmake
 
    To generate a translation file for a single QML file:
 
    \badcode
    lupdate main.qml -ts main_en.ts
    \endcode
 
    To make a translation file for another language, for example French,
    copy main_en.ts to main_fr.ts, and translate the strings in the
    French TS file.
 
    \c lupdate processes QML files that are listed in the \c .qrc file:
 
    \badcode
    RESOURCES += qml.qrc
    \endcode
 
    To have all QML files processed by \c lupdate:
 
    \badcode
    lupdate application.qrc -ts myapp_en.ts
    \endcode
 
    To process all QML files in the current working directory (or its subfolders)
    without using a \c .qrc file:
 
    \badcode
    lupdate . -extensions qml -ts myapp_en.ts
    \endcode
 
    To check for translatable strings in both QML and C++ source files:
 
    \badcode
    lupdate qml.qrc filevalidator.cpp -ts myapp_en.ts
    \endcode
 
    To generate .ts files that will be used for English and French without
    specifying the languages in the project file:
 
    \badcode
    lupdate qml.qrc filevalidator.cpp -ts myapp_en.ts myapp_fr.ts
    \endcode
 
    Give the TS files to the translator who uses \QL to read the files and
    insert the translations.
 
    \section1 XLIFF format files
 
    The TS file format is a simple human-readable XML format that you
    can use with version control systems. In addition, \c lupdate can
    process Localization Interchange File Format (XLIFF) files (\c .xlf).
 
    \note Only XLIFF versions 1.1 and 1.2 are currently supported.
 
    You can open and edit XLIFF files in \QL.
*/
 
/*!
    \page linguist-lrelease.html
    \target lrelease
 
    \previouspage Using lupdate
    \nextpage Using lconvert
 
    \title Using lrelease
 
    The \c lrelease command line tool produces QM files out of TS files. The
    QM file format is a compact binary format that the localized application
    uses. It provides extremely fast lookup for translations.
 
    When building with qmake, specify the files to process at the command line
    or in a .pro file.
 
    When building with CMake, use \l{CMake Commands in Qt6 LinguistTools}
    {CMake commands} to add targets that create or update TS files and
    transform them into QM files. The \c lrelease tool is run with the
    \l {lrelease options}{options} you pass to the commands when you build
    the target.
 
    Run \c lrelease whenever you want to release the application, from the
    initial test version through to the final release version. The application
    does not need QM files to run, but if they are available, the application
    detects them and uses them automatically.
 
    \note The \c lrelease tool only incorporates translations that you
    mark as \e finished. Otherwise, it uses the original text instead.
 
    \section1 lrelease syntax
 
    \badcode
    lrelease [options] -project project-file
    lrelease [options] ts-files [-qm qm-file]
    \endcode
 
    Where:
 
    \list
        \li \c options means one or several \l {lrelease options}.
        \li \c project-file is the project configuration file.
        \li \c ts-files are the TS files to use as input for the QM files.
        \li \c qm-file is the name of the QM file to generate.
   \endlist
 
    \note Passing .pro files to \c lrelease is deprecated. Use the
    \c lrelease-pro tool or the \c lrelease.prf feature when using qmake.
 
    To view the latest help, enter:
 
    \badcode
    lrelease -help
    \endcode
 
    \section2 lrelease options
 
    \table
    \header
        \li Option
        \li Action
    \row
        \li \c {-help}
        \li Display up-to-date help information and exit.
    \row
        \li \c {-idbased}
        \li Deprecated. The flag is not required anymore and will be removed
            in a future version. It was used to enable ID based translation.
    \row
        \li \c {-compress}
        \li Compress the QM files.
    \row
        \li \c {-nounfinished}
        \li Do not include unfinished translations.
    \row
        \li \c {-fail-on-unfinished}
        \li Generate an error if unfinished translations are found
    \row
        \li \c {-removeidentical}
        \li If the translated text is the same as the source text, exclude the
            message.
    \row
        \li \c {-markuntranslated <prefix>}
        \li If a message has no real translation, use the source text
            prefixed with the given string instead.
    \row
        \li \c {-project <filename>}
        \li Name of a file containing the project's description in JSON format.
            You can use the \c lprodump tool to generate the file from a .pro
            file.
    \row
        \li \c {-silent}
        \li Do not explain what is being done.
    \row
        \li \c {-verbose}
        \li Explain what is being done (default).
    \row
        \li \c {-version}
        \li Display the version of \c lrelease and exit.
    \endtable
 
    \section1 Examples
 
    \section2 Using lrelease with CMake
 
    When building with CMake, use \l{CMake Commands in Qt6 LinguistTools}
    {CMake commands} to add translations on targets to the CMakeLists.txt
    file, and then build the targets.
 
    Select one of the following options:
 
    \list
        \li Use \l qt_add_translations on a target, such as \e app.
            This calls \l qt_add_lupdate and \l qt_add_lrelease.
        \li Use \c qt_add_lrelease on a target.
    \endlist
 
    Build a target (for example, \c app_lrelease) to update the .qm
    files for it. To update the .qm files for all targets, build the
    target \c {release_translations}.
 
    \section2 Using lrelease with qmake
 
    To run \c lrelease without specifying a project file:
 
    \badcode
    lrelease.exe main_en.ts languages\main_fr.ts
    \endcode
*/
 
/*!
    \page linguist-lconvert.html
    \target lconvert
 
    \previouspage Using lrelease
    \nextpage Using lconvert
 
    \title Using lconvert
 
    The \c lconvert command line tool filters and converts translation data
    files.
 
    It supports the following file formats:
    \list
        \li \c pot - GNU Gettext localization template files
        \li \c qph - Qt Linguist Phrase Book
        \li \c ts  - Qt translation sources
        \li \c po  - GNU Gettext localization files
        \li \c qm  - Compiled Qt translations
        \li \c xlf - XLIFF localization files
    \endlist
 
    \section1 lconvert syntax
 
    \badcode
    lconvert [options] <infile> [<infile>...]
    \endcode
 
    Where:
 
    \list
        \li \c options means one or several \l {lconvert options}.
        \li \c infile is an input file. You can specify multiple input files.
    \endlist
 
    If you specify multiple input files, they are merged with translations from
    later files taking precedence.
 
    To view the latest \c lconvert help, enter:
 
    \badcode
    lconvert -help
    \endcode
 
    \section2 lconvert options
 
    \table
    \header
        \li Option
        \li Action
    \row
        \li \c -h \br \c -help
        \li Display up-to-date help information and exit.
    \row
        \li \c {-i <infile>} \br \c {-input-file <infile>}
        \li Specify an input file. Use this option if \c{<infile>} starts with a dash.
            Use this option several times to merge inputs.
            May be \c {-} (standard input) for use in a pipe.
    \row
        \li \c {-o <outfile>} \br \c {-output-file <outfile>}
        \li Specify an output file. Default is \c {-} (standard output).
    \row
        \li \c {-if <informat>} \br \c {-input-format <format>}
        \li Specify input format for subsequent input files.
            The format is auto-detected from the file name and defaults to \c ts.
    \row
         \li \c {-of <outformat>} \br \c {-output-format <outformat>}
         \li Specify output format. See \c -if.
    \row
        \li \c {-drop-tags <regexp>}
        \li Drop named extra tags when writing \c TS or \c XLIFF files.
            You can specify this option repeatedly.
    \row
        \li \c {-drop-translations}
        \li Drop existing translations and reset the status to \c unfinished.
            That implies \c {--no-obsolete}.
    \row
        \li \c {-source-language <language>[_<region>]}
        \li Specify/override the language of the source strings. Defaults to
            POSIX if not specified and the file does not name it yet.
    \row
        \li \c {-target-language <language>[_<region>]}
        \li Specify or override the language of the translation.
            By default, the target language is read from the file content or
            guessed from the file name.
    \row
        \li \c {-no-obsolete}
        \li Drop obsolete messages.
    \row
         \li \c {-no-finished}
         \li Drop finished messages.
    \row
        \li \c {-no-untranslated}
        \li Drop untranslated messages.
    \row
        \li \c {-sort-contexts}
        \li Sort contexts in the output \c TS file alphabetically.
    \row
        \li \c {-sort-messages}
        \li Sort messages in a context alphabetically in \c TS files.
    \row
        \li \c {-locations {absolute|relative|none}}
        \li Override how source code references are saved in \c TS files.
            Default is \c absolute.
    \row
        \li \c {-no-ui-lines}
        \li Drop line numbers from references to \c UI files.
    \row
        \li \c {-pluralonly}
        \li Drop non-plural form messages.
    \row
        \li \c {-verbose}
        \li Explain what is being done.
    \endtable
 
    \section1 Examples
 
    \section2 Convert TS file to XLIFF
 
    To convert a single TS file to XLIFF, run the following command in the
    terminal:
 
    \badcode
    lconvert -o myapp_de.xlf myapp_de.ts
    \endcode
 
    \section2 Merge multiple QM files
 
    The following command merges multiple QM files into \c {full_de.qm}:
 
    \badcode
    lconvert -o full_de.qm qtbase_de.qm myapp_de.qm mylib_de.qm
    \endcode
 
    \section2 Using lconvert with CMake
 
    To call \c lconvert when configuring or building your CMake project, load
    the \c Qt6LinguistTools package and use \c
    {$<TARGET_FILE_NAME:Qt6::lconvert>} for locating the \c lconvert executable.
 
    The following example adds a custom target \c xlf_de that converts a single
    TS file to XLIFF.
 
    \badcode
    find_package(Qt6 REQUIRED COMPONENTS LinguistTools)
 
    add_custom_command(
        OUTPUT myapp_de.xlf
        COMMAND $<TARGET_FILE:Qt6::lconvert> -o myapp_de.xlf myapp_de.ts
        DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/myapp_de.ts"
        VERBATIM
    )
 
    add_custom_target(xlf_de
        DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/myapp_de.xlf"
    )
    \endcode
*/
 
/*!
\page linguist-lcheck.html
\target lcheck
\previouspage Using lconvert
\nextpage Translators
 
\title Using lcheck
 
The \c lcheck command line tool validates Qt \c {TS} translation files and
produces a human-readable report. It is part of the Qt Linguist toolchain
and is intended for batch or CI usage to catch common localization issues
early. By default, \c lcheck runs a set of checks and returns a non-zero
exit code if at least one enabled check fails.
 
The default checks are:
 
\list
    \li \b Accelerator check — Verifies that the number of ampersands
        (mnemonics) in source and translation match.
    \li \b Surrounding whitespace check — Verifies that leading and trailing
        whitespace of source and translation match.
    \li \b Ending punctuation check — Verifies that source and translation
        end with the same punctuation.
    \li \b Place marker check — Verifies consistent usage of \c {%1}, \c {%2},
        and so on, between source and translation.
\endlist
 
Each check can be disabled individually using command line options.
 
\section1 lcheck syntax
 
\badcode
lcheck [options] -o report-output-file ts-file
lcheck [options] ts-file
\endcode
 
Where:
 
\list
    \li \c options means one or several \l {lcheck options}.
    \li \c ts-file is the \c {TS} file to validate.
    \li \c report-output-file is the path of the file to write the report to.
        If omitted, the report is written to the standard error stream.
\endlist
 
To view the latest help, enter:
 
\badcode
lcheck -help
\endcode
 
\section2 lcheck options
 
\table
\header
    \li Option
    \li Action
\row
    \li \c {-help}
    \li Display up-to-date help information and exit.
\row
    \li \c {-no-accelerator}
    \li Disable the accelerator (ampersand) consistency check.
\row
    \li \c {-no-punctuation}
    \li Disable the ending punctuation consistency check.
\row
    \li \c {-no-place-marker}
    \li Disable the check that ensures \c {%1}, \c {%2}, … are used
        consistently between source and translation.
\row
    \li \c {-no-whitespaces}
    \li Disable the surrounding whitespace consistency check.
\row
    \li \c {-check-finished}
    \li Also check messages marked as \e finished. By default, finished
        translations are not checked.
\row
    \li \c {-o <outfile>}
    \li Write the validation report to \c <outfile>. If not specified, the
        report is written to standard error.
\row
    \li \c {-version}
    \li Display the version of \c lcheck and exit.
\endtable
 
\note The process exit status is non-zero if any enabled check fails. This
makes \c lcheck suitable for use in CI pipelines.
 
\section1 Examples
 
\section2 Write a report to a file
 
\badcode
lcheck -o lcheck_report.txt translations/myapp_de.ts
\endcode
 
\section2 Disable selected checks
 
The following command runs all checks except accelerator and punctuation:
 
\badcode
lcheck -no-accelerator -no-punctuation translations/myapp_de.ts
\endcode
 
\section2 Check finished translations as well
 
\badcode
lcheck -check-finished translations/myapp_de.ts
\endcode
 
\section2 Use lcheck in a CI step
 
\badcode
lcheck translations/myapp_de.ts && echo "Translations OK" || echo "Issues found"
\endcode
 
\section2 Using lcheck with CMake
 
To call \c lcheck when configuring or building your CMake project, load
the \c Qt6LinguistTools package and use \c {$<TARGET_FILE:Qt6::lcheck>}
to locate the \c lcheck executable.
 
The following example adds a custom target \c check_translations that runs
\c lcheck over a TS file and writes a report next to the build artifacts.
 
\badcode
find_package(Qt6 REQUIRED COMPONENTS LinguistTools)
 
add_custom_command(
    OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/lcheck_report.txt"
    COMMAND $<TARGET_FILE:Qt6::lcheck>
            -o "${CMAKE_CURRENT_BINARY_DIR}/lcheck_report.txt"
            "${CMAKE_CURRENT_SOURCE_DIR}/translations/myapp_de.ts"
    DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/translations/myapp_de.ts"
    VERBATIM
)
 
add_custom_target(check_translations
    DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/lcheck_report.txt"
)
\endcode
 
\section2 Using lcheck with qmake
 
You can run \c lcheck directly on a TS file without specifying a project file:
 
\badcode
lcheck translations/myapp_de.ts
\endcode
*/
 
/*!
    \page linguist-translators.html
 
    \previouspage Using lcheck
    \nextpage Qt Linguist user interface
 
    \title Translators
 
    \image front-ui.png {UI illustration showing Start buttons, toggle,
           controls, and a circular selector on a dark screen}
 
    \QL is a tool for translating strings in Qt applications. Once you have
    installed Qt, you can start \QL in the same way as any other application on
    the development host.
 
    \note You can obtain an installer for \QL only (without the entire Qt SDK)
          from \l {https://download.qt.io/linguist_releases/}. The installer is
          available for Windows, and works with Qt 6.
 
    To address issues that arise from the subtleties and complexities of
    human language, translators and developers may need to:
 
    \list
    \li Translate a single phrase into several different forms depending on
        context. For example, \e open in English might become \e{\ouml}\e{ffnen},
        \e {open file}, or \e aufbauen, \e {open internet connection}, in German.
 
    \li Change the mnemonic characters in keyboard shortcuts without introducing
        conflicts. For example, \c \&Quit in English becomes \e Avslutt in
        Norwegian, which does not contain the letter \e Q. You cannot use a
        letter that is already in use unless you change several shortcuts.
 
    \li Rephrase strings that contain variables. For example, you might need to
        place the variables in a different order when you translate the string
        \e {The 25 files selected will take 63 seconds to process}, where the
        two numbers are inserted programmatically at runtime.
    \endlist
 
    For more information about how to use \QL to translate applications, see:
 
    \list
        \li \l {Qt Linguist user interface}
        \li \l {Translating strings}
        \li \l {Selecting context or label to translate}
        \li \l {Selecting strings to translate}
        \li \l {Viewing strings in context}
        \li \l {Reusing translations}
        \li \l {Validating translations}
        \li \l {Translating multiple languages simultaneously}
        \li \l {AI translation}
    \endlist
*/
 
/*!
    \page linguist-ui.html
 
    \previouspage Translators
    \nextpage Translating strings
 
    \title Qt Linguist user interface
 
    The \QL main window contains a menu bar and the following views:
 
    \list
 
        \li \uicontrol Context/Label (\key F6) lists translation contexts or labels.
 
        \li \uicontrol Strings (\key F7) lists translatable strings in the
            selected context.
 
        \li \uicontrol {Sources and Forms} (\key F9) displays the selected
            string in the source code.
 
        \li Translation area displays the selected string and enables you to
            enter a translation for it.
 
        \li \uicontrol {Phrases and guesses} (\key F10) lists possible
            translations for the current string.
 
        \li \uicontrol Warnings (\key F8) lists translated strings that fail
            validation tests.
 
    \endlist
 
    \image linguist.webp {Qt Linguist UI}
 
    The translation area (1) is always visible. To show or hide the other views,
    select \uicontrol View > \uicontrol Views, or use keyboard shortcuts.
    You can drag the views by their title bars and arrange them around the
    translation area or even outside the main window.
*/
 
/*!
    \page linguist-translating-strings.html
 
    \previouspage Qt Linguist user interface
    \nextpage Selecting context or label to translate
 
    \title Translating strings
 
    Open translation source (TS) files in \QL for translation. TS files are
    human-readable XML files containing source phrases and their translations.
    TS files are usually created and updated by \c lupdate. If you do not have
    a TS file, see \l {Creating translation files} to learn how to generate one.
 
    You can use \QL also to translate files in the international XML
    Localization Interchange File Format (XLIFF) that are generated by other
    programs. However, for standard Qt projects, only the TS file format is
    used. Only XLIFF versions 1.1 and 1.2 are currently supported.
 
    \QL displays the target language in the translation area, and adapts the
    number of input fields for plural forms accordingly. When you open several
    TS files to translate simultaneously, the \uicontrol Translator and
    \uicontrol {Translator comment} fields are displayed for each language.
    For more information about setting the location information, see
    \l{Changing the target locale}.
 
    If the developer provides a disambiguating comment, you can see it in the
    \uicontrol {Developer comments} field.
 
    To translate strings:
    \list 1
 
        \li Select \uicontrol File > \uicontrol Open to load a TS file.
 
        \li Select a context in the \uicontrol Context view to display translatable
            strings in the \uicontrol Strings view.
 
            \image linguist-ui.webp {}
 
        \li Select a string to display it in the \uicontrol {Source text} field
            in the translation area. The whitespace within the source text is
            visualized.
 
        \li Enter the translation of the current string in the \uicontrol Translation
            field.
 
            Double-click an existing translation in the
            \uicontrol {Phrases and guesses} field to use it as the translation
            for the current string. \QL reads the phrases from phrase books and
            bases the guesses on existing translations of similar phrases in the
            TS file.
 
        \li Optionally, enter a comment for other translators in the
            \uicontrol {Translator comment} field.
 
        \li To accept the translation, press \key {Ctrl+Enter}, select
            \inlineimage linguist-doneandnext.png {Icon}
            , or click the icon to the left of the selected source string in the
            string list.
 
        \li Select \uicontrol File > \uicontrol Save to save your work.
 
    \endlist
 
    Repeat this process until all strings in the string list are marked with
    \inlineimage linguist-check-on.png {Check icon}
    (\uicontrol {Accepted/Correct}) or
    \inlineimage linguist-check-warning.png {Check warning icon}
    (\uicontrol {Accepted/Warnings}). Then select the next context and continue.
 
    To view the number of words and characters in the source text and in the
    translated text, select \uicontrol View > \uicontrol Statistics.
 
    Select \uicontrol File > \uicontrol Release to create a QM
    file with the same base name as the current translation source file.
    The  \c lrelease tool performs the same function on \e all of an
    application's translation source files.
 
    To print the translation source and the translations, select \uicontrol File >
    \uicontrol Print.
 
    To quit \QL, select \uicontrol File > \uicontrol Exit.
 
    \section1 Moving between translatable strings
 
    To move to the next unfinished translation, select
    \inlineimage nextunfinished.png {Icon}
    (\uicontrol {Next Unfinished}) or press \key{Ctrl+J}.
 
    To move to the next source text, select \inlineimage next.png {next icon}
    , press \key{Ctrl+Shift+J}, or select \uicontrol Translation >
    \uicontrol Next.
 
    \section1 Phrases that require multiple translations depending on context
 
    The same phrase may occur in more than one context without conflict. When
    you reach another occurrence of a translated phrase, \QL provides
    the previous translation as a possible translation in the
    \uicontrol {Phrases and guesses} view.
 
    If a phrase occurs more than once within a particular context, it appears
    only once in the \uicontrol Context view, and the translation is applied
    to every occurrence within the context. If the same phrase means different
    things within the same context, the developer must provide a comment for
    each occurrence of the phrase. The duplicate phrases appear in the
    \uicontrol Context view. The developer's comments appear in the translation
    area on a light blue background.
 
    \section1 Changing keyboard shortcuts
 
    A keyboard shortcut is a key combination that performs an action.
 
    \section2 Alt key shortcuts
 
    In menu item and button text, a \e mnemonic character (marked by underlining)
    indicates that pressing \key Alt or \key Ctrl with the underlined character
    performs the same action as clicking the menu item or pressing the button.
 
    For example, applications often use \e F as the mnemonic character in the
    \uicontrol {File} menu, so you can either click the menu item or press
    \key {Alt+F} to open the menu. The mnemonic character in the translatable
    string is prefixed with an ampersand: \c {\&File}. The translation for the
    string should also have an ampersand in it, preferably in front of the same
    character.
 
    You can determine the meaning of an \key Alt key shortcut from the phrase
    that contains the ampersand. You can use another mnemonic character if the
    translated phrase does not contain the current one or if it is used in
    the translation of some other shortcut in the context. Some key shortcuts,
    usually those on the menu bar, may apply in other contexts.
 
    \section2 Ctrl key shortcuts
 
    \key Ctrl key shortcuts can exist independently of any visual control.
    Typically, they invoke actions in menus that would require multiple
    keystrokes or mouse clicks or actions that do not appear in any menu
    or on any button. For example, the \uicontrol {File} menu might contain a
    \uicontrol {\underline{N}ew Ctrl+N} item that you can invoke by pressing
    \key {Ctrl+N} even when the \uicontrol {File} menu is closed.
 
    Each \key Ctrl key shortcut appears in the \uicontrol Strings view
    as a separate string. For example, \key{Ctrl+Enter}. Since
    the string does not have a context to give it meaning, such as
    the context of the phrase in which an \key Alt key shortcut appears,
    you must rely on the developer to include a \l{QObject::tr()}
    {disambiguation comment} to explain the action the \key Ctrl key
    shortcut performs. The comment appears under \uicontrol {Developer comments}
    in the translation area below the \uicontrol {Source text} field.
 
    Ideally, you can copy translations for \key Ctrl key shortcuts by
    selecting \uicontrol Translation > \uicontrol {Copy from source text}.
    However, if the character does not make sense in the target language,
    change it. Whichever character (alpha or digit) you choose,  use the form
    \key {Ctrl+} followed by the upper case character. Qt automatically displays
    the correct name at runtime. As with \key Alt key shortcuts, if you change
    the character, make sure that it does not conflict with any other
    \key Ctrl key shortcut.
 
    \note Do not translate the \key Alt, \key Ctrl or \key Shift parts of
    the shortcuts, as Qt recognizes them and automatically translates them
    for supported languages.
 
    \section1 Handling numbered arguments and plural forms
 
    A numbered argument is a placeholder that will be replaced with text at
    runtime. It appears in a source string as a percent sign followed by
    a digit. For example, in the \c{After processing file %1, file %2
    is next in line} string, \c{%1} and \c{%2} are numbered arguments that
    are replaced with the first and second file names at runtime. The
    same numbered arguments must appear in the translation, but not
    necessarily in the same order. A German translation of the string
    might reverse the phrases, for example \c{Datei %2 wird bearbeitet, wenn
    Datei %1 fertig ist}. Both numbered arguments appear in the
    translation, but in the reverse order. A numbered argument is always
    replaced by the same text in the translations, regardless of the position
    in the argument sequence in the source string.
 
    The use of numbered arguments is often accompanied by the use of
    plural forms in the source text. In many languages, the form of the
    text will depend on the value shown, and more than one translation
    is required. If the developers have marked up the source text in
    correct way, fields for each of the possible plural forms will be
    available in the translation area. For more information, see
    \l{Writing Source Code for Translation}.
 
    \section1 Handling numeric character references (NCR) in translations
 
    Select \uicontrol {NCR mode} to toggle the representation of
    numeric character references in both the source text and the translation
    fields. When selected, special characters in the text are displayed as their
    corresponding NCRs (for examlple, &#160; for a non-breaking space). Otherwise, the
    characters appear in their standard visual form. This feature is useful
    for instance to maintain the same special characters (such as
    emojis, special spaces) in both the source text and its translations.
 
    \section1 Changing the target locale
 
    You can set the locale information explicitly in \uicontrol Edit >
    \uicontrol {Translation File Settings}. If the target language and country
    are not explicitly set when you open a translation source file, \QL
    attempts to deduct them from the translation source file name. This
    requires that the translation files adhere to the following file name
    convention:
    \c appname_language[_country].ts, where:
 
    \list
      \li \c language is an ISO 639 language code in lowercase.
      \li \c country is an ISO 3166 two-letter country code in uppercase.
    \endlist
 
    If this attempt to resolve the target language and country fails, the
    \uicontrol {Translation File Settings} window opens.
 
    For example, \c app_de.ts sets the
    target language to German, and \c app_de_CH.ts sets the target language to
    German and the target country to Switzerland. This also helps loading
    translations for the current locale automatically. For more information, see
    \l{Enable Translation}.
 
    \image linguist-translationfilesettings.png {Screenshot showing Qt Linguist
           settings window with source language POSIX and target language German}
*/
 
/*!
    \page linguist-selecting-context.html
 
    \previouspage Translating strings
    \nextpage Selecting strings to translate
 
    \title Selecting context or label to translate
 
    The \uicontrol Context/Label view lists the contexts (\uicontrol {Text based}) or
    labels (\uicontrol {ID based}) in which strings to be translated
    appear. The text-based translations are grouped into contexts, while ID-based
    translations are grouped into labels (see \l{Grouping ID-Based Translations}).
    The \uicontrol Context/Label lists the \e groups (that is, context or labels)
    based on the selected tab:
    \list
    \li Upon switching to the \uicontrol{Text-Based} tab,
    \uicontrol Context lists the context names in
    alphabetical order. Each context is the name of a QML type or a subclass of
    QObject.
    \li Upon switching to the \uicontrol{ID-Based} tab,
    \uicontrol Label lists the label names in
    alphabetical order. More info on labels can be found in \l{Grouping ID-Based Translations}.
    \endlist
 
    \image linguist-context-view.webp {Context/Label view}
 
    The following icons indicate the current translation state for each group:
 
    \table
    \header
    \li State
    \li Icon
    \li Description
 
    \row
    \li Accepted/Correct
    \li \inlineimage linguist-check-on.png {Check icon}
    \li All strings in the group have been translated, and all the
        translations passed the \l{Validating Translations}{validation tests}.
 
    \row
    \li Accepted/Warnings
    \li \inlineimage linguist-check-warning.png {Check warning icon}
    \li All strings in the group have been translated or marked as translated,
        but at least one translation failed the validation tests.
        In the \uicontrol Strings view, you can see which string failed the test.
 
    \row
    \li Not Accepted
    \li \inlineimage linguist-check-off.png {check off icon}
    \li At least one string in the group has not been translated or is not
        marked as translated.
 
    \row
    \li Obsolete
    \li \inlineimage linguist-check-obsolete.png {check obsolete icon}
    \li None of the translated strings appears in the group any more. This
        usually means the context or label no longer exists in the application.
    \endtable
 
    The \uicontrol Items column displays the total number of translatable strings in
    the group and the number of translated strings, separated by a slash (/).
    If the numbers are equal, all the translatable strings in the group have
    translations.
*/
 
/*!
    \page linguist-selecting-strings.html
 
    \previouspage Selecting context or label to translate
    \nextpage Viewing strings in context
 
    \title Selecting strings to translate
 
    The \uicontrol Strings view lists all the translatable strings in the
    current group (that is, context or label) and their translation acceptance
    state. Select a string to view and edit it in the translation area.
 
    \image linguist-strings-view.webp {Strings view}
 
    Click the icon in front of a string to change its translation acceptance
    state. A tick mark, green or yellow, means the string has an accepted
    translation. A question mark means either that the translation does not
    exist or you have not accepted it.
 
    The following icons indicate the current translation state for each string:
 
    \target String Translation States
 
    \table
    \header
    \li State
    \li Icon
    \li Description
 
    \row
    \li Accepted/Correct
    \li \inlineimage linguist-check-on.png {Check icon}
    \li The source string has a translation (possibly empty). You accepted
        the translation, and it passes all the \l{Validating Translations}
        {validation tests}. Click the icon to revoke acceptance of the
        translation. The state becomes \uicontrol {Not Accepted} if the string
        has a translation or \uicontrol {No Translation} if the translation is
        empty. If \c{lupdate} changes the contents of a string, its acceptance
        state becomes \uicontrol {Not Accepted}.
 
    \row
    \li Accepted/Warnings
    \li \inlineimage linguist-check-warning.png {Check warning icon}
    \li You accepted the translation, but it does not pass all the validation
        tests. The \uicontrol Warnings view shows where it failed. If you click
        the icon to revoke acceptance of the translation, the state becomes
        \uicontrol {Validation Failures}.
 
    \row
    \li Not Accepted
    \li \inlineimage linguist-check-off.png {check off icon}
    \li The string has a translation that passes all the validation tests, but
        you have not yet accepted the translation. Click the icon or press
        \key{Ctrl+Enter} to accept the translation. The state becomes
        \uicontrol {Accepted/Correct}.
 
    \row
    \li No Translation
    \li \inlineimage linguist-check-empty.png {check empty icon}
    \li The string does not have a translation. If you click the icon to accept
        the empty translation, the state becomes \uicontrol {Accepted/Correct}.
 
    \row
    \li Validation Failures
    \li \inlineimage linguist-danger.png {danger icon}
    \li The string has a translation, but the translation does not pass all the
        validation tests. The \uicontrol Warnings view shows the validation test
        failures. Click on the icon or press \key{Ctrl+Enter} to
        accept the translation even with validation failures. The state becomes
        \uicontrol {Accepted/Warnings}. Usually, you should fix the causes of the
        validation failures. The state will automatically become
        \uicontrol {Not Accepted} when you fix all failures.
 
    \row
    \li Obsolete
    \li \inlineimage linguist-check-obsolete.png {check obsolete icon}
    \li The string is obsolete. It is no longer used in the context.
        See \l{Using lupdate} for instructions on how to remove obsolete
        messages from the file.
 
    \endtable
*/
 
/*!
    \page linguist-viewing-strings-in-context.html
 
    \previouspage Selecting strings to translate
    \nextpage Reusing translations
 
    \title Viewing strings in context
 
    If \QL can access the source files containing the translatable strings, the
    \uicontrol {Sources and Forms} view shows the source context of the current
    string in the \uicontrol Strings view. It highlights the source code line
    that contains the current string. If \QL cannot find the source file, it
    shows the expected absolute file path.
 
    If the source context shows the wrong source line, the translation file might
    be out of sync with the source files. For more information about how to sync
    the files, see \l{Using lupdate}.
 
    \QD stores UI forms in special UI files (.ui). \QL attempts to show the
    translations in the forms.
*/
 
/*!
    \page linguist-reusing-translations.html
 
    \previouspage Viewing strings in context
    \nextpage Validating translations
 
    \title Reusing translations
 
    If the translated text is similar to the source text, select
    \uicontrol Translation > \uicontrol {Copy from source text}
    (or press \key{Ctrl+B}) to copy the source text into the
    translation area.
 
    \e {Phrase books} provide a common set of translations
    to help ensure consistency. A phrase book is a set of source phrases, target
    (translated) phrases, and optional definitions. Typically, one phrase book
    is created per language and family of applications. Phrase books avoid
    duplication of effort since they contain translations for a family of
    applications.
 
    The \uicontrol {Phrases and guesses} view displays the current string and its
    phrase book translations. If the current string is the same as or similar to
    a translated string, the view also lists the string and its translation.
 
    To copy a translation from the \uicontrol {Phrases and guesses} view to the
    translation area, double-click it or select it and press \key Enter.
 
    \section1 Batch translation
 
    \image linguist-batchtranslation.png {Screenshot showing Qt Linguist batch
           translation window with options and phrase book selection}
 
    Use the batch translation feature to automatically translate source
    texts that are also in a phrase book. To configure which phrase books to use
    in what order during the batch translation process, select \uicontrol Edit >
    \uicontrol {Batch Translation}. You can include only entries with no
    current translation and mark batch translated entries as \uicontrol Accepted.
 
    \section1 Creating and editing phrase books
 
    Phrase book files are human-readable XML files containing standard phrases
    and their translations. \QL creates and update the files. You can use them
    for any number of projects and applications.
 
    To create a new phrase book, select \uicontrol Phrases > \uicontrol {New Phrase Book}.
 
    \image linguist-phrasebookdialog.png {Screenshot of Qt Linguist phrase book editor
           showing source phrases with German translations}
 
    To open a phrase book, select \uicontrol Phrases > \uicontrol {Open Phrase Book}, and
    then select the Qt phrase book file (.qph) to open.
 
    To view and change open phrase books, select \uicontrol Phrases >
    \uicontrol {Edit Phrase Book}.
 
    To add a new phrase, select \uicontrol {New Entry} (or press \key {Alt+N}) and
    type in a new source phrase, the translation, and an optional definition.
    This is useful to distinguish different translations of the same source
    phrase.
 
    To add the translation you are working on to the current phrase book, select
    \uicontrol Phrases > \uicontrol {Add to Phrase Book} or press \key{Ctrl+T}. If multiple
    phrase books are loaded, you have to select one.
 
    If you detect an error in a phrase book entry in the
    \uicontrol {Phrases and guesses} view, you can edit by right
    clicking it and selecting \uicontrol Edit. After fixing the
    error press \key{Enter} to leave the editing mode.
 
    To delete a phrase, select it in the \uicontrol {Source phrase} list, and then
    select \uicontrol {Remove Entry}.
 
    To print an open phrase book, select \uicontrol Phrases >
    \uicontrol {Print Phrase Book}.
*/
 
/*!
    \page linguist-validating-translations.html
 
    \previouspage Reusing translations
    \nextpage Translating multiple languages simultaneously
 
    \title Validating translations
 
    \QL provides the following validation tests for translations:
 
    \list
        \li \e {Accelerator validation} detects translated phrases
            that do not have an ampersand when the source phrase does and vice
            versa.
        \li \e {Punctuation validation} detects differences in the
            terminating punctuation between source and translated phrases when
            this may be significant. For example, warns if the source phrase
            ends with an ellipsis, exclamation mark or question mark, and the
            translated phrase does not, and vice versa.
        \li \e {Phrases validation} detects source phrases that are
            also in the phrase book but whose translation differs from that
            in the phrase book.
        \li \e {Place marker validation} detects whether the same variables
            (like \c %1, \c %2) appear both in the source text and in the
            translation.
    \endlist
 
    To switch validation tests on or off, select \uicontrol Validation or use the
    toolbar buttons.
 
    Not accepted strings that fail validation tests are marked with the
    \uicontrol {Validation Failures} icon in the \uicontrol Strings view.
    Accepted strings are marked with \uicontrol {Accepted/Warnings}.
 
    If you switch validation off and then switch it on later,
    \QL rechecks all phrases and marks any that fail validation.
 
    The \uicontrol Warnings view lists the strings that fail the active
    validation tests. The first warning  is also shown in the status bar
    at the bottom of the main window.
 
    \note Only results of \e{active} validation tests are reported.
*/
 
/*!
    \page linguist-translating-multiple-languages.html
    \target multiple languages
 
    \previouspage Validating translations
    \nextpage AI translation
 
    \title Translating multiple languages simultaneously
 
    You can load and edit multiple translation files simultaneously.
    The following screen shot displays \e{German} and \e{French} translation
    files loaded.
 
    \image linguist-linguist_2.webp {}
 
    The translation area has color-coded text editing areas for both German and
    French. The \uicontrol Context/Label view and the \uicontrol Strings view have
    color-coded status columns for each language.
 
    The \uicontrol Items column in the \uicontrol Context/Label view combines the values
    for both languages. If the number of translatable strings does not match the
    number of accepted strings, either or both languages have strings that you
    need to translate or accept. The \uicontrol Strings view shows the translation
    acceptance state of each string for each language.
*/
 
/*!
 \page linguist-ai-translation.html
 \target ai translation
 
 \previouspage Translating multiple languages simultaneously
 \nextpage Developers
 
 \title AI translation
 
 The AI Translation feature lets you automatically generate
translations for the open TS file using a local LLM via Ollama.
 
 To use AI Translation you must first install
\l{https://github.com/jmorganca/ollama}{Ollama} and pull at least one model, for example:
 
 \list
     \li \c{ollama pull gpt-oss:20b}
     \li \c{ollama pull 7shi/llama-translate:8b-q4_K_M}
 \endlist
 
 Then start the Ollama server if not already started:
 
 \code
 ollama serve
 \endcode
 
 In Linguist, choose \uicontrol{Translation > AI Translation}
to open the AI Translation dialog:
 
 \image linguist-ai-translation-dialog.webp {Screenshot of Qt Linguist AI translation window
        showing server settings and completed translations}
 
 The dialog provides:
 
 \list
     \li \uicontrol {Ollama Server}: the REST endpoint where Ollama listens
                    (default \c http://127.0.0.1:11434).
     \li \uicontrol Model: drop-down of locally installed models.
     \li \uicontrol File: the TS file to translate.
     \li \uicontrol Filter (optional): limit to strings in a specific group (context or label).
     \li \uicontrol Translate button: start the AI translation.
     \li \uicontrol {Apply Translations} button: apply the translated items into the TS file.
 \endlist
 
During translation, progress messages appear in the status bar and in the \uicontrol {Translation
Log}. When complete, you can check out the translated texts on the log. Upon clicking on
\uicontrol{Apply Translations}, AI-generated translations are inserted into the TS file.
 
\note We suggest using one of OpenAI’s open-weight models, e.g., \e{gpt-oss:20b} or other
    LLMs trained for translation, e.g., \e{7shi/llama-translate:8b-q4_K_M}. Feel free to
    try other models to find the best combination of speed, quality, and resource usage.
*/
 
/*!
    \page linguist-programmers.html
    \title Developers
 
    \previouspage AI translation
    \nextpage TS File Format
 
    \image front-coding.png {Illustration showing a code}
 
    Design your application so that it can be adapted to various languages and
    regions without engineering changes.
 
    \list
        \li \l{TS file format}
        \li \l{Text ID based translations}
        \li \l{Meta strings reference}
        \li \l{CMake Commands in Qt6 LinguistTools}{CMake commands}
        \li \l{Examples}
    \endlist
 
    For more information, see also:
    \list
        \li \l {Internationalization with Qt}
        \li \l {Writing Source Code for Translation}
        \li \l {Localizing Applications}.
    \endlist
 
    You can use Qt Creator wizard templates to create Qt widget-based projects
    with translation support. For more information, see
    \l {Qt Creator: Creating Projects}.
 
    The following video shows how to internationalize and localize a simple
    example application:
 
    \youtube xNIz78IPBu0
*/
 
/*!
    \page linguist-programmers-examples.html
    \title  Examples
 
    \nextpage Developers
 
    The following examples illustrate how to prepare Qt applications for
    translation:
 
    \list
    \li \l{hellotr}{Hello tr()} is a C++ application that demonstrates the
    creation of a \l QTranslator object. It also shows the simplest use of
    the \c tr() function to mark user-visible source text for
    translation.
 
    \li \l{arrowpad}{Arrow Pad} is a C++ application that demonstrates how to
    make the application load translations depending on the current locale.
    It also shows the use of the two-argument form of \c tr() which provides
    additional information to the translator.
 
    \li \l{trollprint}{Troll Print} is a C++ application that demonstrates how
    to distinguish identical source text in the same context. It also shows
    how minimize the translator's work when an application is upgraded.
 
    \li \l{Qt Quick I18N} demonstrates how to internationalize Qt Quick
    applications.
    \endlist
*/
 
/*!
    \page linguist-ts-file-format.html
    \title TS file format
 
    \previouspage Developers
 
    \brief TS file format.
 
    The TS file format used by \QL is described by the
    \l{http://www.w3.org/2001/XMLSchema}{XSD} presented below,
    which we include for your convenience. Be aware that the format
    may change in future Qt releases.
 
    \quotefile ../../../shared/ts.xsd
 
*/
 
/*!
    \page linguist-id-based-i18n.html
    \title Text ID based translations
    \ingroup internationalization
 
 
    \brief Text ID based internationalization provides support for large scale
    projects with many target locales and many texts to translate.
 
    The text ID translation mechanism is an \e {industrial strength} system for
    internationalization and localization. Each text in the application has a
    unique identifier (text ID) that you use in the source code instead of text.
    This makes it much easier to manage large numbers of translated texts.
 
    \section1 Internationalizing with text IDs
 
    When using text IDs instead of plain text, the general method of
    internationalizing an application is the same but the details are a bit
    different:
 
    \list 1
 
        \li The functions and macros for the text-ID-based translation system are
        different from the plain-text system. You use the qsTrId() function instead
        of qsTr(), the QT_TRID_NOOP() macro instead of QT_TR_NOOP(),
        and QT_TRID_N_NOOP() macro instead of QT_TR_N_NOOP()).
 
        \li Use text IDs as user interface strings rather than plain text
        strings. For example, \c {qsTrId("id-back-not-front")}
 
        \li You cannot specify a context parameter with a text ID, and therefore
        identically spelled words with different meanings need separate
        text IDs. For example, \c {qsTrId("id-back-backstep")} differentiates
        the back-step \e {Back} from the \c id-back-not-front \e {Back}.
 
        \li Since context names are not allowed for text-ID-based translations,
        \QL lists the IDs in a file without context names.
 
        \li The \e {engineering English} text that you see in the user interface for
        development builds is indicated with a \c {//%} comment. If you do not
        include this, the text ID is shown in the user interface. This is
        especially important when you have texts with parameters. The \c {//%}
        comment needs to include the parameters indicators in the string. For
        example, \c {//% "Number of files: %1"}
 
        \li The \c {//:} comments that provide extra information to the translator
        are optional in the plain-text system. However, with the text-ID-based
        system, this extra information becomes essential because without it you only
        have the text ID and the translator might not be able to make a sensible
        translation from that without further context. You can use long descriptive
        text IDs and no comments, but comments are often easier to understand.
 
    \endlist
 
    The side-by-side code snippets below show a comparison of text-ID -based and
    plain-text-based translations:
 
    \table
        \header
            \li text-ID-based
            \li plain-text-based
        \row
            \li
            \code
            Text {
                id: backTxt;
                //: The back of the object, not the front
                //% "Back"
                //~ Context Not related to back-stepping
                text: qsTrId("id-back-not-front");
            }
            \endcode
 
            \li
            \code
            Text {
                id: backTxt;
                //: The back of the object, not the front
                //~ Context Not related to back-stepping
                text: qsTr("Back","Not front")
            }
            \endcode
    \endtable
 
    \section1 Localizing with text IDs
 
    Localizing with text IDs follows much the same process as for plain text.
 
    You use the \l{Using lupdate}{lupdate} tool to generate the TS files where
    you add the translations. The source values in the translation files will be
    text IDs rather than plain text, and therefore you need either descriptive
    text IDs or good additional comments, or both to ensure that the translations
    are accurate.
 
    The example text-ID-based user interface text from above results in the following
    content in the .ts file:
 
    \code
    <message id="id-back-not-front">
        <source>Back</source>
        <extracomment>The back of the object, not the front</extracomment>
        <translation type="unfinished"></translation>
        <extra-Context>Not related to back-stepping</extra-Context>
    </message>
    \endcode
 
    If there is no translation available for a given text (which is
    generally the case until late in development), the text ID will be shown in
    the user interface rather than a proper text. In order to make the application
    more usable for testing, you can make \c lrelease use the \e {Engineering English}
    source text (from the \c {//%} comments) as the translated text and mark it with
    some indicator, such as an exclamation mark (!), so you can see texts that
    are not yet translated.
 
    \section2 Grouping ID-Based Translations
 
    You can assign each ID-based translation a \e label to organize
    ID-based entries of large projects into smaller groups.
    To assign a \e label to an ID-based entry, add a \c{//@} comment
    naming the label, for example in C++:
    \code cpp
    //% "Open file"
    //@ FileOperations
    qtTrId("msg.open");
    \endcode
    Or in QML:
    \code qml
    //% "Open file"
    //@ FileOperations
    qsTrId("msg.open");
    \endcode
    When you open the TS file in \l {Qt Linguist}, the ID-based entries with
    the same \e label are grouped together, similar to text-based
    entries that are grouped by context.
    Any item without a \e label appears under \c{<unnamed label>}.
    \note Label names have no effect on lookup or uniqueness: IDs remain globally
    unique and can still be loaded via \c{qtTrId("msgid")} without referencing a
    label. The label tag is used only to improve the translator’s navigation
    and does not change runtime behavior.
 
    \section1 CMake configuration
 
    When building with CMake, use the prefix \c qml_ for .ts files.
    For example, \c qml_en.ts. In the CMakeLists.txt file, add the
    \l qt_add_translations function, where you list the *.ts files
    as values of \c TS_FILES, and set the value of RESOURCE_PREFIX to the
    URI of the main.qml file for the project followed by /i18n:
 
    \badcode
    qt_add_translations(${CMAKE_PROJECT_NAME}
        TS_FILES i18n/qml_de_DE.ts i18n/qml_en_US.ts
        RESOURCE_PREFIX Main/i18n
    )
    \endcode
 
    \section1 Advanced use with qmake
 
    For projects that target a large number of locales, you can remove the
    TRANSLATIONS info from the .pro file and, instead, manage the translations
    with a separate script. The script can call \c lrelease and \c lupdate for each of
    the desired targets.
 
    The updates could be scripted something like this:
 
    \code
    lupdate -recursive <project-dir> -ts <project-dir>/i18n/myapp-text_en_GB.ts
    lupdate -recursive <project-dir> -ts <project-dir>/i18n/myapp-text_en_US.ts
    ...
    \endcode
 
    The generation of the final .qm files could be scripted something like this:
 
    \code
    lrelease <project-dir>/i18n/myapp-text_en_GB.ts
    lrelease <project-dir>/i18n/myapp-text_en_US.ts
    ...
    \endcode
 
*/
 
/*!
    \page linguist-meta-strings-reference.html
    \title Meta strings reference
    \ingroup internationalization
 
    \previouspage Text ID based translations
 
    \brief Reference guide for meta strings used in Qt's translation system.
 
    Meta strings are special comments that provide additional information to
    lupdate and \QL for translation processing. They use specific
    prefixes to identify their purpose and can be used in C++, QML, and Python code.
 
    \section1 Meta string syntax overview
 
    Meta strings are special comments that use specific prefixes to provide lupdate
    with additional information about translations:
 
    \table
      \header
          \li Meta String
          \li Purpose
          \li Usage
      \row
          \li \c{//:}
          \li Extra comment for translators
          \li Provides context and guidance to help translators
      \row
          \li \c{//%}
          \li Source text (engineering English)
          \li Defines display text for ID-based translations during development
      \row
          \li \c{//@}
          \li Label for grouping
          \li Organizes ID-based translations into logical groups
      \row
          \li \c{//~}
          \li Extra key-value metadata
          \li Stores additional custom information about the translation
      \row
          \li \c{// TRANSLATOR}
          \li Magic comment for context
          \li Provides context information about the class or file
    \endtable
 
    \note The \c{//=} meta string for message ID mapping is deprecated and should not be used in new code.
 
    \section1 Translator comments (//:)
 
    Use \c{//:} comments to provide additional context and guidance to translators.
    These comments appear in the \QL translation interface and help
    translators understand the meaning and usage of the text.
 
    \section2 C++ example
    \code cpp
    //: Button to navigate backwards in the application
    tr("Back");
 
    //: This is a file menu item that opens an existing document.
    //: Keep translation short to fit in menu.
    tr("Open");
    \endcode
 
    \section2 QML example
    \code qml
    Button {
      //: Emergency stop button - must be clearly visible
      text: qsTr("STOP")
    }
    \endcode
 
    \section2 Python example
    \code python
    #: Button to navigate backwards in the application
    self.tr("Back")
 
    #: This is a file menu item that opens an existing document.
    #: Keep translation short to fit in menu.
    self.tr("Open")
    \endcode
 
    Multiple translator comments can be used for the same string and will be
    concatenated with newlines in the TS file.
 
    \section2 TS file format
 
    Translator comments appear as \c{<extracomment>} elements in the TS file:
 
    \code xml
    <message>
        <source>Back</source>
        <extracomment>Button to navigate backwards in the application</extracomment>
        <translation type="unfinished"></translation>
    </message>
    \endcode
 
    \section1 Source text (//%)
 
    The \c{//%} meta string defines the \e{engineering English} text that appears
    in the user interface during development when using ID-based translations.
    This is essential for making the application usable before translations
    are complete.
 
    \section2 C++ example
    \code cpp
    //% "Save Document"
    qtTrId("file.save");
 
    //% "Found %n items"
    qtTrId("search.results", count);
    \endcode
 
    \section2 QML example
    \code qml
    Text {
      //% "Welcome to the application"
      text: qsTrId("welcome.message")
    }
    \endcode
 
    \section2 Important notes
    \list
      \li Include parameter placeholders (%1, %n) in the source text
      \li The source text should be production-ready English
      \li Without //% comments, the text ID itself appears in the UI
    \endlist
 
    \section2 TS file format
 
    Source text appears as the \c{<source>} element:
 
    \code xml
    <message id="file.save">
        <source>Save Document</source>
        <translation type="unfinished"></translation>
    </message>
    \endcode
 
    \section1 Labels (//@)
 
    Use \c{//@} meta strings to organize ID-based translations into logical
    groups or categories within \QL. This is particularly useful
    for large projects with many translation strings.
 
    \note The \c{//@} meta string is only intended for ID-based translations
    (qtTrId/qsTrId) and should not be used with text-based translations (tr/qsTr).
 
    \section2 C++ example
    \code cpp
    //% "New Document"
    //@ FileOperations
    qtTrId("file.new");
 
    //% "Print Document"
    //@ FileOperations
    qtTrId("file.print");
 
    //% "Connection failed"
    //@ NetworkErrors
    qtTrId("network.error.connection");
    \endcode
 
    \section2 QML example
    \code qml
    Button {
      //% "Login"
      //@ Authentication
      text: qsTrId("auth.login")
    }
    \endcode
 
    \note Labels are not applicable to Python translations since Python only supports
    text-based translations (self.tr()) and not ID-based translations.
 
    Strings with the same label appear grouped together in \QL,
    making it easier for translators to work on related content.
 
    \section2 TS file format
 
    Labels appear as a \c{label} element:
 
    \code xml
    <message id="file.new" label="FileOperations">
        <source>New Document</source>
        <label>FileOperations</label>
        <translation type="unfinished"></translation>
    </message>
    \endcode
 
    \section1 Extra metadata (//~)
 
    The \c{//~} meta string allows you to attach arbitrary key-value metadata
    to translations. This can be used for custom processing or translator
    guidance.
 
    \section2 Syntax
    \code
    //~ key value
    //~ key "quoted value with spaces"
    \endcode
 
    \section2 C++ example
    \code cpp
    //% "Error"
    //: Critical system error dialog
    //~ Severity High
    //~ MaxLength "20"
    //~ Context "Error dialogs"
    qtTrId("system.error");
    \endcode
 
    \section2 QML example
    \code qml
    Text {
      //% "Loading..."
      //~ Context "Progress indicators"
      //~ ShowDuration "true"
      text: qsTrId("progress.loading")
    }
    \endcode
 
    \section2 Python example
    \code python
    #~ Severity High
    #~ Context "Error dialogs"
    self.tr("Critical system error")
    \endcode
 
    \section2 TS file format
 
    Extra metadata appears as \c{<extra-*>} elements in the TS file and can be
    processed by custom tools or translation workflows.
 
    \code xml
    <message id="system.error">
        <source>Error</source>
        <comment>Critical system error dialog</comment>
        <translation type="unfinished"></translation>
        <extra-Severity>High</extra-Severity>
        <extra-MaxLength>20</extra-MaxLength>
        <extra-Context>Error dialogs</extra-Context>
    </message>
    \endcode
 
    \section1 TRANSLATOR magic comments
 
    \c{TRANSLATOR} comments provide context information about a class or
    source file to help translators understand where translations are used.
 
    \section2 C++ example
    \snippet doc_src_linguist-manual.cpp 5
 
    \section2 QML example
    \code qml
    // TRANSLATOR LoginDialog Login dialog for user authentication
    Item {
      Text {
          text: qsTr("Username")
      }
    }
    \endcode
 
    \section2 Python example
    \code python
    # TRANSLATOR MainWindow
    #
    # Main application window containing the primary user interface.
    # Keep button labels concise due to space constraints.
    #
    class MainWindow(QMainWindow):
      def setupUi(self):
          self.tr("File")  # translations for this context
    \endcode
 
    \section2 TS file format
 
    TRANSLATOR comment appear as a \c{<message>} elements with empty source text
    on the \c{<context>} element:
 
    \code xml
    <context>
        <name>Main</name>
        <message>
            <source></source>
            <comment>LoginDialog Login dialog for user authentication</comment>
            <translation></translation>
        </message>
    </context>
    \endcode
 
    \section1 Combining meta strings
 
    Meta strings can be combined to provide comprehensive translation metadata:
 
    \section2 Complete C++ example
    \code cpp
    //: File dialog - confirm destructive action
    //: This will permanently delete the selected files
    //% "Delete Selected Files"
    //@ FileOperations
    //~ Severity High
    //~ RequiresConfirmation "true"
    qtTrId("file.delete.confirm");
    \endcode
 
    \section2 Complete QML example
    \code qml
    Text {
      //: Shows current connection status to server
      //: Updates automatically every few seconds
      //% "Connected to server"
      //@ NetworkStatus
      //~ UpdateFrequency "5000ms"
      //~ Color "green"
      text: qsTrId("status.connected")
    }
    \endcode
 
    \section1 Best practices
 
    \list
      \li Use translator comments (//:) generously to provide context
      \li Always include source text (//%) for ID-based translations
      \li Group related translations using labels (//@) in large projects
      \li Place meta strings immediately before the translation function call
      \li Keep translator comments clear and concise but informative
      \li Use consistent naming for labels and extra metadata keys
    \endlist
*/