diff options
Diffstat (limited to 'src/linguist/linguist/doc/src/linguist-manual.qdoc')
| -rw-r--r-- | src/linguist/linguist/doc/src/linguist-manual.qdoc | 1628 |
1 files changed, 912 insertions, 716 deletions
diff --git a/src/linguist/linguist/doc/src/linguist-manual.qdoc b/src/linguist/linguist/doc/src/linguist-manual.qdoc index 3c718cf89..32caa80f2 100644 --- a/src/linguist/linguist/doc/src/linguist-manual.qdoc +++ b/src/linguist/linguist/doc/src/linguist-manual.qdoc @@ -1,568 +1,848 @@ -/**************************************************************************** -** -** Copyright (C) 2019 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// 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 Overview of the Translation Process + \nextpage Release managers \keyword Qt Linguist - Qt provides excellent support for translating Qt C++ and Qt Quick - applications into local languages. Release managers, translators, and - developers can use Qt tools to accomplish their tasks. + Release managers, translators, and developers can use Qt tools to translate + Qt C++ and Qt Quick applications into local languages. - \l{linguist-manager.html}{Release managers} bear the overall responsibility - for the release of the application. Typically, they coordinate the work of - developers and translators. They can use the \e lupdate tool to synchronize - source code and translations and the \e lrelease tool to create - run-time translation files for use by the released application. + In addition to the Qt translation file (TS) format, \QL and \c lupdate + support XML Localization Interchange File Format (XLIFF). - \l{linguist-translators.html}{Translators} can use the \QL tool to - translate text in applications. - No computer knowledge beyond the ability to start a program and - use a text editor or word processor is required. + \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 - \l{linguist-programmers.html}{Developers} must create Qt applications that are - able to use translated text. They should also help translators identify - the context in which phrases appear. Developers can use tutorials to learn - about their tasks. + The following video shows how to internationalize and localize a simple + example application: - For more information about the supported languages and writing systems, see - \l{Internationalization with Qt}. + \youtube xNIz78IPBu0 +*/ - \section1 Table of Contents +/*! + \page linguist-toc.html + \title All topics \list - \li \l{Overview of the Translation Process} - \li \l{Qt Linguist Manual: Release Manager}{Release Manager} - \li \l{Qt Linguist Manual: Translators}{Translators} - \li \l{Qt Linguist Manual: Developers}{Developers} - \li \l{Qt Linguist Manual: TS File Format}{TS File Format} - \li \l{Qt Linguist Manual: Text ID Based Translations}{Text ID Based Translations} - \li \l{cmake-macros-qtlinguisttools}{CMake Commands} + \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-overview.html - \title Overview of the Translation Process - \ingroup internationalization + \page linguist-manager.html + \title Release managers \previouspage Qt Linguist Manual - \nextpage Qt Linguist Manual: Release Manager - - Most of the text that must be translated 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. - - The phrases are entered into the source code by the developer in - their native language using a simple but special syntax to identify - that the phrases require translation. The Qt tools provide context - information for each of the phrases to help the translator, and the - developer is able to add additional context information to phrases - when necessary. - - The release manager generates a set of translation - files that are produced from the source files and passes these to the - translator. The translator opens the translation files using \QL, - enters their translations, and saves the results back into - the translation files, which they pass back to the release manager. - The release manager then generates fast compact versions of these - translation files ready for use by the application. - - The tools are designed to be used in repeated cycles as applications - change and evolve, preserving existing translations and making it - easy to identify which new translations are required. \QL also - provides a phrase book facility to help ensure consistent - translations across multiple applications and projects. - - Translators and developers must address a number of issues because - of the subtleties and complexities of human language: + \nextpage Creating translation files - \list + \image front-publishing.png - \li A single phrase may need to be translated into several - different forms depending on context. For example, \e open in English - might become \e{\ouml}\e{ffnen}, "open file", or \e aufbauen, - "open internet connection", in German. - - \li Keyboard accelerators may need to be changed but without - introducing conflicts. For example, "\&Quit" in English becomes - "Avslutt" in Norwegian which does not contain a "Q". We cannot - use a letter that is already in use - unless we change several - accelerators. - - \li Phrases that contain variables, for example, "The 25 files - selected will take 63 seconds to process", where the two numbers - are inserted programmatically at runtime, may need to be rephrased. - The word order in the other language may be different, so the - variables will have to be put in another place in the sentence. + 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 - The Qt translation tools provide clear and simple solutions to these - issues. + 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. - \QL and lupdate are able to import and export XML Localization - Interchange File Format (XLIFF) files, making it possible to take - advantage of tools and translation services that work with this - format. For more information on working with these files, see - \l{Qt Linguist Manual: Translators}{Translators}. + 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-manager.html - \title Qt Linguist Manual: Release Manager - \ingroup internationalization + \page linguist-creating-ts-files.html + + \previouspage Release managers + \nextpage Using lupdate - \previouspage Overview of the Translation Process - \nextpage Qt Linguist Manual: Translators + \title Creating translation files - Two tools are provided for the release manager: \c lupdate and - \c lrelease. These tools can process \l {qmake Manual}{qmake} project files, - or operate directly on the file system. + 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. - \section1 Creating Translation Files + 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 Ctrl key - accelerators in an application and translations of that text. + 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 lupdate to generate the first set of translation source (TS) files - with all the user-visible text but no translations. + \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 the translator who adds translations using \QL. \QL - takes care of any changed or deleted source text. + \li Give the TS files to translators who add translations using \QL. + \QL indicates changed and deleted source text. - \li Run lupdate to incorporate any new text added to the application. - lupdate synchronizes the user-visible text from the application with the - translations. It does not destroy any data. + \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 To release the application, run lrelease to read the TS files and - produce the QM files used by the application at runtime. + \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. The files are listed in the application's \c .pro Qt project file. + 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 - \section1 Using lupdate - Usage: \c {lupdate myproject.pro} + \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 - The lupdate command line tool finds the translatable - strings in the specified source, header and \e {Qt Designer} - interface files, and produces or updates \c .ts translation - files. The files to process and the files to update can be set at - the command line, or provided in a \c .pro file specified as a - command line argument. The developer creates the .pro file, as - described in \l{Qt Linguist Manual: Developers}. + 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 - You can generate the translation file for a single QML file in - the following way: + To view the latest help, enter: \badcode - lupdate main.qml -ts main_en.ts + 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, - you copy main_en.ts to main_fr.ts, and translate the strings in the + 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 + RESOURCES += qml.qrc \endcode To have all QML files processed by \c lupdate: \badcode - lupdate application.qrc -ts myapp_en.ts + lupdate application.qrc -ts myapp_en.ts \endcode - You can also process all QML files without using a \c .qrc file: + To process all QML files without using a \c .qrc file: \badcode - lupdate -extensions qml -ts myapp_en.ts + lupdate -extensions qml -ts myapp_en.ts \endcode - If you are mostly processing QML files, but also have C++ code - that contains strings to be translated, you can add it in the same command: + To check for translatable strings in both QML and C++ source files: \badcode - lupdate qml.qrc filevalidator.cpp -ts myapp_en.ts + lupdate qml.qrc filevalidator.cpp -ts myapp_en.ts \endcode - The translation files can be mentioned in the .pro file, but it - is also possible to do without it, and just specify the translation - file on the command line. - - For example, to generate .ts files that will be used for English and - French: + 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 + lupdate qml.qrc filevalidator.cpp -ts myapp_en.ts myapp_fr.ts \endcode - The produced translation files are given to the translator who - uses \QL to read the files and insert the translations. + Give the TS files to the translator who uses \QL to read the files and + insert the translations. - Companies that have their own translators in-house may find it - useful to run lupdate regularly, perhaps monthly, as the - application develops. This will lead to a fairly low volume of - translation work spread evenly over the life of the project and - will allow the translators to support a number of projects - simultaneously. + \section1 XLIFF format files - Companies that hire in translators as required may prefer to run - lupdate only a few times during the application life cycle. The - first time might be just before the first test phase. This will - provide the translator with a substantial single block of work and - any bugs that the translator detects may easily be included with - those found during the initial test phase. The second and any - subsequent lupdate runs would probably take place during the - final beta phase. + 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. +*/ - The TS file format is a simple human-readable XML format that - can be used with version control systems if required. \c lupdate - can also process Localization Interchange File Format (XLIFF) - format files; files in this format typically have file names that - end with the \c .xlf suffix. +/*! + \page linguist-lrelease.html + \target lrelease - \note The minimum supported version for XLIFF format files is - 1.1. XLIFF 1.0 version files are not supported. + \previouspage Using lupdate + \nextpage Translators - Pass the \c -help option to \c lupdate to view supported options. + \title Using lrelease - \QL is also able to import and export XLIFF files. See the - \l{Qt Linguist Manual: Translators}{Translators} section for more - information. + 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. - \target lrelease - \section1 Using lrelease + When building with qmake, specify the files to process at the command line + or in a .pro file. - Usage: \c {lrelease myproject.pro} + 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. - The lrelease command line tool produces QM files out - of TS files. The QM file format is a compact binary format - that is used by the localized application. It provides extremely - fast lookups for translations. The TS files lrelease - processes can be specified at the command line, or given - indirectly by a Qt \c .pro project file. + 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. - This tool is run whenever a release of the application is to be - made, from initial test version through to final release - version. If the QM files are not created, for example because an - alpha release is required before any translation has been - undertaken, the application will run perfectly well using the text - the developers placed in the source files. Once the QM files - are available the application will detect them and use them - automatically. + \note The \c lrelease tool only incorporates translations that you + mark as \e finished. Otherwise, it uses the original text instead. - \c lrelease can be also be run without specifying a \.pro file: + \section1 lrelease syntax \badcode - lrelease.exe main_en.ts languages\main_fr.ts + lrelease [options] -project project-file + lrelease [options] ts-files [-qm qm-file] \endcode - \note The lrelease tool only incorporates translations that are - marked as "finished". Otherwise the original text is used - instead. + Where: - Pass the \c -help option to \c lrelease to view supported options. + \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 - \section1 Missing Translations + \note Passing .pro files to \c lrelease is deprecated. Use the + \c lrelease-pro tool or the \c lrelease.prf feature when using qmake. - Both lupdate and lrelease may be used with TS - translation source files which are incomplete. Missing - translations will be replaced with the native language phrases at - runtime. + 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 - \title Qt Linguist Manual: Translators - \ingroup internationalization - \previouspage Qt Linguist Manual: Release Manager - \nextpage Qt Linguist Manual: Developers + \previouspage Using lrelease + \nextpage Qt Linguist user interface + + \title Translators - \QL is a tool for adding translations to Qt applications. Once you have + \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 \gui Context (\key F6) for selecting from a list of contexts in - which strings to be translated appear. + \li \uicontrol Context (\key F6) lists translation contexts. - \li \gui Strings (\key F7) for viewing translatable strings found in a - context. + \li \uicontrol Strings (\key F7) lists translatable strings in the + selected context. - \li \gui {Sources and Forms} (\key F9) for viewing the context where the - current string is used if the source code for the context is - accessible. + \li \uicontrol {Sources and Forms} (\key F9) displays the selected + string in the source code. - \li Translation area for translating strings. + \li Translation area displays the selected string and enables you to + enter a translation for it. - \li \gui {Phrases and Guesses} (\key F10) for viewing possible + \li \uicontrol {Phrases and guesses} (\key F10) lists possible translations for the current string. - \li \gui Warnings (\key F8) for viewing translated strings that fail + \li \uicontrol Warnings (\key F8) lists translated strings that fail validation tests. \endlist - \image linguist-linguist.png "Qt Linguist UI" + \image linguist-linguist.png {Qt Linguist UI} The translation area (1) is always visible. To show or hide the other views, - select \gui View > \gui Views, or use the keyboard shortcuts listed above. + 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 - \section1 Translating Strings + \previouspage Qt Linguist user interface + \nextpage Selecting context to translate - You open translation source (TS) files in \QL for translation. TS files are + \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 lupdate. If you do not have a TS - file, see \l {Qt Linguist Manual: Release Manager} {Release Manager} to - learn how to generate one. + 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. The minimum supported version for XLIFF format files is 1.1. + 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 \gui Translator and - \gui {Translator comment} fields are displayed for each language. + 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}. + \l{Changing the target locale}. - If the developer provides a \l{QObject::tr()} {disambiguating - comment}, it is displayed in the \gui {Developer comments} field. + If the developer provides a disambiguating comment, you can see it in the + \uicontrol {Developer comments} field. To translate strings: \list 1 - \li Select \gui File > \gui Open to load a TS file. + \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. - \li Select a context in the \gui Context view to load the translatable - strings found in that context into the \gui Strings view. + \image linguist-ui.webp {Two TS files open in Qt Linguist} - \li Select a string to copy it as the \gui {Source text} in the - translation area. The whitespace within the source text is - visualized so that you can see the spacing required within the text. + \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 \gui Translation + \li Enter the translation of the current string in the \uicontrol Translation field. - You can also select an existing translation from the - \gui {Phrases and Guesses} view by double-clicking it. The phrases - are read from phrase books and the guesses are existing translations - of similar phrases in the TS file. + 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 to be read by other translators in the - \gui {Translator comment} field. + \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 \gui File > \gui Save to save your work. + \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 - (\gui {Accepted/Correct}) or + (\uicontrol {Accepted/Correct}) or \inlineimage linguist-check-warning.png - (\gui {Accepted/Warnings}). Then select the next context and continue. + (\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 \gui View > \gui Statistics. + translated text, select \uicontrol View > \uicontrol Statistics. - Select \gui File > \gui Release to create a Qt message QM file with the same - base name as the current translation source file. The release manager's - command line tool lrelease performs the same function on \e all of an + 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 \gui File > - \gui Print. - - To quit \QL, select \gui File > \gui Exit. - - \section2 Leaving a Translation for Later - - If you wish to leave a translation, press \key{Ctrl+L} (Next - Unfinished) to move to the next unfinished translation. To move to - the next translation (whether finished or unfinished) press - \key{Shift+Ctrl+L}. You can also navigate using the \gui Translation - menu. If you want to go to a different context entirely, click the - context you want to work on in the \gui Context list, then click the - source text in the \gui Strings view. - - \section2 Phrases That Require Multiple Translations Depending on Context - - The same phrase may occur in two or more contexts without conflict. Once - a phrase has been translated in one context, \QL notes that the translation - has been made and when the translator reaches a later occurrence of the same - phrase, \QL provides - the previous translation as a possible translation candidate in the - \gui {Phrases and Guesses} view. - - If a phrase occurs more than once in a particular context it is shown only - once in the \gui Context view and the translation is applied to every - occurrence within the context. If the same phrase needs to be translated - differently within the same context, the developer must provide a - distinguishing comment for each occurrence of the phrase. If such comments - are used, the duplicate phrases appear in the \gui Context view. The - developer's comments appear in the translation area on a light blue - background. - - \section2 Changing Keyboard Accelerators - - A keyboard accelerator is a key combination that, when pressed, - causes an application to perform an action. There are two kinds of - keyboard accelerators: Alt key and Ctrl key accelerators. - - \section3 Alt Key Accelerators - - Alt key accelerators are used in menu selection and on buttons. - The underlined character in a menu item or button label signifies - that pressing the Alt key with the underlined character will - perform the same action as clicking the menu item or pressing the - button. For example, most applications have a \e{File} menu with - the "F" in the word "File" underlined. In these applications the - \e{File} menu can be invoked either by clicking the word "File" on - the menu bar or by pressing \e{Alt+F}. To identify an accelerator - key in the translation text ("File") precede it with an ampersand: - \e{\&File}. If a string to be translated has an ampersand in - it, then the translation for that string should also have an - ampersand in it, preferably in front of the same character. - - The meaning of an Alt key accelerator can be determined from the - phrase in which the ampersand is embedded. The translator can - change the character part of the Alt key accelerator, if the - translated phrase does not contain the same character or if that - character has already been used in the translation of some other - Alt key accelerator. Conflicts with other Alt key accelerators - must be avoided within a context. Note that some Alt key - accelerators, usually those on the menu bar, may apply in other - contexts. - - \section3 Ctrl Key Accelerators - - Ctrl key accelerators can exist independently of any visual - control. They are often used to invoke actions in menus that would - otherwise require multiple keystrokes or mouse clicks. They may - also be used to perform actions that do not appear in any menu or - on any button. For example, most applications that have a \e{File} - menu have a \e{New} submenu item in the \e{File} menu. The \e{New} - item might appear as "\underline{N}ew Ctrl+N" in the \e{File} - menu, meaning the \e{New} menu can be invoked by simply pressing - \key{Ctrl+N}, instead of either clicking \e{File} with the mouse - and then clicking \e{New} with the mouse, or by entering \e{Alt+F} - and \e{N}. - - Each Ctrl key accelerator is shown in the \gui Strings view - as a separate string, for example \key{Ctrl+Enter}. Since + 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 Alt key accelerator appears, - the translator must rely on the UI developer to include a - \l{QObject::tr()} {disambiguation comment} to explain the action - the Ctrl key accelerator is meant to perform. This disambiguating - comment (if provided by the developer) will appear under - \gui {Developer comments} in the translation area below the - \gui {Source text} field. - - Ideally, translations for Ctrl key accelerators are simply copied by - selecting \gui Translation > \gui {Copy from source text}. However, in some - cases the character will - not make sense in the target language, and it must be - changed. Whichever character (alpha or digit) is chosen, the - translation must be in the form "Ctrl+" followed by the upper case - character. Qt will automatically display the correct name at - run-time. As with Alt key accelerators, if the translator changes - the character, the new character must not conflict with any other - Ctrl key accelerator. - - \warning Do not translate the "Alt", "Ctrl" or "Shift" parts of - the accelerators. Qt relies on these strings being there. For - supported languages, Qt automatically translates these strings. - - \section2 Handling Numbered Arguments and Plurals - - Some phrases contain numbered arguments. A numbered argument is a - placeholder that will be replaced with text at run-time. A numbered - argument appears in a source string as a percent sign followed by - a digit. Consider an example: \c{After processing file %1, file %2 - is next in line}. In this string to be translated, \c{%1} and - \c{%2} are numbered arguments. At run-time, \c{%1} and \c{%2} will - be replaced with the first and second file names respectively. The + 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. \c{%i} will always be - replaced by the same text in the translation strings, regardless - of where argument \e{i} appears in the argument sequence in the - source string. + 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 - plurals in the source text. In many languages, the form of the + 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#Handling Plurals} - {Writing Source Code for Translation}. + \l{Writing Source Code for Translation}. - \section2 Changing the Target Locale + \section1 Changing the target locale - You can set the locale information explicitly in \gui Edit > - \gui {Translation File Settings}. If the target language and country + 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 @@ -575,25 +855,37 @@ \endlist If this attempt to resolve the target language and country fails, the - \gui {Translation File Settings} window opens. + \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 + 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{linguist-programmers.html}{Developers}. + \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} - \section1 Selecting Context to Translate + A context for QObject itself contains strings passed to the static function + QObject::tr(). - The \gui Context view lists the contexts in which strings to be translated - appear. The column labeled \gui Context lists the context names in - alphabetical order. Each context is the name of a subclass of - QObject. There can also be a context for QObject itself, which - contains strings passed to the static function QObject::tr(). - There can also be an \e{<unnamed context>}, which contains strings - that are not in a subclass of QObject. + 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: @@ -606,7 +898,7 @@ \row \li Accepted/Correct \li \inlineimage linguist-check-on.png - \li All strings in the context have been translated, and all the + \li All strings in the context have been translated, and all the translations passed the \l{Validating Translations}{validation tests}. \row @@ -614,7 +906,7 @@ \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 \gui Strings view, you can see which string failed the test. + In the \uicontrol Strings view, you can see which string failed the test. \row \li Not Accepted @@ -626,25 +918,33 @@ \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 itself no longer exists in the application. + usually means the context no longer exists in the application. \endtable - The \gui Items column displays the total number of translatable strings in + 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 - \section1 Selecting String to Translate + \title Selecting strings to translate - The \gui Strings view lists all the translatable strings found in the - current context and their translation acceptance state. Selecting a string - makes that string the current string in the translation area. + 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 been translated - and the translation has been accepted. A question mark means either that the - translation has not been accepted or that the string does not have a - translation. + 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: @@ -659,154 +959,160 @@ \row \li Accepted/Correct \li \inlineimage linguist-check-on.png - \li The source string has a translation (possibly empty). The user - has accepted the translation, and the translation passes all the - \l{Validating Translations} {validation tests}. If the translation is - empty, the user has chosen to leave it empty. Click the icon to - revoke acceptance of the translation and decrement the number of - accepted translations in the \gui Items column of the \ gui Context view - by 1. The state is reset to \gui {Not Accepted} if the string has a - translation, or to \gui {No Translation} if the string's translation is + \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 is automatically reset to \gui {Not Accepted}. + state becomes \uicontrol {Not Accepted}. \row \li Accepted/Warnings \li \inlineimage linguist-check-warning.png - \li The user has accepted the translation, but the translation does - not pass all the validation tests. The validation test failures are - shown in the \gui Warnings view. Click the icon to revoke acceptance of - the translation. The state is reset to \gui {Validation Failures}, and - the number of accepted translations in the \gui Items column of the - \gui Context view is decremented by 1. + \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 - the user has not yet accepted the translation. Click the icon or press - \key{Ctrl+Enter} to accept the translation. The state is reset to - \gui {Accepted/Correct}, and the number of accepted translations in the - \gui Items column of the \gui Context view is incremented by 1. + 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. Click the icon to - accept the empty translation anyway. The state is reset to - \gui {Accepted/Correct}, and the number of accepted translations in the - \gui Items column of the \gui Context view is incremented by 1. + \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. Validation test failures are shown in the - \gui Warnings view. Click on the icon or press \key{Ctrl+Return} to - accept the translation even with validation failures. The state is - reset to \gui {Accepted/Warnings}. We recommended editing the - translation to fix the causes of the validation failures. The state will - reset automatically to \gui {Not Accepted}, when all the failures have - been fixed. + 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 the \l{Qt Linguist Manual: Release Manager} {Release Manager} - for instructions on how to remove obsolete messages from the file. + See \l{Using lupdate} for instructions on how to remove obsolete + messages from the file. \endtable +*/ - \section1 Viewing Strings in Context +/*! + \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 files containing the translatable strings are - available to \QL, the \gui {Sources and Forms} view shows the source context - of the current string in the \gui Strings view. The source - code line containing the current string should be shown and - highlighted. If the file containing the source string is not - found, the expected absolute file path is shown. + 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}. - If the source context shows the wrong source line, it probably - means the translation file is out of sync with the source files. - For more information about how to re-sync the translation file with the - source 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 - Forms created by \QD are stored in special UI files. \QL can make use of - these UI files to show the translations done so far on the form itself if - the UI files are available to it during the translation process. + \previouspage Viewing strings in context + \nextpage Validating translations - \section1 Reusing Translations + \title Reusing translations If the translated text is similar to the source text, select - \gui Translation > \gui {Copy from source text} (or press \key{Ctrl+B}) to - copy the source text into the translation area. + \uicontrol Translation > \uicontrol {Copy from source text} + (or press \key{Ctrl+B}) to copy the source text into the + translation area. - In \QL, \e {phrase books} are used to provide a common set of translations + \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 can also be - used to avoid duplication of effort since the translations for a family of - applications can be produced once in the phrase book. - - If the current string in the \gui Strings view appears in one or more of the - phrase books that have been loaded, the current string and its phrase book - translations are listed in the \gui {Phrases and Guesses} view. If the - current string is the same as, or similar to, another string that has - already been translated, that other string and its translation - are also listed in this view. - - To copy a translation from the \gui {Phrases and Guesses} view to the + 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. - \section2 Batch Translation + \section1 Batch translation \image linguist-batchtranslation.png - Use the batch translation feature of \QL to automatically translate source + 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 \gui Edit > - \gui {Batch Translation}. You can specify whether only entries with no - current translation should be considered, and whether batch translated - entries should be marked as \gui Accepted. + 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. - \section2 Creating and Editing Phrase Books + \section1 Creating and editing phrase books Phrase book files are human-readable XML files containing standard phrases - and their translations. These files are created and updated by \QL and may - be used by any number of projects and applications. + 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 \gui Phrases > \gui {New Phrase Book}. + To create a new phrase book, select \uicontrol Phrases > \uicontrol {New Phrase Book}. \image linguist-phrasebookdialog.png - To open a phrase book, select \gui Phrases > \gui {Open Phrase Book}, and + 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 \gui Phrases > - \gui {Edit Phrase Book}. + To view and change open phrase books, select \uicontrol Phrases > + \uicontrol {Edit Phrase Book}. - To add a new phrase, select \gui {New Entry} (or press \key {Alt+N}) and - type in a new source phrase, the translation, and an optinal definition. + 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 - \gui Phrases > \gui {Add to Phrase Book} or press \key{Ctrl+T}. If multiple + \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 that is shown in the - \gui {Phrases and Guesses} view, you can also edit it in place by right - clicking on the entry, and selecting \gui Edit. After fixing the error - press \key{Return} to leave the editing mode. + 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}. +*/ - To delete a phrase, select it in the \gui {Source phrase} list, and then - select \gui {Remove Entry}. +/*! + \page linguist-validating-translations.html - To print an open phrase book, select \gui Phrases > - \gui {Print Phrase Book}. + \previouspage Reusing translations + \nextpage Translating multiple languages simultaneously - \section1 Validating Translations + \title Validating translations \QL provides the following validation tests for translations: @@ -821,32 +1127,37 @@ 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 - given in the phrase book. + in the phrase book. \li \e {Place marker validation} detects whether the same variables - (like \c %1, \c %2) are used both in the source text and in the + (like \c %1, \c %2) appear both in the source text and in the translation. \endlist - To switch validation tests on or off, select \gui Validation or use the + 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 - \gui {Validation Failures} icon in the \gui Strings view. Accepted strings - are marked with \gui {Accepted/Warnings}. + \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. - If the translation you enter for the current string fails any of - the active validation tests, the failures - are listed in the \gui Warnings view. The first of these failure - messages is also shown in the status bar at the bottom of the main - window. + 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 - \section1 Translating Multiple Languages Simultaneously + + \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 @@ -854,231 +1165,119 @@ \image linguist-linguist_2.png - The translation area has text editing areas for both Polish and Japanese, - and these are color-coded for easier separation. The \gui Context view and - the \gui Strings view both have two status columns instead of one, - color-coded with the same colors. The left-most column - is related to the top-most language area (Polish above) - in the translation area, and the right-most column is related to the bottom - language area. + 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 \gui Items column in the \gui Context view combines the values + 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 need - to be translated or accepted. The \gui Strings view shows the translation + 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 Qt Linguist Manual: Developers - \ingroup internationalization - - \previouspage Qt Linguist Manual: Translators - \nextpage Qt Linguist Manual: TS File Format - - Support for multiple languages is extremely simple in Qt - applications, and adds little overhead to the developer's workload. - - Qt minimizes the performance cost of using translations by - translating the phrases for each window as they are created. In most - applications the main window is created just once. Dialogs are often - created once and then shown and hidden as required. Once the initial - translation has taken place there is no further runtime overhead for - the translated windows. Only those windows that are created, - destroyed and subsequently created will have a translation - performance cost. - - Creating applications that can switch language at runtime is possible - with Qt, but requires a certain amount of developer intervention and - will of course incur some runtime performance cost. + \title Developers - \section1 Specifying Translation Sources in Qt Project Files + \previouspage Translating multiple languages simultaneously + \nextpage TS File Format - To enable release managers to use lupdate and lrelease, specify - a \c .pro Qt project file. There must be an entry in the \c TRANSLATIONS - section of the project file for each language that is additional to - the native language. A typical entry looks like this: - - \snippet arrowpad/arrowpad.pro 1 - - Using a locale within the translation file name is useful for - determining which language to load at runtime. For more information, see - QLocale. - - The \c lupdate tool extracts user interface strings from your application. - It reads the application .pro file to identify which source files - contain text to be translated. This means your source files must be listed - in the \c SOURCES or \c HEADERS entry in the .pro file, or in resource - files listed in the \c RESOURCE entry. If your files are - not listed, the text in them will not be found. - - An example of a complete \c .pro file with four translation source - files: - - \snippet doc_src_linguist-manual.pro 0 - - \c lupdate expects all source code to be encoded in UTF-8 by default. - Files that feature a BOM (Byte Order Mark) can also be encoded in - UTF-16 or UTF-32. Set the qmake variable \c CODECFORSRC to - \c UTF-16 to parse files without a BOM as UTF-16. - - Some editors, such as Visual Studio, however use a different - encoding by default. One way to avoid encoding issues is to limit any - source code to ASCII, and use escape sequences for translatable strings - with other characters, for example: - - \snippet doc_src_linguist-manual.cpp 3 - - \section1 Internationalizing Applications + \image front-coding.png Design your application so that it can be adapted to various languages and - regions without engineering changes. Qt tries to make internationalization - as painless as possible for you. All input controls and text drawing methods - in Qt offer built-in support for all supported languages. But you still need - to keep the following things in mind when writing source code for your - application: + 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 - \li Make your application look for and load the appropriate translation - file. - - \li Mark user-visible text and Ctrl keyboard accelerators as targets for - translation. - - \li Provide context for text to be translated. - - \li Disambiguate identical texts. - - \li Use numbered arguments (%n) as placeholders for parameters that are - replaced with text or numbers at run-time. - - \li Internationalize numbers, dates, times, and currencies. + For more information, see also: + \list + \li \l {Internationalization with Qt} + \li \l {Writing Source Code for Translation} + \li \l {Localizing Applications}. + \endlist - \li Mark data text strings outside functions translatable. + 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}. - \endlist + The following video shows how to internationalize and localize a simple + example application: - You can develop applications that use both C++ and QML sources in the same - application and even have user interface strings in both sources. The tools - create a single combined translation file and the strings are accessible - from C++ and QML. - - The classes that support internationalizing of Qt applications are described - in \l{Internationalization with Qt}. The process of making source code - translatable is described in \l{Writing Source Code for Translation} and in - \l{Internationalization and Localization with Qt Quick}. - - Each piece of text that requires translating requires context to help - the translator identify where in the program the text appears. In the - case of multiple identical texts that require different translations, - the translator also requires some information to disambiguate the - source texts. Marking text for translation will automatically cause - the class name to be used as basic context information. In some cases - the developer may be required to add additional information to help - the translator. - - \section1 Deploying Translations - - The \c .qm files required for the application should be placed in a - location where the loader code using \l QTranslator can locate them. - Typically, this is done by specifying a path relative to - \l QCoreApplication::applicationDirPath(). - - Usually, there are \c .qm files for the application, and, if a version of - Qt is used that is not installed on the system, Qt's .qm files need to be - deployed as well. - - In Qt 4, there is one big, monolithic \c .qm file per locale. For example, - the file \c qt_de.qm contains the German translation of all libraries. - - In Qt 5, the \c .qm files were split up by module and there is a so-called - meta catalog file which includes the \c .qm files of all modules. The - name of the meta catalog file is identical to the name of Qt 4's monolithic - \c .qm file so that existing loader code works as before provided - all included \c .qm files are found. - - However, it is not necessary to always deploy all of Qt 5's \c .qm files. - We recommend concatenating the \c .qm files of the modules required to - one file matching the meta catalog file name using the tool \c lconvert in - the deploy step. For example, to create a German translation file for an - application using the modules \l{Qt Core}, \l {Qt GUI}, and \l {Qt Quick}, - run: + \youtube xNIz78IPBu0 +*/ - \code - lconvert -o installation_folder/qt_de.qm qtbase_de.qm qtdeclarative_de.qm - \endcode +/*! + \page linguist-programmers-examples.html + \title Examples - \section1 Tutorials + \nextpage Developers - The following tutorials illustrate how to prepare Qt applications for + 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. + 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 the - translation file applicable to the current locale. It also shows the - use of the two-argument form of \c tr() which provides additional - information to the translator. + 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 - identical source texts can be distinguished even when they occur in - the same context. This tutorial also discusses how the translation - tools help minimize the translator's work when an application is - upgraded. - - \li \l{QML Examples - Internationalization}{Internationalization} is a - Qt Quick application that demonstrates how to internationalize Qt Quick - applications. + 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 Qt Linguist Manual: TS File Format - \ingroup internationalization + \title TS file format + + \previouspage Developers - \previouspage Qt Linguist Manual: Developers - \nextpage Qt Linguist Manual: Text ID Based Translations + \brief TS file format. The TS file format used by \QL is described by the - \l{http://www.w3.org/TR/1998/REC-xml-19980210}{DTD} presented below, + \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.dtd + \quotefile ../../../shared/ts.xsd */ /*! \page linguist-id-based-i18n.html - \title Qt Linguist Manual: Text ID Based Translations + \title Text ID based translations \ingroup internationalization - \previouspage Qt Linguist Manual: TS File Format \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 "industrial strength" system for - internationalization and localization. Each text in the application is assigned - a unique identifier (text ID) and these identifiers are used directly in the - source code in place of the plain texts. This requires a little more work for - the user interface developers but makes it much easier to manage large numbers - of translated texts. + 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 + \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 @@ -1087,20 +1286,21 @@ \list 1 \li The functions and macros for the text-ID-based translation system are - different to the plain-text system. You use the \c qsTrId() function instead - of qsTr(), and the \c QT_TRID_NOOP() macro instead of QT_TR_NOOP(). + 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. If there are - identically spelled words with different meanings, these need separate - text IDs. For example, \c {qsTrId("id-back-backstep")} will - differentiate the back-step "Back" from the back-of-the-object "Back". + \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 "Engineering English" text that you see in the user interface for + \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 will be shown in the user interface. This is + 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"} @@ -1144,21 +1344,15 @@ \endcode \endtable - \section1 Localizing With Text IDs + \section1 Localizing with text IDs Localizing with text IDs follows much the same process as for plain text. - The \c lupdate tool is used the same way and translations are made into - the .ts files: - - \code - lupdate <myapp>.pro - \endcode - - Note that the source values in the translation files will be text IDs rather - than plain text. This means you need very descriptive text IDs, or good - additional comments, or both to ensure that the translator makes a correct - translation. + 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: @@ -1172,39 +1366,41 @@ </message> \endcode - When using \c lrelease, you need to specify that the keys for translated - texts are based on text IDs, rather than plain texts. If strings in the code - are specified with \c qsTr() there is no "id" attribute set so they are - ignored by \c lrelease. - - This command produces all the compiled translation .qm files for your - application: - - \code - lrelease -idbased <myapp>.pro - \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 "Engineering English" + 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 so you can see texts that are not yet translated. + some indicator, such as an exclamation mark (!), so you can see texts that + are not yet translated. - For example, this command builds the .qm files and puts a "!" in front of the - untranslated texts: - - \code - lrelease -idbased -markuntranslated ! <myapp>.pro - \endcode + \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 Usage + \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 lrelease and lupdate for each of + 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: |