- Qt 6.12
- Qt Linguist Manual
- Developers
- Meta strings reference
- Qt 6.12.0 Reference Documentation

Text ID based translations ◦ CMake commands

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

For automatic label generation using placeholders like `<context>`, `<class>`, `<file>`, and their combinations, see Automatic Label Generation.

### 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>

### Recognized extra keys

While any key can be used with `//~`, the `no-wrap` flag within `po-flags` is recognized by `lconvert`. See PO format-specific options.

## 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

Text ID based translations ◦ CMake commands