article by Frank Nimphius, May 2020
Oracle Digital Assistant skills provide resource bundles as a feature for skill developers to build multi language bot responses, or just for them to keep label and prompts in a single place for ease of administration and management. Custom components that are uploaded to a skill don't have access to resource bundle, which also has to do with how custom components communicate with a skill. The options skill developers have at current to provide translatable label strings and prompts in a custom component are
- to create a custom message bundle functionality for custom components. This way custom components get deployed with their message translations and all a skill developer needs to do is to pass the detected or desired language code for the component to pick the correct language strings
- pass resources bundle strings to be used as labels and prompts from a skill to a custom component, for which developers create input parameters.
The first option, to create a custom message bundle functionality in a custom component, is a less popular choice among skill developers. Instead the intention is to find a way to pass resource bundle strings for a specific language into the custom component.
In this article I explain a strategy to pass resource bundle strings into a custom component without creating a strong dependency between the skill and the custom component. The implementation introduced in this article also allows developers to pass translations of a language string that matches a detected user language.
———
Note: All resources (skills and custom component) can be downloaded at the end of the following article: TechExchange: How-to allow customers to provide feedback on the usefulness of answers to frequently asked questions
——–
Resource Bundles
Resource bundles in Oracle Digital Assistant are created and managed in the individual skills (image below)
To use resource bundles in a conversation, you need to create a dialog flow variable (context variable) of type nlpresult.
To access a resource string, you then use the resourcebundle variable name along with the key name defined in the resource bundle. This can be done as follows
- ${rb.key_name} or ${rb('key_name')} – for resource strings that don't expect parameter values
- ${rb('key_name','param_value_1','param_value_2', …)} – for resource strings that expect parameter values
The language in which a resource bundle string is read by the above expressions depends on
- Availability of a translation for a specific language (otherwise the default language strings will be used)
- The language setting, which is through the locale setting, or – if the language is auto detected using a translation services – the profile.languageTag variable
Labels And Prompts in Custom Components
Custom components use the conversation.reply() function to return messages to the user. Using the conversation.MessagModel() function, the responses can be complex in that they may render as lists, card carousels, buttons, attachments etc. If using the MessageModel class, each UI response is represented by a sub-function, which in its signature allows you to define the strings for labels and prompts. The string can be provided static or read from a variable you define in the custom component.
Using a variable to hold the label or prompt string is important for using resource bundle strings in a custom component. The code below reads message strings from an object that gets passed as an input parameter to the custom component.
The messagePromptsAndLabels constant gets its value from an input parameter of the custom component.
The value it receives is an object that contains attributes matching key names used in the custom component (for ease of use the variable names shown in the previous image also are named after the key names). Note that the key names are defined in the custom component, which means they need to be communicated to the skill developer so the developer passes a correct object (this is subject of the next section in this article). There is no need that the resource bundle key name in the skill matches the names used in the custom component as you will see later.
As you can see in the previous image that defines the variables, each variable has a default string set. This way the custom component always has a string set even if the object passed from the skill misses a key. In a next step, the custom component tries to assign the label or prompt passed from the skill (through the messagePromptsAndLabels object)
Dialog Flow
With the resource bundle and the custom component created, all you need to do is to pass resource bundle strings from the skill to the custom component. In the dialog flow, you use a System.SetVariable component to create an object that contains attribute / value pairs in which the attribute name matches a key name used in the custom component. The names used in the custom component is what the component developer needs to communicate to the skill developer.
Note: You can also create an input parameter on the custom component for each prompts or label. For small, less complex components this will work well. For complex components it could be seen as an overkill, in which case the strategy explained in this article is a better fit.
As you can see in the image above, the feedbackComponentMessages variable gets populated with attributes and values using the System.SetVariable component and Apache Freemarker expressions. The attribute names match the key names used in the custom component. The values reference a resource bundle string using the resourcebundle variable reference as well as the key name defined in the resource bundle. As mentioned before, the key name in the resource bundle does not need to match the name of the key in the custom component.
The feedbackComponentMessages variable is then referenced in the custom component configuration as follows
If the user language gets set or detected before the feedbackComponentMessages variable gets populated with resource bundle strings, then the language strings will be the translated versions you created for a key name. This way you can pass resource bundle strings easily to a custom component without creating a string binding between the skill and the component. The component remains reusable.
Related content
TechExchange: How-to allow customers to provide feedback on the usefulness of answers to frequently asked questions (article contains the skill and custom component used in this article)
TechExchange: All 2-Minutes Oracle Digital Assistant Tech Tip Videos on YouTube
