API ガイド > テクニカル ノート > プラグインを国際化する >

# 国際化プロセス

国際化により、プラグインは、ユーザ インタフェースでローカライズした文字列をサポートし、ローカライズ環境で正しく動作できます。文字列リソースをローカライズするプロセスは、この文書の後半で概説する、国際化とは別の一連の手順です。ローカライズは、プラグインの国際化後にいつでも実行できます。プラグインは、翻訳が使用可能になるまで、既定のリソース値を使用して動作します。

国際化では、以下の手順が必要です。

1. プラグインのローカライズが必要な面を決定します。
2. 別の言語でプラグインを実行するときに変更する必要があるユーザ インタフェース文字列を特定します。文字列は、C++ コードまたは MEL スクリプト内にある場合があります。ハードコードされた文字列の代わりに文字列リソースを使用するように、コードとスクリプトを修正します。
3. プラグインの初期化シーケンスに文字列登録コールを追加します。
4. シングル バイトとマルチバイトのエンコーディングで文字列を適切に処理するために、文字列処理コードを確認し、必要な場合は修正を加えます。

要件の評価

プラグインを国際化する作業を行う前に、実際の要件を評価することをお勧めします。状況ごとに、プラグインの国際化の一部の面が不必要、または不適切な場合があります。

最も重要な考慮事項は、プラグインがサポートする必要があるターゲット言語の数を決定することです。プラグインのターゲット言語が 1 言語(たとえば、日本語など)のみの場合は、文字列リソースを使用する代わりに、スクリプトをローカライズしてプラグインのカスタム UI を提供することも可能な場合があります。

プラグインが以下の条件を 1 つ以上満たす場合は、文字列リソースが必要です。

- プラグインが複数のユーザ インタフェース言語(たとえば、英語と日本語など)をサポートする
- プラグインが C++ コードからユーザ メッセージを発行する(たとえば、displayError() のコールなど)
- プラグインが、ローカライズしたノードとアトリビュート名のラベルを使用して UI に表示されるノードを作成する

文字列処理のタイプやプラグイン コードが実行する入出力も検討する必要があります。文字列操作やファイル処理がほとんどまたはまったくないプラグインでは、変更はほとんど必要ないはずですが、その他のプラグインは見直して、マルチバイト文字を適切に処理することを確認する必要があります。

文字列リソースの定義と登録

このセクションでは、C++ スクリプトと MEL スクリプトでどのように文字列リソースが使用されるかと、プラグインの初期化中に文字列リソースを登録する方法を説明します。

文字列リソース キー

Maya String Catalog 内の各文字列リソースは、一意のキーによって識別されます。プラグインの場合、キーは順序が付いた文字列のペアで構成されます。ペアの最初の要素はプラグイン名で、そのプラグインで使用されるすべての文字列で共通です。キーの 2 番目の部分は、定義する文字列の一意の識別子です。たとえば、closestPointOnCurve プラグインが使用する文字列リソース キーは、以下のような形式を持ちます。

    ("closestPointOnCurve", "stringId1");
    ("closestPointOnCurve", "stringId2");
    ("closestPointOnCurve", "stringId3");

C++ の文字列リソース

MStringResourceId クラスと MStringResource クラスは、プラグイン C++ コードで文字列リソースを定義し、文字列リソースにアクセスするために使用します。MStringResourceId コンストラクタは、リソース キーを形成するために使用する 2 つの要素とリソース文字列の既定値の 3 つの引数を受け取ります。以下の例では、プラグイン名は「closestPointOnCurve」で、この文字列に与えられるユーザ定義の一意のキーは「kNoValidObject」です。

    MStringResourceId invalidObject("closestPointOnCurve", "kNoValidObject", "A curve or its transform node must be specified as a command argument, or using your current selection.");

#define ステートメントを使用して MStringResourceId を定数に関連づけると、各リソースの単一の定義点を提供するために役立ちます。一般的に、プラグインの MStringResourceId 宣言は、それを必要とする C++ モジュール間で共有されるヘッダ ファイルにまとめられています。

    #define kPluginId  "closestPointOnCurve"
    #define kNoValidObject MStringResourceId(kPluginId, "kNoValidObject", \"A curve or its transform node must be specified as a command argument, or using your current selection.")

MStringResource::getString メソッドは、コードで文字列が必要なときに、カタログの項目を検索するために使用します。カタログ検索は、既定値またはローカライズ文字列値(使用可能な場合)のいずれかを返します。文字列をロードすると、ほかの MString 同様に使用できます。

    MStatus stat;
    MString msg = MStringResource::getString(kNoValidObject, stat);
    displayError(msg);

