メタ文字列のリファレンス
メタ文字列は、翻訳処理のために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>ラベル(//@)
//@ メタ文字列を使用して、Qt Linguist 内で ID ベースの翻訳を論理的なグループやカテゴリに整理します。これは、翻訳文字列が多数ある大規模なプロジェクトで特に役立ちます。
注: ` //@ ` メタ文字列は 、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 はテキストベースの翻訳 (self.tr()) のみをサポートしており、ID ベースの翻訳はサポートしていないため、ラベルは Python の翻訳には適用されません。
同じラベルを持つ文字列は、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 contextTS ファイル形式
TRANSLATORコメントは、<context> 要素に対してソーステキストが空の<message> 要素として表示されます:
<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.