スキルのリソース・バンドル

スキルが複数の言語を処理するように設計されているときに、スキルのレスポンスの表現を制御するには、リソース・バンドルを使用します。必要な言語および方言と同数のリソース・バンドルを提供できます。

スキルが1つの言語のみを対象としている場合でも、リソース・バンドルを使用すると、すべてのユーザー向けテキストを一箇所に配置できるなどの利点が得られます。

リソース・バンドル・エントリをパラメータ化するために多数のオプションがあり、それらを使用して文字列に変数を埋め込むことができます。また、バンドル・エントリにICUフォーマットを使用すると、パラメータの解決方法に応じてレスポンスの表現を作成す際に役立ちます。これにより、あるものが単数形か複数形かに応じた表現の調整などを行えるようになります。

リソース・バンドルのキーのタイプ

スキルのユーザー向け文字列は、スキルの複数の部分にあります。場合によっては、リソース・バンドル・キーが自動的に作成されます。それ以外の場合、キーは生成されませんが、自分で定義できます。

ここでは、ユーザー向け文字列が存在する場所、およびリソース・バンドルでの文字列の管理方法について説明します。

インテントの「会話名」フィールド。
会話名を設定すると、リソース・バンドル・キーが自動的に作成され、デフォルト言語で設定した値が移入されます。会話名のバンドル・キーにアクセスするには、をクリックして「インテント」タブを選択します。
インテントの「回答」フィールド(回答インテント)。
インテントに回答を設定すると、リソース・バンドル・キーが自動的に作成され、デフォルト言語で回答テキストが移入されます。回答のバンドル・キーにアクセスするには、をクリックして「Q&A」タブを選択します。
スキルの構成設定(をクリックし、「構成」タブを選択してアクセスします)。
これらの設定では、リソース・バンドル・キーはデフォルト値を使用して生成され、設定値はリソース・バンドル・キーへの参照として表されます。これらのキーの値を編集するには、をクリックして「構成」タブを選択します。
標準ダイアログ・フロー・コンポーネントに組み込まれているデフォルトのプロンプト、ラベルおよびメッセージ。
これらのプロパティのデフォルト値を変更するには、リソース・バンドル内でをクリックして「構成」タブを選択します。

リソース・バンドルで更新された値を参照するために、ダイアログ・フロー定義のコンポーネントにプロパティを追加する必要はありません。

これらのプロパティのいずれかの値を特定の状態のコンポーネントに対して変更するが、デフォルト値は変更したくない場合は、その状態のコンポーネントにプロパティを追加します。
ダイアログ・フローの文字列。コンポーネントに組み込むテキストの場合、独自のリソース・バンドル・キーを定義し、それらのキーをダイアログ・フロー定義から参照できます。
このようなキーを作成および編集するには、をクリックして「ユーザー定義」タブを選択します。
エンティティ定義のプロンプトおよびメッセージ。これらの文字列の場合、独自のリソース・バンドル・キーを定義して、エンティティ定義のこれらのプロパティのフィールドからそれらのキーを参照できます。
このような文字列のキーを作成および編集するには、をクリックして「ユーザー定義」タブを選択します。

ノート

リソース・バンドルは、値リスト・エンティティを翻訳するためのメカニズムではありません。かわりに、カスタム・エンティティ定義内で翻訳を指定します。ネイティブ・サポート言語を使用するスキルの場合は、そのネイティブ言語の値を指定します。翻訳サービスに基づくスキルの場合は、翻訳された値をデフォルト言語の値のシノニムとして指定します。

リソース・バンドル・キーの作成

リソース・バンドル・キーを使用して、翻訳が必要な出力テキストを識別し、1つ以上の言語で値を提供します。インテント会話名、回答インテントのレスポンス、いくつかの共通プロパティについては、キーが自動的に定義されます。ただし、翻訳が必要な他の出力テキスト(ダイアログ・フローのテキストなど)のキーは自分で作成する必要があります。

