Localiser votre agent

Les agents sont essentiellement des applications pour Microsoft 365. Elles partagent un schéma de manifeste, un empaquetage d’application et un processus de distribution et de gestion communs. Le manifeste de votre 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 de l’application Teams et pour les agents. 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 langue, les champs liés à l’agent sont référencés à l’aide de clés du dictionnaire. Contrairement aux fonctionnalités classiques de l’application Teams, 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 et pour chaque langue supplémentaire.

Diagramme montrant la relation entre le manifeste d’application, le manifeste d’agent déclaratif et un fichier de langue à des fins de localisation d’un agent

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

Mettre à jour vos manifestes d’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 doubles crochets, 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..."
}

Ajouter localizationInfo à votre manifeste d’application

Ajoutez la section à votre manifeste d’application, avec des localizationInfobalises de langue et des chemins 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 les 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’applications unilingues ne nécessitent pas de fichier de langue distinct pour la langue par défaut.

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

Créez un fichier de localisation pour chaque langue prise en charge avec des valeurs pour les clés tokenisées, à l’aide des noms de fichier 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 à partir du schéma de localisation de l’application qui doivent être localisées.

Champ Manifest 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 de schéma du manifeste doit être la même pour le manifeste de l’application et les fichiers 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 app manifest.json, mais sans doubles crochets) avec leurs valeurs localisées. Par exemple : "DA_Name": "Agent de Communications"
Paires JSONPath/valeur pour les chaînes localisées de n’importe quel autre composant de l’application Pour tous les autres composants de l’application (Teams classique), utilisez les 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 la référence du schéma de localisation.

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

Les champs suivants sont localisables dans le manifeste de l’agent déclaratif.

Champ Manifest Description Longueur maximale Obligatoire
name Nom de l’agent déclaratif. Doit contenir au moins un caractère autre qu’un espace. 100 caractères ✔️
description Description de l’agent déclaratif. Doit contenir au moins un caractère autre qu’un espace. 1 000 caractères ✔️
conversation_starters Liste (tableau) d’exemples de questions auxquelles l’agent déclaratif peut répondre, où chaque exemple est un objet avec title et text, les deux étant localisables. 12 objets dans le tableau

Pour plus d’informations, consultez Référence du 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 Manifest Description Longueur maximale Obligatoire
name_for_human Nom court et lisible par l’homme pour le plug-in. Il doit contenir au moins un caractère autre qu’un espace. 20 caractères ✔️
description_for_model Description du module fournie au modèle, y compris à quoi sert le module et dans quelles circonstances ses fonctions sont pertinentes. 2 048 caractères
description_for_human Description lisible du module. 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.
conversation_starters Une liste (tableau) d’exemples de questions auxquelles le plugin peut répondre, où chaque exemple est un objet avec title et text, qui sont tous deux localisables.

Pour en savoir plus, consultez la référence du manifeste du plug-in.