本地化代理

2025-01-10

代理实质上是适用于 Microsoft 365 的应用。它们共享通用清单架构、应用打包以及分发和管理过程。应用清单引用对象中copilotAgents声明性代理的定义文件。

本地化代理的方式与本地化 (Microsoft 365 应用清单中) 选项卡、机器人和消息扩展等其他功能的方式略有不同。

对于 Teams 应用功能和代理，每种语言) 使用相同的本地化文件 (。但是，虽然所有其他应用清单字段都是使用语言文件中的 JSONPath 表达式引用的，但代理相关的字段是使用字典键引用的。与经典 Teams 应用功能（在应用清单本身中使用默认语言字符串）不同，本地化代理需要默认语言和每种其他语言的语言文件。

显示应用清单、声明性代理清单和用于本地化代理的语言文件之间的关系的关系图

本文介绍如何向代理添加对除默认语言) 以外的其他语言的支持 (。

使用标记化密钥更新代理清单

使用标记化密钥更新声明性代理和/或 API 插件清单， (用双方括号指示，例如 [[PLUGIN_NAME]] ，要本地化的任何字段值) 。本地化键必须与以下正则表达式匹配： ^[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`	声明性代理的名称。必须至少包含一个非白空间字符。	100 个字符	✔️
`description`	声明性代理的说明。必须至少包含一个非白空间字符。	1,000 个字符	✔️
`conversation_starters`	一个列表 (数组) 声明性代理可以回答的问题示例，其中每个示例都是一个对象，其中包含 `title` 和 `text`，这两者都是可本地化的。	数组中的六个对象

若要了解详细信息，请参阅声明性代理清单参考。

API 插件清单中的可本地化字段

以下字段可在 API 插件清单中本地化。

清单字段	说明	最大长度	必需
`name_for_human`	插件的简短用户可读名称。它必须至少包含一个非白空间字符。	20 个字符	✔️
`description_for_model`	为模型提供的插件的说明，包括插件的用途，以及其函数在什么情况下相关。	2048 个字符
`description_for_human`	插件的可读说明。	100 个字符	✔️
`logo_url`	用于提取可由业务流程协调程序使用的徽标的 URL。
`legal_info_url`	一个绝对 URL，用于查找包含插件服务条款的文档。
`privacy_policy_url`	一个绝对 URL，用于查找包含插件隐私策略的文档。

若要了解详细信息，请参阅 API 插件清单参考。

代理应用包