Lokalisieren Ihres Agents

Agents sind im Wesentlichen Apps für Microsoft 365. Sie nutzen ein gemeinsames Manifestschema, eine gemeinsame App-Verpackung sowie einen gemeinsamen Verteilungs- und Verwaltungsprozess. Ihr App-Manifest verweist auf die Definitionsdatei für Ihre deklarativen Agents im copilotAgents Objekt.

Die Art und Weise, wie Sie einen Agent lokalisieren, unterscheidet sich geringfügig von der Art und Weise, wie Sie andere Funktionen (z. B. Registerkarten, Bots und Nachrichtenerweiterungen) in einem Microsoft 365-App-Manifest lokalisieren.

Sie verwenden dieselbe Lokalisierungsdatei (pro Sprache) sowohl für die Funktionen der Teams-App als auch für Agents. Während jedoch in den Sprachdateien auf alle anderen App-Manifestfelder mithilfe von JSONPath-Ausdrücken verwiesen wird, wird auf Agent-bezogene Felder mithilfe von Wörterbuchschlüsseln verwiesen. Im Gegensatz zu klassischen Teams-App-Funktionen, die Standardsprachzeichenfolgen im App-Manifest selbst verwenden, benötigen lokalisierte Agents eine Sprachdatei für die Standardsprache und für jede zusätzliche Sprache.

Diagramm, das die Beziehung zwischen App-Manifest, deklarativem Agent-Manifest und einer Sprachdatei zum Zweck der Lokalisierung eines Agents zeigt

In diesem Artikel wird beschrieben, wie Sie Ihren Agents Unterstützung für andere Sprachen (über die Standardsprache hinaus) hinzufügen.

Aktualisieren Ihrer Agentmanifeste mit tokenisierten Schlüsseln

Aktualisieren Sie Ihre deklarativen Agent- und/oder API-Plug-In-Manifeste mit tokenisierten Schlüsseln (z. B [[PLUGIN_NAME]]. durch doppelte eckige Klammern gekennzeichnet) für alle Feldwerte, die Sie lokalisieren möchten. Lokalisierungsschlüssel müssen mit diesem regulären Ausdruck übereinstimmen: ^[a-zA-Z_][a-zA-Z0-9_]*$

Das folgende Beispiel zeigt ein deklaratives Agentmanifest mit tokenisierten Werten für seinen Namen und seine Beschreibung.

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

Hinzufügen localizationInfo zu Ihrem App-Manifest

Fügen Sie den localizationInfo Abschnitt Ihrem App-Manifest hinzu, mit Sprachtags und relativen Pfaden zu jeder unterstützten Sprachdatei in Ihrem App-Paket.

Wenn Ihr Agent mehr als eine Sprache unterstützt, müssen Sie für jede unterstützte Sprache, einschließlich Ihrer Standardsprache, eine eigenständige Sprachdatei angeben.

Das folgende Beispiel zeigt den localizationInfo Abschnitt in einem App-Manifest.

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

Wenn Ihr Agent keine anderen Sprachen unterstützt, werden die Standardsprachzeichenfolgen in der App-Manifestdatei selbst dargestellt. Für einsprachige App-Pakete ist keine separate Sprachdatei für die Standardsprache erforderlich.

Erstellen Sie eine Lokalisierungsdatei für jede zusätzliche Sprache

Erstellen Sie eine Lokalisierungsdatei für jede unterstützte Sprache mit Werten für die tokenisierten Schlüssel unter Verwendung der Dateinamen, die im App-Manifest im vorherigen Schritt angegeben wurden (für die defaultLanguageFile Eigenschaften und file und).

Das folgende Beispiel zeigt eine Sprachdatei fr.jsonmit lokalisierten Zeichenfolgen für einen Agent und persönliche Registerkarten.

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

Lokalisierbare Felder im App-Manifest

Geben Sie für jede Sprachdatei die folgenden Eigenschaften aus dem App-Lokalisierungsschema an, die lokalisiert werden müssen.

