Localize your agent

Agents are essentially apps for Microsoft 365. They share a common manifest schema, app packaging, and distribution and management process. Your app manifest references the definition file for your declarative agents in the copilotAgents object.

The way you localize an agent is slightly different than how you localize other capabilities (such as tabs, bots, and message extensions) in a Microsoft 365 app manifest.

You use the same localization file (per language) for both Teams app capabilities and agents. However, while all other app manifest fields are referenced using JSONPath expressions in the language files, agent-related fields are referenced using dictionary keys. Unlike classic Teams app capabilities, which use default language strings in the app manifest itself, localized agents require a language file for the default language as well as for each additional language.

This article describes how to add support for additional languages (beyond the default language) to your agents.

1. Update your agent manifests with tokenized keys

Update your declarative agent and/or API plugin manifests with tokenized keys (indicated with double square brackets, for example [[PLUGIN_NAME]]) for any field values you want to localize. Localization keys must match this regular expression: ^[a-zA-Z_][a-zA-Z0-9_]*$

The following example shows a declarative agent manifest with tokenized values for its name and 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. Add localizationInfo to your app manifest

Add the localizationInfo section to your app manifest, with language tags and relative paths to each supported language file within your app package.

If your agent supports more than one language, you must specify a standalone language file for every supported language, including your default language.

The following example shows the localizationInfo section in an app manifest.

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

If your agent doesn't support additional languages, the default language strings are represented within the app manifest file itself. Single language app packages don't require a separate language file for the default language.

3. Create a localization file for each additional language

Create a localization file for each additional supported language with values for the tokenized keys, using the file names specified (for the defaultLanguageFile and file properties) in the app manifest in the previous step.

The following example show a language file, fr.json, with localized strings for both a agent and personal tabs.

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

Localizable fields in app manifest

For each language file, specify the following properties from the app localization schema that are required to be localized.

To learn more, see Localize your app (Microsoft Teams) and the Localization schema reference.

Localizable fields in declarative agent manifest

The following fields are localizable within the declarative agent manifest.

To learn more, see Declarative agent manifest reference.

Localizable fields in API plugin manifest

The following fields are localizable within the API plugin manifest.

To learn more, see API plugin manifest reference.

Related content

• Agent app package