Here are the initial steps for setting up a digital assistant in Natively-Supported language mode:

1. Click to open the side menu, select Development > Digital Assistants, and click New Digital Assistant.

2. Complete the dialog, paying particular attention to these fields:
   • Platform Version: The platform version affects the behavior of your digital assistants, such as the way the Natural Language Understanding (NLU) engine resolves intents and which languages are supported natively.

     For the natively-supported language mode, you need to set this to 20.12 or higher.

     See Platform Version.

   • Primary Language: This determines both the default language for the digital assistant and whether the digital assistant will use native support for that language or rely on a translation service.

     In this field, you need to select one of the languages in the Natively-Supported section of the dropdown.

3. If you need to add any additional languages to the digital assistant:
   1. In the left navigation of the newly created digital assistant, click .
   2. Click Add Language and select the language you want to add.

In digital assistants based on Oracle Digital Assistant's native language support, the languages that you configure for the digital assistant should match the languages that are configured for the skills.

To help you monitor whether the languages configured for your skills and digital assistant are in alignment, a check is run whenever you add a language or a skill to the digital assistant and each language is marked as either Complete or In-Progress:

• Complete languages are those in which each of the digital assistant's skills are configured for that language.
• In-progress languages are those languages for which one or more skills are not configured.

You can find the list of complete and in-progress languages on the General tab of the digital assistant's Settings page ().

If you want to take advantage of Oracle Digital Assistant native language support in a digital assistant that has already been configured to use a translation service, follow these general steps:

1. For all of the skills in the digital assistant, create versions that use the native language support.

   See Create a Skill with Natively-Supported Languages.

   For the list of natively-supported languages, see Natively-Supported Languages. (If any of the languages that you want to support aren't on that list, you need to continue using translation service mode.)

2. Create a new version or clone of the digital assistant.

   1. Click to open the side menu and select Development > Digital Assistants.

   2. In the tile for the digital assistant that you want to version or clone, click and select Version or Clone.

   3. Fill in the required fields and click Create.

3. Remove all of the skills from the new version or clone that you just created.

   This is necessary, because you can't create switch the digital assistant to use the native language support if it contains any skills that are in translation service mode.

4. Create a new version or clone of that modified digital assistant, select Platform Version 20.12 or higher, and select the Natively-Supported language mode.

   With this step, you are able to preserve the configuration that you have done for the digital assistant, even though you have to handle the skills separately.

5. Add the native-language support versions of the skills to the digital assistant.

In digital assistants (or standalone skills) that use multiple natively-supported languages, the digital assistant can automatically detect the user's language at the beginning of the session. Here's how it works:

• The language is automatically detected for digital assistants and skills that are configured with multiple natively-supported languages.
  • If there is only one (natively-supported) language in the digital assistant, language detection is turned off.
  • If the digital assistant uses a translation service, the translation service handles the language detection, not the digital assistant.
• The language is not automatically detected if the digital assistant is accessed through a channel where the profile.languageTag or profile.locale variable has been set.
• The language is detected in the first utterance of the conversation and not updated in the session, even if the user switches languages.
• By default, the channel session last 7 days before it expires.

Here are the initial steps for setting up a non-English single-language digital assistant in Translation Service language mode:

1. Click to open the side menu, select Development > Digital Assistants, and click New Digital Assistant.

2. Complete the dialog, paying particular attention to these fields:
   • Platform Version: The platform version affects the behavior of your digital assistants, such as the way the Natural Language Understanding (NLU) engine resolves intents and which languages are supported natively.

     If you are starting with a new digital assistant, you should select the most recent version available, since support for that version will last the longest.

     See Platform Version.

   • Primary Language: This field only appears if you have selected Platform Version 20.12 or higher.

     In this field, you need to select your target language in the Translation Service section of the dropdown.

     Caution:

     Be sure that you have selected from the Translation Service section. If you select from the Natively-Supported section, the digital assistant will only accept skills that use Natively-Supported mode.

     If this field doesn't appear, the language of the digital assistant is determined by the language of the first skill that you add to it. In this case, this language is referred to as the predominant language instead of the primary language.

Here are the initial steps for setting up a multi-language digital assistant in Translation Service language mode:

1. Click to open the side menu, select Development > Digital Assistants, and click New Digital Assistant.

2. Complete the dialog, paying particular attention to these fields:
   • Platform Version: The platform version affects the behavior of your digital assistants, such as the way the Natural Language Understanding (NLU) engine resolves intents and which languages are supported natively.

     If you are starting with a new digital assistant, you should select the most recent version available, since support for that version will last the longest.

     See Platform Version.

   • Primary Language: This field only appears if you have selected Platform Version 20.12 or higher.

     In this field, you need to select English in the Translation Service section of the dropdown.

     Caution:

     Be sure that you have selected from the Translation Service section. If you select from the Natively-Supported section, the digital assistant will only accept skills that use Natively-Supported mode.

     If this field doesn't appear, the language of the digital assistant is determined by the language of the first skill that you add to it. In this case, this language is referred to as the predominant language instead of the primary language.

1. If you haven't done so already, configure a translation service for your Digital Assistant instance by:
   1. Clicking 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.

   Note
   
   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 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() icon and selecting the General tab.
   3. Navigating to the Translation Service dropdown and selecting your translation service.

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 Detect Language 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 Detect Language 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 in a skill with a dialog flow developed in Visual mode, you need to set the Detect Language component's Existing Profile Language Tag property to True in each skill.

To prevent this switch back to English in a YAML-based skill, you need to add the following property to the Detect Language 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:
      ...

For user-visible text in a digital assistant that uses a translation service, 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.

In digital assistants that use a translation service, explicit invocation of skills is recognized by the digital assistant in both the detected language and in English.

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

• On the Skills () 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 () page, within the Configurations tab, within the Conversation Parameters section. Starting in platform version 21.04, resource bundle entries are automatically created for these settings.

Resource bundle keys are used to identify output text that needs to be translated and provide values in one or more languages. For digital assistants that use platform version 21.04 or later, keys are generated automatically for digital assistant's configuration settings. For other strings (and for configuration settings in digital assistants that are on platform version 21.02 or earlier), you need to create keys manually.

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

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. For example: ${rb('WhatType')}. You can also use dot notation, e.g.: ${rb.WhatType}

1. In the digital assistant's left navbar, click the Settings () 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')}

You can also use parameters in values for 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 value 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}')}

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

Starting with platform version 21.04, resource bundle entries are automatically created for digital assistant configuration settings. If your digital assistant is based on platform version 21.02 or earlier, you can upgrade to 21.04 or higher to have these entries generated for you.

Here is a list of all of the system resource bundle entries for digital assistants along with their default values.

If you'd like to use resource bundle entries for your configuration settings without upgrading the platform version of the digital assistant to 21.04 or higher, 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.