エージェントをローカライズする

エージェントは、基本的に Microsoft 365 用のアプリです。 これらは、共通のマニフェスト スキーマ、アプリ パッケージ、および配布と管理プロセスを共有します。 アプリ マニフェストは、copilotAgents オブジェクト内の宣言型エージェントの定義ファイルを参照します。

エージェントをローカライズする方法は、Microsoft 365 アプリ マニフェストで他の機能 (タブ、ボット、メッセージ拡張機能など) をローカライズする方法と若干異なります。

Teams アプリの機能とエージェントの両方に同じローカリゼーション ファイル (言語ごと) を使用します。 ただし、他のすべてのアプリ マニフェスト フィールドは言語ファイルの JSONPath 式を使用して参照されますが、エージェント関連のフィールドはディクショナリ キーを使用して参照されます。 アプリ マニフェスト自体で既定の言語文字列を使用する従来の Teams アプリ機能とは異なり、ローカライズされたエージェントには、既定の言語と追加の言語ごとに言語ファイルが必要です。

エージェントをローカライズするためのアプリ マニフェスト、宣言型エージェント マニフェスト、および言語ファイルの関係を示す図

この記事では、エージェントに (既定の言語以外の) 他の言語のサポートを追加する方法について説明します。

トークン化されたキーを使用してエージェント マニフェストを更新する

ローカライズするフィールド値のトークン化されたキー (たとえば、 [[PLUGIN_NAME]] のように二重角かっこで示される) を使用して、宣言型エージェントや API プラグインのマニフェストを更新します。 ローカライズ キーは次の正規表現と一致する必要があります。 ^[a-zA-Z_][a-zA-Z0-9_]*$

次の例は、名前と説明にトークン化された値を持つ宣言型エージェント マニフェストを示しています。

{
    "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.0/schema.json",
    "name": "[[DA_Name]]",
    "description": "[[DA_Description]]",
    "instructions": "# You are an assistant..."
}

アプリ マニフェストに localizationInfo を追加する

localizationInfo セクションを、言語タグと、アプリ パッケージ内でサポートされる各言語ファイルへの相対パスを含めてアプリ マニフェストに追加します。

エージェントが複数の言語をサポートしている場合は、 デフォルト言語を含め、サポートされているすべての言語にスタンドアロン言語ファイルを指定する必要があります。

次の例は、アプリ マニフェストの localizationInfo セクションを示しています。

"localizationInfo": {
    "defaultLanguageTag": "en",
    "defaultLanguageFile": "en.json",
    "additionalLanguages": [
        {
            "languageTag": "fr",
            "file": "fr.json"
        }
    ]
},

エージェントが他の言語をサポートしていない場合、既定の言語文字列はアプリ マニフェスト ファイル自体で表されます。 単一言語のアプリ パッケージでは、既定の言語に個別の言語ファイルは必要ありません。

追加の言語ごとにローカライズ ファイルを作成する

前の手順でアプリ マニフェストで指定されたファイル名 ( defaultLanguageFile プロパティと file プロパティに対して) を使用して、トークン化されたキーの値を持つ、サポートされている言語ごとにローカリゼーション ファイルを作成します。

次の例は、エージェント タブと個人用タブの両方のローカライズされた文字列を含む言語ファイル fr.json を示しています。

{
    "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json",
    "name.short": "Agent de Communications",
    "name.full": "Agent pour les Communications",
    "description.short": "Outils pour les professionnels de la communication",
    "description.full": "Outils pour les professionnels de la communication Contoso, y compris la galerie de ressources et les assistants personnels",
    "localizationKeys": {
        "DA_Name": "Agent de Communications",
        "DA_Description": "Un assistant pour les professionnels de la communication et des relations publiques chez Contoso."
    },
    "staticTabs[0].name": "Accueil",
    "staticTabs[1].name": "Galerie de ressources",
    "staticTabs[2].name": "À propos de Contoso"
}

アプリ マニフェストのローカライズ可能フィールド

言語ファイルごとに、ローカライズする必要があるアプリのローカライズ スキーマから次のプロパティを指定します。

マニフェスト フィールド 説明 最大長 必須
$schema ローカリゼーション スキーマの URL。 エージェントの場合は、devPreview: https://developer.microsoft.com/en-us/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json を使用します。 マニフェスト スキーマのバージョンは、アプリ マニフェスト ファイルとローカリゼーション ファイルの両方で同じである必要があります。 ✔️
name.short アプリ マニフェストの短い名前を、指定された値に置き換えます。 30 文字 ✔️
name.full アプリ マニフェストの完全な名前を、指定された値に置き換えます 100 文字 ✔️
description.short アプリ マニフェストの短い説明を、指定された値に置き換えます。 80 文字 ✔️
description.full アプリ マニフェストの完全な説明を、指定された値に置き換えます。 4,000 文字 ✔️
エージェントのローカライズされた文字列のキーと値のペア エージェントの場合は、トークン化されたキー (アプリ manifest.json で指定されているとおり、二重角かっこは含まない) をローカライズされた値とともに使用します。 例: "DA_Name": "Agent de Communications"
他のアプリ コンポーネントのローカライズされた文字列の JSONPath/値ペア 他のすべての (クラシック Teams) アプリ コンポーネントについては、ローカライズされた値のキーとして JSONPath 式を使用します。 例: "staticTabs[0].name": "Accueil"

詳細については、「 アプリのローカライズ (Microsoft Teams) とロー カライズ スキーマ リファレンス」を参照してください。

宣言型エージェント マニフェストのローカライズ可能なフィールド

次のフィールドは、宣言型エージェント マニフェスト内でローカライズ可能です。

マニフェスト フィールド 説明 最大長 必須
name 宣言型エージェントの名前。 少なくとも 1 文字の非空白文字を含める必要があります。 100 文字 ✔️
description 宣言型エージェントの説明。 少なくとも 1 文字の非空白文字を含める必要があります。 1,000 文字 ✔️
conversation_starters 宣言型エージェントが回答できる質問の例のリスト (配列)。各例は title と text を持つオブジェクトであり、どちらもローカライズ可能です。 配列内の 12 個のオブジェクト

詳細については、「 宣言型エージェント マニフェスト リファレンス」を参照してください。

API プラグイン マニフェストのローカライズ可能なフィールド

次のフィールドは、API プラグイン マニフェスト内でローカライズできます。

マニフェスト フィールド 説明 最大長 必須
name_for_human 人が読める短いプラグイン名。 少なくとも 1 つの非空白文字を含める必要があります。 20 文字 ✔️
description_for_model モデルに提供されるプラグインの説明 (プラグインの目的や関連する状況など)。 2,048 文字
description_for_human 人が読めるプラグインの説明。 100 文字 ✔️
logo_url オーケストレータによって使用される可能性があるロゴをフェッチするために使用される URL。
legal_info_url プラグインのサービス利用規約を含むドキュメントを探す絶対 URL。
privacy_policy_url プラグインのプライバシー ポリシーを含むドキュメントを探す絶対 URL。
conversation_starters プラグインが回答できる質問の例のリスト (配列)で、各例は title と text を持つオブジェクトであり、どちらもローカライズ可能です。

詳細については、 プラグイン マニフェスト リファレンス を参照してください。