Translation Services in Skills
For skills that target languages other than English and which don't use Digital Assistant's native language support, you need to configure a translation service.
For such skills, when a user enters a non-English request or response, the skill uses the translation service to convert this input to English. Once it’s translated, the Natural Language Processing (NLP) engine can resolve it to an intent and match the entities. The skill can then respond to the user by using the translation service to translate the labels and prompts or by referencing language-specific strings in resource bundles.
For skills that have a training corpus in a non-English language, the translation service is also used at design time. When you train such a non-English skill, it creates English versions of the example utterances and custom entity values to be used in the training model (though these translations are not shown in the skill designer).
If you intend to add a skill that is based on a translation service to a digital assistant, that digital assistant must also use a translation service.
Translation Services Supported
OCI Language
Oracle Cloud Infrastructure (OCI) provides its own translation service called Language. If you use this service as your translation service in Oracle Digital Assistant, user messages are not exposed to a third-party translation service.
To use OCI Language as a translation service, you need to subscribe to the service and create permissions for Digital Assistant to access it. See Policies for OCI Language.
Google Translation API
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.
Microsoft Translator
If you want to use Microsoft Translator as your translation service in Oracle Digital Assistant, you need to subscribe to Translator or the Cognitive Services multi-service and get a secret key. See https://docs.microsoft.com/en-gb/azure/cognitive-services/translator/reference/v3-0-reference.
These are the main things you need to know:
- You need to use the Global region and its corresponding URL (
https://api.cognitive.microsofttranslator.com/
). - You need to obtain a secret key for authentication. You can get it from the Keys and Endpoints section of the Azure Portal.
Register a Translation Service in Oracle Digital Assistant
-
Click to open the side menu and select Settings > Translation Service.
-
Click + Service.
-
In the Translation Services dialog, enter the URL and authorization key (for the Microsoft Translator service) or authorization token (for the Google Translation API) .
- URL
- Authorization key (for the Microsoft Translator service) or authorization token (for the Google Translation API) .
Add a Translation Service to Your Skill
- If you haven't done so already, register a translation service in Oracle Digital Assistant.
- Click to open the side menu, select Development > Skills, and select your skill.
- In the skill's left navbar, click the Settings() icon and select the General tab.
- Navigate to the Translation Service dropdown and select your translation service.
Approaches Based on Translation Services
When you use a translation service to support skills that converse in non-English languages, you can use one of these development approaches:
-
Create non-English single-language skills where you:
- Prepare the training corpus in the target language of the skill.
When you develop non-English single-language digital assistants, you populate them with such single-language skills (where all of the skills in a given digital assistant have the same predominant language).
-
Create multi-language skills where you:
- Prepare the training corpus in English.
- Configure the skill's dialog flow to manage the translation of the user input and the skill's responses.
- Optionally (but preferably), create resource bundles for one or more languages for the skill's labels, prompts, and messages. This is desirable because it allows you to control the wording of the skill's responses.
In both cases, Digital Assistant uses the translation service to translate user input to the base language. For responses, it uses resource bundles (if provided in the skill) or the translation service to translate the skill's response back to the user's language.
Non-English Single-Language Skill Using a Translation Service
To develop a skill for a single non-English language that relies on a translation service, you:
-
If you haven't already done so, add a translation service to your skill.
- Create the utterances for your skill in the target language of the skill (instead of in English):
- Click to open the side menu, select Development > Skills, and open your skill.
- In the left navigation for the skill, click
- Select an intent.
- In the Examples text field, type the utterance and press Enter.
- Repeat the previous two sub-steps for each intent.
-
For any custom entities in your skill, make sure the values are in the skill's primary language.
You can add and edit custom entities by clicking in the left navigation of the skill.
If you don't provide custom entity values in the skill's primary language, the skill won't be able to properly process user input that contains any values that need to be matched by a custom entity.
- In the skill, update all of the configuration messages and prompts to use the
primary language:
To access these messages and prompts:
- In the left navigation for the skill, click .
The messages and prompts are located on the Configuration and Digital Assistant tabs.
-
You can’t translate the names of the built-in entities.
-
When you set up your skill this way, the language processing framework detects non-English input and then translates it into English (the language of the training model) behind the scenes. After evaluating the input, it determines the appropriate response and translates it back to the target language.
This can impact translation costs because it requires more calls to the translation service than a skill where the training corpus is already in the English.
Multi-Language Skills with Auto-Translation
For skills that use a translation service, you can enable the skill to automatically detect the user’s language and communicate in that language.
To set this up, you need to update the dialog flow to:
- Detect the user's language.
- Translate the user input so that it can be resolved.
Translation for Skills in Visual Dialog Mode
For multi-language skills designed in Visual dialog mode, here are the steps for setting up translation:
- If you haven't already done so, add a translation service to your skill.
- At the beginning of the flow that you intend to be the starting point of the skill, insert a Detect Language component.
- In the Main Flow, add the Start Skill built-in event and map it to the flow that contains the Detect Language component.
- On the skill's Settings page, select the
Configuration tab and set the Translate User
Input Message and Translate Bot Response
Message properties.
- Set Translate User Input Message to true to translate user input.
- If you are not using resource bundles for the target languages, set Translate Bot Response Message to true.
Translation for Skills in YAML Dialog Mode
For skills designed in YAML dialog mode, you can determine what to have translated
component by component by using either or both the autotranslate
context variable and the component-level translate
property.
- The
autotranslate
context variable applies globally to the whole skill. If you don't specifyautotranslate
, it's value isfalse
. - The
translate
property can be set individually for each component. When thetranslate
property is set for a component, it overrides theautotranslate
value for that component.
For both autotranslate
and translate
, you can set the value as a single Boolean or you can specify separate Boolean values for input and output.
Examples: autotranslate
Context Variable
Here's an example of using autotranslate
to turn on automatic translation for both input and output:
setAutoTranslate:
component: "System.SetVariable"
properties:
variable: "autoTranslate"
value: true
And here's how you could use autotranslate
to translate input by default, but not output:
setAutoTranslate:
component: "System.SetVariable"
properties:
variable: "autoTranslate"
value:
input: true
output: false
You don't have to specify
autotranslation
values that are false. For example, in the previous snippet, you don't need to include the line:
output: false
Examples: translate
Property
Here's an example of setting the translate
property to send both the component's input and output to the translation service that has been specified for the skill:
askName:
component: "System.Text"
properties:
prompt: "${rb.askNamePrompt}"
variable: "name"
translate: true
And here's an example of sending only the component's input to the translation service:
askName:
component: "System.Text"
properties:
prompt: "${rb.askNamePrompt}"
variable: "name"
translate:
input: true
output: false
Opt-In Translation
For skills designed in YAML dialog mode, here are the steps if you want to individually specify which components to translate:
- If you haven't already done so, add a translation service to your skill.
- Make sure that the
autoTranslate
context variable is not set (or set tofalse
). - Above the state for the
System.Intent
component, add the System.DetectLanguage component:detect: component: "System.DetectLanguage" properties: useExistingProfileLanguageTag: true transitions: ...
Note
TheuseExistingProfileLanguageTag
property is used when a skill is part of a digital assistant that has a translation service. This enables the skill to use the language that is detected by the digital assistant immediately. Otherwise, the skill might provide a message or prompt in English before the language is (re-)detected. If the skill is not in a translation-enabled digital assistant, the property is ignored. - In the System.Intent component, set the translate property to
true
.intent: component: "System.Intent" properties: variable: "iResult" translate: true
- For other input components, also set the translate property property to
true
, or set theinput
attribute of thetranslate
property totrue
, e.g.:askName: component: "System.Text" properties: prompt: "${rb.askNamePrompt}" variable: "name" translate: input: true output: false
Example: Multi-Language Skill with Auto-Translation (Opt-In)
metadata:
platformVersion: "1.0"
main: true
name: "AutoTranslatePizzaJoe"
parameters:
age: 18
context:
variables:
size: "PizzaSize"
type: "PizzaType"
crust: "PizzaCrust"
iResult: "nlpresult"
states:
detect:
component: "System.DetectLanguage"
properties:
useExistingProfileLanguageTag: true
transitions:
next: "intent"
intent:
component: "System.Intent"
properties:
variable: "iResult"
translate: true
ShowMenu:
component: "System.CommonResponse"
properties:
processUserMessage: true
translate:
input: true
output: false
metadata:
responseItems:
- type: "text"
text: "Hello ${profile.firstName}, this is our menu today:"
...
...
Opt-Out Translation
For skills designed in YAML dialog mode, here are the steps for using auto-translation by default (and individually specify components to not translate) :
- If you haven't already done so, add a translation service to your skill.
- Add
autoTranslate: "map"
as a variable to thecontext
node.context: variables: ... autoTranslate: "map"
- Within the
states
node, above yourSystem.Intent
component, add aSystem.SetVariable
component. Then set thevariable
property to use theautoTranslate
context variable and set theinput
(and, optionally,output
) attribute of thevalue
property totrue
.setAutoTranslate: component: "System.SetVariable" properties: variable: "autoTranslate" value: input: true output: true transitions: ...
Note
If you are using resource bundles, you'd set theoutput
value tofalse
. - For the next state, add the System.DetectLanguage
component:
detect: component: "System.DetectLanguage" properties: useExistingProfileLanguageTag: true transitions: ...
Note
TheuseExistingProfileLanguageTag
property is used when a skill is part of a digital assistant that has a translation service. This enables the skill to use the language that is detected by the digital assistant immediately. Otherwise, the skill might provide a message or prompt in English before the language is (re-)detected. If the skill is not in a translation-enabled digital assistant, the property is ignored. - For any components that you don't want auto-translated, see the translate property to
false
, e.g.:done: component: "System.Output" properties: text: "${rb('OnTheWay','${size.value}','${type.value}')}" translate: input: true output: false transitions: return: "done"
Example: Multi-Language Skill with Auto-Translation for Input (Opt-Out)
In this example, auto-translation is set up for input, but it is off for output (so that output text can be specified in resource bundles).
metadata:
platformVersion: "1.0"
main: true
name: "AutoTranslatePizzaJoe"
parameters:
age: 18
context:
variables:
size: "PizzaSize"
type: "PizzaType"
crust: "PizzaCrust"
iResult: "nlpresult"
autoTranslate: "map"
states:
setAutoTranslate:
component: "System.SetVariable"
properties:
variable: "autoTranslate"
value:
input: true
output: false
transitions:
next: "detect:
detect:
component: "System.DetectLanguage"
properties:
useExistingProfileLanguageTag: true
transitions:
...
Manipulate Input Before Translation
If you want to be able to manipulate input text before sending it to the translation service, you can use the Translate Input (Visual dialog mode) or System.TranslateInput (YAML dialog mode) component. For example, you might want to process user input to remove some personal data before sending it to the translation service.
sourceString
variable holds the
text to be translated. (This text, for example, may have been gathered by another component.)
After the System.TranslateInput
completes its processing, the English
translation is stored in the translatedString
variable.context:
variables:
autoTranslate: "boolean"
translatedString: "string"
sourceString: "string"
...
states:
...
translateInputString:
component: "System.TranslateInput"
properties:
source: "sourceString"
variable: "translatedString"
transitions:
...
Predominant Language
For skills that you set up to use Platform Version 20.09 or earlier and which have been configured with a translation service, Oracle Digital Assistant automatically assigns a predominant language for that skill, based on the language of the skill's example utterances.
You can find what predominant language has been assigned for a skill by clicking the Settings() icon in the skill's left navbar, selecting the General tab, and checking the value of the Predominant Language property.
For such skills, make sure that all of your intent example utterances, entities, and dialog response text are in the predominant language.
If you are designing the skill to support multiple languages, the predominant language must be English.
For digital assistants that are based on Platform Version 20.09 or earlier, the predominant language is determined by the predominant language of the first skill that you add to the digital assistant. Any other skills that you add to the digital assistant must have the same predominant language.
If the first skill that you add has no predominant language (because no translation service has been specified in the skill), the digital assistant's predominant language is set to English. In this case, you can either add skills that have English as the predominant language (or which have no predominant language set).
For skills and digital assistants that are based on Platform Version 20.12 or higher, a predominant language is not set. Instead, you specify the primary language when you create the skill or digital assistant.