# Multilingual Agent

The multilingual capability allows virtual agents to understand and respond in multiple languages, enhancing user experience and broadening accessibility. This feature eliminates the need for creating separate virtual agents for different languages, enabling users to interact in their preferred language.

{% hint style="warning" %}

* Multilingual support is currently a beta feature; some use cases may not function as expected.
* We recommend its use in development environments only and not in production. &#x20;
  {% endhint %}

## Feature overview

1. **Automatic Language Detection and Translation**: When a user sends a message, the system detects the language and translates the message into the agents's primary language to search in the knowledge base. After that, the virtual agent answer will be translated and delivered in the user's language.
2. **Primary and Additional Languages**: Users can configure a primary language for the knowledge base and add complementary languages at the Advanced Resources page.
3. **Comprehensive Language Support**: Provides accurate and clear translations for all languages supported by Azure OpenAI.
4. **Integration with your Knowledge Base**: Ensures efficient information retrieval and answer generation in any language.
5. **Flexible Language Settings**: Allows configuration to detect language either at the beginning of the conversation or with each interaction.
6. **Isolating Terms:** To [prevent specific terms from being translated](#isolating-terms)—like product names or technical terms—you can use specific characters, like curly braces `{}` around the term.&#x20;

{% hint style="info" %}
Enabling this feature may result in additional costs for each new request.&#x20;
{% endhint %}

## **Primary Language**&#x20;

The primary language is selected when you're creating the virtual agent. The list of languages may vary depending on the NLP provider in use (Syntphony NLP, Dialogflow, Amazon Lex, IBM Watson and Microsoft Luis, or Open AI and Azure OpenAI for [Zero-Shot option](https://docs.eva.bot/user-guide/zero-shot-llm)). See the languages supported by each NLP:

* [Amazon Lex](https://docs.aws.amazon.com/lex/latest/dg/how-it-works-language.html)
* [Dialogflow](https://cloud.google.com/dialogflow/es/docs/reference/language)
* [IBM Watson](https://cloud.ibm.com/docs/assistant?topic=assistant-language-support)
* [Microsoft Luis](https://learn.microsoft.com/es-es/azure/ai-services/luis/luis-language-support)

## Configuration

To start using this feature, first go to the [Advanced Resources ](https://docs.eva.bot/user-guide/configurations/advanced-resources)page to enable it, as it comes disabled by default. After enabling it, a pop-up window will appear where you can set up translation options and add languages.

### **Translation Settings**

You can choose to detect the language either only the first time or with each interaction.

<figure><img src="https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2FWo0m4romQ2KOkcYC2R7a%2Fimage.png?alt=media&#x26;token=74dfd88e-4626-4069-a809-c1b85129e164" alt=""><figcaption><p>Choose between detect the language only at the first interaction or with each interaction</p></figcaption></figure>

* **Detect and respond based on recent history**: The agent will detect the language based on recent interactions and the conversation context, avoiding unwanted language switches triggered by foreign terms. If the user actually switches the language during the conversation, the agent will respond in the new language detected, provided it is included in the list of additional languages.\
  \
  If a user starts a chat in English and later switches to Spanish, the virtual agent will respond in Spanish, as long as Spanish is listed as one of the additional languages in the settings. But if the user input language detected is not set as additional language, the system will translate the input into the primary language, process it, and provide the answer in the primary language.\\

* **Answer only with the initially detected language**: If you choose to detect the language only at the start of the conversation, the virtual agent will always respond in that initial language, even if the user switches to another language during the conversation. \
  \
  If English is set as the primary language and Spanish and French as additional languages, the virtual agent will respond in these languages. For example, if the conversation starts in Spanish and the user switches to French, the agent will understand the input but will continue to respond in the language the conversation started in—Spanish in this case. If the initial language is not listed as an additional language, the agent will always respond in the primary language.

{% hint style="info" %}
You must consent to share **masked data** with third-party translation providers for entity extraction and answers purposes before enabling this feature.
{% endhint %}

#### Set translation language

You can configure the agent's content translation within the flow using transactional services. This does not affect language detection, only the translation of the subsequent responses.&#x20;

This can be interesting if you want to disambiguate a flow in multiple languages or define that a flow responds in only one specific language.

<figure><img src="https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2Fz8ow43yZCT5uZ5TaPtZq%2Fimage.png?alt=media&#x26;token=8d7746ad-5200-483d-9fb1-0527d5148c4e" alt=""><figcaption><p>Example of the use of code cell to set the translation of the following answer to Japanese.</p></figcaption></figure>

If the requested language doesn't match the list of configured languages or if the multilingual support is disabled, the answer will be provided in the agent's primary language.

* Use this code to set the language:

```
if(hiddenContext) {
 hiddenContext._eva = {'api': {'multilanguage': { 'language': 'fr'}}};
}
```

* Use this code to reset the language:

```
if(hiddenContext) {
 hiddenContext._eva = {'api': {'multilanguage': { 'language': ''}}};
}
```

The cache will be saved in the defined language.

It's important to note that the translation language is not considered as a user input.

### Ambiguities

In cases where the language cannot be determined—due to ambiguity, abbreviations, or one-word input terms used in multiple languages—the system will prioritize the context of the conversation, based on the last five user interactions, over the most recent input when determining the language.&#x20;

This approach aims to provide a more accurate understanding of the user's intended language by considering the broader context.

#### **Examples:**&#x20;

**Ambiguous input with abbreviations:**

> * **User:** "Bonjour"
> * **User:** "Comment ça va?"
> * **User:** "J’ai une question sur le compte."
> * **User:** "Où puis-je trouver mes relevés bancaires?"
> * **User:** "Merci"

**Recent input:** "OK"

In this scenario, the system detects that "OK" could be understood in many languages, so it prioritizes the context from previous interactions, which were all in French. Based on this context, the system continues to respond in French, given that it's among the ones you set as additional languages.

Another example.

#### One-Word term used in multiple languages

> * **User:** "Hola, necesito ayuda con mi pedido."
> * **User:** "No entiendo el seguimiento."
> * **User:** "¿Puedes verificarlo?"
> * **User:** "Gracias"
> * **User:** "Me podrías ayudar con esto?"

**Recent input:** "Yes"

Though "Yes" could suggest a switch to English, the system identifies the broader context from previous interactions, which indicate the user has been communicating in Spanish. Thus, the system continues to reply in Spanish.

### Isolating terms

During the translation process, there may be specific terms that you don't want to translate. These could be product names, commands, or other technical terms that need to remain in their original language. To ensure that these remain unchanged, you can "isolate" them using special characters, such as curly braces `{}`. Simply enclose the term you want to keep in the original language within `{}`, and the system will then skip translating these terms, keeping them in their original language.

You can also configure that certain values are not translated, such as button values. You can configure that only the text field for the call-to-action is translated, preserving the value of the button (see [Conversation API](https://docs.eva.bot/user-guide/api-docs/api-guidelines/creating-channels-the-conversation-api#advanced-options)).

### Additional Languages&#x20;

You have the option to include all available languages, or selectively add specific languages from the provided list.

<details>

<summary><strong>See list of supported languages</strong> (in alphabetical order)</summary>

**Albanian** (sq-AL)

**Arabic** (ar)

**Armenian** (hy)

**Awadhi** (awa-IN)

**Azerbaijani** (az)

**Bashkir** (ba-RU)

**Basque** (eu-ES)

**Belarusian** (be)

**Bengali** (bn-BD)

**Bhojpuri** (bho-IN)

**Bosnian** (bs-BA)

**Brazilian Portuguese** (pt-BR)

**Bulgarian** (bg-BG)

**Burmese** (my)

**Cantonese** (yue-CN)

**Catalan** (ca-ES)

**Chhattisgarhi** (hne-IN)

**Chinese** (zh)

**Croatian** (hr-HR)

**Czech** (cs)

**Danish** (da-DK)

**Dogri** (doi-IN)

**Dutch** (nl-NL)

**English** (en-GB)

**Estonian** (et)

**Faroese** (fo-FO)

**Finnish** (fi)

**French** (fr-FR)

**French Canadian** (fr-CA)

**Galician** (gl-ES)

**Georgian** (ka)

**German** (de)

**Greek** (el)

**Gujarati** (gu-IN)

**Haryanvi** (bgc-IN)

**Hebrew** (he-IL)

**Hindi** (hi-IN)

**Hungarian** (hu)

**Indonesian** (id-ID)

**Irish** (ga-IE)

**Italian** (it)

**Japanese** (ja)

**Javanese** (jv-ID)

**Kannada** (kn-IN)

**Kashmiri** (ks-IN)

**Kazakh** (kk-KZ)

**Konkani** (kok-IN)

**Korean** (ko-KR)

**Kyrgyz** (ky-KG)

**Kurdish** (ku)

**Latvian** (lv)

**Lithuanian** (lt)

**Macedonian** (mk)

**Maithili** (mai-IN)

**Malay** (ms-MY)

**Maltese** (mt)

**Mandarin Chinese** (cmn-CN)

**Marathi** (mr-IN)

**Marwari** (mwr-IN)

**Min Nan** (nan-CN)

**Moldovan** (ro-MD)

**Mongolian** (mn)

**Montenegrin** (srp-ME)

**Nepali** (ne-NP)

**Norwegian** (no)

**Oriya** (or-IN)

**Pashto** (ps-AF)

**Persian** (fa-IR)

**Polish** (pl)

**Portuguese** (pt-PT)

**Punjabi** (pa-IN)

**Rajasthani** (raj-IN)

**Romanian** (ro)

**Russian** (ru)

**Sanskrit** (sa-IN)

**Santali** (sat-IN)

**Serbian** (sr-RS)

**Sindhi** (sd-PK)

**Sinhala** (si-LK)

**Slovak** (sk)

**Slovenian** (sl)

**Swedish** (sv)

**Thai** (th)

**Turkish** (tr)

**Ukrainian** (uk)

**Urdu** (ur-PK)

**Uzbek** (uz-UZ)

**Vietnamese** (vi)

**Welsh** (cy-GB)

**Wu** (wuu-CN)

</details>

The multilingual capabilities support all text-based inputs and virtual agent answers, including Zero-Shot, Assist Answer, and Rephrase functionalities.

{% hint style="info" %}
Translation capabilities do not extend to audio, video, technical texts, or images.
{% endhint %}

### Request Timeout

It's the amount of time (in seconds) the virtual agent should wait for a response from the generative service. If the request fails or exceeds the time set, the system will deliver the configured fallback answer. You can set this timeout value between 1 to 10 seconds, with the recommended default being 5 seconds. In this scenario, the system will seek for Intents starting a flow, then a FAQ (pairs of an even Intent and Answer), after that Knowledge AI, if enabled, and finally a Not Expected flow.

This parameter can be configured in the [Parameters](https://docs.eva.bot/user-guide/configurations/parameters) section.

### Disable &#x20;

To disable the Multilingual Agent, go back to the Advanced Resources page and turn off the toggle switch of the related card. **Once multilingual support is disabled, the virtual agent will interact solely in the primary language**. If the user interacts in any other language, the system will redirect them to the fallback measure you have set.

## Channels

Multilingual agents can currently be used in the following text channels:

| Apple Business Chat | Kakao              | Slack              |
| ------------------- | ------------------ | ------------------ |
| App Mobile          | Line               | SMS                |
| Facebook Messenger  | Microsoft Teams    | Telegram           |
| Instagram           | RCS                | Web                |
| Skype               | Skype for Business | Web Mobile         |
| WeChat              | WhatsApp           | X (former Twitter) |

{% hint style="info" %}
Multilingual support is not currently available in Telephony, Smart Speakers, and Voice Assistants.
{% endhint %}

## Limitations

* **Masking**: When multilingual support is enabled, masking features cannot be used simultaneously. Assess each case carefully, prioritizing either multilingual support or masking to optimize efficiency. \\

* **Fallback Measures**: If the virtual agent cannot identify the language, it will respond in the agent's primary language. If multilingual support is disabled, the system will not detect inputs in unsupported languages, which could result in the user going to the Not Expected flow.\\

* **Buttons and one-word inputs:** The beta version has a limitation regarding language detection when buttons are used at the beginning of a conversation. The button value will be sent in the agent's primary language, which may affect language selection, as the system relies on the last five interactions to determine the predominant language. \
  \
  This can result in incorrect detection when one-word inputs, like "no," are recognized as a different language.\
  \
  -> For this reason, it is recommended to set the button values to the primary language, so that the translation of the answer will be based on the user's previous input; if there is none, the primary language will be used.

## **Handling Errors**

If there is an error in translating different languages, you can create a rule (using [rule cells](https://docs.eva.bot/user-guide/build-dialogs/dialog-cells/rule)) in the Not Expected flow to ensure the user will get a proper response in case of error.&#x20;

Just add the following rules `$hiddenContext._eva.api.errors.grouped.MULTILANGUAGE` to filter errors by the feature, but if you need to check all errors in the order they have happened use `$hiddenContext._eva.api.errors.details` at the Not Expected flow followed by a regular answer cell with the variables above so you can check the details and address the errors.
