Partager via

Localiser votre agent

  • Article

Les agents sont essentiellement des applications pour Microsoft 365. Ils partagent un schéma de manifeste, un empaquetage d’application et un processus de distribution et de gestion communs. Votre manifeste d’application fait référence au fichier de définition de vos agents déclaratifs dans l’objet copilotAgents .

La façon dont vous localisez un agent est légèrement différente de la façon dont vous localisez d’autres fonctionnalités (telles que les onglets, les bots et les extensions de message) dans un manifeste d’application Microsoft 365.

Vous utilisez le même fichier de localisation (par langue) pour les fonctionnalités et les agents de l’application Teams. Toutefois, alors que tous les autres champs de manifeste d’application sont référencés à l’aide d’expressions JSONPath dans les fichiers de langage, les champs liés à l’agent sont référencés à l’aide de clés de dictionnaire. Contrairement aux fonctionnalités d’application Teams classiques, qui utilisent des chaînes de langue par défaut dans le manifeste de l’application lui-même, les agents localisés nécessitent un fichier de langue pour la langue par défaut ainsi que pour chaque langue supplémentaire.

Diagramme montrant la relation entre le manifeste d’application, le manifeste de l’agent déclaratif et un fichier de langue pour les besoins de la localisation d’un agent

Cet article explique comment ajouter la prise en charge de langues supplémentaires (au-delà de la langue par défaut) à vos agents.

1. Mettre à jour les manifestes de votre agent avec des clés tokenisées

Mettez à jour vos manifestes d’agent déclaratif et/ou de plug-in d’API avec des clés tokenisées (indiquées par des crochets doubles, par exemple [[PLUGIN_NAME]]) pour toutes les valeurs de champ que vous souhaitez localiser. Les clés de localisation doivent correspondre à cette expression régulière : ^[a-zA-Z_][a-zA-Z0-9_]*$

L’exemple suivant montre un manifeste d’agent déclaratif avec des valeurs tokenisées pour son nom et sa description.

{
    "$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..."
}

2. Ajouter localizationInfo au manifeste de votre application

Ajoutez la localizationInfo section au manifeste de votre application, avec des balises de langue et des chemins d’accès relatifs à chaque fichier de langue pris en charge dans votre package d’application.

Si votre agent prend en charge plusieurs langues, vous devez spécifier un fichier de langue autonome pour chaque langue prise en charge, y compris votre langue par défaut.

L’exemple suivant montre la localizationInfo section dans un manifeste d’application.

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

Si votre agent ne prend pas en charge d’autres langues, les chaînes de langue par défaut sont représentées dans le fichier manifeste de l’application lui-même. Les packages d’application à langue unique ne nécessitent pas de fichier de langue distinct pour la langue par défaut.

3. Créer un fichier de localisation pour chaque langue supplémentaire

Créez un fichier de localisation pour chaque langue prise en charge supplémentaire avec des valeurs pour les clés tokenisées, en utilisant les noms de fichiers spécifiés (pour les defaultLanguageFile propriétés et file ) dans le manifeste de l’application à l’étape précédente.

L’exemple suivant montre un fichier de langue, fr.json, avec des chaînes localisées pour un agent et des onglets personnels.

{
    "$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"
}

Champs localisables dans le manifeste de l’application

Pour chaque fichier de langue, spécifiez les propriétés suivantes du schéma de localisation de l’application qui doivent être localisées.

Champ manifeste Description Longueur maximale Obligatoire
@schema URL du schéma de localisation. Pour les agents, utilisez devPreview : https://developer.microsoft.com/en-us/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json. La version du schéma de manifeste doit être identique pour les fichiers manifeste d’application et de localisation. ✔️
name.short Remplace le nom court du manifeste de l’application par la valeur fournie. 30 caractères ✔️
name.full Remplace le nom complet du manifeste de l’application par la valeur fournie 100 caractères ✔️
description.short Remplace la brève description du manifeste de l’application par la valeur fournie. 80 caractères ✔️
description.full Remplace la description complète du manifeste de l’application par la valeur fournie. 4 000 caractères ✔️
Paires clé/valeur pour les chaînes localisées dans les agents Pour les agents, utilisez des clés tokenisées (comme spécifié dans l’application manifest.json, mais sans crochets doubles) avec leurs valeurs localisées. Par exemple : "DA_Name": "Agent de Communications"
Paires JSONPath/valeur pour les chaînes localisées de tout autre composant d’application Pour tous les autres composants d’application (Teams classiques), utilisez des expressions JSONPath comme clés pour les valeurs localisées. Par exemple : "staticTabs[0].name": "Accueil"

Pour plus d’informations, consultez Localiser votre application (Microsoft Teams) et informations de référence sur le schéma de localisation.

Champs localisables dans le manifeste de l’agent déclaratif

Les champs suivants peuvent être localisés dans le manifeste de l’agent déclaratif.

Champ manifeste Description Longueur maximale Obligatoire
name Nom de l’agent déclaratif. Doit contenir au moins un caractère non-espace blanc. 100 caractères ✔️
description Description de l’agent déclaratif. Doit contenir au moins un caractère non-espace blanc. 1 000 caractères ✔️
conversation_starters Liste (tableau) d’exemples de questions auxquelles l’agent déclaratif peut répondre, où chaque exemple est représenté par un objet avec title et text, qui sont tous deux localisables. 6 objets dans le tableau

Pour plus d’informations, consultez Informations de référence sur le manifeste de l’agent déclaratif.

Champs localisables dans le manifeste du plug-in d’API

Les champs suivants sont localisables dans le manifeste du plug-in d’API.

Champ manifeste Description Longueur maximale Obligatoire
name_for_human Nom court et lisible par l’utilisateur pour le plug-in. Il doit contenir au moins un caractère non-espace blanc. 20 caractères ✔️
description_for_model Description du plug-in fourni au modèle, y compris à quoi sert le plug-in et dans quelles circonstances ses fonctions sont pertinentes. 2 048 caractères
description_for_human Description lisible du plug-in. 100 caractères ✔️
logo_url URL utilisée pour extraire un logo qui peut être utilisé par l’orchestrateur.
legal_info_url URL absolue qui localise un document contenant les conditions d’utilisation du plug-in.
privacy_policy_url URL absolue qui localise un document contenant la politique de confidentialité du plug-in.

Pour plus d’informations, consultez Informations de référence sur le manifeste de plug-in d’API.

Contenu connexe