1. Using Oracle Digital Assistant
  2. Skills
  3. Languages and Skills
  4. Native Language Support for Skills

Native Language Support for Skills

Starting with Platform Version 20.12, there is native support in Oracle Digital Assistant for some languages. When you develop a skill with this native language support, you don't need to use a 3rd-party translation service to handle user input and skill responses in those languages.

If you are developing such skills for inclusion in a digital assistant, that digital assistant must also use the native language support. See Native Language Support in Digital Assistants.

How Native Language Support Works

  • Training data can be supplied in each of the (natively-supported) languages that you are designing the skill for.

    When you use native language support, the skill is trained according to a unified model that incorporates all of the natively-supported languages. You can provide training utterances in one or more of your skill's target languages. The training utterances that you provide in one language help build the model for all of the skill's languages. For skills that you target to multiple languges, typically you will start by building your training corpus in the skill's primary language. Then you can (and should) add training utterances in the other languages, though you probably won't need nearly as many in those other languages.

    This differs from skills that use a translation service. In those skills, the underlying training model is always in English, even if the training corpus is provided in another language.

  • Entity values for built-in entity types (such as NUMBER, EMAIL, and DATE) are extracted in the language of the conversation. (This differs from the case with skills in translation service mode, where the values are extracted after the input has been translated by the translation service.
  • Entity values for custom entities are matched to the values provided for the language of the current conversation.
  • Skills that support non-English languages must be trained with Trainer TM.

Natively-Supported Languages

Here are the languages (and the corresponding languages codes) that are currently supported natively in Oracle Digital Assistant.

  • Arabic (ar)
  • Dutch (nl)
  • English (en)
  • French (fr)
  • German (de)
  • Italian (it)
  • Portuguese (pt)
  • Spanish (es)

This means that you can create skills and digital assistants for these languages without using a translation service, such as Google Translate.

Here's an overview of the level of support for each language.

Language Language Understanding Voice Insights Data Manufacturing Conversation Designer
Arabic (ar) Yes No Yes Yes No
Dutch (nl) Yes No Yes Yes No
English (en) Yes Yes, including the en-US, en-GB, and en-AU locales) Yes Yes Yes
French (fr) Yes Yes Yes Yes No
German (de) Yes Yes Yes Yes No
Italian (it) Yes Yes Yes Yes No
Portuguese (pt) Yes Yes Yes Yes No
Spanish (es) Yes Yes Yes Yes No

For a more detailed comparison of the support for each language, see Feature Support by Language.

Create a Skill with Natively-Supported Languages

Here are the general steps for creating a skill that uses Oracle Digital Assistant's native language support.

  1. When creating the skill, select Platform Version 20.12 or higher and select the primary language that you want to support from the Primary Language dropdown.

    The language you select must be within the Natively-Supported section of the dropdown.

  2. For each intent that you create, add utterances for your skill in the primary language:
    1. Click icon to open the side menu to open the side menu, select Development > Skills, and open your skill.
    2. In the left navigation for the skill, click This is an image of the Intent icon.
    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.

  3. 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 An image of the Entities icon in the left navigation of the skill.

  4. For any components in your dialog flow that have properties that display prompts or labels, make sure that you explicitly define those properties. If you don't define these properties, customers may encounter default text from those properties, which are in English.
  5. In the skill's settings, 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 Settings icon.

    The messages and prompts are located on the Configuration and Digital Assistant tabs.

Note:

If you're planning to support multiple languages in the skill, you will need to define resource bundle keys for the properties, prompts, and messages that may be displayed to users. And, even if you don't plan to support multiple languages, you may want to do this anyway, since the resource bundle provides a single place where you can edit the values of all of your strings. See Resource Bundles for Skills.

Add Natively-Supported Languages to a Skill

