Share via

Configure and create multilingual agents

Multilingual agents are agents that can communicate with customers in different languages while keeping all the content in a single agent. In many cases, they can automatically detect the desired language based on the agent user's web browser setting and respond in the same language, providing a more personalized and engaging experience for customers.

When you create an agent, you specify its primary language.

After you add secondary languages to an agent, you're responsible for providing the translations for messages in topics you create. For agents that use generative orchestration, generated messages are translated automatically.

When a user starts a session with a published agent, the agent selects one of its languages to match the language specified in the client or browser of the user. If the agent can't detect the client or browser language, or if the language detected isn't one of the languages you specified for your agent, the agent defaults to its primary language.

You can design an agent to change the language it uses during a conversation (see Make an agent switch to another language). You can also set up an agent that uses generative orchestration to dynamically switch languages to follow the language used in the current conversation turn (see Set up an agent for dynamic language switching).

For the list of supported languages, see Language support.

Note

Classic chatbots support only one language. For more information about converting a classic chatbot to an agent, see Upgrade to Copilot Studio unified authoring.

Add languages to an agent

  1. Go to the Settings page for the agent, and select Languages.

  2. Select Add languages.

  3. In the Add languages panel, select the languages you want to add to the agent, and select Add at the bottom.

  4. Review the list of languages, and close the Settings panel.

Manage localization for a multilingual agent

In Copilot Studio, you perform all topic and content editing in the agent's primary language. This section explains how to localize the strings into your agent's secondary languages. Once the strings are localized and uploaded to the agent as described here, you can see the localized content on the authoring canvas by switching the language in the test panel.

Prepare localized content

When you first download the localization file for a secondary language, all strings are in the agent's primary language. After you download a localization file, use it with your preferred localization process.

  1. Go to the Settings page for your agent, and select Languages.

  2. On the Languages page, in the list of secondary languages, select Upload for the language you want to update.

  3. In the Update localizations panel, select either the JSON or ResX format to download the current localization file for that language.

    Note

    The downloaded file contains the latest localization content for the agent. If you need to download previous versions of the localization file, open the agent's solution.

  4. Open the downloaded file and replace the primary language strings with the appropriate translated text.

  5. Return to the Update localizations panel, select Browse, and upload the translated file.

  6. Close the Update localizations panel.

Update localized content

If you make changes to the primary language strings, you must also update the content in the secondary languages. This process includes both new content and modified content. Incremental changes aren't automatically translated. You must download the secondary language JSON or ResX file, and update the untranslated strings using your preferred localization process.

The following scenario is typical of the workflow for translated content. You previously translated your primary language (en-US) into a secondary language (fr-FR), and you added and modified content in the primary language. When you download the secondary language localization file, all the new content is in the primary language (en-US). However, the modified content still appears in the secondary language. Because the modified content is using the same ID, you must compare the new file against the previously uploaded file.

Test a multilingual agent

  1. Open the test panel.

  2. Select the More icon (…) at the top of the test panel, and select the desired language.

    Screenshot showing where to select a secondary language from the test panel's More menu.

    The test panel reloads itself, this time using the selected secondary language. The authoring canvas shows the secondary language.

  3. To test the agent, enter a message in the secondary language.

You can also set your browser language to one of your agent' secondary languages, and go to the prebuilt demo website. The demo website opens in the specified language, and the agent chats using the translated strings.

Make an agent switch to another language

When authoring, you can configure the agent to switch to another language in the middle of a conversation. The logic can reside in any topic in the agent. However, the best practice is to switch the language right after a Question node, which ensures that all the following messages until the next Question node are in the same language.

To change the agent's current language, you can set the User.Language system variable to one of your agent's secondary languages. This selection changes the language spoken by your agent immediately.

Set up an agent for dynamic language switching

Note

This feature is only available for agents with generative orchestration enabled.

You can configure an agent to detect the language used by a user and respond in the same language. With this configuration, the agent can switch languages multiple times over the course of a single conversation. The following scenario shows how to set up an agent to switch between Dutch and English. You can extend it for any combination of the languages your agent supports.

This scenario uses a topic with a Message received topic trigger. This topic trigger lets your agent examine every message it receives. This topic uses a custom prompt to detect the language and a condition to set the agent language system variable.

  1. Create a topic.

  2. Replace the default trigger type for the topic with A message is received.

  3. Add a prompt to your topic:

    1. Select the Add node icon below the Trigger node.

    2. Select Add a tool > New prompt.

    3. In the prompt editor, enter a representative name for your prompt: "Detect language," for example.

    4. In the Instructions pane, enter "Determine which language this message is written in: ".

    5. At the bottom of the Instructions pane, select Add content and select Text. A window appears inviting you to enter a name and a sample message.

    6. For Name enter "Message," for Sample data enter "Message from the user," and select Close.

    7. In the Model response pane, switch the Output format to JSON.

    8. Select Test. Your prompt shows a JSON literal, with a single property identifying the language as English.

      Screenshot of a prompt configured to detect the language of a message.

    9. Select Save. A Prompt node appears on the canvas.

  4. Configure the Prompt node:

    1. For Input, select the system variable Activity.Text (the text of the incoming message).
    2. For Output, create a new variable called DetectedLanguage.

  5. Branch your logic based on the detected language:

    1. Add a condition below the Prompt node.

    2. Base your condition on the custom variable DetectedLanguage.structuredOutput.language, which holds the name of the detected language.

    3. Add a condition branch for each language you need to detect.

    4. Under each branch, add a Set variable value node to set the User.Language system variable accordingly. The following image shows a topic with a condition to switch between Dutch and English.

      Screenshot of the topic that detects and switches the agent language.

Troubleshoot a multilingual agent

This section provides tips to understand unexpected multilingual agent behavior.

Multilingual agent behavior for languages that aren't configured

If the user of an agent has their browser configured for a language the agent wasn't configured for, the agent always falls back to its primary language.

You specify the primary language for an agent when you create the agent. It's not possible to change the primary language after creation but you can change the region for the agent's primary language, if more than one region is available.

Multilingual agent behavior for missing translations

If you add messages to an agent in its primary language, but you don't upload the translations for the new messages, the agent shows the untranslated changes in its primary language. Always make sure the translations are up-to-date after making changes to an agent.

Errors when publishing a multilingual agent

When you attempt to publish a multilingual agent, if you see the "Validation for the bot failed" error message with the raw response error code, SynonymsNotUnique, your secondary localization file contains either duplicate synonyms or a synonym that matches a DisplayName value. This error is typically encountered when a node contains an Entity.Definition.'closedListItem' where either of the following scenarios occurred:

  • One of the Synonyms elements isn't unique.
  • One of the Synonyms elements has the same value as the DisplayName element.

All Synonyms for the same entity must be unique, and have a different name than the DisplayName element.

To correct the error, review your secondary language's JSON or ResX file, and identify any instances where this condition might be present.