Bot Builder includes a rich localization system for building bots that can communicate with the user in multiple languages. All of your bots prompts can be localized using JSON files stored in your bots directory structure and if you’re using a system like LUIS to perform natural language processing you can configure your LuisRecognizer with a separate model for each language your bot supports and the SDK will automatically select the model matching the users preferred locale.
The first step to localizing your bot for the user is adding the ability to identify the users preferred language. The SDK provides a session.preferredLocale() method to both save and retrieve this preference on a per user basis. Below is short example dialog to prompt the user for their preferred language and then persist their choice:
Another option is to install a piece of middleware that uses a service like Microsofts Text Analytics API to automatically detect the users language based upon the text of the message they sent:
session.preferredLocale() will automatically return the detected language if a user selected locale hasn’t been assigned. The exact search order for
- Locale saved by calling
session.preferredLocale(). This value is stored in
- Detected locale assigned to
- Bots configured default locale.
- English (‘en’).
You can configure the bots default locale during construction:
The default localization system for Bot Builder is file based and lets a bot support multiple languages using JSON files stored on disk. By default, the localization system will search for the bots prompts in the
./locale/<IETF TAG>/index.json file where
<IETF TAG> is a valid IETF language tag representing the preferred locale to use the prompts for. Below is a screenshot of the directory structure for a bot that supports three languages, English, Italian, and Spanish:
The structure of the file is straight forward. It’s a simple JSON map of message ID’s to localized text strings. If the value is an
array instead of a
string a prompt will be chosen at random anytime that value is retrieved using session.localizer.gettext(). Returning the localized version of a message generally happens automatically by simply passing the message ID in a call to session.send() instead of language specific text:
Internally, the SDK will call
session.preferredLocale() to get the users preferred locale and will then use that in a call to
session.localizer.gettext() to map the message ID to its localized text string. There are times where you may need to manually call the localizer. For instance, the enum values passed to Prompts.choice() are never automatically localized so you may need to manually retrieve a localized list prior to calling the prompt:
The default localizer will search for a message ID across multiple files and if it can’t find an ID (or if no localization files were provided) it will simply return the text of ID, making the use of localization files transparent and optional. Files are searched in teh following order:
- First the
index.jsonfile under the locale returned by
session.preferredLocale()will be searched.
- Next, if the locale included and optional subtag like
en-USthen the root tag of
enwill be searched.
- Finally, the bots configured default locale will be searched.
The default localizer supports the namespacing of prompts to avoid collisions between message ID’s. Name spaced prompts can also be overridden by the bot to essentially let a bot customize or re-skin the prompts from another namespace. Today, you can leverage this capability to customize the SDK’s built-in messages, letting you either add support for additional languages or to simply re-word the SDK’s current messages. For instance, you can change the SDK’s default error message by simply adding a file called
BotBuilder.json to your bots locale directory and then adding an entry for the
default_error message ID: