Using lupdate

The lupdate command line tool finds translatable strings in source, header, 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 CMake commands to add targets that create or update TS files and transform them into QM files. The lupdate tool is run with the options you pass to the commands when you build the target.

For more information about specifying translations in project files, see Localizing Applications.

lupdate syntax

lupdate [options] [project-file]...
lupdate [options] [source-file|path|@lst-file]... -ts ts-files|@lst-file

Where:

options means one or several lupdate options.
project-file is the project configuration file.
source-file is a file that contains translatable strings.
path is the path to a folder that contains translation source files.
@lst-file reads additional file names (one per line) or includepaths (one per line and prefixed with -I) from lst-file.
ts-files are the TS files to generate or update.

To view the latest help, enter:

lupdate -help

lupdate options

Option	Action
`-help`	Display up-to-date help information and exit.
`-no-obsolete`	Drop all obsolete and vanished strings.
`-extensions <ext>[,<ext>]...`	Process files with the given extensions, only. Use commas to separate extensions in the list. Do not use whitespace. The default value is: `java,jui,ui,c,c++,cc,cpp,cxx,ch,h,h++,hh,hpp,hxx,js,qs,qml,qrc`.
`-pluralonly`	Only include plural form messages.
`-silent`	Do not explain what is being done.
`-no-sort`	Do not sort contexts in TS files.
`-no-recursive`	Do not recursively scan directories.
`-recursive`	Recursively scan directories (default).
`-I <includepath> or -I<includepath>`	Look for include files in this additional location. You can specify multiple paths.
`-locations {absolute\|relative\|none}`	Specify or override the way to save source code references in TS files. `absolute` means that the source file path is relative to the target file, but the line number is absolute. `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. `none` stores no information about source location. If you do not specify the location, `lupdate` determines it from existing TS files. The default value for new files is `absolute`.
`-no-ui-lines`	Do not record line numbers in references to UI files.
`-disable-heuristic {sametext\|similartext\|number}`	Disable the named merge heuristic. Can be specified multiple times.
`-project <filename>`	Name of a file containing the project's description in JSON format. You can use the `lprodump` tool to generate the file from a .pro file.
`-pro <filename>`	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 `lupdate-pro` tool instead.
`-pro-out <directory>`	Virtual output directory for processing subsequent .pro files.
`-pro-debug`	Trace processing .pro files. Specify twice for more verbosity.
`-source-language <language>[_<region>]`	Specify the language of the source strings for new files. Defaults to POSIX if not specified.
`-target-language <language>[_<region>]`	Specify the language of the translations for new files. If you do not specify the language, `lupdate` determines it from the file name.
`-tr-function-alias <function>{+=,=}<alias>[,<function>{+=,=}<alias>]...`	With `+=`, recognize `<alias>` as an alternative spelling of `<function>`. With `=,` recognize `<alias>` as the only spelling of `<function>`. Available `<function>` values (with their currently defined aliases) are: `Q_DECLARE_TR_FUNCTIONS` (`=Q_DECLARE_TR_FUNCTIONS`) `QT_TR_N_NOOP` (`=QT_TR_N_NOOP`) `QT_TRID_N_NOOP` (`=QT_TRID_N_NOOP`) `QT_TRANSLATE_N_NOOP` (`=QT_TRANSLATE_N_NOOP`) `QT_TRANSLATE_N_NOOP3` (`=QT_TRANSLATE_N_NOOP3`) `QT_TR_NOOP` (`=QT_TR_NOOP`) `QT_TRID_NOOP` (`=QT_TRID_NOOP`) `QT_TRANSLATE_NOOP` (`=QT_TRANSLATE_NOOP`) `QT_TRANSLATE_NOOP3` (`=QT_TRANSLATE_NOOP3`) `QT_TR_NOOP_UTF8` (`=QT_TR_NOOP_UTF8`) `QT_TRANSLATE_NOOP_UTF8` (`=QT_TRANSLATE_NOOP_UTF8`) `QT_TRANSLATE_NOOP3_UTF8` (`=QT_TRANSLATE_NOOP3_UTF8`) `findMessage` (`=findMessage`) `qtTrId` (`=qtTrId`) `tr` (`=tr`) `trUtf8` (`=trUtf8`) `translate` (`=translate`) `qsTr` (`=qsTr`) `qsTrId` (`=qsTrId`) `qsTranslate` (`=qsTranslate`)
`-ts <ts-file>...`	Specify the output files. This overrides `TRANSLATIONS`.
`-version`	Display the version of `lupdate` and exit.
`-clang-parser [compilation-database-dir]`	Use clang to parse .cpp files. Otherwise, use a custom parser. This option needs a clang compilation database (`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 `-clang-parser` option, or in the project file. When using qmake, set the `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, `lupdate` searches for the compilation database from all parent paths of the first input file.
`-project-roots <directory>...`	Specify one or more project root directories. Only files below a project root are considered for translation when using the `-clang-parser` option.

Examples

Using lupdate with CMake

When building with CMake, use CMake commands to add translations on targets to the CMakeLists.txt file, and then build the targets.

Select one of the following options:

Use qt_add_translations on a target, such as app. This calls qt_add_lupdate and qt_add_lrelease.
Use qt_add_lupdate on a target.

Build a target (for example, app_lupdate) to update the .ts files for it. To update the .ts files for all targets, build the target update_translations.

Using lupdate with qmake

To generate a translation file for a single QML file:

lupdate main.qml -ts main_en.ts

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.

lupdate processes QML files that are listed in the .qrc file:

RESOURCES += qml.qrc

To have all QML files processed by lupdate:

lupdate application.qrc -ts myapp_en.ts

To process all QML files without using a .qrc file:

lupdate -extensions qml -ts myapp_en.ts

To check for translatable strings in both QML and C++ source files:

lupdate qml.qrc filevalidator.cpp -ts myapp_en.ts

To generate .ts files that will be used for English and French without specifying the languages in the project file:

lupdate qml.qrc filevalidator.cpp -ts myapp_en.ts myapp_fr.ts

Give the TS files to the translator who uses Qt Linguist to read the files and insert the translations.

XLIFF format files

The TS file format is a simple human-readable XML format that you can use with version control systems. In addition, lupdate can process Localization Interchange File Format (XLIFF) files (.xlf).

Note: Only XLIFF versions 1.1 and 1.2 are currently supported.

You can open and edit XLIFF files in Qt Linguist.

Release managers Using lrelease

© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.