テキストIDに基づく翻訳

テキスト ID による翻訳メカニズムは、国際化およびローカライゼーションのための産業レベルの堅牢なシステムです。アプリケーション内の各テキストには一意の識別子（テキスト ID）が割り当てられており、ソースコード内ではテキストの代わりにこのテキスト ID を使用します。これにより、大量の翻訳テキストの管理が格段に容易になります。

テキストIDを用いた国際化

プレーンテキストの代わりにテキストIDを使用する場合、アプリケーションを国際化する一般的な方法は同じですが、詳細が若干異なります：

1. テキストIDベースの翻訳システム用の関数やマクロは、プレーンテキストシステムとは異なります。qsTr()の代わりにqsTrId()関数を、QT_TR_NOOP()の代わりにQT_TRID_NOOP()マクロを、QT_TR_N_NOOP()の代わりにQT_TRID_N_NOOP()マクロを使用します。
2. プレーンテキスト文字列の代わりに、テキストIDをユーザーインターフェースの文字列として使用してください。例えば、qsTrId("id-back-not-front")
3. テキスト ID ではコンテキストパラメータを指定できないため、綴りが同じでも意味が異なる単語には、それぞれ個別のテキスト ID が必要です。例えば、qsTrId("id-back-backstep") は、後退を表す「Back」と、id-back-not-front における「Back」を区別します。
4. テキスト ID ベースの翻訳ではコンテキスト名を使用できないため、Qt Linguist はコンテキスト名なしで ID をファイルに一覧表示します。
5. 開発ビルドのユーザーインターフェースに表示されるエンジニアリング英語のテキストは、//% コメントで示されます。これを含めない場合、ユーザーインターフェースにはテキスト ID が表示されます。これは、パラメータを含むテキストがある場合に特に重要です。//% コメントには、文字列内にパラメータの識別子を含める必要があります。例えば、//% "Number of files: %1"
6. プレーンテキスト方式では、翻訳者に追加情報を提供する//: コメントは任意です。しかし、テキストIDベースのシステムでは、この追加情報が不可欠となります。なぜなら、これがないとテキストIDしかなく、翻訳者はそれだけでは文脈がわからないため、適切な翻訳を行うことができない可能性があるからです。 長い説明的なテキストIDを使用し、コメントを省略することも可能ですが、コメントがある方が理解しやすい場合が多いです。

以下の並列コードスニペットは、text-IDベースの翻訳とプレーンテキストベースの翻訳を比較したものです：

Text {
    id: backTxt;
    //: The back of the object, not the front
    //% "Back"
    //~ Context Not related to back-stepping
    text: qsTrId("id-back-not-front");
}

Text {
    id: backTxt;
    //: The back of the object, not the front
    //~ Context Not related to back-stepping
    text: qsTr("Back","Not front")
}

テキストIDを使用したローカライズ

テキスト ID を使用したローカライズは、プレーンテキストの場合とほぼ同じプロセスに従います。

lupdateツールを使用して TS ファイルを生成し、そこに翻訳を追加します。翻訳ファイル内のソース値はプレーンテキストではなくテキスト ID となるため、翻訳の正確性を確保するには、説明的なテキスト ID または適切な追加コメント、あるいはその両方が必要になります。

上記のテキスト ID ベースのユーザーインターフェーステキストの例では、.ts ファイルには次のような内容が記述されます。

<message id="id-back-not-front">
    <source>Back</source>
    <extracomment>The back of the object, not the front</extracomment>
    <translation type="unfinished"></translation>
    <extra-Context>Not related to back-stepping</extra-Context>
</message>

特定のテキストに対する翻訳が存在しない場合（通常、開発の終盤まではこの状態が続きます）、ユーザーインターフェースには適切なテキストの代わりにテキスト ID が表示されます。 テストにおいてアプリケーションをより使いやすくするために、lrelease で「エンジニアリング英語」のソーステキスト（//% のコメントから取得）を翻訳テキストとして使用し、感嘆符（!）などの目印を付けることができます。これにより、まだ翻訳されていないテキストを識別できるようになります。

ID ベースの翻訳のグループ化

大規模なプロジェクトの ID ベースのエントリを小さなグループに整理するために、各 ID ベースの翻訳にラベルを割り当てることができます。ID ベースのエントリにラベルを割り当てるには、ラベル名を指定した `//@ ` コメントを追加します。例えば C++ では次のようにします:

//% "Open file"
//@ FileOperations
qtTrId("msg.open");

または、QMLでは次のようにします：

//% "Open file"
//@ FileOperations
qsTrId("msg.open");

TSファイルを Qt LinguistでTSファイルを開くと、同じラベルを持つIDベースのエントリは、コンテキストごとにグループ化されるテキストベースのエントリと同様に、まとめて表示されます。ラベルのない項目はすべて「<unnamed label> 」の下に表示されます。

ラベルの自動生成

ラベル名を手動で指定する代わりに、プレースホルダーを使用してコード構造に基づいてラベルを自動的に生成することができます：

• //@ <context> - 完全なコンテキスト（名前空間::クラス）を自動的に使用します
• //@ <class> - クラス名のみ（名前空間を除く）を自動的に使用
• //@ <file> - ソースファイル名を自動的に使用

プレースホルダーの組み合わせ

プレースホルダーをカスタムテキストと組み合わせることで、より説明的なラベルを作成できます:

• //@ <file>:<class> - ファイル名とクラスを組み合わせる:filehandler.cpp:FileHandler
• //@ <context>_customSuffix - 接尾辞を追加:MyApp::FileHandler_customSuffix
• //@ module_<file>_<class>-label - カスタム接頭辞と接尾辞:module_filehandler.cpp_FileHandler-label
• //@ <context>:<file> - ファイルに関連するコンテキスト:MyApp::FileHandler:filehandler.cpp

たとえば、C++では：

namespace MyApp {
class FileHandler : QObject {
    Q_OBJECT
    void open() {
        //% "Open file"
        //@ <context>
        qtTrId("msg.open"); // Label: MyApp::FileHandler

        //% "Save file"
        //@ <class>
        qtTrId("msg.save"); // Label: FileHandler

        //% "Export"
        //@ <file>
        qtTrId("msg.export"); // Label: filehandler.cpp
    }
};
}

あるいはQMLでは：

Item {
    id: myComponent
    Component.onCompleted: {
        //% "Loading"
        //@ <context>
        qsTrId("msg.loading") // Label: <component-name>

        //% "Ready"
        //@ <file>
        qsTrId("msg.ready") // Label: main.qml

        //% "Initialized"
        //@ <file>:<context>-state
        qsTrId("msg.init") // Label: main.qml:<component-name>-state
    }
}

自動ラベルは、多数のファイルにわたってラベル名を手動で管理するのが煩雑になりがちな大規模なプロジェクトにおいて特に有用です。これにより、コード構造に基づいた一貫したグループ化が保証され、翻訳者に対してその翻訳がどこで使用されるかについてのヒントが提供されます。

CMakeの設定

CMake を使用してビルドする場合は、.ts ファイルにプレフィックスqml_ を使用してください。 例えば、qml_en.ts などです。CMakeLists.txt ファイルにqt_add_translations関数を追加し、TS_FILES の値として *.ts ファイルを列挙するとともに、RESOURCE_PREFIX の値をプロジェクトの main.qml ファイルの URI の後に /i18n を付加した形式に設定してください:

qt_add_translations(${CMAKE_PROJECT_NAME}
    TS_FILES i18n/qml_de_DE.ts i18n/qml_en_US.ts
    RESOURCE_PREFIX Main/i18n
)

qmake を使用した高度な使い方

多数のロケールを対象とするプロジェクトの場合、.proファイルからTRANSLATIONS情報を削除し、代わりに別のスクリプトで翻訳を管理することができます。このスクリプトでは、対象となる各ターゲットに対してlrelease およびlupdate を呼び出すことができます。

更新処理は、次のようなスクリプトで実現できます：

lupdate -recursive <project-dir> -ts <project-dir>/i18n/myapp-text_en_GB.ts
lupdate -recursive <project-dir> -ts <project-dir>/i18n/myapp-text_en_US.ts
...

最終的な .qm ファイルの生成は、次のようなスクリプトで実現できます:

lrelease <project-dir>/i18n/myapp-text_en_GB.ts
lrelease <project-dir>/i18n/myapp-text_en_US.ts
...