For skills (or versions of skills) where you have chosen a natively-supported primary language, you can add additional natively-supported languages.

  1. Make sure your skill is running on Platform Version 20.12 or higher.

    If it isn't, you need to create a clone or a new version of the skill and set it to use Platform Version 20.12 or higher.

  2. In the skill's left navbar, click the Settings(the Settings icon) icon and select the General tab.
  3. Scroll down to the languages section, click Add Language and select the language from the dropdown.
  4. For each of the intents in the skill, add a conversation name and additional utterances in the added language:
    1. Click Intents (This is an image of the Intent icon.) in the left navbar.
    2. Select the intent to edit.
    3. Select the tab for the language that you just added.
    4. Click This is an image of the Edit icon to enter a descriptive name or phrase for the intent in the Conversation Name field.
  5. For any entities that are based on key-value pairs (value list entities and dynamic entities), enter values for that language.
  6. Enable the skill to display entity values in the language of the conversation:
    1. In components that you use to resolve entities (Resolve Entity and Common Response), make sure that the useFullEntityMatches property is set to true.

      By doing this, you ensure that custom entity values are stored as JSON objects instead of as simple strings.

    2. In all of your FreeMarker expressions that reference custom entity values (whether in the dialog flow or in various skill properties), insert the attribute corresponding to the value you want to read. You can use any of the following attributes:
      • value - returns the value of the entity in the conversation of the language.
      • primaryLanguageValue - returns the value of the entity in the primary language of the skill. You would use this option for expressions that are used for business logic (e.g. to determine whether or not to display a prompt, based on the entity value).
      • originalString - returns the value that the user entered to match the entity. This value could be a synonym of the entity value.

      For example, if you have the expression ${PizzaSize} for referencing the value of the PizzaSize entity, you would change it to ${PizzaSize.value} to display the value in the language of the conversation.

  7. If you haven't already done so, create resource bundle keys for all of the output that users will see, enter values for the primary language, and insert references to those keys in the appropriate places. This includes:
    • Output text in the dialog flow.
    • Prompts for entities that are included in the entity definitions.
    • Messages and prompts defined in the skill's settings. To access them:
      • In the left navigation for the skill, click the Settings icon.

      The messages and prompts are located on the Configuration and Digital Assistant tabs.

    See Resource Bundles for Skills.
  8. For any components in your dialog flow that have properties that display prompts or labels, make sure that you have explicitly defined those properties (so that they don't default to English values) and create resource bundle entries for them.
  9. Add values in the additional language for all of the resource bundle keys.
  10. Augment the training corpus as necessary in the additional language.

    Since skills with natively-supported languages are based on a unified training model in which all of the training helps with intent resolution in all of the skill's target languages, the training model should already work for your additional language, even without adding utterances in that language. But its accuracy will be probably be lower than it is for the primary language. To improve the accuracy, do the following:

    • Build batch tests in the additional language and run them to determine how well the model performs without any utterances in the additional language. See Create Test Runs.
    • Iteratively add training utterances in that language and test until you get a satisfactory level of intent resolution.
      1. Click Intents (This is an image of the Intent icon.) in the left navbar.
      2. Select the intent to edit.
      3. Select the tab for the language that you just added.
      4. In the Examples section, enter example utterances in the additional language.

      You probably won't need to add as many utterances in those additional target languages as you did in the primary language.

Note:

See the Design Camp video on Multilingual NLU to learn about best practices when making your skills multilingual.

Switch from a Translation Service to Native Language Support

If you want to take advantage of Oracle Digital Assistant native language support in a skill that has been configured to use a translation service, you can create a new version or clone of that skill and enable that support.

Prerequisite:

  • The skill that you are converting must only use languages that are supported natively in the version of the platform that you are converting to. For that list, see Natively-Supported Languages.

If that prerequisite isn't met, you'll need to continue using a translation service for all of the non-English languages in the skill.

To convert a skill to use Digital Assistant's native language support:

  1. Create the new version or clone, and specify the primary language for the skill.

    1. Click icon to open the side menu to open the side menu and select Development > Skills.

    2. In the tile for the skill that you want to version or clone, click icon to open the Options menu and select Version or Clone.

    3. In the Platform Version field, select version 20.12 or later.

      If it wasn't present before, a Primary Language field will appear.

    4. In the Primary Language dropdown, select the language from the Natively Supported section of the dropdown that best corresponds to the predominant language of the previous version of the skill.

      Note:

      The platform version and primary language can't be changed after you click Create.
    5. Click Create.
  2. Add any additional languages that you want to support.
  3. Adjust your dialog flow to stop using the following mechanisms related to sending text to a translation service:
    1. Any translation components ( Detect Language, Translate Input, and Translate Output.
    2. (For YAML-based flows) the autotranslate context variable.
    3. (For YAML-based flows) the component-level translate property.

Training Corpus for an Additional Language

When you add a language, here's how the various parts of the skill are handled:

  • Intents—The intent names, whatever their language, remain the same for each language. For each intent, you can add example utterances in each language. Since the model for natively-supported skills is unified, any utterances that you add for a given language can also help the model for other languages. Nevertheless, you can strengthen your model by adding utterances for each language.

    In particular, you should concentrate on adding phrases that express an intent in a languages that are not direct translations of the phrase in the primary language.

  • Entities—For entities that are based on key-value pairs (value list entities and dynamic entities), you define the values in the primary language and then, for each additional language, add values that correspond to the primary language's values.

    For prompts and messages that are defined in the entities (including prompts that are defined in composite bag entities), you reference resource bundle keys, where you provide the appropriate text in each target language.

    For other properties, such as Enumeration Range Size, the values apply for all languages.

    Note:

    The Fuzzy Match property is disabled for skills where it is not supported for all of the languages.

Language Detection in Skills with Natively-Supported Languages

In skills that use multiple natively-supported languages, the digital assistant (or standalone skill) 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 skill or digital assistant, language detection is turned off.
    • If the digital assistant or skill uses a translation service, the translation service handles the language detection, not the skill or digital assistant.
  • The language is not automatically detected if the skill or 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.