元字符串参考

元字符串是一种特殊注释，可为 lupdate 和Qt Linguist 的翻译处理提供额外信息。它们使用特定的前缀来标识其目的，可用于 C++、QML 和 Python 代码中。

元字符串语法概述

元字符串是使用特定前缀的特殊注释，可为 lupdate 提供有关翻译的附加信息：

元字符串	目的	用法
`//:`	为翻译人员提供额外注释	为翻译人员提供上下文和指导
`//%`	源文本（工程英语）	在开发过程中为基于 ID 的翻译定义显示文本
`//@`	分组标签	将基于 ID 的翻译组织成逻辑组
`//~`	额外的键值元数据	存储有关翻译的其他自定义信息
`// TRANSLATOR`	上下文魔法注释	提供有关类或文件的上下文信息

注意： 用于消息 ID 映射的//= 元字符串已被弃用，不应在新代码中使用。

翻译注释 (//:)

使用//: 注释为翻译人员提供额外的上下文和指导。这些注释会出现在Qt Linguist 翻译界面中，帮助翻译人员理解文本的含义和用法。

C++ 示例

//: 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 示例

Button {
  //: Emergency stop button - must be clearly visible
  text: qsTr("STOP")
}

Python 示例

#: 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")

同一字符串可使用多个翻译注释，这些注释将在 TS 文件中用换行符连接起来。

TS 文件格式

翻译注释在 TS 文件中显示为<extracomment> 元素：

<message>
    <source>Back</source>
    <extracomment>Button to navigate backwards in the application</extracomment>
    <translation type="unfinished"></translation>
</message>

源文本 (//%)

//% 元字符串定义了在开发过程中使用基于 ID 的翻译时出现在用户界面中的工程英语文本。这对于在翻译完成之前使应用程序可用至关重要。

C++ 示例

//% "Save Document"
qtTrId("file.save");

//% "Found %n items"
qtTrId("search.results", count);

QML 示例

Text {
  //% "Welcome to the application"
  text: qsTrId("welcome.message")
}

重要说明

在源文本中包含参数占位符 (%1, %n)
源文本应为可直接用于生产的英语
如果没有 //% 注释，文本 ID 本身会出现在用户界面中

TS 文件格式

源文本显示为<source> 元素：

<message id="file.save">
    <source>Save Document</source>
    <translation type="unfinished"></translation>
</message>

标签 (//@)

使用//@ 元字符串可将基于 ID 的翻译组织到Qt Linguist 中的逻辑组或类别中。这对于有许多翻译字符串的大型项目尤其有用。

注意： //@ 元字符串仅用于基于 ID 的翻译 (qtTrId/qsTrId)，不应与基于文本的翻译 (tr/qsTr) 一起使用。

C++ 示例

//% "New Document"
//@ FileOperations
qtTrId("file.new");

//% "Print Document"
//@ FileOperations
qtTrId("file.print");

//% "Connection failed"
//@ NetworkErrors
qtTrId("network.error.connection");

QML 示例

Button {
  //% "Login"
  //@ Authentication
  text: qsTrId("auth.login")
}

注意： 标签不适用于 Python 翻译，因为 Python 只支持基于文本的翻译 (self.tr())，而不支持基于 ID 的翻译。

具有相同标签的字符串会在Qt Linguist 中组合在一起，便于翻译人员处理相关内容。

关于使用占位符（如<context>,<class>,<file>, 及其组合）自动生成标签，请参阅自动标签生成。

TS 文件格式

标签以label 元素的形式出现：

<message id="file.new" label="FileOperations">
    <source>New Document</source>
    <label>FileOperations</label>
    <translation type="unfinished"></translation>
</message>

额外元数据 (//~)

//~ 元字符串允许您为翻译附加任意键值元数据。这可用于自定义处理或翻译指导。

语法

//~ key value
//~ key "quoted value with spaces"

C++ 示例

//% "Error"
//: Critical system error dialog
//~ Severity High
//~ MaxLength "20"
//~ Context "Error dialogs"
qtTrId("system.error");

QML 示例

Text {
  //% "Loading..."
  //~ Context "Progress indicators"
  //~ ShowDuration "true"
  text: qsTrId("progress.loading")
}

Python 示例

#~ Severity High
#~ Context "Error dialogs"
self.tr("Critical system error")

TS 文件格式

额外元数据在 TS 文件中显示为<extra-*> 元素，可由自定义工具或翻译工作流程处理。

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

可识别的额外键

虽然任何键都可以与//~ 一起使用，但po-flags 中的no-wrap 标志会被lconvert 识别。请参见PO 格式特定选项。

翻译神奇注释

TRANSLATOR 注释提供类或源文件的上下文信息，帮助翻译人员理解翻译的使用位置。

C++ 示例

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

// TRANSLATOR LoginDialog Login dialog for user authentication
Item {
  Text {
      text: qsTr("Username")
  }
}

Python 示例

# 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 文件格式

TRANSLATOR 注释以<message> 元素的形式出现，<context> 元素上的源文本为空：

<context>
    <name>Main</name>
    <message>
        <source></source>
        <comment>LoginDialog Login dialog for user authentication</comment>
        <translation></translation>
    </message>
</context>

组合元字符串

元字符串可以组合使用，以提供全面的翻译元数据：

完整的 C++ 示例

//: File dialog - confirm destructive action
//: This will permanently delete the selected files
//% "Delete Selected Files"
//@ FileOperations
//~ Severity High
//~ RequiresConfirmation "true"
qtTrId("file.delete.confirm");

完整的 QML 示例

Text {
  //: Shows current connection status to server
  //: Updates automatically every few seconds
  //% "Connected to server"
  //@ NetworkStatus
  //~ UpdateFrequency "5000ms"
  //~ Color "green"
  text: qsTrId("status.connected")
}

最佳实践

大量使用翻译注释 (//:) 来提供上下文
对于基于 ID 的翻译，始终包含源文本 (//%)
在大型项目中使用标签 (//@) 对相关翻译进行分组
将元字符串放在翻译函数调用之前
保持译员注释简洁明了但信息丰富
对标签和额外元数据键使用一致的命名方式

基于 ID 的文本翻译 CMake 命令

© 2026 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.