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

Note

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) .
1. URL
2. 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):
1. Click to open the side menu, select Development > Skills, and open your skill.
2. In the left navigation for the skill, click
3. Select an intent.
4. In the Examples text field, type the utterance and press Enter.
5. 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.

There are a couple of other things to keep in mind:

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 specify autotranslate, it's value is false.
The translate property can be set individually for each component. When the translate property is set for a component, it overrides the autotranslate 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

Note

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 to false).
Above the state for the System.Intent component, add the System.DetectLanguage component:
```
  detect:
    component: "System.DetectLanguage"
    properties:
      useExistingProfileLanguageTag: true
    transitions:
      ...
```
Note

The useExistingProfileLanguageTag 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 the input attribute of the translate property to true, 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 the context node.
```
context:
  variables:
    ...
    autoTranslate: "map"
```
Within the states node, above your System.Intent component, add a System.SetVariable component. Then set the variable property to use the autoTranslate context variable and set the input (and, optionally, output) attribute of the value property to true.
```
  setAutoTranslate:
    component: "System.SetVariable"
    properties:
      variable: "autoTranslate"
      value:
        input: true
        output: true
    transitions:
      ...
```
Note

If you are using resource bundles, you'd set the output value to false.
For the next state, add the System.DetectLanguage component:
```
  detect:
    component: "System.DetectLanguage"
    properties:
      useExistingProfileLanguageTag: true
    transitions:
      ...
```
Note

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

In the following YAML snippet, the 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).

Note

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.

Oracle Cloud Infrastructure Documentation