Configure and create multilingual agents

Multilingual agents communicate with customers in different languages while keeping all the content in a single agent. In many cases, they 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 customer 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 customer. If the agent can't detect the client or browser language, or if the detected language 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.

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.

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

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 download strings from your agent and translate them into your agent's secondary languages. Once you upload the translated strings, you can switch the language in the test panel and verify that conversations in the secondary languages also flow as expected.

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 and the Settings page.

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 localization file for the secondary language, 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 uses the same ID, you must compare the new file against the previously uploaded file.

Make dynamic content from Adaptive Cards available for localization

Localization files don't include mixed-typed strings from Adaptive Cards. If you need to localize an Adaptive Card where a string can include both static text and variables (dynamic content), use the following workaround. The procedure shows you how to use a Set text variable node to store the full string with the static text and variables in an intermediate variable. Then you reference only that intermediate variable in your Adaptive Card. When you download a localization file for your agent, the value of your intermediate variable, with the static text and the variable references, is available for localization as part of a setVariable action.

To make an Adaptive Card's dynamic content localizable:

1. Add a Set variable value node before your Adaptive Card. This step creates a YAML representation that you can update by using the code editor to convert the node into a Set text variable node. You can't create Set text variable nodes directly from the authoring canvas.

2. In the Set variable value node, create a new variable but don't set the value yet.

3. Open the code editor for your topic.

4. In the code editor, locate the part that represents your Set variable value node and replace kind: SetVariable with kind: SetTextVariable. This change converts your Set variable value node into a Set text variable node.

5. Close the code editor.

6. Select the bottom field of the Set text variable node and enter the full string with the static text and variables you want to show on your Adaptive Card. Insert a variable in the same way you would insert a variable in a message.

7. Update your Adaptive Card with a reference to this new variable.

8. Save your topic. You can now download the localization file and verify that it includes the dynamic content for your Adaptive Cards.

Test a multilingual agent

1. Open the test panel.

2. Select the More icon (…) at the top of the test panel, and select the language you want. The test panel reloads itself, this time using the selected language. The authoring canvas stays in the primary language and you can't save changes you make to a topic until you switch back to the primary language.

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

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

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, 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

You can configure an agent to detect the language a customer uses 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, such as "Detect language."

   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.

      

   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.

      

Troubleshoot a multilingual agent

This section provides tips to understand unexpected multilingual agent behavior.

Multilingual agent behavior for languages that aren't configured

If a user configures their browser for a language that you didn't configure for the agent, the agent falls back to its primary language.

You specify the primary language for an agent when you create the agent. You can't 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.

Localization files don't include mixed-typed strings from Adaptive Cards. If you need to localize Adaptive Cards where a string can include both static text and variables (dynamic content), you must use a workaround. Learn how to store a mixed-typed string in a text variable before using it in an Adaptive Card.

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 localization file contains either duplicate synonyms or a synonym that matches a DisplayName value. You typically encounter this error 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 the JSON or ResX file for your secondary language, and identify any instances where this condition might be present.