Manifestfeld Beschreibung Max. Länge Erforderlich
$schema Die URL zum Lokalisierungsschema. Verwenden Sie für Agents devPreview: https://developer.microsoft.com/en-us/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json. Die Manifestschemaversion muss für App-Manifest- und Lokalisierungsdateien identisch sein. ✔️
name.short Ersetzt den Kurznamen aus dem App-Manifest durch den angegebenen Wert. 30 Zeichen ✔️
name.full Ersetzt den vollständigen Namen aus dem App-Manifest durch den angegebenen Wert 100 Zeichen ✔️
description.short Ersetzt die Kurzbeschreibung aus dem App-Manifest durch einen bereitgestellten Wert. 80 Zeichen ✔️
description.full Ersetzt die vollständige Beschreibung aus dem App-Manifest durch den angegebenen Wert. 4.000 Zeichen ✔️
Schlüssel-Wert-Paare für lokalisierte Zeichenfolgen in Agents Verwenden Sie für Agents tokenisierte Schlüssel (wie in der App manifest.jsonangegeben, aber ohne doppelte eckige Klammern) mit ihren lokalisierten Werten. Zum Beispiel: "DA_Name": "Agent de Communications"
JSONPath/Wert-Paare für lokalisierte Zeichenfolgen beliebiger anderer App-Komponenten Verwenden Sie für alle anderen (klassischen Teams-) App-Komponenten JSONPath-Ausdrücke als Schlüssel für die lokalisierten Werte. Zum Beispiel: "staticTabs[0].name": "Accueil"

Weitere Informationen finden Sie unter Lokalisieren Ihrer App (Microsoft Teams) und in der Lokalisierungsschemareferenz.

Lokalisierbare Felder im Manifest des deklarativen Agents

Die folgenden Felder sind innerhalb des Manifests des deklarativen Agents lokalisierbar.

Manifestfeld Beschreibung Max. Länge Erforderlich
name Der Name des deklarativen Agents. Muss mindestens ein Nicht-Leerzeichen enthalten. 100 Zeichen ✔️
description Die Beschreibung des deklarativen Agents. Muss mindestens ein Nicht-Leerzeichen enthalten. 1.000 Zeichen ✔️
conversation_starters Eine Liste (Array) von Beispielen von Fragen, die der deklarative Agent beantworten kann, wobei jedes Beispiel ein Objekt mit title und textist, die beide lokalisierbar sind. 12 Objekte im Array

Weitere Informationen finden Sie unter Referenz zum deklarativen Agent-Manifest.

Lokalisierbare Felder im API-Plug-In-Manifest

Die folgenden Felder sind innerhalb des API-Plug-In-Manifests lokalisierbar.

Manifestfeld Beschreibung Max. Länge Erforderlich
name_for_human Ein kurzer, für Menschen lesbarer Name für das Plugin. Sie muss mindestens ein Nicht-Leerzeichen enthalten. 20 Zeichen ✔️
description_for_model Die Beschreibung für das Plug-In, die dem Modell zur Verfügung gestellt wird, einschließlich des Zwecks des Plug-Ins und der Umstände, unter welchen Umständen seine Funktionen relevant sind. 2.048 Zeichen
description_for_human Eine für Menschen lesbare Beschreibung des Plug-Ins. 100 Zeichen ✔️
logo_url Eine URL, die zum Abrufen eines Logos verwendet wird, das vom Orchestrator verwendet werden kann.
legal_info_url Eine absolute URL, die ein Dokument findet, das die Nutzungsbedingungen für das Plug-In enthält.
privacy_policy_url Eine absolute URL, die ein Dokument lokalisiert, das die Datenschutzrichtlinie für das Plug-In enthält.
conversation_starters Eine Liste (Array) von Beispielen für Fragen, die das Plugin beantworten kann, wobei jedes Beispiel ein Objekt mit title und textist, die beide lokalisierbar sind.

Weitere Informationen finden Sie in der Plug-In-Manifestreferenz.