8000 Merge pull request #422 from microsoft/trboehre-17.multilingual-bot · rusty0209/botbuilder-python@4040105 · GitHub
[go: up one dir, main page]
Skip to content

Commit 4040105

Browse files
tracyboehrertracyboehrer
authored
Merge pull request microsoft#422 from microsoft/trboehre-17.multilingual-bot
Added 17.multilingual-bot
2 parents aafd297 + a7eb9f2 commit 4040105

File tree

12 files changed

+714
-0
lines changed

12 files changed

+714
-0
lines changed

‎samples/17.multilingual-bot/README.md

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Multilingual Bot
2+
3+
Bot Framework v4 multilingual bot sample
4+
5+
This bot has been created using [Bot Framework](https://dev.botframework.com), it shows how to translate incoming and outgoing text using a custom middleware and the [Microsoft Translator Text API](https://docs.microsoft.com/en-us/azure/cognitive-services/translator/).
6+
7+
## Concepts introduced in this sample
8+
9+
Translation Middleware: We create a translation middleware that can translate text from bot to user and from user to bot, allowing the creation of multi-lingual bots.
10+
11+
The middleware is driven by user state. This means that users can specify their language preference, and the middleware automatically will intercept messages back and forth and present them to the user in their preferred language.
12+
13+
Users can change their language preference anytime, and since this gets written to the user state, the middleware will read this state and instantly modify its behavior to honor the newly selected preferred language.
14+
15+
The [Microsoft Translator Text API](https://docs.microsoft.com/en-us/azure/cognitive-services/translator/), Microsoft Translator Text API is a cloud-based machine translation service. With this API you can translate text in near real-time from any app or service through a simple REST API call.
16+
The API uses the most modern neural machine translation technology, as well as offering statistical machine translation technology.
17+
18+
## Running the sample
19+
- Clone the repository
20+
```bash
21+
git clone https://github.com/Microsoft/botbuilder-python.git
22+
```
23+
- Activate your desired virtual environment
24+
- Bring up a terminal, navigate to `botbuilder-python\samples\17.multilingual-bot` folder
25+
- In the terminal, type `pip install -r requirements.txt`
26+
27+
- To consume the Microsoft Translator Text API, first obtain a key following the instructions in the [Microsoft Translator Text API documentation](https://docs.microsoft.com/en-us/azure/cognitive-services/translator/translator-text-how-to-signup). Paste the key in the `SUBSCRIPTION_KEY` and `SUBSCRIPTION_REGION` settings in the `config.py` file.
28+
29+
- In the terminal, type `python app.py`
30+
31+
## Testing the bot using Bot Framework Emulator
32+
[Microsoft Bot Framework Emulator](https://github.com/microsoft/botframework-emulator) is a desktop application that allows bot developers to test and debug their bots on localhost or running remotely through a tunnel.
33+
34+
- Install the Bot Framework emulator from [here](https://github.com/Microsoft/BotFramework-Emulator/releases)
35+
36+
### Connect to bot using Bot Framework Emulator
37+
- Launch Bot Framework Emulator
38+
- File -> Open Bot
39+
- Paste this URL in the emulator window - http://localhost:3978/api/messages
40+
41+
42+
### Creating a custom middleware
43+
44+
Translation Middleware: We create a translation middleware than can translate text from bot to user and from user to bot, allowing the creation of multilingual bots.
45+
Users can specify their language preference, which is stored in the user state. The translation middleware translates to and from the user's preferred language.
46+
47+
### Microsoft Translator Text API
48+
49+
The [Microsoft Translator Text API](https://docs.microsoft.com/en-us/azure/cognitive-services/translator/), Microsoft Translator Text API is a cloud-based machine translation service. With this API you can translate text in near real-time from any app or service through a simple REST API call.
50+
The API uses the most modern neural machine translation technology, as well as offering statistical machine translation technology.
51+
52+
# Further reading
53+
54+
- [Bot Framework Documentation](https://docs.botframework.com)
55+
- [Bot Basics](https://docs.microsoft.com/azure/bot-service/bot-builder-basics?view=azure-bot-service-4.0)
56+
- [Bot State](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-storage-concept?view=azure-bot-service-4.0)
57+
- [Activity processing](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-concept-activity-processing?view=azure-bot-service-4.0)
58+
- [Channels and Bot Connector Service](https://docs.microsoft.com/en-us/azure/bot-service/bot-concepts?view=azure-bot-service-4.0)

‎samples/17.multilingual-bot/app.py

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Copyright (c) Microsoft Corporation. All rights reserved.
2+
# Licensed under the MIT License.
3+
4+
import asyncio
5+
import sys
6+
from datetime import datetime
7+
from types import MethodType
8+
9+
from flask import Flask, request, Response
10+
from botbuilder.core import (
11+
BotFrameworkAdapter,
12+
BotFrameworkAdapterSettings,
13+
MemoryStorage,
14+
TurnContext,
15+
UserState,
16+
)
17+
from botbuilder.schema import Activity, ActivityTypes
18+
19+
from bots import MultiLingualBot
20+
21+
# Create the loop and Flask app
22+
from translation import TranslationMiddleware, MicrosoftTranslator
23+
24+
LOOP = asyncio.get_event_loop()
25+
app = Flask(__name__, instance_relative_config=True)
26+
app.config.from_object("config.DefaultConfig")
27+
28+
# Create adapter.
29+
# See https://aka.ms/about-bot-adapter to learn more about how bots work.
30+
SETTINGS = BotFrameworkAdapterSettings(app.config["APP_ID"], app.config["APP_PASSWORD"])
31+
ADAPTER = BotFrameworkAdapter(SETTINGS)
32+
33+
34+
# Catch-all for errors.
35+
async def on_error(context: TurnContext, error: Exception):
36+
# This check writes out errors to console log .vs. app insights.
37+
# NOTE: In production environment, you should consider logging this to Azure
38+
# application insights.
39+
print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr)
40+
41+
# Send a message to the user
42+
await context.send_activity("The bot encountered an error or bug.")
43+
await context.send_activity("To continue to run this bot, please fix the bot source code.")
44+
# Send a trace activity if we're talking to the Bot Framework Emulator
45+
if context.activity.channel_id == 'emulator':
46+
# Create a trace activity that contains the error object
47+
trace_activity = Activity(
48+
label="TurnError",
49+
name="on_turn_error Trace",
50+
timestamp=datetime.utcnow(),
51+
type=ActivityTypes.trace,
52+
value=f"{error}",
53+
value_type="https://www.botframework.com/schemas/error"
54+
)
55+
# Send a trace activity, which will be displayed in Bot Framework Emulator
56+
await context.send_activity(trace_activity)
57+
58+
ADAPTER.on_turn_error = on_error
59+
60+
# Create MemoryStorage and state
61+
MEMORY = MemoryStorage()
62+
USER_STATE = UserState(MEMORY)
63+
64+
# Create translation middleware and add to adapter
65+
TRANSLATOR = MicrosoftTranslator(app.config["SUBSCRIPTION_KEY"], app.config["SUBSCRIPTION_REGION"])
66+
TRANSLATION_MIDDLEWARE = TranslationMiddleware(TRANSLATOR, USER_STATE)
67+
ADAPTER.use(TRANSLATION_MIDDLEWARE)
68+
69+
# Create Bot
70+
BOT = MultiLingualBot(USER_STATE)
71+
72+
73+
# Listen for incoming requests on /api/messages.
74+
@app.route("/api/messages", methods=["POST"])
75+
def messages():
76+
# Main bot message handler.
77+
if "application/json" in request.headers["Content-Type"]:
78+
body = request.json
79+
else:
80+
return Response(status=415)
81+
82+
activity = Activity().deserialize(body)
83+
auth_header = (
84+
request.headers["Authorization"] if "Authorization" in request.headers else ""
85+
)
86+
87+
try:
88+
task = LOOP.create_task(
89+
ADAPTER.process_activity(activity, auth_header, BOT.on_turn)
90+
)
91+
LOOP.run_until_complete(task)
92+
return Response(status=201)
93+
except Exception as exception:
94+
raise exception
95+
96+
97+
if __name__ == "__main__":
98+
try:
99+
app.run(debug=False, port=app.config["PORT"]) # nosec debug
100+
except Exception as exception:
101+
raise exception

‎samples/17.multilingual-bot/bots/__init__.py

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Copyright (c) Microsoft Corporation. All rights reserved.
2+
# Licensed under the MIT License.
3+
4+
from .multilingual_bot import MultiLingualBot
5+
6+
__all__ = ["MultiLingualBot"]

‎samples/17.multilingual-bot/bots/multilingual_bot.py

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Copyright (c) Microsoft Corporation. All rights reserved.
2+
# Licensed under the MIT License.
3+
4+
import json
5+
import os
6+
7+
from botbuilder.core import ActivityHandler, TurnContext, UserState, CardFactory, MessageFactory
8+
from botbuilder.schema import ChannelAccount, Attachment, SuggestedActions, CardAction, ActionTypes
9+
10+
from translation.translation_settings import TranslationSettings
11+
12+
"""
13+
This bot demonstrates how to use Microsoft Translator.
14+
More information can be found at:
15+
https://docs.microsoft.com/en-us/azure/cognitive-services/translator/translator-info-overview"
16+
"""
17+
18+
19+
class MultiLingualBot(ActivityHandler):
20+
def __init__(self, user_state: UserState):
21+
if user_state is None:
22+
raise TypeError(
23+
"[MultiLingualBot]: Missing parameter. user_state is required but None was given"
24+
)
25+
26+
self.user_state = user_state
27+
28+
self.language_preference_accessor = self.user_state.create_property("LanguagePreference")
29+
30+
async def on_members_added_activity(
31+
self, members_added: [ChannelAccount], turn_context: TurnContext
32+
):
33+
# Greet anyone that was not the target (recipient) of this message.
34+
# To learn more about Adaptive Cards, see https://aka.ms/msbot-adaptivecards for more details.
35+
for member in members_added:
36+
if member.id != turn_context.activity.recipient.id:
37+
await turn_context.send_activity(
38+
MessageFactory.attachment(self._create_adaptive_card_attachment())
39+
)
40+
await turn_context.send_activity(
41+
"This bot will introduce you to translation middleware. Say \'hi\' to get started."
42+
)
43+
44+
async def on_message_activity(self, turn_context: TurnContext):
45+
if self._is_language_change_requested(turn_context.activity.text):
46+
# If the user requested a language change through the suggested actions with values "es" or "en",
47+
# simply change the user's language preference in the user state.
48+
# The translation middleware will catch this setting and translate both ways to the user's
49+
# selected language.
50+
# If Spanish was selected by the user, the reply below will actually be shown in Spanish to the user.
51+
current_language = turn_context.activity.text.lower()
52+
if current_language == TranslationSettings.english_english.value \
53+
or current_language == TranslationSettings.spanish_english.value:
54+
lang = TranslationSettings.english_english.value
55+
else:
56+
lang = TranslationSettings.english_spanish.value
57+
58+
await self.language_preference_accessor.set(turn_context, lang)
59+
60+
await turn_context.send_activity(f"Your current language code is: {lang}")
61+
62+
# Save the user profile updates into the user state.
63+
await self.user_state.save_changes(turn_context)
64+
else:
65+
# Show the user the possible options for language. If the user chooses a different language
66+
# than the default, then the translation middleware will pick it up from the user state and
67+
# translate messages both ways, i.e. user to bot and bot to user.
68+
reply = MessageFactory.text("Choose your language:")
69+
reply.suggested_actions = SuggestedActions(
70+
actions=[
71+
CardAction(
72+
title="Español",
73+
type=ActionTypes.post_back,
74+
value=TranslationSettings.english_spanish.value
75+
),
76+
CardAction(
77+
title="English",
78+
type=ActionTypes.post_back,
79+
value=TranslationSettings.english_english.value
80+
)
81+
]
82+
)
83+
84+
await turn_context.send_activity(reply)
85+
86+
def _create_adaptive_card_attachment(self) -> Attachment:
87+
"""
88+
Load attachment from file.
89+
:return:
90+
"""
91+
card_path = os.path.join(os.getcwd(), "cards/welcomeCard.json")
92+
with open(card_path, "rt") as in_file:
93+
card_data = json.load(in_file)
94+
95+
return CardFactory.adaptive_card(card_data)
96+
97+
def _is_language_change_requested(self, utterance: str) -> bool:
98+
if not utterance:
99+
return False
100+
101+
utterance = utterance.lower()
102+
return (utterance == TranslationSettings.english_spanish.value
103+
or utterance == TranslationSettings.english_english.value
104+
or utterance == TranslationSettings.spanish_spanish.value
105+
or utterance == TranslationSettings.spanish_english.value)

‎samples/17.multilingual-bot/cards/welcomeCard.json

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
{
2+
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
3+
"type": "AdaptiveCard",
4+
"version": "1.0",
5+
"body": [
6+
{
7+
"type": "Image",
8+
"url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQtB3AwMUeNoq4gUBGe6Ocj8kyh3bXa9ZbV7u1fVKQoyKFHdkqU",
9+
"size": "stretch"
10+
},
11+
{
12+
"type": "TextBlock",
13+
"spacing": "medium",
14+
"size": "default",
15+
"weight": "bolder",
16+
"text": "Welcome to Bot Framework!",
17+
"wrap": true,
18+
"maxLines": 0
19+
},
20+
{
21+
"type": "TextBlock",
22+
"size": "default",
23+
"isSubtle": "true",
24+
"text": "Now that you have successfully run your bot, follow the links in this Adaptive Card to expand your knowledge of Bot Framework.",
25+
"wrap": true,
26+
"maxLines": 0
27+
}
28+
],
29+
"actions": [
30+
{
31+
"type": "Action.OpenUrl",
32+
"title": "Get an overview",
33+
"url": "https://docs.microsoft.com/en-us/azure/bot-service/?view=azure-bot-service-4.0"
34+
},
35+
{
36+
"type": "Action.OpenUrl",
37+
"title": "Ask a question",
38+
"url": "https://stackoverflow.com/questions/tagged/botframework"
39+
},
40+
{
41+
"type": "Action.OpenUrl",
42+
"title": "Learn how to deploy",
43+
"url": "https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-howto-deploy-azure?view=azure-bot-service-4.0"
44+
}
45+
]
46+
}

‎samples/17.multilingual-bot/config.py

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
#!/usr/bin/env python3
2+
# Copyright (c) Microsoft Corporation. All rights reserved.
3+
# Licensed under the MIT License.
4+
5+
import os
6+
7+
""" Bot Configuration """
8+
9+
10+
class DefaultConfig:
11+
""" Bot Configuration """
12+
13+
PORT = 3978
14+
APP_ID = os.environ.get("MicrosoftAppId", "")
15+
APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
16+
SUBSCRIPTION_KEY = os.environ.get("SubscriptionKey", "")
17+
SUBSCRIPTION_REGION = os.environ.get("SubscriptionRegion", "")

0 commit comments

Comments
 (0)
0