Localize a bot

Localizing a bot for different languages, markets, and/or cultures is a common use case. This is accomplished in Teneo through branching, where we have the option of creating a 'Master' version of a solution and its own 'Local' versions for each of the different languages we are interested in. In this way, Teneo allows us to create local solutions with all of the parts of the master solution that we want to include, making it an efficient way to create bots for different languages and markets. You can read more about localization here.

In this guide, we will demonstrate how it is possible to localize the 'Longberry Baristas' solution, which is in English, to another language with resources, Swedish. More on branching can be found in the Documentation.

Prepare your solution

We will start by preparing the solution we want to localize. In this case, it is the 'Longberry Baristas' solution that's included in the free trial account you can create at Teneo Developers.

1. Select the solution, 'Longberry Baristas'.
2. Click on 'Open' above the Solutions field.

Include relevant content for branching

It is time to include the relevant content from Longberry Baristas for branching.

Flows

We will start off with two of the bots' key flows.

1. Select the flows 'User wants to order a coffee' and 'User asks about coffees we offer'.
2. Click on 'Include' in the 'Branching' section in the ribbon bar. The buttons in the 'Branching' section look like this:

A more detailed explanation of these steps can be found here.

Classes

These flows use class match requirements, which also means that they depend on Classes. These are stored in the Class Manager.

1. Open the 'Class Manager' by selecting the 'Class Manager' button located in the 'Solution' section.
2. Select the classes 'ANOTHER_ONE_PLEASE', 'ORDER_A_COFFEE' and 'TELL_ME_ABOUT_YOUR_COFFEE'.
3. Finally, click on the 'Include' button in the 'Branching' section.

Entities

Entities are also used in these flows, and also need to be included for branching.

1. Select the 'Language Objects' folder.
2. Select 'COFFEES_SERVED.ENTITY'. Click the ‘Include’ button in the ‘Branching’ section.

Variables

The 'User wants to order a coffee' flow also makes use of a global variable that needs to be included for branching.

1. Click on the 'Solution' button in the upper left corner of the Solution window.
2. Click on 'Globals' in the left sidebar.
3. Under 'Variables', select the variable 'coffeeTypeInFocus'.
4. Click on the 'Include' button located above the list of variables.
5. Finally, click on the 'Save All' button located on the sidebar in the solution backstage. This will make sure everything you selected to be included for branching inside the solution will be stored and saved.

Other solution content

At this point, we would also need to go over any other content we may need to include, such as Integrations, Contexts, Global Scripts and Listeners. However, for the two key flows we have selected in Longberry Baristas, no other content is used. Therefore, we can go ahead and start localizing!

Forget something?

Don't worry! It is possible to update your 'Master' solution if you forgot to include something before branching. Simply go back to the 'Master' Longberry Baristas solution, and include it. Then return to your 'Local' solution, go to the Solution backstage, and click on the 'My Work' section. We can now see the changes from the 'Master' solution, where we can either select Update All items to update everything or Update Selected items to only update relevant parts. Once updated, the local solution will pull in the changes from the Master solution.

Localizing Longberry Baristas

Now that we have prepared our solution, let’s branch our English Longberry Baristas bot to a different language. This process is fairly similar regardless of language; we will be using Swedish for this example.

1. While in the Solution window, select the 'Longberry Baristas' solution.
2. Click on 'Branch' above the solutions field.
3. Fill in a name for your solution, for example Swedish Longberry Baristas.
4. Make sure the 'Solution Language' for this first bot is Swedish. This will be the mother tongue of your bot.
5. Under 'Solution Content', click on 'Import additional content from Template' and select the latest version of 'Teneo Dialogue Resources Swedish' from the list.

   For languages without resources leave the Just master content selected under 'Solution Content'.

6. Finally, click 'OK' and wait for the branching to complete.

Assign Teneo Lexical Resources

Teneo comes with pre-built Lexical Resources for a couple of languages. These resources help your bot to understand a specific language's words, synonyms, and expressions. This step should be skipped if the selected language does not have any resources.

Let's specify which Teneo Lexical Resources to use for your bot. This is what you need to do:

1. Open your solution by double-clicking its name in the Solutions window.
2. Click on the 'SOLUTION' tab in the upper left corner.
3. Select 'Resources' in the sidebar on the left.
4. Make sure the 'Lexical' tab at the top of the window is selected.
5. Click on 'Edit' in the upper right corner.
6. Click 'Assign Lexical Resource' in the upper left corner, and select Teneo Lexical Resources Swedish in the drop-down.
7. Click 'Save' in the upper right corner.

Identify Warnings and steps to take

Warnings in Try Out appear as yellow warning triangles. To see more detailed warning messages, open the Try Out window and navigate to the Messages section. More information on warnings can be found here.

User asks about coffees we offer

The most important aspect when localizing bots is for the final language to actually make sense for the target audience. Both in respect to the language that they actually use and the language that fits the market and culture. Flow triggers with Class-based match requirements are usually the easiest to localize. They usually use a limited number of Language Objects, where the only parts that need any localization are the training examples. To localize a Class-based match requirement trigger, do the following:

1. Open the 'User asks about coffees we offer' in edit mode.
2. Select the trigger and change its name to the local version of your selected language; for Swedish this is, Vad har ni för utbud?.
3. Replace the testing examples with these Swedish translations,

   Vad har ni för utbud?
   Har ni bryggkaffe
   Har ni cappuccino
   Serverar ni macchiato
   Vilka kaffesorter har ni tillgängliga?
   Vilka typer av kaffe har ni
   Vilken kaffesort serverar ni
   Har ni latte?
   Vilka olika kaffedrinkar har ni
   Vad säljer ni?
   Vad har Longberry Baristas för utbud?
   Vad för kaffeutbud har ni?

4. Open the selected Class Match Requirement by holding CTRL and clicking once on the class name. This will open the 'Class Manager'.
5. Edit the same class and rename it BESKRIV_KAFFEUTBUD.
6. Replace the training examples from the translated examples above.
7. Press 'Save' and return to your flow.

Now that we are done with the class, next up we have the transition and the outputs to be localized.

1. Select the transition 'Coffee type mentioned and served' and rename it to Kaffedryck nämns och serveras
2. Go down the same path and select the Output node, 'We serve coffee type!' and replace its name with Vi serverar kaffedrycken!. While at it, replace the output answer with Ja, ${mentionedCoffee} finns med bland vårt utbud!
3. Go ahead and select the other Output node and replace its name with Vi erbjuder en mängd olika handgjorda kaffesorter....
4. Replace the Answer with the Swedish translation, Vi erbjuder en mängd olika handgjorda kaffesorter från espresso till macchiatos, flat whites och ännu fler..
5. Press 'Save'.

Congratulations, you have now localized part of your solution! Let us move on to the next flow.

User wants to order a coffee

Some flows will have multiple triggers with multiple match requirements. Localizing these is simply a matter of going trigger by trigger and match requirement by match requirement. Let us start by going through the triggers one by one.

Order a coffee trigger (Class and Entity)

1. Open the 'User asks about coffees we offer' in edit mode.
2. Let us start with the trigger 'Order a coffee'. Replace its name with Jag vill beställa kaffe.
3. Replace the examples with

   En vanlig kaffe, tack!
   Jag vill beställa kaffe!
   Har ni Espresso?
   Skulle jag kunna få en macchiato?
   Jag vill ha en flat white.
   En latte tack!
   Jag vill ha en latte tack!
   Har ni vanligt bryggkaffe?
   En bryggkaffe

4. Open the selected Class Match Requirement by holding Alt and clicking once on the class name. This will open the 'Class Manager' in Edit mode.
5. Edit the same class and rename it BESTÄLL_KAFFE.
6. Replace the training examples with the translated examples above.
7. Press 'Save' and return to your flow.

Next in line is the Entity Match Requirement for 'PERSON.ENTITY', which uses a Named Entity Recognizer tagger to recognize personal names . As the Swedish Teneo Lexical Resources includes a 'PERSON.ENTITY' already, there is nothing here to update. For languages without any Lexical Resources we recommend creating their own Language Objects for storing different names and using Data Actions on Language Objects to retrieve the name. If that is not an option, remove this 'Data Action' and use the store the users name condition in the transition 'Get user name'.

