12 Localization of Digital Assistants

If you have skills for non-English-speaking audiences, chances are that you want to localize any digital assistants that can contain those skills as well. By localizing a digital assistant, you ensure that the digital assistant detects the user's language and presents welcome, help, disambiguation, and other messages in that language.

You can use one of these approaches to localize a digital assistant:

  • Create a multi-language digital assistant in which you:
    • Add a translation service.
    • Configure the System.DetectLanguage component in any skills that you want to add to the digital assistant to interact with the user in the language detected by the digital assistant.
    • Optionally (but preferably), add resource bundles for one or more languages for the digital assistant's labels, prompts, and messages. This is desirable because it allows you to control the wording of the digital assistant's responses.
    • Add skills which are set up with a translation service and where the training data is in English. See Multi-Language Skills with Auto-Translation.
  • Create a non-English single-language digital assistants in which you:
    • Add a translation service.
    • Configure the System.DetectLanguage component in any skills that you want to add to the digital assistant to interact with the user in the language detected by the digital assistant.
    • Provide translations for the various output strings (using resource bundles or directly in the fields for the properties).
    • Add skills which are set up with a translation service and where the training corpus is in the target language of the skill and digital assistant. See Non-English Single-Language Skills.

Add a Translation Service to a Digital Assistant

No matter which approach you use for localizing a digital assistant, you need to set up a translation service. Here are the steps:

  1. If you haven't done so already, configure a translation service for your Digital Assistant instance by:
    1. Clicking icon to open the side menu to open the side menu and selecting Settings > Translation Service.
    2. Clicking + Service.
    3. Entering the URL and Authorization token for the Microsoft Translator service or the Google Translation API in the Translation Services dialog.
    Refer to the documentation for Microsoft Translator and Google Translation API to find out how to get the URL and access token.

    Important:

    To use the Google Translation API, you need to generate the API Key. You create this key from the GCP Console (APIs & services > Credentials). To find out more, see the Google Cloud Platform Documentation.
  2. Set the translation service in your digital assistant by:
    1. Clicking icon to open the side menu to open the side menu, selecting Development > Digital Assistants, and selecting your digital assistant.
    2. In the digital assistant's left navbar, clicking the Settings(an image of the left navbar's Settings icon) icon and selecting the General tab.
    3. Navigating to the Translation Service dropdown and selecting your translation service.

Enable Language Detection by the Digital Assistant

By default, if a digital assistant is set up with a translation service, the digital assistant will detect the user's language in the same way that a skill with the System.DetectLanguage component does.

However, you also need to make sure that the skills in the digital assistant use the language that is detected by the digital assistant. When a skill is part of a digital assistant, the digital assistant translates user input into English and passes that translated English text to the skill. Therefore, by default, the skill's System.DetectLanguage component would detect English as the language and set the profile.LanguageTag variable to English, even though the user entered non-English text. To prevent this switch back to English, you need to add the following property to the System.DetectLanguage component in each skill:


      useExistingProfileLanguageTag: true

This ensures that the skill will honor the value of the profile.LanguageTag variable that is set by the digital assistant.

Here's an example of a skill's System.DetectLanguage component with the useExistingProfileLanguageTag set:

  detectLang:
    component: "System.DetectLanguage"
    properties:
      useExistingProfileLanguageTag: true
    transitions: {}

Note:

You can add that property to all of your skills, even if they are not all used in a digital assistant. If the skill isn't part of a digital assistant, the property has no effect.

Translating Output Text

For text in your digital assistant that is presented to users, you can use either of these translation approaches:

  • Use the translation service that is configured for the digital assistant.

    If you use this approach, you just need to have your output messages in English. No other configuration is needed. The translation service that you have configured will automatically translate any output messages to the user's language.

  • Use a resource bundle to translate the output messages yourself.

    Note:

    For any output messages that don't have a reference to a resource bundle key, the translation service will be automatically used to translate the messages.

Resource Bundles for Digital Assistants

When you want to control the wording for your digital assistant’s responses (instead of relying on the text provided by the translation service), use resource bundles. You can provide resources bundles for as many languages as you need.

