本地化代理

代理本质上是 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 声明式代理可以回答的问题示例) (数组列表,其中每个示例都是一个对象,其中包含 titletext和 ,两者都是可本地化的。 数组中的 12 个对象

要了解详细信息,请参阅 声明式代理清单参考。

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

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

清单字段 说明 最大长度 必需
name_for_human 插件的简短、可读的名称。 它必须至少包含一个非空格字符。 20 个字符 ✔️
description_for_model 提供给模型的插件的描述,包括插件的用途以及其功能在什么情况下是相关的。 2,048 个字符
description_for_human 插件的可读说明。 100 个字符 ✔️
logo_url 用于提取业务流程协调程序可能使用的徽标的 URL。
legal_info_url 用于查找包含插件服务条款的文档的绝对 URL。
privacy_policy_url 一个绝对 URL,用于查找包含插件隐私策略的文档。
conversation_starters 插件可以回答的问题示例) (数组列表,其中每个示例都是一个对象,其中包含 titletext和 ,两者都是可本地化的。

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