For skills that you target to the languages that Oracle Digital Assistant supports natively, you can add training data for all of the target languages. This includes example utterances for intents and custom entity values.

Prerequisites:

• The languages you are targeting all are on the list of Natively-Supported Languages.
• The Platform Version of the skill is 20.12 or higher.

General steps:

• When creating the version (or clone) of the skill, designate one of the natively-supported languages as the primary language. This language will serve as the default language in the skill. Once you have set it, you can not change it.
• On the skill's Settings, Intents, or Entities page, add any additional natively-supported languages that you want to target.
• Build the training corpus in the primary language.
• For each additional language, augment the training corpus as necessary.
• For any value list entities that you create in the primary language, add values in the additional language that correspond to each of the values in the primary language.
• Create resource bundles for each of the skill's output strings, provide entries for each language, and reference the resource bundle keys from the appropriate places in the dialog flow and the skill's settings.

Other notes and considerations:

• In terms of user experience, this approach gives you the best opportunity to satisfy user expectations in multiple languages.
• To realize the potential of this approach, be sure to allocate adequate resources for multi-language intent training and formulating effective output messages in all of the target languages.

If you want to create a skill with one or more non-English languages but don't want to use a 3rd-party translation service, you can use Digital Assistant's native language support. See the above Ability to Train in Multiple Languages topic.

Typically, if the language you are targeting for a skill is supported natively in Oracle Digital Assistant, you would use that native language support for the skill. However, if that language is not supported natively, you can use a translation service.

Prerequisite:

• You have configured a translation service (either Microsoft Translator or the Google Translation API).

General steps:

• When creating the skill, designate the target language as the primary language (and in translation mode).
• Create intent utterances and entity values in the language that you are supporting.
• Add code to the dialog flow to detect the language of the user input and to translate it behind the scenes. (For non-English skills that rely on a translation service, the underlying training model of the skill is in English.)
• Create resource bundles for the skill responses.

Other notes and considerations:

• If the target language of your skill is among the natively-supported languages, consider using the native language approach. Then, if you later need to add other languages that are natively supported, you will be able to optimize intent resolution for each language (in addition to having more control over the output messages).
• If you later want to add other languages to the skill and one or more of the desired languages isn't supported natively, you would need to create a new skill from scratch and set English as the primary language in the new skill.
• Entity values for built-in entity types (such as NUMBER, EMAIL, and DATE) are extracted after the user input has been translated to English behind the scenes.

If you are designing a skill that targets multiple languages and one or more those languages are not supported natively, you can use a translation service for the skill.

Prerequisite:

• You have configured a translation service (either Microsoft Translator or the Google Translation API).

General steps:

• When creating the skill, designate English as the primary language (and in translation mode).
• Create intent utterances and entity values in English.
• Add code to the dialog flow to detect the language of the user input and to translate it behind the scenes.
• To handle skill responses, either:
  • Set up the dialog flow to translate skill responses from English to the user's language.
  • Create resource bundles with entries for each target language and configure the skill to use them in its responses.

Other notes and considerations:

• Entity values for built-in entity types (such as NUMBER, EMAIL, and DATE) are extracted after the user input has been translated to English behind the scenes.

