Meta strings reference
Meta strings are special comments that provide additional information to lupdate and Qt Linguist for translation processing. They use specific prefixes to identify their purpose and can be used in C++, QML, and Python code.
Meta string syntax overview
Meta strings are special comments that use specific prefixes to provide lupdate with additional information about translations:
Meta String | Purpose | Usage |
---|---|---|
//: | Extra comment for translators | Provides context and guidance to help translators |
//% | Source text (engineering English) | Defines display text for ID-based translations during development |
//@ | Label for grouping | Organizes ID-based translations into logical groups |
//~ | Extra key-value metadata | Stores additional custom information about the translation |
// TRANSLATOR | Magic comment for context | Provides context information about the class or file |
Note: The //=
meta string for message ID mapping is deprecated and should not be used in new code.
Translator comments (//:)
Use //:
comments to provide additional context and guidance to translators. These comments appear in the Qt Linguist translation interface and help translators understand the meaning and usage of the text.
C++ example
//: Button to navigate backwards in the application tr("Back"); //: This is a file menu item that opens an existing document. //: Keep translation short to fit in menu. tr("Open");
QML example
Button { //: Emergency stop button - must be clearly visible text: qsTr("STOP") }
Python example
#: Button to navigate backwards in the application self.tr("Back") #: This is a file menu item that opens an existing document. #: Keep translation short to fit in menu. self.tr("Open")
Multiple translator comments can be used for the same string and will be concatenated with newlines in the TS file.
TS file format
Translator comments appear as <extracomment>
elements in the TS file:
<message> <source>Back</source> <extracomment>Button to navigate backwards in the application</extracomment> <translation type="unfinished"></translation> </message>
Source text (//%)
The //%
meta string defines the engineering English text that appears in the user interface during development when using ID-based translations. This is essential for making the application usable before translations are complete.
C++ example
//% "Save Document" qtTrId("file.save"); //% "Found %n items" qtTrId("search.results", count);
QML example
Text { //% "Welcome to the application" text: qsTrId("welcome.message") }
Important notes
- Include parameter placeholders (%1, %n) in the source text
- The source text should be production-ready English
- Without //% comments, the text ID itself appears in the UI
TS file format
Source text appears as the <source>
element:
<message id="file.save"> <source>Save Document</source> <translation type="unfinished"></translation> </message>
Labels (//@)
Use //@
meta strings to organize ID-based translations into logical groups or categories within Qt Linguist. This is particularly useful for large projects with many translation strings.
Note: The //@
meta string is only intended for ID-based translations (qtTrId/qsTrId) and should not be used with text-based translations (tr/qsTr).
C++ example
//% "New Document" //@ FileOperations qtTrId("file.new"); //% "Print Document" //@ FileOperations qtTrId("file.print"); //% "Connection failed" //@ NetworkErrors qtTrId("network.error.connection");
QML example
Button { //% "Login" //@ Authentication text: qsTrId("auth.login") }
Note: Labels are not applicable to Python translations since Python only supports text-based translations (self.tr()) and not ID-based translations.
Strings with the same label appear grouped together in Qt Linguist, making it easier for translators to work on related content.
TS file format
Labels appear as a label
element:
<message id="file.new" label="FileOperations"> <source>New Document</source> <label>FileOperations</label> <translation type="unfinished"></translation> </message>
Extra metadata (//~)
The //~
meta string allows you to attach arbitrary key-value metadata to translations. This can be used for custom processing or translator guidance.
Syntax
//~ key value //~ key "quoted value with spaces"
C++ example
//% "Error" //: Critical system error dialog //~ Severity High //~ MaxLength "20" //~ Context "Error dialogs" qtTrId("system.error");
QML example
Text { //% "Loading..." //~ Context "Progress indicators" //~ ShowDuration "true" text: qsTrId("progress.loading") }
Python example
#~ Severity High #~ Context "Error dialogs" self.tr("Critical system error")
TS file format
Extra metadata appears as <extra-*>
elements in the TS file and can be processed by custom tools or translation workflows.
<message id="system.error"> <source>Error</source> <comment>Critical system error dialog</comment> <translation type="unfinished"></translation> <extra-Severity>High</extra-Severity> <extra-MaxLength>20</extra-MaxLength> <extra-Context>Error dialogs</extra-Context> </message>
TRANSLATOR magic comments
TRANSLATOR
comments provide context information about a class or source file to help translators understand where translations are used.
C++ example
/* TRANSLATOR MainWindow This class contains the main application window interface. All menu items and toolbar buttons are defined here. */ class MainWindow : public QMainWindow { // ... translations for this context };
QML example
// TRANSLATOR LoginDialog Login dialog for user authentication Item { Text { text: qsTr("Username") } }
Python example
# TRANSLATOR MainWindow # # Main application window containing the primary user interface. # Keep button labels concise due to space constraints. # class MainWindow(QMainWindow): def setupUi(self): self.tr("File") # translations for this context
TS file format
TRANSLATOR comment appear as a <message>
elements with empty source text on the <context>
element:
<context> <name>Main</name> <message> <source></source> <comment>LoginDialog Login dialog for user authentication</comment> <translation></translation> </message> </context>
Combining meta strings
Meta strings can be combined to provide comprehensive translation metadata:
Complete C++ example
//: File dialog - confirm destructive action //: This will permanently delete the selected files //% "Delete Selected Files" //@ FileOperations //~ Severity High //~ RequiresConfirmation "true" qtTrId("file.delete.confirm");
Complete QML example
Text { //: Shows current connection status to server //: Updates automatically every few seconds //% "Connected to server" //@ NetworkStatus //~ UpdateFrequency "5000ms" //~ Color "green" text: qsTrId("status.connected") }
Best practices
- Use translator comments (//:) generously to provide context
- Always include source text (//%) for ID-based translations
- Group related translations using labels (//@) in large projects
- Place meta strings immediately before the translation function call
- Keep translator comments clear and concise but informative
- Use consistent naming for labels and extra metadata keys
© 2025 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.