> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-language

> Configure your agent to handle conversations in multiple languages from a single project.

Use multi-language support when your agent serves callers who speak different languages. A multilingual agent detects the caller's language, switches mid-conversation if needed, and uses language-appropriate voices and content.

<img src="https://mintcdn.com/polyai/ZLF0Qj3pBejcJlai/images/release-notes/2604/add-languages.png?fit=max&auto=format&n=ZLF0Qj3pBejcJlai&q=85&s=578ff919819251559f35480de3c44180" alt="multi-language-settings" width="3012" height="1478" data-path="images/release-notes/2604/add-languages.png" />

<Note>
  Languages are now managed directly in Agent Studio. This replaces the older `start_function` approach and one-project-per-language setups.
</Note>

## Setting up multi-language support

<img src="https://mintcdn.com/polyai/6pR9_QDXCUwa3AK0/images/agent-settings/multilingual-settings.png?fit=max&auto=format&n=6pR9_QDXCUwa3AK0&q=85&s=9870fd2b68e8094c524e1c864e1bccdb" alt="Multi-language settings showing Response language and Additional languages fields" width="3002" height="1626" data-path="images/agent-settings/multilingual-settings.png" />

<Steps>
  <Step title="Add languages">
    Go to **Behavior** and find the **Additional languages** field. Select up to 10 additional languages from the dropdown. The **Response language** set during project creation becomes the **main language**.
  </Step>

  <Step title="Configure voices per language">
    Each language has its own voice configuration. Go to **Voice > Settings** where you'll see a voice card for each configured language. The main language card is tagged as "Main language".

    * Select a voice for each language from the [Voice Library](/voice-channel/voice-library)
    * You can configure separate voices for **Agent voice** and **Disclaimer** per language
    * Multi-voice is supported per language, so you can assign multiple voices to a single language
  </Step>

  <Step title="Add translations (optional)">
    If you need manual translation overrides for specific content, use the [Translations](/behavior/language/translations) page under **Behavior > Language**.
  </Step>

  <Step title="Test in Agent Chat">
    Use the **language dropdown** in Agent Chat to select a language and test your agent's behavior in each configured language.
  </Step>
</Steps>

### Supported languages