The process of translating with resource bundles consists of the following steps:

  • Identify the fields and properties that need to be translated.
  • Create a resource bundle.
  • In the resource bundle, for each of the items to be translated, create keys, values for the default language, and translations for those values in as many languages as you need.
  • For the fields and properties that you have provided translations for, enter references to the corresponding resource bundle key. For simple strings, use the following expression format (where rb is an identifier reserved for the resource bundle):
    ${rb.BundleKeyName}

    For properties that use variables, use the following expression format:

    ${rb('bundleKey', '${variableForParam0}', '${variableForParam1}')}

Translatable Strings in Digital Assistants

Before you create resource bundle keys for a digital assistant, you naturally need to identify what strings need to be translated.

You can find the translatable strings in the following two places:

  • On the Skills (Skills icon) page of the digital assistant.

    Here you'll find the strings that are primarily used for the help cards that are displayed when a user asks for help in the digital assistant and when the digital assistant first greets the user.

    For each skill, you can translate
    • The One-sentence Description, Description, and Invocation fields.
    • The Example Utterances.
  • On the Settings (an image of the left navbar's Settings icon) page, within the Configurations tab, within the Conversation Parameters section.

    Note:

    Only the properties that apply to output text can access the resource bundle. Others, such as Help Cards - Optimize Rendering on Text-Only Channels (which expects a Boolean expression) can't.

Create a Resource Bundle

Once you have identified the strings to translate, you create a resource bundle and then create the keys, default values, and translations for each string.

To create and populate a resource bundle for a digital assistant.
  1. In the digital assistant's left navbar, click Resource Bundle icon..

  2. Click Add Bundle.

  3. In the Key field, enter a value that you can use to identify the field or property that it corresponds to.

    For example, if the key is for the first example utterance for a pizza skill, you could use something like PizzaSkillExampleUtterance1.

  4. Enter the text for the entry in the language that you want to use as the default language for the digital assistant. (The default language doesn't have to be in English. It's merely the language that is used for output messages if there are no translations for the detected language.)

    For skill-specific properties (such as Invocation and Example Utterances), you may wish to use the values inherited from the skills.

    For digital assistant conversation parameters (such as Acknowledgement Response), you may wish to merely use the default values for those properties if your digital assistant's default language is English.

    Note:

    For properties that use system variables as parameters to do things like access the name of an intent or skill, use substitution codes ({0}, {1}, etc.) for the parameters. Then, in the property's reference to the bundle key, the given system variables can be specified.
  5. Optionally, fill in the Annotation field to help other developers understand what the string is for and where it is used.
  6. Click Create Entry.

  7. To add an additional language version of the string, click Add Language.

  8. In the Create Entry dialog, fill in the following fields and click Create.
    • Language—Add an IETF BCP 47 language tag like fr for French or de for German.

    • Text—The output string for that language.

    • Annotation —(Optional). Information to help other developers understand what the string is for and where it is used.

  9. For each additional string that you need to translate, create another entry by clicking Add Key and repeating steps 3 through 8.

Reference Resource Bundle Keys for Help Cards in a Digital Assistant

When a digital assistant welcomes the user or presents help information for the skills it contains, it uses values from the Skills page in the digital assistant to populate the welcome and help cards. You can translate the information that appears on these help cards by editing some of the fields on the Skills page.

  1. In the left navigation for the digital assistant, click Skills icon
  2. Select a skill.
  3. Update the One-sentence Description, Description, and Invocation fields with references to resource bundles in the form:
    ${rb.BundleKeyName}

    For example, you could use the following for a reference to a key for a pizza skill's one-line description.

    ${rb.PizzaSkillShortDescription}
  4. In the Examples section of the page, hover over an example, click its Edit icon, and replace the text with a reference to a resource bundle key as above.
  5. Repeat the previous step for the skill's other example utterances.
  6. Repeat the previous four steps for each skill.

Note:

When you update the version of a skill in the digital assistant, you are presented with the Overwrite Interaction Model switch. If you keep this switch in the ON position, the values of the invocation and the example utterances will be updated with values set on the Digital Assistant tab of the updated skill's Settings page. This may mean you will need to translate the invocation and example utterances again.

Reference Resource Bundle Keys for Prompts and Messages

Digital assistants have a number of configuration properties which are used to display various prompts and messages.

To set the output for a configuration property, you reference the resource bundle context variable and message key using dot notation. For example: ${rb.WhatType}.

  1. In the digital assistant's left navbar, click the Settings (an image of the left navbar's Settings icon) icon and select the Configurations tab.

  2. For the properties within the Conversation Parameters section of the page, enter the references to resource bundle keys that you have defined for each of them.

    For example, if you have a key in your resource bundle called daAcknowledgementResponse for the Acknowledgement Response property, you would enter the following in the Acknowledgement Response field:

    ${rb.daAcknowledgementResponse}
