1. Using Oracle Digital Assistant
  2. Digital Assistant Development Blueprint
  3. Additional Languages

9 Additional Languages

Here are some best practices for developing digital assistants to support multiple languages.

The requirement for digital assistants to support multiple languages is quite common and affects different areas of your digital assistant and skill development. Support for additional languages is an implementation task that goes beyond the translation of user and bot messages and that also needs to be considered in your conversation design to capture regional and cultural differences.


Description of second-language.png follows
Description of the illustration second-language.png

Language support is configured and implemented at the skill level. This includes the setting for the type of translation to be used and the configurations required for the type of translation. For skills exposed though a digital assistant, the digital assistant also needs to be configured to support multiple languages.

Translation Service vs. Multilingual NLU

Oracle Digital Assistant provides two options for supporting multiple languages in digital assistants.

  • The use of a translation service requires you to configure a translation service key from Google or Microsoft with your digital assistant instance. Incoming user messages are translated to the base language configured for a skill. The base language is the language you use to train the model, which for translation services most often is English. The benefit of using translation services at the moment is that it supports more languages than native language support does.

  • Native language support supports a smaller number of languages directly in the linguistic model (natural language understanding – NLU) without the need for a translation service. While the built-in language recognition is pretty good without any further language specific training, you can refine it by adding utterances for each language you want to support. For entities, you need to add translation strings for the values and synonyms in value-list entities.

The decision of which approach to use depends on the number of languages you need to support in your digital assistant project, the immediate need for each language, and whether or not the language exists as a natively supported language.

It is not possible to use skills using translation services with skills using NLU native support in the same digital assistant. Therefore, the decision as to which translation option to use should be made for all skills in a digital assistant when creating your first skill.

Our recommendation is to use native NLU language support if you can because of its better support for extraction of list entities and the ability to fine tune the understanding for additional languages by adding sample utterances for that language.

Both translation options support non-English language as a base language for training your intent models and building your skills.

Use Resource Bundles Everywhere

We recommend using resource bundle strings for all bot messages and prompts. Even if you use a translation service to support multiple languages in your bot, don't use translation services for outgoing messages: always use resource bundles and use them everywhere.

Why Resource Bundles

Digital assistant development is all about the persona you’ve designed for it. The persona defines the language, the tone of voice, and the attitude of a digital assistant.

To ensure that your digital assistant takes on the persona you designed, you need to stay in control of the bot's outgoing messages for each language you support. Resource bundles represent a single place where you manage bot messages, which makes it easy to ensure consistency in the tone of voice. For building digital assistants that support a second language, there is no realistic alternative to resource bundles for displaying bot messages.

About Resource Bundle Strings

Resource bundle strings are declaratively created in Oracle Digital Assistant skills and digital assistants. You reference them from conversations, in entities, and in skill configuration settings using Apache FreeMarker expressions. To reference a message string, you use an expression like the following:

${rb('message_key')}

rb references the resource bundle definition and looks for a message identifier with the specified name. In the sample above, it would look for a message key with the name message_key.

If a resource bundle key name does not exist for the user’s language, then the string defined for the default language (the base language) will be used. If a message string is missing for the default language, then an exception is thrown during runtime testing.

If you need to pass data to a message printed through a resource bundle, then you can do this through positional and named parameters.

Positional parameter: Hello {0}, {1}

Named parameter: Hello {name}, {greeting}

To pass values that you read from variables added to a conversation, you use an expression like the one shown below.

For positional parameters: ${rb('message_key',firstname.value, greetingMessage.value)}

For named parameters: ${rb('message_key','name,greeting',firstname.value, greetingMessage.value)}

Although positional parameters seem simpler to use, we recommend that you use named parameters when you can, because they provide the context for the type of data that is added to a message. Knowing the context makes a translator's life easier.

Consider a Naming Convention for Resource Bundle Key Names

Comprehensive use of resource bundles in your skill means referring to them from entities, the dialog flow, and from skill and digital assistant settings. To make resource bundles string references easier to find in your skill and digital assistant, we recommend adding context to the resource bundle key names by implementing a naming convention.

