Share via

Configure and create multilingual agents

  • Article

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

Add languages to an 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 add languages to an agent:

  1. Go to the Settings page for your 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

Note

All 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 on the authoring canvas by switching the language in the test panel.

To add the localization strings to your multilingual agent:

  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

When you first download the localization file for a secondary language, the strings are in the primary language. After you download a localization file, use it 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 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.

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 system variable to one of your agent's secondary languages. This selection changes the language spoken by your agent immediately.

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 the secondary language supported by your agent, and open the prebuilt demo 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. Always make sure the translations are up-to-date after making changes to the agent in the primary language.

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.

Related content