テキスト ローカライゼーション

Text (テキスト) は、Unreal Engine 4 (UE4) のローカライゼーションにおける主要なコンポーネントです。これは C++ では、FText 型で表される特別な文字列です。これは、ユーザー向けにテキストをローカライズする必要があるときに使用します。

内部的には、FText は TSharedRef として ITextData に実装されています。 これにより非常に低コストでコピーが可能となり、FTextSnapshot ユーティリティを使用して、キャッシュされた FText 値が実際に変更されたかどうかを効率的に検出することができます。

FText インスタンス内に保持されているデータは、FText の作成方法によって異なります。この違いは、内部の「テキスト履歴」(FTextHistory) で処理されます。テキスト履歴は、カルチャに合ったテキストの再ビルドをサポートし、以下の主要なコンポーネントで構成されます。

• カルチャのライブへの切り替え。

• ネットワークを介した FText の転送。

• カルチャ関連のソース作成。

FText から FString への変換は、テキスト履歴を失うため、通常は損失の多い操作となります。これは、ローカライゼーション データが不要になった場合にのみ実行してください。たとえば、文字列を処理する低レベルの API がある場合、テキストの変更を監視する高レベルの API (StxtBlock など) によって管理されます。この変換は、文字列のみを受け入れる外部 API にデータを渡すときにも使用できます。

