本页内容

元字符串参考

元字符串是用于向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 本身会显示在 UI 中

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 魔术注释

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 的翻译,请务必包含源文本(//%)
  • 在大型项目中,使用标签(//@)将相关翻译分组
  • 将元字符串放置在翻译函数调用的正前方
  • 翻译注释应清晰简洁,但信息丰富
  • 为标签和额外元数据键采用一致的命名规则

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