文字列リソースには、登録するまでアクセスできません。これには、MstringResource::registerString をコールします。登録手順は、「文字列リソースの登録」で説明されています。

MEL スクリプトの文字列リソース

MEL スクリプトは、C++ コードと同じような方法で文字列リソースを使用できます。

文字列リソースを使用するには、getPluginResource コマンドを使用して値を検索します。渡される引数は、文字列リソース キーの 2 つの要素です。

    string $titleStr = getPluginResource("closestPointOnCurve", "kAETitle");
    editorTemplate -beginScrollLayout;
    editorTemplate -beginLayout $titleStr -collapse 0;

MEL リソースは、registerPluginResource コマンドを使用して登録します。登録プロセスを以下に説明します。

文字列リソースの登録

このセクションでは、プラグインで文字列リソースを登録するプロセスを説明します。すべての文字列登録は、プラグインの初期化中に実行します。

各文字列リソースは、使用する前に登録しておく必要があります。この登録手順によって、リソースの既定値が文字列カタログに確実にロードされます。プラグイン作成者は既定値を登録後、ローカライズしたリソース値をロードするコールを追加する必要があります。Maya を実行している言語でローカライズしたリソース値を使用可能な場合、ローカライズした値が既定値をオーバーライドします。

主要な登録メソッドは、MFnPlugin::registerUIStrings です。このルーチンのコールは、プラグインの initializePlugin() 関数に追加されます。文字列リソースはコールされるまでは使用できません。他の初期化メソッドで必要な場合があるため、初期化シーケンスの最初のほうに記述してください。

MFnPlugin::registerUIStrings 関数は、2 つの引数を使用します。最初の引数は、C++ コードで使用する文字列を登録するプロシージャの名前です。2 番目の引数は、MEL スクリプトで使用する文字列リソースを登録するスクリプトの名前です。

     // Register string resources used in the code and scripts
    status = plugin.registerUIStrings(registerMStringResources, "closestPointOnCurveInitStrings");
    if (!status)
    {
        status.perror("registerUIStrings");
        return status;
    }

このコールで参照される C++ ルーチン registerMStringResources は、C++ コードで使用する各 MStringResourceId を登録します。

    // Register all strings used by the plugin C++ source
    static MStatus registerMStringResources(void)
    {
        MStringResource::registerString(kNoValidObject);
        // other resources would go here
        return MS::kSuccess;
    }

この例は、ヘッダ ファイルで事前に定義されている定数を使用します。

    #define kPluginId  "closestPointOnCurve"
    #define kNoValidObject MStringResourceId(kPluginId, "kNoValidObject", \"A curve or its transform node must be specified as a command argument, or using your current selection.")

2 番目の引数は、プラグインの MEL スクリプトで使用するすべてのリソースを初期化するスクリプトの名前です。各リソースは registerPluginResources をコールして登録します。

初期化スクリプトには 2 つの目的があります。初期化リソースには、MEL リソースの登録に加え、プラグインの言語依存リソースをロードするロジックも含まれています。ルーチン loadPluginLanguageResources は、プラグイン文字列リソースのローカライズ バージョンを含むリソース ファイルの名前を使用します。ローカライズ リソース ファイルの作成とインストールの詳細については、以下の「ローカリゼーション プロセス」を参照してください。

    global proc closestPointOnCurveInitStrings()
    {
        // Register script resources
        registerPluginResource("closestPointOnCurve", "kAETitle",
            "Closest Point On Curve Attributes");
        registerPluginResource("closestPointOnCurve", "kInputCurve",
            "Input Curve");
        registerPluginResource("closestPointOnCurve", "kResults",
            "Results");
        // Load any localized resources
        loadPluginLanguageResources("closestPointOnCurve", "closestPointOnCurve.pres.mel");
    }

登録シーケンスが完了すると、文字列を Maya Catalog で使用し、MString::getStringResource (C++)または getPluginResource (MEL)を使用して検索できるようになります。リソースのローカライズ値が loadPluginLanguageResources によって特定された場合は、既定値ではなくローカライズ値がカタログから返されます。

文字列の処理

MString クラスを使用するプラグインの大部分は、ロケールに合わせて変更する必要はありませんが、一部の文字列処理コードは、シングル バイトとマルチバイトの両方の環境で正しく動作するように変更する必要があります。このセクションは、ローカライズ環境での MString の使用に関係する問題に主に重点を置いていますが、説明されている問題の多くは、文字処理全般にも適用できます。

エンコーディング

MString クラスは、既定では、ロケールのコードセットで char* 形式の文字データをエンコードするという前提の下で動作します。これは、MString クラスの既存の機能の自然な拡張です。多くの場合、既存のプラグインは、ローカライズ環境でも変更なしで引き続き機能します。新しいメソッドは、国際化アプリケーションで一般的に使用される UTF-8 とワイド文字形式を使用して、明示的に文字列を割り当て、文字列にアクセスできるように追加されました。