PolyAI supports **73 response languages** for multilingual agents, covering the full union of languages officially supported by the underlying LLM providers. Pass the BCP 47 code (e.g. `es-ES`) when setting the language in the UI or via [`conv.set_language()`](/tools/classes/conv-object#set_language).

<AccordionGroup>
  <Accordion title="Full list of supported languages and codes">
    | Language | Code |
    | - | - |
    | Albanian | `sq-AL` |
    | Amharic | `am-ET` |
    | Arabic | `ar` |
    | Armenian | `hy-AM` |
    | Bengali | `bn-BD` |
    | Bosnian | `bs-BA` |
    | Bulgarian | `bg-BG` |
    | Burmese | `my-MM` |
    | Cantonese | `yue-Hant-HK` |
    | Catalan | `ca-ES` |
    | Chinese (China) | `zh-CN` |
    | Chinese (Taiwan) | `zh-TW` |
    | Croatian | `hr-HR` |
    | Czech | `cs-CZ` |
    | Danish | `da-DK` |
    | Dutch (Belgium) | `nl-BE` |
    | Dutch (Netherlands) | `nl-NL` |
    | English (Australia) | `en-AU` |
    | English (Canada) | `en-CA` |
    | English (New Zealand) | `en-NZ` |
    | English (Singapore) | `en-SG` |
    | English (UK) | `en-GB` |
    | English (US) | `en-US` |
    | Estonian | `et-EE` |
    | Finnish | `fi-FI` |
    | French (Belgium) | `fr-BE` |
    | French (Canada) | `fr-CA` |
    | French (France) | `fr-FR` |
    | Georgian | `ka-GE` |
    | German (Germany) | `de-DE` |
    | Greek | `el-GR` |
    | Gujarati | `gu-IN` |
    | Hebrew | `he-IL` |
    | Hindi | `hi` |
    | Hungarian | `hu-HU` |
    | Icelandic | `is-IS` |
    | Indonesian | `id-ID` |
    | Italian (Italy) | `it-IT` |
    | Japanese | `ja-JP` |
    | Kannada | `kn-IN` |
    | Kazakh | `kk-KZ` |
    | Korean | `ko-KR` |
    | Latvian | `lv-LV` |
    | Lithuanian | `lt-LT` |
    | Macedonian | `mk-MK` |
    | Malay | `ms-MY` |
    | Malayalam | `ml-IN` |
    | Marathi | `mr-IN` |
    | Mongolian | `mn-MN` |
    | Norwegian | `nb-NO` |
    | Persian (Farsi) | `fa-IR` |
    | Polish | `pl-PL` |
    | Portuguese (Brazil) | `pt-BR` |
    | Portuguese (Portugal) | `pt-PT` |
    | Punjabi | `pa-IN` |
    | Romanian | `ro-RO` |
    | Russian | `ru-RU` |
    | Serbian | `sr-RS` |
    | Slovak | `sk-SK` |
    | Slovenian | `sl-SI` |
    | Somali | `so-SO` |
    | Spanish (Spain) | `es-ES` |
    | Spanish (US) | `es-US` |
    | Swahili | `sw-KE` |
    | Swedish | `sv-SE` |
    | Tagalog (Filipino) | `tl-PH` |
    | Tamil | `ta-IN` |
    | Telugu | `te-IN` |
    | Thai | `th-TH` |
    | Turkish | `tr-TR` |
    | Ukrainian | `uk-UA` |
    | Urdu | `ur-PK` |
    | Vietnamese | `vi-VN` |
  </Accordion>
</AccordionGroup>

<Note>
  Serbian uses `sr-RS` (Republic of Serbia). If you were previously using the non-standard `sr-SP` code, update your project configuration to `sr-RS`.
</Note>

Voice (TTS) coverage depends on the provider you select for each language. Some languages support fewer voices – see the [Voice Library](/voice-channel/voice-library) for what's available per language.

## How multilingual agents work

Multilingual agents can:

* **Detect the caller's language** automatically with ASR
* **Switch languages mid-conversation** if the caller changes language
* **Automatically switch voices** when the language changes, if a voice is configured for that language
* **Maintain language-specific knowledge** using language variants on FAQs
* **Filter content by language** using `<language:xx>` tags in prompts
* **Handle mixed-language queries** (code-switching)

<Info>
  Auto voice switching only works for the main language and configured additional languages. If the conversation changes to an unsupported language, the voice stays the same.
</Info>

## Forcing a language by dialled number (DNIS routing)

If you serve different markets on different phone numbers and want to bypass auto-detection, set the language explicitly in `start_function` based on `conv.callee_number` (the number the caller dialled).

<Note>
  The language you pass to `conv.set_language()` must already be added under **Behavior > Additional languages** (or be the main language). If the code is not configured on the project, the agent falls back to the default language.
</Note>

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def start_function(conv: Conversation):
    spanish_dnis = {"+34911234567", "+34931234567"}

    if conv.callee_number in spanish_dnis:
        conv.set_language("es-ES")
    else:
        conv.set_language("en-US")

    return str()
```

Use the full IETF locale code (e.g. `"es-ES"`, `"en-US"`, `"fr-FR"`), not the short form (`"es"`, `"en"`). See [`conv.set_language`](/tools/classes/conv-object#set_language) and [`conv.callee_number`](/tools/classes/conv-object#callee_number) for the full reference.

## Configuring voices per language

When multilingual support is enabled, the **Agent Voice** page shows separate voice sections organized by language.

<img src="https://mintcdn.com/polyai/mC-hBNxhbQLRsMMg/images/agent-settings/agent-voice-set-language-by-voice.png?fit=max&auto=format&n=mC-hBNxhbQLRsMMg&q=85&s=4a61407d032b271a2e0f6908cc653678" alt="Agent voice set language by voice" width="3002" height="1588" data-path="images/agent-settings/agent-voice-set-language-by-voice.png" />

1. Go to **Voice > Settings**
2. You'll see an **Agent** tab and a **Disclaimer** tab
3. On the **Agent** tab, each language has its own voice card
4. Click into a language card to select or change the voice
5. To assign multiple voices to a language, add them from the voice card – multi-voice is supported per language

**Voice quality tips:**

* Use native voices – don't use an English voice for Spanish
* Match regional accents – use Mexican Spanish for Mexico, Castilian for Spain
* Test pronunciation for language-specific characters
* Multilingual TTS models are convenient but may have slightly lower quality than language-specific models

You can also configure voices programmatically. See [Voice classes](/tools/classes/voice) for available providers including ElevenLabs, Cartesia, Hume, Rime, Minimax, PlayHT, and Google TTS.

## Conditional content filtering

Use `<language:xx>` tags to serve language-specific content within a single prompt, without needing separate variants:

```
<language:en>
Please hold while I check your account.
</language>
<language:es>
Por favor espere mientras reviso su cuenta.
</language>
```

<Note>
  Closing tags are always plain `</language>` (or `</channel>`) – never `</language:en>`. The closing tag matches the most recently opened tag.
</Note>

This works in:

* [Behavior rules](/behavior/general/rules)
* [FAQs](/knowledge/faqs/introduction) content
* [Flow steps](/flows/introduction)
* [Function](/tools/introduction) descriptions

## Language variants on FAQs

FAQs support **language variants** so you can manage multilingual knowledge base content within a single agent. Each topic can have language-specific versions of its content and sample questions.

1. Go to **Knowledge > FAQs**
2. Create or edit a topic
3. Add **language variants** for each supported language
4. Translate sample questions and content for each variant

<Tip>
  Sample questions must be in the same language as caller inputs – they are compared with user inputs during the retrieval process.
</Tip>

## Language-specific pronunciation rules

Pronunciation rules in [Advanced voice settings](/voice-channel/advanced/call-settings#pronunciation) are organized by language. Each language has its own set of rules, displayed as separate collapsible cards. Rules within a language card only apply to responses in that language. Rules with no language specified apply globally.

## What to translate

Some project content needs translation, and some does not:

| Area | Element | Translate? | Notes |
| - | - | :-: | - |
| **Knowledge** | Sample questions | <Icon icon="check" iconType="solid" color="#2ecc71" size={14} /> | Must match user input language for retrieval |
| | Content | <Icon icon="check" iconType="solid" color="#2ecc71" size={14} /> | Translate for brand accuracy and better output |
| | Topic names and actions | <Icon icon="x" iconType="solid" color="#e74c3c" size={14} /> | Keep in English (used internally, not user-facing) |
| **SMS** | SMS content | <Icon icon="check" iconType="solid" color="#2ecc71" size={14} /> | Translate anything user-facing |
| **ASR & Voice** | ASR keywords and corrections | <Icon icon="check" iconType="solid" color="#2ecc71" size={14} /> | Leave in native language – these may differ significantly from English |
| | Response control and pronunciations | <Icon icon="check" iconType="solid" color="#2ecc71" size={14} /> | Leave in native language – these may differ significantly from English |
| **Functions** | Python code | <Icon icon="x" iconType="solid" color="#e74c3c" size={14} /> | Leave in English |
| | Function names and descriptions | <Icon icon="x" iconType="solid" color="#e74c3c" size={14} /> | Leave in English |
| | Hard-coded responses and LLM prompts | <Icon icon="check" iconType="solid" color="#2ecc71" size={14} /> | Translate only user-facing content (e.g., utterances) |

## General rules

* Keep **instructions** in English (e.g., "Ask for the user's phone number")
* Translate **example utterances** or scripted responses
* If it's directed at the **agent**, keep it in English. If it's going to be spoken aloud directly to the customer, translate it.

> `Ask the user for their number by saying "¿Me puedes dar tu número de teléfono?"`

### Function examples

If you're using a function with a hard-coded response, translate the user-facing string:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
return {
  "utterance": "Respuesta fija en español aquí"
}
```

If you're re-prompting the LLM, you only need to translate example responses:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
return {
  "content": "Inject prompt here"
}
```

### Accessing the current language in functions

You can access the caller's detected language in functions:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def dynamic_response():
    current_language = conv.language

    if current_language == "es":
        return {"utterance": "Respuesta en español"}
    else:
        return {"utterance": "Response in English"}
```

### Accessing translations in functions

For hard-coded utterances that need language-specific versions, use the translations object:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
conv.translations.tn_name
```

Or for translation keys with special characters:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
getattr(conv.translations, "name with special chars!!!!")
```

## Testing multilingual agents

The Agent Chat panel includes a **language dropdown** that lets you select a language to test with – similar to how you select variants.

1. Open Agent Chat
2. Select a language from the dropdown (defaults to the main language on the first turn)
3. Interact with your agent and verify it responds correctly
4. Switch languages mid-conversation to test detection and voice switching

## Reviewing multilingual conversations

Language information surfaces across Agent Studio so you can review and filter multilingual traffic:

* **Conversations table** – add the **Language** column from the **Column** menu to see which language was used in each conversation, then sort or scan for patterns.

* **Filter by language** – open **Filter** and add a `Language is …` condition to narrow the table to a specific language. The condition shows as a chip above the table and can be saved into a [Custom View](/analytics/conversations/views).

  <img src="https://mintcdn.com/polyai/rSFEoR-hN0C8DJ2I/images/analytics/conv-review-filter-chip-language.png?fit=max&auto=format&n=rSFEoR-hN0C8DJ2I&q=85&s=82a2a1798685d5a7f5458de6ce48de55" alt="Conversations table filtered to French, showing the Language is French chip above the table" width="2486" height="562" data-path="images/analytics/conv-review-filter-chip-language.png" />

  The filter builder supports combining language with other conditions (for example, **Environment includes Draft, Sandbox, Staging** AND **Language is French**) so you can carve out a per-language QA queue.

  <img src="https://mintcdn.com/polyai/rSFEoR-hN0C8DJ2I/images/analytics/conv-review-filter-builder-language.png?fit=max&auto=format&n=rSFEoR-hN0C8DJ2I&q=85&s=666cb1a9d9086971482f14f5c34aa91e" alt="Filter builder side panel showing an Environment condition combined with a Language is French condition" width="2502" height="1608" data-path="images/analytics/conv-review-filter-builder-language.png" />

* **Review side panel** – the panel header shows the detected language for the conversation, and per-turn language information appears alongside the transcript when the agent switched languages mid-call.

* **Audio management** – cached audio files include language metadata so you can identify and manage TTS audio per language.

## Related pages

<CardGroup cols={2}>
  <Card title="Translations" icon="language" href="/behavior/language/translations">
    Manually override auto-translations for specific content in your agent's responses.
  </Card>

  <Card title="Multi-language updates" icon="refresh" href="/learn/maintain/multi-language-updates">
    Maintain and optimize your multilingual agent over time.
  </Card>

  <Card title="Voice Library" icon="music" href="/voice-channel/voice-library">
    Browse and select voices per language for your agent.
  </Card>

  <Card title="Pronunciations" icon="sound" href="/voice-channel/advanced/call-settings#pronunciation">
    Configure language-specific pronunciation rules for natural speech.
  </Card>
</CardGroup>