メタ文字列リファレンス
メタ文字列は特別なコメントで、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はテキストベースの翻訳(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 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.