path: root/src/linguist/linguist/doc/src/linguist-manual.qdoc

// 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
        \li \inlineimage front-ui.png
        \li \inlineimage front-coding.png
    \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}
            \endlist
        \li
            \list
                \li \l {Qt Linguist user interface}
                \li \l {Translating strings}
                \li \l {Selecting context 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{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 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{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

    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. It does not destroy any data.

        \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 {-no-recursive}
        \li Do not recursively scan directories.
    \row
        \li \c {-recursive}
        \li Recursively scan directories (default).
    \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.
    \row
        \li \c {-clang-parser [compilation-database-dir]}
        \li Use clang to parse .cpp files. Otherwise, use a custom
            parser. This option needs a clang compilation database
            (\c compile_commands.json) for the files to be parsed.
            Specify the path to the directory containing this file
            on the command line, directly after the \c -clang-parser
            option, or in the project file.

            When using qmake, set the \c LUPDATE_COMPILE_COMMANDS_PATH
            variable in the .pro file.

            A directory specified on the command line takes precedence. If you
            do not specify a path, \c lupdate searches for the compilation
            database from all parent paths of the first input file.
    \row
        \li \c {-project-roots <directory>...}
        \li Specify one or more project root directories. Only files
            below a project root are considered for translation when
            using the \c -clang-parser option.
    \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 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 Translators

    \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 Use IDs instead of source strings for message keying.
    \row
        \li \c {-compress}
        \li Compress the QM files.
    \row
        \li \c {-nounfinished}
        \li Do not include unfinished translations.
    \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 {-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-translators.html

    \previouspage Using lrelease
    \nextpage Qt Linguist user interface

    \title Translators

    \image front-ui.png

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

    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 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
*/

/*!
    \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 (\key F6) lists translation contexts.

        \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-linguist.png {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 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 {Two TS files open in Qt Linguist}

        \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
            , 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
    (\uicontrol {Accepted/Correct}) or
    \inlineimage linguist-check-warning.png
    (\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
    (\uicontrol {Next Unfinished}) or press \key{Ctrl+J}.

    To move to the next source text, select \inlineimage next.png
    , 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 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
*/

/*!
    \page linguist-selecting-context.html

    \previouspage Translating strings
    \nextpage Selecting strings to translate

    \title Selecting context to translate

    The \uicontrol Context view lists the contexts in which strings to be translated
    appear. The column labeled \uicontrol Context lists the context names in
    alphabetical order. Each context is the name of a QML type or a subclass of
    QObject.

    \image linguist-context-view.webp {Context view}

    A context for QObject itself contains strings passed to the static function
    QObject::tr().

    An \e{<unnamed context>} contains strings that are not in a subclass of
    QObject.

    The following icons indicate the current translation state for each context:

    \table
    \header
    \li State
    \li Icon
    \li Description

    \row
    \li Accepted/Correct
    \li \inlineimage linguist-check-on.png
    \li All strings in the context have been translated, and all the
        translations passed the \l{Validating Translations}{validation tests}.

    \row
    \li Accepted/Warnings
    \li \inlineimage linguist-check-warning.png
    \li All strings in the context 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
    \li At least one string in the context has not been translated or is not
        marked as translated.

    \row
    \li Obsolete
    \li \inlineimage linguist-check-obsolete.png
    \li None of the translated strings appears in the context any more. This
        usually means the context no longer exists in the application.
    \endtable

    The \uicontrol Items column displays the total number of translatable strings in
    the context and the number of translated strings, separated by a slash (/).
    If the numbers are equal, all the translatable strings in the context have
    translations.
*/

/*!
    \page linguist-selecting-strings.html

    \previouspage Selecting context to translate
    \nextpage Viewing strings in context

    \title Selecting strings to translate

    The \uicontrol Strings view lists all the translatable strings in the
    current context 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
    \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
    \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
    \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
    \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
    \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
    \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

    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

    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 Developers

    \title Translating multiple languages simultaneously

    You can load and edit multiple translation files simultaneously.
    The following screen shot displays \e{Polish} and \e{Japanese} translation
    files loaded.

    \image linguist-linguist_2.png

    The translation area has color-coded text editing areas for both Polish and
    Japanese. The \uicontrol Context view and the \uicontrol Strings view have
    color-coded status columns for each language.

    The \uicontrol Items column in the \uicontrol Context 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-programmers.html
    \title Developers

    \previouspage Translating multiple languages simultaneously
    \nextpage TS File Format

    \image front-coding.png

    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{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.

    \note You must use only plain-text-based or only text-ID-based functions in
    one application. If you mix them, you will end up with an incomplete set of
    texts to be translated.


    \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 \c qsTrId() function instead
        of qsTr(), the \c QT_TRID_NOOP() macro instead of QT_TR_NOOP(),
        and \c 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 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

    When using \l{Using lrelease}{lrelease}, you need to specify that the keys
    for translated texts are based on text IDs, rather than plain text. If you
    use \c qsTr() to mark the strings as translatable in the code, the \c id
    attribute is not set and \c lrelease ignores them.

    However, 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.

    \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, set the value of RESOURCE_PREFIX to the
    URI of the main.qml file for the project followed by /i18n, and
    set the value of \c LRELEASE_OPTIONS to \c -idbased:

    \badcode
    qt_add_translations(${CMAKE_PROJECT_NAME}
        TS_FILES i18n/qml_de_DE.ts i18n/qml_en_US.ts
        RESOURCE_PREFIX Main/i18n
        LRELEASE_OPTIONS -idbased
    )
    \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 -idbased <project-dir>/i18n/myapp-text_en_GB.ts
    lrelease -idbased <project-dir>/i18n/myapp-text_en_US.ts
    ...
    \endcode

*/