リソース・バンドル・エントリを作成するには:

スキルの左側のナビゲーション・バーで、をクリックします。
「ユーザー定義」タブをクリックします。
「バンドルの追加」をクリックします。

「エントリの作成」ダイアログが表示されます。ここでは、スキルのプライマリ言語で最初のエントリを作成できます。
キー(バンドル・エントリの参照に使用)および対応するテキストを入力します。たとえば、ユーザー・プロンプトHow old are you?の場合は、「キー」フィールドにHowOld、「テキスト」フィールドに「How old are you?」と入力します。
「注釈」には、翻訳者など後でエントリを参照する必要がある人にとって役立つ情報を入力します。
「エントリの作成」をクリックします。

リソース・バンドル・キーへの言語の追加

バンドル・キーを作成すると、その初期テキスト値はスキルのデフォルト(プライマリ言語または主言語)に対応します。

別の言語でバンドル・キーのテキストを追加するには:

キーを選択して「言語の追加」をクリックします。
「エントリの作成」ダイアログを完成させます:
- 言語— フランス語はfr、ドイツ語はdeのように、IETF BCP 47言語タグを入力または選択します。
- テキスト—出力文字列。たとえば、HowOldキーのフランス語翻訳(fr)に、quel âge avez-vous ?のような文字列を追加します

ノート

より特定的なロケール(en-USなど)を使用することもできますが、ほとんどの場合有用ではありません。たとえば、翻訳サービスを使用して言語を検出すると、2文字のコードのみが返されます。

スキルが入力言語をバンドルで定義されている言語タグと一致させることができなかった場合、より特定的ではないタグ(ある場合)にデフォルト設定されます。エントリのいずれもブラウザの言語に一致しなかった場合、デフォルトのエントリである英語がスキルで使用されます。詳細は、リソース・バンドル・エントリの解決を参照してください。

会話名の翻訳

ユーザーがたどるフローをスキルが判断しようとしている場合など、会話内のいくつかのポイントで、1つ以上のインテントを参照するダイアログがスキルによって表示される場合があります。このような場合、スキルはインテントをその会話名で参照し、それに対してキーとデフォルトのエントリがリソース・バンドル内に生成されます。

会話名の翻訳を指定するには:

左側のナビゲーション・バーで「リソース・バンドル」()をクリックします。
「リソース・バンドル」ページの「インテント」タブをクリックします。

図rb-conversation-name.pngの説明
インテントを選択します
「言語の追加」をクリックします。
「エントリの作成」ダイアログを完成させます:
- 言語—フランス語の場合はfr、ドイツ語の場合はde、アメリカ英語の場合はen-USのように、IETF BCP 47言語タグを追加します。
- テキスト—出力文字列。たとえば、HowOldキーのフランス語翻訳(fr)に、quel âge avez-vous ?のような文字列を追加します

ノート

会話名を変更するインテントがリストに表示されない場合は、

をクリックして「インテント」ページに戻り、インテントを選択して、その「会話名」フィールドを編集します。「リソース・バンドル」ページに戻ると、「インテント」タブに表示されるようになります。

回答インテントの回答の翻訳

回答インテントを作成すると、その回答のリソース・バンドル・キーが自動的に作成されます。

回答インテントの回答に翻訳を指定するには:

左側のナビゲーション・バーで「リソース・バンドル」()をクリックします。
「リソース・バンドル」ページの「Q&A」タブをクリックします。
翻訳する回答のキーを選択します。
「言語の追加」をクリックします。
「エントリの作成」ダイアログを完成させます:
- 言語—フランス語の場合はfr、ドイツ語の場合はde、アメリカ英語の場合はen-USのように、IETF BCP 47言語タグを追加します。
- テキスト—出力文字列。

ダイアログ・フローのリソース・バンドルの参照