If you'd like to create a multi-language skill but do not want to create resource bundle entries for the various languages, you can use the translation service to handle the skill's responses. (This approach does not work with Digital Assistant's native language support.)

Prerequisite:

• You have configured a translation service (either Microsoft Translator or the Google Translation API).

General steps:

• When creating the skill, designate English as the primary language (and in translation mode).
• Add code to the dialog flow to detect the language of the user input and to translate it behind the scenes.
• Set up the dialog flow to translate skill responses to the user's language.

Other notes and considerations:

• If all of the target languages of your skill are all among the natively-supported languages, consider using the native language approach instead, since this will enable you to optimize intent resolution for each language (in addition to having more control over the output messages).
• Even if you need to target languages that are not natively supported, you may find that the benefits of having greater control of the output messages justifies the costs.

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

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.

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

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

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 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 messages and prompts are located on the Configuration and Digital Assistant tabs.

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() 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 () in the left navbar.
   2. Select the intent to edit.
   3. Select the tab for the language that you just added.
   4. Click 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 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 () 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.

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 to open the side menu and select Development > Skills.

   2. In the tile for the skill that you want to version or clone, click 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.

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.

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.

1. Click to open the side menu and select Settings > Translation Service.

2. Click + Service.

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

1. If you haven't done so already, register a translation service in Oracle Digital Assistant.
2. Click to open the side menu, select Development > Skills, and select your skill.
3. In the skill's left navbar, click the Settings() icon and select the General tab.
4. Navigate to the Translation Service dropdown and select your translation service.

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.

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.

context:
  variables:
    autoTranslate: "boolean" 
    translatedString: "string"
    sourceString: "string"    
   ...
states:
   ...
  translateInputString:
    component: "System.TranslateInput"
    properties:
      source: "sourceString"
      variable: "translatedString"
    transitions:
      ...

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

A skill's user-facing strings come from several parts of the skill. In some cases, a resource bundle key is automatically created for you. In other cases, no key is generated, but you can define one yourself.

Here are the places from where user-facing strings originate and how you can manage them in the resource bundle.

• The Conversation Name field for intents.

  When you set conversation names, resource bundle keys are created automatically and populated with the value that you have set for the default language. You can access the bundle keys for conversation names by clicking and selecting the Intents tab.

• The Answer field for intents (answer intents).

  When you set answers in intents, resource bundle keys are created automatically and populated with the answer text in the default language. You can access the bundle keys for answers by clicking and selecting the Q&A tab.

• The skill's configuration settings (which you access by clicking and selecting the Configuration tab).

  For these settings, resource bundle keys are generated with default values and the setting values are expressed as references to the resource bundle keys. You can edit the values of these keys by clicking and selecting the Configuration tab.

• Default prompts, labels, and messages that are built into standard dialog flow components.

  If you want to change the default value of any of these properties, you can do so within the resource bundle by clicking and selecting the Configuration tab.

  You don't need to add the property to the component in the dialog flow definition to reference the updated value in the resource bundle.

  If you want to change the value of one of those properties for a component in a particular state without changing the default, you add the property to the component in that state.

• Dialog flow strings. For text that you incorporate into your components, you can define your own resource bundle keys and then reference those keys from the dialog flow definition.

  You can create and edit these keys by clicking and selecting the User-Defined tab.

• Prompts and messages from entity definitions. For these strings, you can define your own resource bundle keys and then reference those keys from the fields for these properties in the entity definition.

  You can create and edit keys for these strings by clicking and selecting the User-Defined tab.

Resource bundle keys are used to identify output text that needs to be translated and provide values in one or more languages. Keys are automatically defined for the intent conversation names, the responses for answer intents, and some common properties. However, you need to create keys yourself for other output text that you want to translate, such as text from your dialog flow.

To create resource bundle entries:

1. In the skill's left navbar, click .

2. Click the User-Defined tab.

3. Click Add Bundle.

   The Create Entry dialog appears, which enables you to create your first entry in the skill's primary language.

4. Enter the a key (which you use to reference the bundle entry) and its corresponding text. For example, for the user prompt How old are you?, you might enter HowOld in the Key field and then How old are you? in the Text field.

5. For Annotation, enter any information that will be useful for those that may need to reference the entry later, such as translators.

6. Click Create Entry.

When you create a bundle key, its initial Text value is for the skill's default (i.e. primary or predominant language).

To add text for a bundle key in another language:

1. Select the key and then click Add Language.

2. Complete the Create Entry dialog:

   • Language—Enter or select an IETF BCP 47 language tag like fr for French or de for German.

   • Text—The output string. For example, for a French translation (fr) of the HowOld key, you’d add a string like quel âge avez-vous ?

At some points within a conversation, such as when the skill is trying to determine what flow the user wants to follow, the skill may present a dialog that refers to one more intents. In these cases, the skill refers to the intents by their conversation names, for which keys and default entries are generated in the resource bundle.

To provide a translation for a conversation name:

1. Click Resource Bundle in the left navbar ().

2. Click the Intents tab on the Resource Bundles page.

   
   
   
   
   
   

3. Select the intent

4. Click Add Language.

5. Complete the Create Entry dialog:

   • Language—Add an IETF BCP 47 language tag like fr for French, de for German, or en-US for U.S. English.

   • Text—The output string. For example, for a French translation (fr) of the HowOld key, you’d add a string like quel âge avez-vous ?

Note

If the intent for which you want to change the conversation name doesn't appear in the list, click to go back to the Intents page, select the intent, and edit its Conversation Name field. When you return the Resource Bundles page, it should then appear under the Intents tab.

When you create an answer intent, a resource bundle key is automatically created for the answer.

To provide a translation for an answer in an answer intent:

1. Click Resource Bundle in the left navbar ().

2. Click the Q&A tab on the Resource Bundles page.

3. Select the key for the answer that you want to translate.

4. Click Add Language.

5. Complete the Create Entry dialog:

   • Language—Add an IETF BCP 47 language tag like fr for French, de for German, or en-US for U.S. English.

   • Text—The output string.

To set the output for a built-in component, you reference the message key through the variable rb (which is reserved for resource bundles).

Here is a simple expression that references a bundle key called WhatType to return a simple string:

${rb('WhatType')}

Here is an expression that uses dynamic values. It references a bundle key called OnTheWay where size.value and type.value are the arguments for the OnTheWay key.

${rb('OnTheWay','${size.value}','${type.value}')}

You can also create bundle entries with more complex message formats to handle plurals and other cases. See the following topics to learn about the range of message formats and how to reference them in your dialog flow.

There are several formats that you can use for your resource bundle messages to handle everything from returning static messages to assembling messages depending on multiple variables.

Here are the general steps for setting up a skill to use a translation service only for user input while using resource bundles for the skill's responses:

1. If you haven't already done so, add a translation service to your skill.
2. Use the Detect Language component to determine the language of the user's input.
3. Apply resource bundles to handle the skill's responses to the user.
4. For any components that reference resource bundles, make sure that the output is not translated automatically.
   • For skills developed in Visual dialog mode, set the Translate Bot Response Message property on the skill's Settings page to False.
   • For skills developed in YAML dialog mode, you can handle this globally in the skill by setting the autoTranslate context variable to translate input and not translate output. For example:

       setAutoTranslate:
         component: "System.SetVariable"   
         properties:
           variable: "autoTranslate"     
           value:
            input: true
            output: false

  askName:
    component: "System.Text"
    properties:   
      prompt: "${rb.askNamePrompt}"
      variable: "name"
      translate:       
        input: true
        output: false

The resource bundle that gets applied depends on the value stored for the two location-specific user profile variables, profile.languageTag and profile.locale. If both variables are set, profile.languageTag takes precedence.

When resolving which language to use, Oracle Digital Assistant first searches for an exact match. If it doesn't find one, it incrementally broadens its search until it succeeds. If it still can't find a match, it returns the default language, which is English (en).

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 .

Just as you can use resource bundles for messages in built-in components, answer intents, etc., you can use resource bundles for your custom components as well. To do so, you:

1. Define resource bundle entries in the skill for your message. See Create Resource Bundle Keys.
2. Using the Bots Node SDK's context.translate() method, reference the resource bundle keys from the custom component code.

   The context.translate() takes a specified resource bundle key name (and any parameters specified in the resource bundle entry) and generates the appropriate FreeMarker template required to load the named resource bundle language string when the conversation is sent back to the user via the context.reply() method.

3. Use the context.reply helper method to print the translated response. For example:

   context.reply(translate('date.message', dateToday, dayOfWeek ));

4. Document all of the resource bundle keys that the custom component references as well as the expected default strings. (Since the custom component directly references the resource bundle key within the skill, there needs to be a high degree of coordination between the developer of the custom component and those building out the skill to ensure that the referenced keys are valid within the skill).

In this example, date.message is a resource bundle key, dateToday and dayOfWeek are variables, and a FreeMarker expression like the following is returned:

${rb('date.message', 'Monday', 'July 12, 2021')}

You can use a system component to assemble messages using resource bundle entries and data that has been returned from a custom component. You define the base message strings in resource bundle entries. The bundle entries might include parameters for data (such as numbers and dates) that are output from the custom component. Since the base message strings are defined in the dialog flow, this approach ensures that custom components are not dependent on specific implementation code and remain reusable.

Here are the general steps:

1. For the custom component, include a required input parameter for the name of the context variable to store the returned data in.
2. Since the custom component developer and dialog flow developer may not be the same person or even on the same team, carefully document what data the custom component returns in that variable and make the information available to any custom component consumers so that they understand how to present the returned data to the user in a message.
3. In the dialog flow, create a context variable to store the custom component's returned data and pass its name in the required input parameter.
4. Define resource bundle entries in the skill for your message. See Create Resource Bundle Keys.
5. In the dialog flow, reference the resource bundle entry and fill in any required parameters.

The following sample from a skill developed in YAML dialog mode references a custom component in the initializeReceipt state and passes the name of the context variable (receipt) that holds the component response and purchaseId as input parameters. The printProduct state then incorporates the receipt value as a parameter in a reference to the resource bundle entry named receiptMessage.

  initializeReceipt:
    component: "sample.receipt.dataresponse"
    properties:
      dataVariable: "receipt"
      purchaseId: "${purchaseId.value}"
 ...
  printProduct:
    component: "System.CommonResponse"
    properties:
      keepTurn: true
      metadata:
        responseItems:        
        - type: "text" 
          text: "${rb('receiptMessage','${receipt.value}')}"

The custom code for accessing these input parameters might look something like the following code:

module.exports = {
  metadata: () => ({
    name: 'myComponent',   
    properties: {
       dataVariable: { required: true, type: 'string' },    
       purchaseId: { required: true, type: 'string' },
    },
...
    // Retrieve the value of the 'dataVariable' component property.
    const { dataVariable } = context.properties();
    if (!dataVariable) {
      context.transition();
      done(new Error('The state is missing the dataVariable property.'));
    }
...
    // Retrieve the value of the 'purchaseId' component property.
    const { purchaseId } = context.properties();
    if (!purchaseId) {
      context.transition();
      done(new Error('The state is missing the purchaseId property.'));
    }
...
    context.setVariable(dataVariable, data);      
    context.transition();
    done();
  }
}

If you don't have a way of knowing what the component's response text will be (e.g. if it is queried from a remote backend), you can use the skill's translation service to translate the responses. To do so:

1. Make sure the component is set up to have its output sent to the translation service by defining the translate property on the component and setting it to true.
2. In the custom component, use the context.reply helper method to return the response.

This approach only works with skills that are set up in the Translation Service language mode.

Custom components that query backend services might return data in a complex format like an object or an array of objects. If you are using a translation service, these data objects can't be sent to the translation service as is. Instead, you need to form a message that references any necessary attributes of the data object individually.

1. For the custom component, include a required input parameter for the name of the context variable to store the returned data in.
2. Since the custom component developer and dialog flow developer may not be the same person or even on the same team, carefully document what data the custom component returns in that variable and make the information available to any custom component consumers so that they understand how to present the returned data to the user in a message.
3. In the dialog flow, create a context variable to store the custom component's returned data and pass its name in the required input parameter.
4. Using the information in the context variable, assemble the response in a system component, like Common Response.
5. Make sure that the skill is configured for auto-translation.
   • For skills developed in Visual dialog mode, set the Translate Bot Response Message property on the skill's Settings page to true.
   • For skills developed in YAML dialog mode, you can handle this globally in the skill by setting the autoTranslate context variable. For example:

       setAutoTranslate:
         component: "System.SetVariable"   
         properties:
           variable: "autoTranslate"     
           value:
            input: true
            output: true

  printProduct:
    component: "System.CommonResponse"
    properties:
      keepTurn: true
      metadata:
        responseItems:        
        - type: "text" 
          text: "The product in your cart is a ${dialogVar.value.type}. It is
           ${dialogVar.value.product} from ${dialogVar.value.origin}"
      translate: true

The custom code for accessing this input parameter might look something like the following code:

module.exports = {
  metadata: () => ({
    name: 'myComponent',   
    properties: {
       dialogVar: { required: true, type: 'string' },    
    },
...
    // Retrieve the value of the 'dialogVar' component property.
    const { dialogVar } = context.properties();
    if (!dialogVar) {
      context.transition();
      done(new Error('The state is missing the dialogVar property.'));
    }
...
    context.setVariable(dialogVar, data);    
    context.transition();
    done();
  }
}

If the custom component needs the user's language to do things like provide correct date formats, you can provide it to the component in one of these ways:

• Access the profile.locale and profile.languageTag variables from the custom component code as shown in the following example:

  //detect user locale. If not set, define a default
  const locale = context.getVariable('profile.locale') ?
                 context.getVariable('profile.locale') : 'en-AU';
  //Make sure locale is returned with hyphen, not underscore. JavaScript requires a hyphen.
  const jsLocale = locale.replace('_','-'); 
  //when profile languageTag is set, use it. If not, use profile.locale
  const languageTag = context.getVariable('profile.languageTag')?
                      context.getVariable('profile.languageTag') : jslocale;

• Pass the values of profile.locale and/or profile.languageTag as input parameters to the component.