microsoft · tracyboehrer · Nov 11, 2019 · Nov 8, 2019 · Nov 11, 2019 · Nov 11, 2019
diff --git a/samples/17.multilingual-bot/README.md b/samples/17.multilingual-bot/README.md
@@ -0,0 +1,58 @@
+# Multilingual Bot
+
+Bot Framework v4 multilingual bot sample
+
+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/).
+
+## Concepts introduced in this sample
+
+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.
+
+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.
+
+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.
+
+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.
+The API uses the most modern neural machine translation technology, as well as offering statistical machine translation technology.
+
+## Running the sample
+- Clone the repository
+```bash
+git clone https://github.com/Microsoft/botbuilder-python.git
+```
+- Activate your desired virtual environment
+- Bring up a terminal, navigate to `botbuilder-python\samples\17.multilingual-bot` folder
+- In the terminal, type `pip install -r requirements.txt`
+
+- 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.
+
+- In the terminal, type `python app.py`
+
+## Testing the bot using Bot Framework Emulator
+[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.
+
+- Install the Bot Framework emulator from [here](https://github.com/Microsoft/BotFramework-Emulator/releases)
+
+### Connect to bot using Bot Framework Emulator
+- Launch Bot Framework Emulator
+- File -> Open Bot
+- Paste this URL in the emulator window - http://localhost:3978/api/messages
+
+
+### Creating a custom middleware
+
+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.
+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.
+
+### Microsoft Translator Text API
+
+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.
+The API uses the most modern neural machine translation technology, as well as offering statistical machine translation technology.
+
+# Further reading
+
+- [Bot Framework Documentation](https://docs.botframework.com)
+- [Bot Basics](https://docs.microsoft.com/azure/bot-service/bot-builder-basics?view=azure-bot-service-4.0)
+- [Bot State](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-storage-concept?view=azure-bot-service-4.0)
+- [Activity processing](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-concept-activity-processing?view=azure-bot-service-4.0)
+- [Channels and Bot Connector Service](https://docs.microsoft.com/en-us/azure/bot-service/bot-concepts?view=azure-bot-service-4.0)
diff --git a/samples/17.multilingual-bot/app.py b/samples/17.multilingual-bot/app.py
@@ -0,0 +1,101 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+import asyncio
+import sys
+from datetime import datetime
+from types import MethodType
+
+from flask import Flask, request, Response
+from botbuilder.core import (
+    BotFrameworkAdapter,
+    BotFrameworkAdapterSettings,
+    MemoryStorage,
+    TurnContext,
+    UserState,
+)
+from botbuilder.schema import Activity, ActivityTypes
+
+from bots import MultiLingualBot
+
+# Create the loop and Flask app
+from translation import TranslationMiddleware, MicrosoftTranslator
+
+LOOP = asyncio.get_event_loop()
+app = Flask(__name__, instance_relative_config=True)
+app.config.from_object("config.DefaultConfig")
+
+# Create adapter.
+# See https://aka.ms/about-bot-adapter to learn more about how bots work.
+SETTINGS = BotFrameworkAdapterSettings(app.config["APP_ID"], app.config["APP_PASSWORD"])
+ADAPTER = BotFrameworkAdapter(SETTINGS)
+
+
+# Catch-all for errors.
+async def on_error(context: TurnContext, error: Exception):
+    # This check writes out errors to console log .vs. app insights.
+    # NOTE: In production environment, you should consider logging this to Azure
+    #       application insights.
+    print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr)
+
+    # Send a message to the user
+    await context.send_activity("The bot encountered an error or bug.")
+    await context.send_activity("To continue to run this bot, please fix the bot source code.")
+    # Send a trace activity if we're talking to the Bot Framework Emulator
+    if context.activity.channel_id == 'emulator':
+        # Create a trace activity that contains the error object
+        trace_activity = Activity(
+            label="TurnError",
+            name="on_turn_error Trace",
+            timestamp=datetime.utcnow(),
+            type=ActivityTypes.trace,
+            value=f"{error}",
+            value_type="https://www.botframework.com/schemas/error"
+        )
+        # Send a trace activity, which will be displayed in Bot Framework Emulator
+        await context.send_activity(trace_activity)
+
+ADAPTER.on_turn_error = on_error
+
+# Create MemoryStorage and state
+MEMORY = MemoryStorage()
+USER_STATE = UserState(MEMORY)
+
+# Create translation middleware and add to adapter
+TRANSLATOR = MicrosoftTranslator(app.config["SUBSCRIPTION_KEY"], app.config["SUBSCRIPTION_REGION"])
+TRANSLATION_MIDDLEWARE = TranslationMiddleware(TRANSLATOR, USER_STATE)
+ADAPTER.use(TRANSLATION_MIDDLEWARE)
+
+# Create Bot
+BOT = MultiLingualBot(USER_STATE)
+
+
+# Listen for incoming requests on /api/messages.
+@app.route("/api/messages", methods=["POST"])
+def messages():
+    # Main bot message handler.
+    if "application/json" in request.headers["Content-Type"]:
+        body = request.json
+    else:
+        return Response(status=415)
+
+    activity = Activity().deserialize(body)
+    auth_header = (
+        request.headers["Authorization"] if "Authorization" in request.headers else ""
+    )
+
+    try:
+        task = LOOP.create_task(
+            ADAPTER.process_activity(activity, auth_header, BOT.on_turn)
+        )
+        LOOP.run_until_complete(task)
+        return Response(status=201)
+    except Exception as exception:
+        raise exception
+
+
+if __name__ == "__main__":
+    try:
+        app.run(debug=False, port=app.config["PORT"])  # nosec debug
+    except Exception as exception:
+        raise exception
diff --git a/samples/17.multilingual-bot/bots/__init__.py b/samples/17.multilingual-bot/bots/__init__.py
@@ -0,0 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .multilingual_bot import MultiLingualBot
+
+__all__ = ["MultiLingualBot"]
diff --git a/samples/17.multilingual-bot/bots/multilingual_bot.py b/samples/17.multilingual-bot/bots/multilingual_bot.py
@@ -0,0 +1,105 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+import json
+import os
+
+from botbuilder.core import ActivityHandler, TurnContext, UserState, CardFactory, MessageFactory
+from botbuilder.schema import ChannelAccount, Attachment, SuggestedActions, CardAction, ActionTypes
+
+from translation.translation_settings import TranslationSettings
+
+"""
+This bot demonstrates how to use Microsoft Translator.
+More information can be found at:
+https://docs.microsoft.com/en-us/azure/cognitive-services/translator/translator-info-overview"
+"""
+
+
+class MultiLingualBot(ActivityHandler):
+    def __init__(self, user_state: UserState):
+        if user_state is None:
+            raise TypeError(
+                "[MultiLingualBot]: Missing parameter. user_state is required but None was given"
+            )
+
+        self.user_state = user_state
+
+        self.language_preference_accessor = self.user_state.create_property("LanguagePreference")
+
+    async def on_members_added_activity(
+            self, members_added: [ChannelAccount], turn_context: TurnContext
+    ):
+        # Greet anyone that was not the target (recipient) of this message.
+        # To learn more about Adaptive Cards, see https://aka.ms/msbot-adaptivecards for more details.
+        for member in members_added:
+            if member.id != turn_context.activity.recipient.id:
+                await turn_context.send_activity(
+                    MessageFactory.attachment(self._create_adaptive_card_attachment())
+                )
+                await turn_context.send_activity(
+                    "This bot will introduce you to translation middleware. Say \'hi\' to get started."
+                )
+
+    async def on_message_activity(self, turn_context: TurnContext):
+        if self._is_language_change_requested(turn_context.activity.text):
+            # If the user requested a language change through the suggested actions with values "es" or "en",
+            # simply change the user's language preference in the user state.
+            # The translation middleware will catch this setting and translate both ways to the user's
+            # selected language.
+            # If Spanish was selected by the user, the reply below will actually be shown in Spanish to the user.
+            current_language = turn_context.activity.text.lower()
+            if current_language == TranslationSettings.english_english.value \
+                    or current_language == TranslationSettings.spanish_english.value:
+                lang = TranslationSettings.english_english.value
+            else:
+                lang = TranslationSettings.english_spanish.value
+
+            await self.language_preference_accessor.set(turn_context, lang)
+
+            await turn_context.send_activity(f"Your current language code is: {lang}")
+
+            # Save the user profile updates into the user state.
+            await self.user_state.save_changes(turn_context)
+        else:
+            # Show the user the possible options for language. If the user chooses a different language
+            # than the default, then the translation middleware will pick it up from the user state and
+            # translate messages both ways, i.e. user to bot and bot to user.
+            reply = MessageFactory.text("Choose your language:")
+            reply.suggested_actions = SuggestedActions(
+                actions=[
+                    CardAction(
+                        title="Español",
+                        type=ActionTypes.post_back,
+                        value=TranslationSettings.english_spanish.value
+                    ),
+                    CardAction(
+                        title="English",
+                        type=ActionTypes.post_back,
+                        value=TranslationSettings.english_english.value
+                    )
+                ]
+            )
+
+            await turn_context.send_activity(reply)
+
+    def _create_adaptive_card_attachment(self) -> Attachment:
+        """
+        Load attachment from file.
+        :return:
+        """
+        card_path = os.path.join(os.getcwd(), "cards/welcomeCard.json")
+        with open(card_path, "rt") as in_file:
+            card_data = json.load(in_file)
+
+        return CardFactory.adaptive_card(card_data)
+
+    def _is_language_change_requested(self, utterance: str) -> bool:
+        if not utterance:
+            return False
+
+        utterance = utterance.lower()
+        return (utterance == TranslationSettings.english_spanish.value
+                or utterance == TranslationSettings.english_english.value
+                or utterance == TranslationSettings.spanish_spanish.value
+                or utterance == TranslationSettings.spanish_english.value)
diff --git a/samples/17.multilingual-bot/cards/welcomeCard.json b/samples/17.multilingual-bot/cards/welcomeCard.json
@@ -0,0 +1,46 @@
+{
+  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
+  "type": "AdaptiveCard",
+  "version": "1.0",
+  "body": [
+    {
+      "type": "Image",
+      "url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQtB3AwMUeNoq4gUBGe6Ocj8kyh3bXa9ZbV7u1fVKQoyKFHdkqU",
+      "size": "stretch"
+    },
+    {
+      "type": "TextBlock",
+      "spacing": "medium",
+      "size": "default",
+      "weight": "bolder",
+      "text": "Welcome to Bot Framework!",
+      "wrap": true,
+      "maxLines": 0
+    },
+    {
+      "type": "TextBlock",
+      "size": "default",
+      "isSubtle": "true",
+      "text": "Now that you have successfully run your bot, follow the links in this Adaptive Card to expand your knowledge of Bot Framework.",
+      "wrap": true,
+      "maxLines": 0
+    }
+  ],
+  "actions": [
+    {
+      "type": "Action.OpenUrl",
+      "title": "Get an overview",
+      "url": "https://docs.microsoft.com/en-us/azure/bot-service/?view=azure-bot-service-4.0"
+    },
+    {
+      "type": "Action.OpenUrl",
+      "title": "Ask a question",
+      "url": "https://stackoverflow.com/questions/tagged/botframework"
+    },
+    {
+      "type": "Action.OpenUrl",
+      "title": "Learn how to deploy",
+      "url": "https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-howto-deploy-azure?view=azure-bot-service-4.0"
+    }
+  ]
+}
diff --git a/samples/17.multilingual-bot/config.py b/samples/17.multilingual-bot/config.py
@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+import os
+
+""" Bot Configuration """
+
+
+class DefaultConfig:
+    """ Bot Configuration """
+
+    PORT = 3978
+    APP_ID = os.environ.get("MicrosoftAppId", "")
+    APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
+    SUBSCRIPTION_KEY = os.environ.get("SubscriptionKey", "")
+    SUBSCRIPTION_REGION = os.environ.get("SubscriptionRegion", "")