System Variables in Resource Bundles

You can also use parameters in bundle keys, which enables you to make use of system variables in the output. For example, the default value of the Exit Flow Confirmation property is:

Exited ${system.routingFromIntent} in ${system.routingFromSkill}.

You can preserve the references to the system variables (in this case, system.routingFromIntent and system.routingFromSkill) in your translated responses by doing the following:

  1. In the text for the corresponding resource bundle key, insert {0}, {1}, etc. as substitution codes for each system variable. For example, in the English (or default) entry you create for the Exit Flow Confirmation property, you could use the following text:
    Exited {0} in {1}.
  2. Then, in the value of the property, enter the reference to the bundle key in the following format:
    ${rb('bundleKey', '${systemVariableForParam0}', '${systemVariableForParam1}')}

    For example, this is what it would look like for the Exit Flow Confirmation property (where daExitFlowConfirmation is the corresponding bundle key):

    ${rb('daExitFlowConfirmation', '${system.routingFromIntent}', '${system.routingFromSkill}')}

Sample Resource Bundle Entries

For convenience, here's a list of the customization properties that you can translate along with suggested names for the bundle keys and the expressions you'd use to reference those bundle keys from the fields for the properties. You don't have to use the names for the bundle keys that are suggested here.

Property to Be Translated Suggested Name for Bundle Key Default English Text Expression to Reference Bundle Key
Acknowledgement Response daAcknowledgementResponse Okay ${rb.daAcknowledgementResponse}
Answer No daAnswerNo No ${rb.daAnswerNo}
Answer Yes daAnswerYes Yes ${rb.daAnswerYes}
Digital Assistant Exit Flow in Selection daExitFlowInSelection Exit conversation ${rb.daExitFlowInSelection}
Digital Assistant Exit Skill in Selection daExitSkillInSelection Exit {0} ${rb('daExitSkillInSelection', '${system.routingFromSkill}')}
Exit Current To Go to New Skill Prompt daExitCurrentToGoToNewSkillPrompt This will exit current conversation. Do you want to go to {0} now? ${rb('daExitCurrentToGoToNewSkillPrompt', '${system.routingToSkill}')}
Exit Flow Confirmation daExitFlowConfirmation Exited {0} in {1}. ${rb('daExitFlowConfirmation', '${system.routingFromIntent}', '${system.routingFromSkill}')}
Exit Prompt daExitPrompt Do you want to exit {0} in {1} now? ${rb('daExitPrompt', '${system.routingFromIntent}', '${system.routingFromSkill}')}
Exit Skill Confirmation daExitSkillConfirmation Exited {0}. ${rb('daExitSkillConfirmation', '${system.routingFromSkill}')}
Flow Information in Selection daFlowInformationInSelection {0} in {1} ${rb('daFlowInformationInSelection', '${system.routingToIntent}', '${system.routingToSkill}')}
Flow Selection Prompt daFlowSelectionPrompt Do you want to go to: ${rb.daFlowSelectionPrompt}
Help Cards - Skill Detail Footer rb.daHelpCardsSkillDetailFooter Enter the number prefix to execute the action of your choice, or enter '0' to go back to the skill list. ${rb.daHelpCardsSkillDetailFooter}
Help Cards - Skill Detail Header daHelpCardsSkillDetailHeader Here are some sample actions ${rb.daHelpCardsSkillDetailHeader}
Help Cards - Skill List Footer daHelpCardsSkillListFooter Enter skill number to see sample actions supported by the skill. ${rb.daHelpCardsSkillListFooter}
Help Show more prompt daHelpShowMorePrompt Show more ${rb.daHelpShowMorePrompt}
History action disabled prompt daHistoryActionDisabledPrompt Sorry, this choice is no longer available. ${rb.daHistoryActionDisabledPrompt}
Interrupt Message daInterruptMessage Switching to {0} in {1} now. ${rb('daInterruptMessage', '${system.routingToIntent}', '${system.routingToSkill}')}
Interrupt Prompt daInterruptPrompt Do you want to switch to {0} in {1} now? ${rb('daInterruptPrompt', '${system.routingToIntent}', '${system.routingToSkill}')}
Interrupt To Unmatch Flow Prompt daInterruptToUnmatchFlowPrompt No match found in {0}. Do you still want to switch to it? ${rb('daInterruptToUnmatchFlowPrompt', '${system.routingToSkill}')}
Invalid History Action Message daInvalidHistoryActionMessage Sorry, this choice is no longer available. ${rb.daInvalidHistoryActionMessage}
Label for Q & A daLabelForQnA Ask Question ${rb.daLabelForQnA}
No Matches Were Found Prompt daNoMatchesWereFoundPrompt No matches were found. Here are some things you can do: ${rb.daNoMatchesWereFoundPrompt}
No Skill Bot Prompt daNoSkillBotPrompt You don't have any skills registered yet. Register one or more skills so that you can see the digital assistant in action. ${rb.daNoSkillBotPrompt}
None of the above daNoneOfTheAbove None of the above ${rb.daNoneOfTheAbove}
Nothing to Exit Prompt daNothingToExitPrompt There's nothing to exit. You don't have any requests in progress. ${rb.daNothingToExitPrompt}
Notification Interrupt Prompt daNotificationInterruptPrompt You have just received a notification from {0}. Would you like to switch to it? ${rb('daNotificationInterruptPrompt', '${system.routingToSkill}')}
Resume Message daResumeMessage Resuming {0} in {1} now. ${rb('daResumeMessage', '${system.routingFromIntent}', '${system.routingFromSkill}')}
Resume Prompt daResumePrompt Do you want to resume {0} in {1} now? ${rb('daResumePrompt', '${system.routingFromIntent}', '${system.routingFromSkill}')}
Skill Bot Exit-On-Help Label daSkillBotExitOnHelpLabel Exit conversation and view assistant help ${rb.daSkillBotExitOnHelpLabel}
Skill Bot Help Prompt daSkillBotHelpPrompt You are at {0}. Here are some things you can do: ${rb('daSkillBotHelpPrompt', '${system.routingFromSkill}')}
Skill Bot View Help Again Label daSkillBotViewHelpAgainLabel View current skill help again ${rb.daSkillBotViewHelpAgainLabel}
Skill Welcome Flow in Selection daSkillWelcomeFlowInSelection Welcome ${rb.daSkillWelcomeFlowInSelection}
Start Message daStartMessage Starting {0} in {1} now. ${rb('daStartMessage', '${system.routingFromIntent}', '${system.routingFromSkill}')}
Start Prompt daStartPrompt Do you want to start with {0} in {1} now? ${rb('daStartPrompt', '${system.routingFromIntent}', '${system.routingFromSkill}')}
Skill Bot Welcome Prompt daSkillBotWelcomePrompt Welcome to {0}. ${rb('daSkillBotWelcomePrompt', '${system.routingFromSkill}')}
Expired Session Error Prompt daExpiredSessionErrorPrompt Your session has expired. Please start again. ${rb.daExpiredSessionErrorPrompt}
Max States Exceeded Error Prompt daMaxStatesExceededErrorPrompt Your session appears to be in an infinite loop. ${rb.daMaxStatesExceededErrorPrompt}
OAuth Cancel Prompt daOAuthCancelPrompt Authentication canceled. ${rb.daOAuthCancelPrompt}
OAuth Success Prompt daOAuthSuccessPrompt Authentication successful! You can return to the conversation. ${rb.daOAuthSuccessPrompt}
Unexpected Error Prompt daUnexpectedErrorPrompt Oops I'm encountering a spot of trouble. Please try again later... ${rb.daUnexpectedErrorPrompt}

Export and Import Resource Bundles

You can export and import resource bundles in the form of a CSV file, which enables you to work with the bundles offline.

The CSV file needs to have the following columns:

  • languageTag
  • key
  • message
  • annotation

To export a CSV file with the existing resource bundle:

  • On the Resource Bundle page for your skill or digital assistant, click Export Resource Bundle icon to export a CSV file with the existing resource bundle.

    Even if you haven't yet added any keys to the resource bundle, a file with the required format of the CSV will be exported.

To import a resource bundle file:

  • On the Resource Bundle page for your skill or digital assistant, click Import Resource Bundle icon .

Explicit Invocation in Localized Digital Assistants

In multi-language (and single-language non-English) digital assistants, explicit invocation of skills is recognized by the digital assistant in both the detected language and in English.