For example, you could use the following names for an error message, a disambiguation message, and prompts in a value list entity:

  • list.<entity_name>.errorMessage

  • list.<entity_name>.disambiguationMessage

  • list.<entity_name>.prompt1

  • list.<entity_name>.prompt2

For a composite bag entity, you could use a similar naming structure, but add the name of the bag item to it:

  • cbe.<entity_name>.<bag_item_name>.errorMessage

  • cbe.<entity_name>.<bag_item_name>.disambiguationMessage

  • cbe.<entity_name>.<bag_item_name>.prompt1

  • cbe.<entity_name>.<bag_item_name>.prompt2

If you reference a resource bundle string from the prompt of a dialog flow state, or if a dialog flow state just prints a user message you could use:

  • <dialog_flow_state_name>.prompt

  • <dialog_flow_state_name>.message

For global items, like pagination or help buttons on a Common Response component, you could use a naming convention that does not contain the name of a specific dialog flow state:

  • button.next

  • button.previous

  • button.cancel

  • button.help

There is no strict rule as to whether you use dot notation as in the examples above, underscores, or something of your own.

Use Resource Bundles for Keywords

The Common Response component allows you to define keywords for action items so the user can "virtually press" them by sending the keyword as a message. Keywords are especially important if the user interface does not allow the user to press a button (such as when using text-only channels or voice).

As a gentle but obvious reminder, "submit" is not called "submit" in German, Portuguese, French, Arabic and all the other languages you support with your bot. So it’s good to know that the keyword property of action items in the Common Response component can be read from a resource bundle key. The resource bundle message would be a comma-separated list of keywords you want to use.

Use the ICU Message Format

In addition to named parameters that you add to a resource bundle message, there are a number of other options that you can use to handle certain conditions when translating messages. For example, the message you print for multiple items is usually different from the message you print when a single item is ordered or shipped.

ICU, which stands for International Components for Unicode, is a language formatting syntax supported by message packets in Oracle Digital Assistant. This syntax allows you to write very flexible messages that make it easy to apply language-specific and regional differences to bot messages.

For starters, it may be sufficient to use the ICU message syntax for handling messages with singular and plural value references and for messages that change due to conditions such as the gender of the user working with the digital assistant.

Impact of Second Language Support on the Bot Persona

It is not necessary to change the digital assistant’s persona for a specific language. However, if regional or cultural differences require a change in the attitude, voice, or wording of the bot persona, it is legitimate to apply those changes. The goal of a digital assistant is to please and engage users, which also means it needs to adapt to regional habits.

You can use resource bundles in the ICU format to help with changing messages according to region. You can do so by passing an argument to the resource bundle to identify a region for which you need to adapt the bot persona, and use the ICU message format to display a message different from the one it would display otherwise.

Example: Handling Regional Differences in Messages

This resource bundle message example expects argument for region to be passed when referencing the resource bundle key name. In the example, the values to be handled differently are defined as region1 and region2. You can set those values however you want, e.g. to a country code. 

{region, select,
  region1 {message for region 1}
  region2 {message for region 2}
  other {message for all other regions}
}

To reference the message in the resource bundle for one of the regions, you would use the following expression in your dialog flow, entity or skill configuration:

${rb('the_key_name','region','<VARIABLE_CONTAINING_REGION_VALUE>.value')}

<VARIABLE_CONTAINING_REGION_VALUE> needs to be replaced by a variable name in your skill that holds the value for which you have a different message defined.

Checklist for Additional Languages

  • ☑ Decide between using translation services or native language support before building your skills.
  • ☑ Ensure all skills that you want to add to a digital assistant use the same language support type.
  • ☑ Use resource bundles for all prompts and messages displayed by your bot.
  • ☑ Use named parameters when passing dynamic data to a resource bundle message.
  • ☑ Use the ICU message format for plurals in messages and for messages that change based on a condition.
  • ☑ Use resource bundle references when creating keywords.
  • ☑ Use the Annotation field of the resource bundle string to provide the translator with additional information about the meaning and the use of a string and, optionally, how you want message to be translated.
  • ☑ Understand regional and cultural differences.

Learn More