文字列の長さと位置の値

ローカライズしたテキストを処理する場合の最も一般的な問題は、文字列の長さの正確な解釈です。マルチバイト環境では、文字列の文字(char *)表現は、文字列の各文字を表現するのに ·1 バイトまたはそれ以上のバイトを使用します。つまり、バイト単位の文字列のストレージ長が、必ずしも文字列の個々の文字数に対応するとは限らず、この前提を使用するコードは予想どおりに動作しない場合があります。下位互換性を提供するために、MString::length メソッドは、文字バッファ内のバイト数を引き続き返します。文字列の個々の文字の数を確定する必要がある場合は、代わりに新しいメソッドの MString::numChars を使用できます。

マルチバイト環境では、文字列データへの位置インデックスの解釈も同様に問題になる場合があります(たとえば、MString::substring メソッドを使用する場合)。マルチバイト文字列を正しく処理するために追加された内容の詳細については、新しい MString メソッドを参照してください。

メッセージ文字列のフォーマット

ユーザ メッセージ文字列は、多くの場合、複数の文字列や変数を連結して構築します。別の言語では文字列の文脈や配置を変更する必要がある場合があるので、このテクニックは、ローカライズする予定の文字列には適していません。

文字列をフォーマットするには、MString::format メソッドまたは MEL format コマンドを使用します。フォーマットを使用すると、文字列を翻訳するときに、位置の引数を文脈に正しく配置できます。

次の例は、文字列の連結を使用してファイルの名前を含むエラー メッセージを作成するコードのオリジナルのブロックです。

    MString filename;
    MString msg;
    msg = "The file ";
    msg += filename;
    msg += " cannot be opened";
    displayError(msg);

次の置き換えコードは、国際化したアプリケーションで、この例がどのように正しく処理されるかを示しています。このメッセージは、リソース文字列と MString::format コマンドを使用して作成しています。

    #define kOpenError MStringResourceId("myPlugin", "kOpenError", "File ^1s cannot be opened");
    MString filename;
    MString msgFmt = MStringResource::getString(kOpenError,status);
    MString msg;
    msg.format(msgFmt, filename);
    displayError(msg);

MEL スクリプトは、MEL フォーマット コマンドも同様に使用できます。

新しい MString メソッド

以下の表は、国際化をサポートするために MString に追加された新しいメソッドの一覧です。各メソッドの詳細とローカライズ環境内の既存のメソッドの動作に関する注意については、MString クラスのマニュアルを参照してください。

新しい MString メソッド | 説明
--- | ---
MString::numChars | このルーチンは、文字列の文字数を返します。これは、文字列のバイト数、つまり MString::length によって返される値とは必ずしも対応しません。
MStatus MString::setUTF8( const char * utf8String )const char * MString::asUTF8()const char * MString::asUTF8(int *length) | これらのメソッドは、UTF-8 エンコード文字列として文字列の値を割り当て、また文字列の値にアクセスします。
Mstring::MString(wchar_t *str)MString::MString(wchar_ *str, int length)MStatus MString::setWChar(wchar_t *str, int length)MStatus MString::setWChar(wchar_t *str, int length)const wchar_t* MString::asWChar()const wchar_t* MString::asWChar(int length) | これらのメソッドを使用すると、ワイド文字の値を使用して、文字列の値を設定することや、文字列の値にアクセスすることができます。注: 永続記憶装置には、ワイド文字列表現はお勧めしません。代わりに、UTF-8 などの移植可能なフォーマットの使用をお勧めします。
int MString::indexW(char c) constint MString::indexW(wchar_t c) constint MString::rindexW(char c) constint MString::rindexW(wchar_t c) const | これらのルーチンは、それぞれ、 MString::index と MString::rindex のマルチバイト互換バージョンで、文字に基づく位置の値を返します。国際化したプラグインには、これらのルーチンを使用することをお勧めします。「MString::substringW」も参照してください。
MString MString MString::substringW(int start, int end) | (MString::indexW や MString::rindexW の戻り値など)文字に基づく位置の値を受け取る MString::substring のマルチバイト互換バージョンです。
MStatus MString::split(wchar_t c, MStringArray& array) const | MString::split のこのバージョンは、区切り文字としてワイド文字の値を受け取ります。
MStatus MString::format( const MString &fmt, const MString &arg1, const MString &arg2, ... ,const MString &arg10 ) | このルーチンは、フォーマット指定子と最高 10 個の位置引数を使用し、文字フォーマット機能を提供します。