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.
For the list of supported languages, see Language support.
Note
Copilot Studio classic chatbots don't support multilingual agents. For more information about converting a classic chatbot to an agent, see Upgrade to Copilot Studio unified authoring.
When published to a channel, if no language is specified at session start, the multilingual agent defaults to the primary language. You can configure the agent to change the language during a conversation, see Authoring considerations for multilingual agents.
Configuring a multilingual agent
When an agent is initially created, a primary language is defined. For more information on how to select the agent's primary language, see Language support.
To enable a multilingual agent:
With an agent open, select Settings at the top of the page, and then select Languages.
Select Add Languages on the Settings page.
Choose the languages you want to add to the agent in the Add Languages pane and select Add Languages at the bottom.
Confirm the list of languages is correct on the Languages page.
Note
You can add as many secondary languages as desired to the agent, as long as they're in the list of supported languages.
Managing localization in a multilingual agent
Note
All agent topic and content editing must be done in the agent's primary language. To edit the agent's secondary language to localize the strings, you must use the steps in this section.
Once the agent strings are localized and uploaded to the agent as described here, you can see the localized content in the authoring canvas by switching the language in the test agent.
To add the localization strings to your multilingual agent:
With an agent open, select Settings at the top of the page, and then select Languages.
On the Languages page, in the table of added secondary languages, select Upload in the Localization column for the language you want to update.
On the Update localizations page for the selected secondary language, 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 to download previous versions.
Open the downloaded file and replace the primary language strings with the appropriate translated text.
Return to the Update localizations page, select Browse, and upload the translated file.
Close the Update localizations page.
Updating localized content
When you first download the localization file for a secondary language, the strings are in the primary language. After you've downloaded the localization file, you use these files with your preferred localization process.
If you make changes to the primary language strings, you need to also update the localized content in the secondary language. This 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 non-translated 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. This is because the modified content is using the same ID. You need to compare the new file against the previously uploaded file.
Authoring considerations for multilingual agents
When authoring, you can configure the agent to change the current spoken language in the middle of a conversation. That 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 variable value to one of your agent's secondary languages. This selection changes the language spoken by your agent immediately.
Testing a multilingual agent
To test a multilingual agent:
Open the Test your agent pane.
Open the menu at the top of the test agent, and select one of the secondary languages.
The test agent reloads itself, this time using the selected secondary language. The authoring canvas shows the secondary language.
To test the agent, enter a message in the secondary language.
You can also set your browser language to the secondary language supported by your agent, and open the Demo agent website. The demo website opens in the secondary language, and the agent chats using the secondary language strings.
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.
Important
The agent's primary language can't be changed after agent creation.
Multilingual agent behavior for missing translations
If the agent author makes a change to the agent in the primary language and doesn't upload the translations, the agent shows the untranslated changes in its primary language. This configuration leads to a confusing dual-language experience. Always make sure the translations are up-to-date after making changes to the agent in the primary language.