You can develop both single-language and multi-language digital assistants. Though the majority of the language-related work is done in the digital assistant's skills, you also need to ensure that the digital assistant itself detects the user's language and presents welcome, help, disambiguation, and other messages in that language.
These are your high level options:
Create a single-language or multi-language digital assistant for skills that use Oracle Digital Assistant's native language support.
In the digital assistant, you specify the target languages and then add skills that support those languages. When users initiate conversations in the digital assistant, the language is automatically detected and then used by the digital assistant for the duration of the conversation.
For output, you define resource bundle entries for each language.
Create a non-English single-language digital assistant based on a translation service, in which you:
Add a translation service.
Add skills that are set up with a translation service, are configured with the
Detect Language component, and have their training data in the target
language of the skill and digital assistant.
Provide translations for the various output strings (using resource bundles or directly in the fields for the properties).
Choosing Between Native Language Mode and Translation Service Mode 🔗
When you create skills and digital assistants, you can use either Oracle Digital Assistant's native language support or you can use a 3rd-party translation service. However, in each skill and digital assistant, you can only use one of those approaches. A skill can only be added to a digital assistant if it uses the same translation approach as the digital assistant
You will probably want to use the native support for languages if all of the languages that you are targeting are on the list of natively-supported languages. By using the native language support:
You can build the skills' and digital assistant's training model with data from all of your target languages. (When you use the translation service approach, you can only provide training data for the predominant language.)
You avoid paying a 3rd-party service for translation charges.
You don't need to give a 3rd-party service access to your skill's training data or text from the user conversations.
Use a translation service if you want to support any languages that are not supported natively.
Native Language Support in Digital Assistants 🔗
Starting with Platform Version 20.12, you can develop digital assistants with native language support. For such digital assistants, you don't need to use a 3rd-party translation service to handle user input and skill responses in those languages.
A digital assistant with native language support must contain skills with native language support. To learn about developing such skills, see Native Language Support for Skills.
Set Up a Digital Assistant in Native Language Mode 🔗
Here are the initial steps for setting up a digital assistant in Natively-Supported language mode:
Click to open the side menu, select Development > Digital Assistants, and click New Digital Assistant.
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.
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.
If you need to add any additional languages to the digital assistant:
In the left navigation of the newly created digital assistant, click .
Click Add Language and select the language you want to add.
Complete and In-Progress Languages 🔗
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 ().
Note
It's also possible to add skills that are configured for a language that the digital assistant isn't configured for. These languages are not reflected on the digital assistant's Settings page.
Switch from a Translation Service to Native Language Support 🔗
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:
For all of the skills in the digital assistant, create versions that use the native language support.
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.)
Create a new version or clone of the digital assistant.
Click to open the side menu and select Development > Digital Assistants.
In the tile for the digital assistant that you want to version or clone, click and select Version or Clone.
Fill in the required fields and click Create.
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.
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.
Add the native-language support versions of the skills to the digital assistant.
Language Detection in Digital Assistants with Natively-Supported Languages 🔗
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.
Digital Assistants with Translation Services 🔗
Set Up a Non-English Single-Language Digital Assistant in Translation Service Mode 🔗
Here are the initial steps for setting up a non-English single-language digital assistant in Translation Service language mode:
Click to open the side menu, select Development > Digital Assistants, and click New Digital Assistant.
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.
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.
Set Up a Multi-Language Digital Assistant in Translation Service Mode 🔗
Here are the initial steps for setting up a multi-language digital assistant in Translation Service language mode:
Click to open the side menu, select Development > Digital Assistants, and click New Digital Assistant.
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.
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.
Add a Translation Service to a Digital Assistant 🔗
If you haven't done so already, configure a translation service for your Digital Assistant instance by:
Clicking to open the side menu and selecting Settings > Translation Service.
Clicking + Service.
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.
Set the translation service in your digital assistant by:
Clicking to open the side menu, selecting Development > Digital Assistants, and selecting your digital assistant.
In the digital assistant's left navbar, clicking the Settings() icon and selecting the General tab.
Navigating to the Translation Service dropdown and selecting your translation service.
Enable Language Detection in Translation-Enabled Digital Assistants 🔗
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.
This ensures that the skill will honor the value of the
profile.LanguageTag variable that is set by the digital assistant.
To prevent this switch back to English in a YAML-based skill, you need to
add the following property to the System.DetectLanguage component in each
skill:
useExistingProfileLanguageTag: true
Here's an example of a YAML-based skill's System.DetectLanguage
component with the useExistingProfileLanguageTag set:
You can use that property in 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 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.
Explicit Invocation in Translated Digital Assistants 🔗
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.
Conditions for Adding a Skill to a Digital Assistant 🔗
When you try to add a skill to a digital assistant, you are only offered skills that are compatible with the digital assistant. Here are the compatibility rules:
The skill and the digital assistant must both support its target languages in the same way (either natively or through a translation service).
For digital assistants that are created in Natively-Supported Language Mode, the skill needs to support all of the languages that are supported in the digital assistant.
If the skill supports more languages, the digital assistant will ignore those languages.
If the skill is published and supports only a subset of the digital assistant's languages, it can't be added.
If the skill is in draft mode, it can be added, even if it only supports a subset of the digital assistant's languages. However, you need to add any missing languages to the skill before you publish it.
Note
If you upgrade a digital assistant (whether through cloning, versioning, or rebasing) and change its language mode, the skills in the digital assistant will be disabled. To get those skills to work, you can replace them with versions that are configured with the same language mode of the digital assistant.
Resource Bundles for Digital Assistants 🔗
When you want to control the wording for your digital assistant’s responses in multiple languages, 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 resource bundle keys for any of those fields that don't already have them and provide values for the default language.
For each key, enter translated 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:
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.
Create and Edit Resource Bundle Keys 🔗
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.
To create and populate resource bundle keys for a digital assistant:
In the digital assistant's left navbar, click .
Click Add Bundle.
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.
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.
Optionally, fill in the Annotation field to help other developers understand what the string is for and where it is used.
Click Create Entry.
To add an additional language version of the string, click Add Language.
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.
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.
In the left navigation for the digital assistant, click
Select a skill.
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}
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.
Repeat the previous step for the skill's other example utterances.
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
variable and message key. For example: ${rb('WhatType')}. You can also
use dot notation, e.g.: ${rb.WhatType}
In the digital assistant's left navbar, click the Settings () icon and select the Configurations tab.
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')}
Note
Starting with Release 21.04, these resource bundle keys are generated automatically and the conversation parameters are set to reference these bundle keys.
System Variables in Resource Bundles 🔗
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:
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}.
Then, in the value of the property, enter the reference to the bundle key in the following format:
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 .
Resource Bundle Entries for Digital Assistant Configuration Settings 🔗
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.
No match found in {0}. Do you still want to switch to it?
The prompt to display when interrupting a flow to go to a different skill but that skill doesn't have a matching flow. This might happen when a user interrupts a flow with input that contains an explicit invocation, but with a phrase that doesn't match an intent in the invoked skill.
systemConfiguration_conversationNoMatchPrompt
No matches were found. Here are some things you can do:
The prompt to display (before the help card) when no matches were found.
The message to display before the start of a flow.
systemConfiguration_conversationStartPrompt
Do you want to start with {0} in {1} now?
The prompt to display before the start of a flow.
systemConfiguration_errorExpiredSessionPrompt
Your session has expired. Please start again.
The message when the session has expired.
systemConfiguration_errorMaxStatesExceededPrompt
Your session appears to be in an infinite loop.
The message when the bot appears to be in an infinite loop.
systemConfiguration_errorUnexpectedErrorPrompt
Oops I'm encountering a spot of trouble. Please try again later...
The message when there is an unexpected error.
systemConfiguration_internalWelcomeMessage
help
The internal message sent to the digital assistant when a channel handles the event that a new user has gotten access to the digital assistant. The reply to the internal message is sent as welcome message to the new user.
systemConfiguration_oauthCancelPrompt
Authentication canceled.
The message when OAuth authorization is canceled.
systemConfiguration_oauthSuccessPrompt
Authentication successful! You can return to the conversation.
The message when OAuth authorization succeeds.
Sample Resource Bundle Entries 🔗
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.