ローカライズができないテキスト (たとえば、外部 API のプレーヤ名を UI に表示できる形式に変換したテキストなど) が必要な場合は、FText::AsCultureInvariant を使用して、ローカライゼーション データを含まない (そして、ローカライズができない) [ インスタンスを作成します。INVTEXT マクロで文字列リテラルに対して同様の操作を実行することができます。

テキスト リテラル

ローカライズ可能なテキストは、名前空間、キー (これは、そのアイデンティティを形成します)、そしてソース文字列 (これが翻訳された内容をもとに、「古い」翻訳の検証として機能します) の 3 つのコンポーネントから構成されています。UE4 でローカライズ可能なテキストを作成する最も一般的な方法は、テキスト リテラルを使用することです。

C++ でテキスト リテラルを作成する

LOCTEXT ファミリーのマクロを使用すると、 C++ でテキスト リテラルを作成できます。

テキスト リテラル マクロ

例：

	// Define the namespace to use with LOCTEXT
	// This is only valid within a single file, and must be undefined before the end of the file
	#define LOCTEXT_NAMESPACE "MyNamespace"
	// Create text literals
	constFTextHelloWorld= NSLOCTEXT("MyOtherNamespace","HelloWorld","Hello World!")
	constFTextGoodbyeWorld= LOCTEXT("GoodbyeWorld","Goodbye World!")
	// Undefine the namespace before the end of the file
	#undef LOCTEXT_NAMESPACE
Copy full snippet

// Define the namespace to use with LOCTEXT // This is only valid within a single file, and must be undefined before the end of the file #define LOCTEXT_NAMESPACE "MyNamespace" // Create text literals constFTextHelloWorld= NSLOCTEXT("MyOtherNamespace","HelloWorld","Hello World!") constFTextGoodbyeWorld= LOCTEXT("GoodbyeWorld","Goodbye World!") // Undefine the namespace before the end of the file #undef LOCTEXT_NAMESPACE

INI ファイルでテキスト リテラルを作成する

NSLOCTEXT マクロを使用すると、 INI ファイルでテキスト リテラルを作成できます。

アセットでテキスト リテラルを作成する

FTextプロパティを使用して、 テキスト リテラルを作成できます。 キーは自動的に生成されますが、テキスト フィールドの横にある詳細コンボボックスを使用して、テキストのカスタム名前空間またはキーを定義できます。デフォルトの名前空間またはキーを使用することもできます。

テキスト フォーマット

テキスト フォーマットは、実際のテキストを挿入してフォーマット プレース ホルダを置き換えるローカライズ可能なフォーマット パターンを使用してテキストを組み合わせることで、ローカライズを容易にします。

フォーマット プレース ホルダは一対の中括弧で囲まれ、数字 (インデックス ベースのフォーマットの場合) または文字列 (名前ベースのフォーマットの場合) を指定できます。例：

"You have {0} health left." "You have {CurrentHealth} health left."

フォーマット プレース ホルダは、引数データに対して実行する関数 (「引数修飾子」と呼ばれています) を指定することもできます。これらは、パイプの後に関数名と引数が続く形で指定されます。例：

"{NumCats} {NumCats}|plural(one=cat,other=cats)"

バックティック (`) 文字は、フォーマッティング マークアップとして処理されることを避けるために丸括弧とパイプをエスケープします。また、リテラル ` 文字を生成することをエスケープするために使用することもできます。

例：

"Result `{ {Res} }" formatted with Res set to 10 would produce "Result { 10 }"

"Result ``{Res}``" formatted with Res set to 10 would produce "Result `10`"

C++ によるテキスト フォーマット化

C++ によるテキストフォーマット化は、 FText::Format ファミリーの関数によって処理されます。各関数は、FText インスタンスから暗黙的に構成された FTextFormat パターンを受け取り、以下の表で定義されます。

頻繁に使用するフォーマット パターンを FTextFormat にプリコンパイルしておけば、フォーマット化のパフォーマンスが向上します。アクティブなカルチャが変更されると、コンパイルされたパターンは自動的に再コンパイルされます。

ブループリントによるテキスト フォーマット化

ブループリントによるテキスト フォーマット化は、Format Text ノードによって処理されます。このノードは、リテラル フォーマット パターンや、別のテキスト ピンに接続されたパターンを使用することもできます。

• リテラル フォーマット パターンを指定すると、Format 引数のピンが自動的に生成されます。

• フォーマット パターンが別のテキスト ピンに接続されている場合、ノードの [Details (詳細)] パネルを使用してフォーマットの引数を手動で指定する必要があります。

引数修飾子

引数修飾子を使用すると、フォーマット化された文字列に引数が追加される前に、引数を前処理できます。引数修飾子は拡張可能です。引数修飾子を作成するには、ITextFormatArgumentModifier インターフェースを実装し、特定のキーワード (FTextFormatter::RegisterTextArgumentModifier を参照してください) に対してファクトリ関数を登録します。

UE4 には、デフォルトでいくつかの引数修飾子が用意されており、複数形、性別、ハングルの助詞に対応した修飾子があります。

複数用フォーム

複数形では、テキスト フォーマットに指定された数値変数に基づいて異なるテキストを使用できます。複数形は、基数詞 (「4 匹の猫がいます」や「猫が 1 匹います」など) または序数詞 (「2 位でしたね！」や「1 着でした！」など) でも使用できます。複数形は、キーと値のペアとして指定され、0、1、2、少数、多数、その他のいずれかの (カルチャ用に CLDR データに定義されている) キーワードをサポートします。値は、オプションで引用符で囲まれた文字列で、フォーマット マーカーを含めることもできます。

基数詞フォーマットの例：

	"There {NumCats}|plural(one=is,other=are) {NumCats} {NumCats}|plural(one=cat,other=cats)"
Copy full snippet

"There {NumCats}|plural(one=is,other=are) {NumCats} {NumCats}|plural(one=cat,other=cats)"

序数詞フォーマットの例：

	"You came {Place}{Place}|ordinal(one=st,two=nd,few=rd,other=th)!"
Copy full snippet

"You came {Place}{Place}|ordinal(one=st,two=nd,few=rd,other=th)!"

性別用フォーマット

性別フォーマットでは、テキスト フォーマットに指定された ETextGender や「Le guerrier est fort」などの値に基づいて異なるテキストを使用できます。性別フォーマットでは、[男性、女性、中性]の順序で値のリストとして指定します。ここで、中性はオプションです。 値は、オプションの引用符付き文字列で、フォーマット マーカーを含めることもできます。値は、オプションの引用符付き文字列で、フォーマット マーカーを含めることもできます。

フォーマットの例：

	"{Gender}|gender(Le,La) {Gender}|gender(guerrier,guerrière) est {Gender}|gender(fort,forte)"
Copy full snippet

"{Gender}|gender(Le,La) {Gender}|gender(guerrier,guerrière) est {Gender}|gender(fort,forte)"

ハングル文字の助詞用フォーム:

ハングルの助詞を使用すると、韓国語の文法ルールに従い、挿入される値の終わりが子音か母音かに基づいて適切な文字が挿入されます。 例えば、 "사람은" や "사자는" となります。ハングルの助詞は、[子音、母音]の順序で値のリストとして指定されます。値は、オプションの引用符付き文字列です。

フォーマットの例：

	"{Arg}|hpp(은,는)"
Copy full snippet

"{Arg}|hpp(은,는)"

テキスト フォーマット化のベスト プラクティス

• 文に影響を与える数値を入力するときは、コードを分岐させるより、複数形引数修飾子を使ってこれらの差異を処理してください。複数形を使用した場合、ソース言語の複数形の規則が同じでない言語でも正しく翻訳することができます。

• 人称名詞を挿入するときは、その人の性別を示す引数を必ず含めてください。 これは、文法上の規則で性別が指定されている言語を使用するときに、翻訳者が性別に基づいて翻訳を切り替えることができるようになるため重要です ([「Gender Forms」[を参照してください)。

• オブジェクト (たとえば、「テーブル」、「ドア」、「椅子」など) に名詞を挿入することは避けるか、ローカライズが可能な名前にする必要があります。これらの名詞は、ある言語では 1 つの性別を持ち、別の言語では別の性別を持つ場合があります。そのため、カルチャごとのメタデータがなければ、フォーマット パターン ストリングを正確にローカライズすることはできません。理想的には、名詞だけではなく全文を含める必要があります。これにより、正確な翻訳が保証されます。

UE4 の将来のリリースには、メタデータを使用して名詞を表すテキストにタグを付け、フォーマット パターンに分岐して正確な翻訳を生成できる機能が含まれる予定です。

• 部分的な文の結合は避ける必要があります。これにより、各句または部分が正しく変換されても、全体が正しく変換されない可能性があるため、問題が発生することがあります。正確な翻訳ができるように、テキストを完全な文に書き換えることをお勧めします。

テキスト生成

テキスト生成は、国際化データを使用してローカライズに直接依存しないカルチャに合ったテキストを生成します。テキスト生成には、数値、時系列、およびトランスフォーマティブの 3 種類があります。

数字からのテキストの生成

数値生成は、数値型を人間が読みやすいテキスト表現に変換するために使用します。この変換はカルチャ固有の規則に基づいていますが、特定の制御が必要なときには、世代ごとに調整することもできます。

たとえば、デフォルトの生成規則において、浮動小数点数「1234.5」は、英語の場合 「1,234.5」、フランス語では「1 234,5」、そしてアラビア語では 「١٬٢٣٤٫٥」として生成されます。

C++ による数字からのテキストの生成

C++ による数値生成は、以下の関数によって処理されます。

表中のほとんどの関数は、出力を制御するためにオプションの [FNumberFormattingOptions](https://api.unrealengine.com/INT/API/Runtime/Core/Internationalization/FNumberFormattingOptions/index.html) とカルチャ (デフォルトはアクティブなロケールです) を使用します。

ブループリントによる数値生成

ブループリントによる数値生成は、以下の関数によって処理されます。

テーブル内のほとんどのノードは、拡張パラメータを使用して出力を制御します。

日時からのテキストの生成

時系列生成は、日時型を人間が読みやすいテキスト表現に変換するために使用されます。この変換はカルチャ固有の規則に基づいていますが、特定の制御が必要なときには、生成ごとに日付 / 時間のスタイルを調整することもできます。

デフォルトの生成規則では、1998年の 5 番目の月の 22日を表す日付は、英語 (米国) の場合は「May 22, 1998」、英語 (イギリス) の場合は「22 May 1998」、フランス語の場合は「22 mai 1998」、アラビア語の場合は「٢٢‏/٠٥‏/١٩٩٨」を生成します。

C++ による日時からのテキストの生成

C++ による字形レス生成は、以下の関数によって処理されます。

上記のほとんどは、EDateTimeStyle を使って出力を制御しています (デフォルトではアクティブなロケールから取得されますが、「short」、「medium」、「long」、または、「full」に設定できます)。

時間生成は、デフォルトで UTC ベースの時間が与えられることを想定しています (ローカル タイムゾーンに変換されます)。与えられた時間が UTC ベースではない (たとえば、ローカル時間を使用している場合) 場合は、タイムゾーン引数として [FText::GetInvariantTimeZone](https://api.unrealengine.com/INT/API/Runtime/Core/Internationalization/FText/GetInvariantTimeZone/index.html) を渡す必要があります。

ブループリントによる日時からのテキストの生成

ブループリントによる時系列生成は、以下のノードによって処理されます。

派生テキスト生成

派生テキスト生成は、テキストを他の表現に変換するために使用します。たとえば、小文字のテキストを大文字のテキストに変換したり、大文字のテキストを小文字のテキストに変換することができます。

C++ による派生テキスト生成

C++ による派生テキスト生成は、以下の関数によって処理されます。

ブループリントによる派生テキスト生成

ブループリントによる派生テキスト生成は、以下のノードによって処理されます。

文字列テーブル

文字列テーブルは、ローカライズしたテキストをひとつ (または複数) の決まった場所にまとめます。次に他のアセットまたはコードから文字列テーブル内のエントリを参照し、ローカライズしたテキストを簡単に再利用できるようにします。

文字列テーブルは C++ で定義し、CSV ファイルで読み込むか、アセットとして作成します。詳細は、「文字列テーブル」を参照してください。

テキスト値のマーシャリング

テキスト値は、文字列として可逆的にマーシャリングできます (FTextStringHelper、または ImportText と ExportTextUTextProperty 関数を使用します)。

サポートされているフォーマットは、以下の通りです。

「Raw」ストリングをインポートすることもできますが、インポートするたびに新しいキーが生成されます。これにより、ローカライゼーション キーが不安定になります。

データ テーブル

ローカライゼーション キーが不安定になる一般的な原因の 1 つは、CSV ファイルからデータ テーブルに Raw 文字列を繰り返しインポートすることで、インポートのたびに新しいキーが生成されることです。 この問題を解決するには、行構造体の OnPostDataImport 関数をオーバーライドし、FText::ChangeKey を呼び出して新しいキーを割り当てることによって、インポートされたテキストにインポート後の確定キーを割り当てます。

通常、データ テーブル名を名前空間として使用し、行名とプロパティ名の組み合わせをキーとして使用します。例：

	voidFMyTableRow::OnPostDataImport(constUDataTable*InDataTable,constFNameInRowName,TArray&OutCollectedImportProblems)
	{
	#if WITH_EDITOR
		MyTextProperty = FText::ChangeKey(
		InDataTable->GetName(),
		FString::Printf(TEXT("%s_%s"),*InRowName.ToString(), GET_MEMBER_NAME_STRING_CHECKED(FMyTableRow,MyTextProperty)),
		MyTextProperty
		);
	#endif// WITH_EDITOR
	}
Copy full snippet

voidFMyTableRow::OnPostDataImport(constUDataTable*InDataTable,constFNameInRowName,TArray&OutCollectedImportProblems) { #if WITH_EDITOR MyTextProperty = FText::ChangeKey( InDataTable->GetName(), FString::Printf(TEXT("%s_%s"),*InRowName.ToString(), GET_MEMBER_NAME_STRING_CHECKED(FMyTableRow,MyTextProperty)), MyTextProperty ); #endif// WITH_EDITOR }

4.22 リリースの時点で、決定性キーはデータ テーブルにインポートされた Raw 文字列にすでに適用されていますが、カスタムのキーイング動作が必要な場合は、OnPostDataImport をオーバーライドすることができます。

多言語データ

多言語データを使用すると、実行時に新しいローカライゼーション データを追加して、外部システムとのインターフェースになり、新しい LocRes ファイルをビルドせずにホット フィックス ローカライズを行うことができます。

多言語データは、名前空間とキー (自身のアイデンティティ)、ネイティブ文字列、多言語データを使用するタイミングをコントロールするテキストのカテゴリ (ゲーム、エンジン、エディタなど)、オプションの固有のカルチャ (設定されていない場合は、カテゴリのネイティブ カルチャにフォールバックします)、カルチャごとの一連の翻訳で構成されます。

多言語データを使用して既存の変換をオーバーライドする場合は、多言語データの名前空間、キー、ネイティブ文字列が、置き換えるソース テキストの名前空間、キー、ネイティブ文字列と一致していることを確認する必要があります。

C++ の多言語データ

C++ を用いた多言語データは FPolyglotTextData 型によって表され、(FPolyglotTextData::GetText を使用して多言語データをテキスト インスタンスとして解釈して) 直接の使用や FTextLocalizationManager::RegisterPolyglotTextData に転送 (既存のテキスト エントリをパッチ処理するため) することも可能です。

ブループリントの多言語データ

ブループリントの多言語データは、Polyglot Text データ型で表され、Polyglot Data to Text 関数とともに使用して、多言語データをテキスト インスタンスとして解釈することができます。

ローカライズされたテキスト ソース

ローカライズされたテキスト ソースは、UE4 テキスト ローカライゼーション マネージャがローカライズされたテキスト データを検索して処理する主要な方法です。UE4 には、デフォルトで FLocalizationResourceTextSource (LocRes がサポートするホスト) と FPolyglotTextSource (多言語データ サポートのホスト) の 2 つが用意されています。

ローカライズされたテキスト ソースは、外部システムとのインターフェースを提供でき、ILocalizedTextSource から派生した型を作成して登録することで、プロジェクトごとに追加できます。