Another one please Trigger (Class)

1. Next, let's move on to the trigger 'Another one please'. Replace its name with En till tack.
2. Replace the examples with

   1 till
   En till
   En till beställning
   får jag beställa en till
   Jag vill lägga en till beställning
   Kan jag få en till kopp

3. Open the selected Class Match Requirement by holding Alt and pressing once on the class name. This will open the 'Class Manager'.
4. Edit the same class and rename it EN_TILL_TACK.
5. Replace the training examples from the translated examples above.
6. Press 'Save' and return to your flow.

Can I have one of those trigger (Conditional and Context)

1. Finally, let's move on to the trigger 'Can I have one of those'. Replace its name with Kan jag få en sån
2. Replace the examples inside the trigger with the following:

   Kan jag få en sån?
   Då tar jag en sån
   Kan jag få en sån, tack!

   In the same trigger, the Global Variable Context match requirement will continue to work, but the Condition match requirement will need some updating. As you’ve already translated the examples, you can let Teneo generate a condition for you as done here.

3. Expand the Advanced Options under the condition panel and click on ‘Draft Condition’.
4. Finally, click on the 'Save' button.

Localize the transitions

Next in line is the localizing of the three transitions with conditions found inside the flow.

User responds with coffee type

This transition has a condition for 'COFFEES_SERVED.ENTITY' which needs to be localized by doing the following,

1. Select the transition 'User responds with coffee type' and rename it to Användaren svarar med kaffesort.
2. Scroll down to the 'Match Requirement' section. Open the mentioned Entity by holding Alt and clicking once on the 'COFFEES_SERVED.ENTITY'. This will open the entity in edit mode in a new window.
3. Replace the current entity with the following:

   Coffee name	coffeeType
   americano	americano
   %CAPPUCCINO.NN.LEX	cappuccino
   cortado	cortado
   %ESPRESSO.NN.LEX	espresso
   frappuccino	frappuccino
   latte	latte
   lungo	lungo
   macchiato	macchiato
   ristretto	ristretto
   flat white	flat white
   kokkaffe	kokkaffe
   bryggkaffe	bryggkaffe
   brygg kaffe	bryggkaffe
   bryggd kaffe	bryggkaffe
   bryggkaffen	bryggkaffe

4. Save and return to your flow.

Get user name

Lastly, we have the final transition, which includes 'PERSON.NER' as a condition.

1. Select the transition called 'Get user name' and rename it to Användaren svarar med namn.
2. Leave the condition as it is. For languages without language resources we suggest you replace 'PERSON.NER' with the Language Object created in the earlier steps here.

Localize the outputs

Next up we need to localize the four outputs found inside the flow.

Ask for coffee type

1. Select the first output node called 'Ask for coffee type'. This will open the output configuration panel to the right.
2. Rename the output node to Fråga om kaffesort.
3. Locate the 'Answers' field and replace the answer with Ok, vilket kaffe vill du beställa?.
4. There is also a Resume Prompt that should be replaced with Vi fortsätter med din beställning. Vilket kaffe vill du ha?.

Ask for name

1. Select the third output node called 'Ask for name'. This will open the output configuration panel to the right.
2. Rename the output node to Fråga om namn.
3. Locate the 'Answers' field and replace the answer with Ok, vilket namn ska jag skriva ner för beställningen?.

Summarize Order

Last in line is the final output node where the user's order is summarized.

1. Select the third output node called 'Summarize Order'. This will open the output configuration panel to the right.
2. Rename the output node Sammanfatta order.
3. Locate the 'Answers' field and replace the answer with Tack för din beställning, ${userNameForOrder}. En ${orderedCoffeeSize} ${orderedCoffeeType} är redo att hämtas om fem minuter..

Try it Out

You are now done with the key flows in your first localization of the whole solution. Let us test it in Try Out!

1. Open the 'Try Out' window located in the 'Solution' section.
2. Let us try the flows we just localized. In this case, you can test your flow by trying out the following examples:
   • Vad för kaffeutbud har ni?
   • Jag vill ha en bryggkaffe

Test Yourself

Go ahead and include more flows to localize from the original 'Longberry Baristas'. Use your local language when following the steps above.