組込みコンポーネントの出力を設定するには、変数rb (リソース・バンドル用に予約済)を使用してメッセージ・キーを参照します。

単純な文字列を戻すためにWhatTypeというバンドル・キーを参照する単純な式を次に示します。

${rb('WhatType')}

動的値を使用する式を次に示します。OnTheWayというバンドル・キーを参照します。ここで、size.valueおよびtype.valueはOnTheWayキーの引数です。


${rb('OnTheWay','${size.value}','${type.value}')}

また、より複雑なメッセージ・フォーマットのバンドル・エントリを作成して、複数形やその他のケースを処理することもできます。様々なメッセージ・フォーマットやダイアログ・フローでメッセージ・フォーマットを参照する方法は、次のトピックを参照してください。

ヒント:

テスターを使用してリソース・バンドルをテストするには、ブラウザを別の言語に設定します。

メッセージ・フォーマット

リソース・バンドル・メッセージには、静的なメッセージを返すことから、複数の変数を使用してメッセージを組み立てることまで、あらゆる処理のために使用できるいくつかのフォーマットがあります。

シンプル・メッセージ

単純で静的メッセージの場合:

バンドル・キーの値として、プレーン・テキストを指定します。例: This is the value of my bundle key
ダイアログ・フローまたは構成プロパティで、次の形式でバンドル・キーを参照します: {rb.bundleKey}または{rb('bundleKey')}

例: 単純なメッセージ

パラメータなしの例を次に示します。

リソース・バンドル・キー: pizzaOnTheWay
リソース・バンドル・メッセージ: Your pizza is on the way.
リソース・バンドル・キーを参照する式: ${rb('pizzaOnTheWay')} (または ${rb.pizzaOnTheWay})

パラメータを含むメッセージ

変数を含むメッセージの場合:

バンドル・キーの値として、テキストを指定し、次のいずれかのフォーマットでパラメータを含めます:
- {parameterName}という形式の名前付きパラメータ
- {0}から始まる順序を示す番号付きパラメータ
ダイアログ・フローまたは構成プロパティで、次の形式でバンドル・キーを参照します:
```
${rb('bundleKey','variable1','variable2',...)}
```

例: 名前付きパラメータを含むメッセージ

2つの名前付きパラメータを含む例を次に示します:

リソース・バンドル・キー: pizzaOnTheWayWithNamedParams
リソース・バンドル・メッセージ(英語):
```
Your {pizzaSizeParam} {pizzaTypeParam} pizza is on the way.
```
({pizzaSizeParam}および{pizzaTypeParam}は会話中に解決されて挿入される値のパラメータです)
リソース・バンドル・キーを参照する式:
```
${rb('pizzaOnTheWayWithNamedParams','pizzaSizeParam,pizzaTypeParam',pizzaSize.value,
      pizzaType.value)}
```
(pizzaSizeおよびpizzaTypeは、ダイアログ・フローで定義された変数です)

例: 番号付きパラメータを含むメッセージ

番号付きパラメータを使用する例を次に示します:

リソース・バンドル・キー: pizzaOnTheWayWithNumberedParams
リソース・バンドル・メッセージ:
```
Your {0} {1} pizza is on the way.
```
({0}および{1}は、会話中に解決されて挿入される値のパラメータです)
リソース・バンドル・キーを参照する式:
```
${rb('pizzaOnTheWayWithNumberedParams',pizzaSize.value, pizzaType.value)}
```
(pizzaSizeおよびpizzaTypeは、ダイアログ・フローで定義された変数です)

複雑なメッセージ

メッセージ内の1つ以上の変数の値が周囲の出力テキストに影響する可能性がある、複雑なメッセージを作成することもできます。たとえば、オーダーしたピザの枚数のための変数がレスポンスに含まれている場合、複雑なメッセージを使用して、単数形("pizza")と複数形("pizzas")のどちらを使用するかを決定できます。

ヒント:

複雑なバンドル・エントリを作成するときは、このテスター(https://format-message.github.io/icu-message-format-for-translators/editor.html)を使用して、意図どおりにエントリが解決することを確認します。

単数形と複数形の両方を処理するメッセージ

ものの数量を表す変数を含むメッセージでは、変数の解決方法に応じて、組み立てられるメッセージの表現を変更する必要がある場合があります。また、一部の言語では、単純な単数形/複数形の区別以外にも考慮が必要になる可能性があります。数量の変数を含むメッセージを処理するには、キーの値でplural引数を使用して、メッセージの作成方法をどのように変えるかを指定します。

plural引数では、メッセージの一部は、数値と指定言語の文法規則によって決まります。plural引数がどのように解決されるかに応じて、ケースごとにメッセージ・テキストを定義します。one、two、few、many、otherなど、いくつかの事前定義済ケースがあります。また、=を数の前に付けて(たとえば=3)、特定の数のケースも指定できます。事前定義済のすべてのケースが、すべての言語に関連するわけではありません。たとえば、英語の場合は、=0、=1およびotherのみが使用されます。

otherには常にケースとメッセージを含める必要があります。解決した数値をケースのメッセージ・テキストに含めるには、#を使用して数値を出力します。

plural引数を使用する場合、通常は次のようなフォーマットになります:

{plural_arg_name, plural,
=0 {Text used when the plural argument resolves to 0}
=1 {Text used when the plural argument resolves to 1}
other {Text used when the plural argument resolves to a value that doesn't match the other cases (in this case 0 or 1)}
}

前述の例では、0、1およびotherが可能性がある数量です。pluralという引数のタイプの動作の詳細は、Unicodeロケール・データ・マークアップ仕様を参照してください。

様々な言語での複数形サポートの詳細は、unicode.orgの言語の複数形ルールを参照してください。

その他の複雑なメッセージ

メッセージの内容を他の条件に基づいて作成する必要がある場合は、メッセージを組み立てるために、定義するキーワードとともにselect引数を使用できます。

{select_arg_name, select,
keyword1 {Text used when the select argument resolves to keyword1}
keyword2 {Text used when the select argument resolves to keyword2}
other {Text used when the plural argument resolves to a value that doesn't match the other keywords}
}

plural引数とselect引数を入れ子にすることもできます:

{select_arg_name, select,
keyword1 {
{plural_arg_name, plural,
=0{Text used when the select argument resolves to keyword1 and the plural argument resolves to 0.}
=1 {Text used when the select argument resolves to keyword1 and the plural argument resolves to 1}
other {Text used when the select argument resolves to keyword1 and the plural argument resolves to a value that doesn't match the other cases (in this case 0 or 1)}}}
keyword2 {
{plural_arg_name, plural,
=0 {Text used when the select argument resolves to keyword2 and the plural argument resolves to 0.}
=1 {Text used when the select argument resolves to keyword2 and the plural argument resolves to 1}
other {Text used when the select argument resolves to keyword2 and the plural argument resolves to a value that doesn't match the other cases (in this case 0 or 1)}}}
other {
{plural_arg_name, plural,
=0 {Text used when the select argument resolves to other and the plural argument resolves to 0.}
=1 {Text used when the select argument resolves to other and the plural argument resolves to 1}
other {Text used when the select argument resolves to other and the plural argument resolves to a value that doesn't match the other cases (in this case 0 or 1)}}}
}

ノート

キーワード名には、ASCIIアルファベット(A-Z、a-z)しか使用できません。

複雑なメッセージの詳細は、https://unicode-org.github.io/icu/userguide/format_parse/messages/#complex-argument-typesを参照してください。

複雑なメッセージの参照

複雑なリソース・バンドル・メッセージは、次のいずれかの方法で参照できます:

各パラメータの値を組み立てるマップ変数の使用:
```
${rb('bundleKey', formatMap.value)}
```
パラメータ名の後に各値の引数を指定するリスト引数の組込み:
```
${rb('bundleKey', 'param1, param2, param3', paramValue1, paramValue2, paramValue3)}
```
ノート

パラメータ値が文字列の場合は、一重引用符(')で囲む必要があります。

詳細は、ICUドキュメントの複合引数タイプのトピックを参照してください。

複雑なリソース・バンドル値のマップ

複雑なメッセージのパラメータを組み立てるためにマップ変数の使用を決めた場合は、次のことを行います:

マップ型の変数を定義し、有効なJSON形式の値を指定します。たとえば、ピザ・バンドル・エントリの値は次のようになります。
```
{
    "pizzaSize": "${pizzaSize.value}",
    "pizzaType:": "${pizzaType.value}",
    "count": "${pizzaNum.value}"
}
```
ノート

YAMLベースのダイアログ・フローでは、最初にcontextノード内で変数を宣言してから、System.SetVariableコンポーネントを使用して、次のような構文でその値を設定します:
```
  populateMap:
    component: "System.SetVariable"
    properties:
      variable: "formatMap"
      value:
        pizzaSize: "${pizzaSize.value}"
        pizzaType: "${pizzaType.value}"
        count: "${pizzaNum.value}"
```
バンドル・キーを参照する式に、引数としてマップを含めます。例:
```
${rb('pizzaOnTheWaySingularOrPlural', formatMap.value)}
```

例: 単数形バリアントと複数形バリアントの両方を処理するメッセージ

次に、内容に単数形または複数形が含まれるメッセージのリソース・バンドル・エントリの例を示します:

リソース・バンドル・キー: pizzaOnTheWaySingularOrPlural

リソース・バンドル・メッセージ(英語):

{count, plural,
=0 {No pizzas will be delivered.}
=1 {Your {pizzaSizeParam} {pizzaTypeParam} pizza is on the way.}
other {# pizzas are on the way.}
}

リソース・バンドル・キーの参照の式:
```
${rb('pizzaOnTheWaySingularOrPlural','count, pizzaSizeParam, pizzaTypeParam', 'pizzaNum.value, pizzaSize.value, pizzaType.value')}
```
表示されているように、式には2つの引数があります:
- パラメータ名のリスト(count, pizzaSizeParam, pizzaTypeParam)
- それらのパラメータの値のリスト(pizzaNum.value, pizzaSize.value, pizzaType.value)

例: パラメータがネストされているメッセージ

{ gender, select,
female
{{count, plural,
=0 {She has not ordered anything.}
=1 {She has ordered only one.}
other {She has ordered #.}}}
male
{{count, plural,
=0 {He has not ordered anything.}
=1 {He has ordered only one.}
other {He has ordered #.}}}
other
{{count, plural,
=0 {They have not ordered anything.}
=1 {They have ordered only one.}
other {They have ordered #.}}}}

このメッセージがどのように解決されるかというバリエーションを次に示します:

She has not ordered anything.
She has ordered only one.
She has ordered 2.
He has not ordered anything.
He has ordered only one.
He has ordered 2.
They have not ordered anything.
They have ordered only one.
They have ordered 2.

ノート

前の例ではcount引数によって解決される数値として2が示されていますが、0または1以外の任意の数値を使用できます。

リソース・バンドルとスキルの自動翻訳

スキルのレスポンスにリソース・バンドルを使用しているときに、ユーザー入力にのみ翻訳サービスを使用するようにスキルを設定する一般的なステップを次に示します:

まだ実行していない場合は、翻訳サービスをスキルに追加します。
言語の検出コンポーネントを使用して、ユーザー入力の言語を特定します。
リソース・バンドルを適用して、ユーザーに対するスキルのレスポンスを処理します。
リソース・バンドルを参照するコンポーネントがある場合は、出力が自動的に翻訳されないようにしてください。
- ビジュアル・ダイアログ・モードで開発されたスキルの場合、スキルの「設定」ページの「ボット・レスポンス・メッセージの翻訳」プロパティをFalseに設定します。
- YAMLダイアログ・モードで開発されたスキルの場合は、入力を翻訳して出力を翻訳しないようにautoTranslateコンテキスト変数を設定することで、スキル内でこれをグローバルに処理できます。例:
```
  setAutoTranslate:
    component: "System.SetVariable"   
    properties:
      variable: "autoTranslate"     
      value:
       input: true
       output: false
```

ノート

YAMLモードで開発されたスキルの場合、各コンポーネントのtranslateプロパティを使用してコンポーネント・レベルでこれを処理し、autoTranslate変数を設定しません。たとえば、System.Textコンポーネントの入力に対して自動翻訳を設定し、出力に対して自動翻訳を無効にするには、次のようにします:

  askName:
    component: "System.Text"
    properties:   
      prompt: "${rb.askNamePrompt}"
      variable: "name"
      translate:       
        input: true
        output: false

スキルが一部のコンポーネントでリソース・バンドルを使用し、他のコンポーネントで自動翻訳に依存する場合は、次のようにできます:

autoTranslateコンテキスト変数をtrueに設定します。
前述のコード・サンプルと同様に、リソース・バンドルを使用するコンポーネントごとにtranslate:inputプロパティをfalseに設定します。

条件付き自動翻訳

一部の言語に対してリソース・バンドルを定義しているが、リソース・バンドル・エントリがない言語に対してもレスポンスを提供できるようにするには、FreeMarker式を使用して、「ユーザー入力メッセージの翻訳」および「ボット・レスポンス・メッセージの翻訳」設定(ビジュアル・フロー・デザイナのスキル)およびautotranslateおよびtranslateプロパティ(YAMLベースのスキル)の解決方法を決定できます。

たとえば、英語およびオランダ語のみリソース・バンドルが定義されている場合、他の言語の出力翻訳を条件付きで有効にできます。この式は次のようになります。

${profile.languageTag!='en'&& profile.languageTag!='nl'}

リソース・バンドル・エントリの解決

適用されるリソース・バンドルは、2つのロケーション固有のユーザー・プロファイル変数であるprofile.languageTagとprofile.localeに格納されている値に依存します。両方の変数が設定されている場合は、profile.languageTagが優先されます。

使用する言語を解決する際、Oracle Digital Assistantでは最初に完全一致を検索します。それが見つからない場合は、成功するまで検索範囲を徐々に広げていきます。それでも一致が見つからない場合は、デフォルト言語である英語(en)を返します。

たとえば、${profile.locale}の値がen-AU-sydneyの場合(およびprofile.languageTagが設定されていない場合)、Oracle Digital Assistantは次の処理を実行して最適一致の言語を見つけます:

言語-国-バリアント(en-AU-sydney)を基準としてバンドルを検索します。
見つからない場合、言語と国(en-AU)でバンドルを検索します。
これでも見つからない場合は、検索の範囲を言語(en)に広げます。

ノート

profile.localeでは、ISO言語国またはISO language_country形式の値がサポートされています。

リソース・バンドルのエクスポートおよびインポート

リソース・バンドルはCSVファイルの形式でエクスポートおよびインポートできるため、バンドルをオフラインで操作できます。

CSVファイルには次の列が必要です:

languageTag
key
message
annotation

既存のリソース・バンドルを含むCSVファイルをエクスポートするには:

スキルまたはデジタル・アシスタントの「リソース・バンドル」ページで、をクリックして既存のリソース・バンドルを含むCSVファイルをエクスポートします。

リソース・バンドルにまだキーを追加していない場合でも、必要なフォーマットのCSVでファイルがエクスポートされます。

リソース・バンドル・ファイルをインポートするには:

スキルまたはデジタル・アシスタントの「リソース・バンドル」ページで、をクリックします。

Oracle Cloud Infrastructureドキュメント