Language Labeling and Compliance

To ensure that your bot adheres to accessibility standards, it is crucial that all text is marked with the correct language.
This is important for users of screen readers and other assistive technologies as it aids in the correct pronunciation and understanding of the content.

Context Language

The most important aspect of language compliance is ensuring that the language is set in context.
This can be done in several ways, such as during messenger initialization, in a flow using a setContext node, or dynamically detecting the user’s language in flow.

This context language is important for several reasons:

  • It ensures that the bot’s messages are labeled with the chosen language
  • It helps in retrieving the correct content from the CMS, which is often language-specific
  • It provides a consistent user experience for users who may rely on screen readers or other assistive technologies

Without setting the language, the messenger defaults to the browser’s language, which has implications when using CMS.
If hardcoding a language in context is not feasible, please see the section on dynamic languages for guidance.

Language in Context on Messenger Init

One of the simplest ways to set the language for your bot is to include the lang property in the context init parameter when initializing the Messenger:

// Setting language when launching the Messenger
const sbConfig = {
    organization: "Your Organization",
    endpoint: "Endpoint Address",
    sbRegion: "Your Region",
    version: "2",
    context: {
      lang: "fr" // Set the language to French
    },
};
sbMessenger = ServisBot.init(sbConfig);

If the lang property is not set in the context, the Messenger will default to the browser’s language. In this case, we recommend using a function node to determine whether the language is supported by the bot and, if not, to set it to a default supported language. See the section on dynamic languages for examples.

Changing Language in Flow

In flows, the language can be changed by updating the lang property in the context object.
Once this is done, all subsequent messages will be sent with the new language label.

Example using the setContext node:

Setting language to Spanish using the setContext node

Dynamic Languages

In some cases, a bot has the capability to speak in multiple languages - when lang is not set in context for a new conversation, the Messenger attempts to detect the user’s browser language automatically. This has one major drawback when using CMS as shown in the example below:

  1. Through CMS, the bot has text content support for: English, French, Spanish, and German.
  2. The user’s browser language is set to Italian.
  3. The bot is unable to retrieve any content for Italian, as it does not exist in the CMS.
  4. The CMS falls back to English.
  5. The bot sends a message with English text, but the lang attribute is set to Italian. ⚠️

To address this, we recommend one of the following approaches:

Detect Language in Flow

User language detection and validation can be implemented in a flow using the function node. In this example:

  1. The bot starts without a lang property in context.
  2. The function node checks the browser’s language and validates it against a list of supported languages.
  3. If the language is supported, it sets the lang property in context
  4. If the language is not supported, it falls back to a default language.
  5. The function node’s output is passed to a setContext node, applying the language change.
  6. From this point on, all messages include the determined language.

Detect Language Flow

Function Node

Detect Language Flow Function Node

const fallbackLang = 'en';
const supportedLangs = ['en', 'es', 'de', 'fr-FR'];
const contextLang = msg.payload.context.lang;

try {
    let newLang;
    if (supportedLangs.includes(contextLang)) { // Is the context language supported?
        newLang = contextLang;
    } else {
        newLang = fallbackLang;
    }
    msg.validatedLang = newLang;
    return msg;
} catch (err) {
    msg.validatedLang = fallbackLang;
    return msg;
}
Set Context Node

Detect Language Flow Set Context Node

Setting a Language for Messages

Whenever a message includes multilingual content, or otherwise differs from the main language of the bot, it must be labeled accordingly.

Using the lang attribute in Timeline Markup

Similarly to regular HTML, you can use the lang attribute in Timeline Markup to specify the language of the content. This is particularly useful for:

  • A text message in a different language than the bot’s main language
  • Messages that contain elements of varying languages

Message in a Different Language

Message with Multiple Languages

When a message contains multiple languages, you can set the lang attribute on the parent component, and it will be inherited by child components unless overridden.

The result is a number of lang attributes in the resulting HTML:

<!-- Simplified example -->
<ul lang="en">
  <li role="button" lang="en">English</li>
  <li role="button" lang="fr">Français</li>
  <li role="button" lang="es">Español</li>
  <li role="button" lang="de">Deutsch</li>
</ul>

Also note that the lang attribute is inherited by child components, so it is not necessary to set it everywhere - only where it differs from the parent.

<!-- The `en` lang from List is picked up by the Items and overridden only by Item 3 -->
<TimelineMessage>
  <List type="disc" selectable="true" title="Please choose an option" lang="en">
    <Item id="1" title="FAQ" />
    <Item id="2" title="Account information" />
    <Item id="3" title="Français" lang="fr-FR" />
  </List>
</TimelineMessage>

EdgeTier

For EdgeTier conversations, the context language at the time of live chat start is passed to the agent, setting their language picker to the same language. Messages sent by the agent use lang attribute to indicate the language of the message, which can change for subsequent messages if the agent switches their language.