Teneo Developers

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.

A webinar on Localization can be found 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.

Note that branching is also supported for languages without resources.

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 environment you can request access 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:

branching in ribbon

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

We selected these two flows as they offer the key functionality that we want to offer in Longberry Baristas. In a real use case we would also want to include a 'User wants to know if we have a store in city', as this is also an integral part of what a user would expect Longberry Baristas to be able to answer.

Classes

These flows use Class Match, 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' tab.
  2. Click on 'Globals'.
  3. Under 'Variables', select the variable 'coffeeTypeInFocus'.
  4. Click on the 'Include' button.
  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.

While this guide is written with a Swedish translation, feel free to pick another language and translate as necessary for the following steps.

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

For languages without dialogue resources leave the Master only selected under 'Solution Content'.

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

Identify Warnings and steps to take

Warnings in Tryout 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.

t1 warnings in tryout

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 Intent examples with these Swedish translations,

example-inputs

1Vad har ni för utbud?
2Har ni bryggkaffe
3Har ni cappuccino
4Serverar ni macchiato
5Vilka kaffesorter har ni tillgängliga?
6Vilka typer av kaffe har ni
7Vilken kaffesort serverar ni
8Har ni latte?
9Vilka olika kaffedrinkar har ni
10Vad säljer ni?
11Vad har Longberry Baristas för utbud?
12Vad för kaffeutbud har ni?
13
  1. Open the selected Class Match by holding Ctrl and clicking once on the class name. This will open the 'Class Manager'.
  2. Edit the same class and rename it BESKRIV_KAFFEUTBUD.
  3. Replace the training examples from the translated examples above.
  4. 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. Hit '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 Intent examples with

example-inputs

1En vanlig kaffe, tack!
2Jag vill beställa kaffe!
3Har ni Espresso?
4Skulle jag kunna få en macchiato?
5Jag vill ha en flat white.
6En latte tack!
7Jag vill ha en latte tack!
8Har ni vanligt bryggkaffe?
9En bryggkaffe
10
  1. Open the selected Class Match by holding Ctrl and clicking once on the class name. This will open the 'Class Manager' in a new window.
  2. Edit the same class and rename it BESTÄLL_KAFFE.
  3. Replace the training examples with the translated examples above.
  4. Press 'Save' and return to your flow.

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 Intent examples with

example-inputs

11 till
2En till
3En till beställning
4får jag beställa en till
5Jag vill lägga en till beställning
6Kan jag få en till kopp
7
  1. Open the selected Class Match by holding Alt and pressing once on the class name. This will open the 'Class Manager'.
  2. Edit the same class and rename it EN_TILL_TACK.
  3. Replace the training examples from the translated examples above.
  4. Press 'Save' and return to your flow.

Can I have one of those trigger (TLML Syntax 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 Intent examples inside the trigger with the following:

example-inputs

1Kan jag få en sån?
2Då tar jag en sån
3Kan jag få en sån, tack!
4

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

  1. Expand the Advanced Options under the syntax panel and click on ‘Draft’.

Localize the transitions

Next in line is the localizing of the 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' section. Open the mentioned Entity by holding Ctrl and clicking once on the 'COFFEES_SERVED.ENTITY'. This will open the entity in a new window.

  3. Click on Edit and replace the current entity with the following:

    Coffee namecoffeeType
    americanoamericano
    %CAPPUCCINO.NN.LEXcappuccino
    cortadocortado
    %ESPRESSO.NN.LEXespresso
    frappuccinofrappuccino
    lattelatte
    lungolungo
    macchiatomacchiato
    ristrettoristretto
    flat whiteflat white
    kokkaffekokkaffe
    bryggkaffebryggkaffe
    brygg kaffebryggkaffe
    bryggd kaffebryggkaffe
    bryggkaffenbryggkaffe
  4. Save and return to your flow.

Get user name

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

  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.

If you have not created a Language Object, please follow these steps to store the users input.

Localize the outputs

Next up we need to localize the 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.
  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.
  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.
  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 ${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 Tryout!

  1. Open the 'Tryout' 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 solution language when following the steps above.