Локализация агента

Агенты — это, по сути, приложения для 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 свойств and 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/value для локализованных строк любых других компонентов приложения Для всех остальных (классических Teams) компонентов приложения используйте выражения JSONPath в качестве ключей для локализованных значений. Например: "staticTabs[0].name": "Accueil"

Дополнительные сведения см. в статьях Локализация приложения (Microsoft Teams) и Справочник по схеме локализации.

Локализуемые поля в манифесте декларативного агента

В манифесте декларативного агента можно локализовать следующие поля.

Поле манифеста Описание Максимальная длина Обязательно
name Имя декларативного агента. Должен содержать хотя бы один непробельный символ. 100 символов ✔️
description Описание декларативного агента. Должен содержать хотя бы один непробельный символ. 1 000 символов ✔️
conversation_starters Список (массив) примеров вопросов, на которые может ответить декларативный агент, где каждый пример является объектом с title и text, оба из которых локализуемы. 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 Список (массив) примеров вопросов, на которые может ответить плагин, где каждый пример представляет собой объект с title и text, оба из которых локализуемы.

Дополнительные сведения см. в справочнике по манифесту подключаемого модуля.