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

# How Language Switching Works

> The decision engine behind Bolna's mid-call language switching: the two-listener model, exactly what triggers a switch versus what doesn't, supported auto-detection languages, and troubleshooting steps.

A multilingual Bolna agent holds a single conversation across several languages — there's no separate agent per language and no menu asking the caller to pick. It auto-detects when a caller moves to a different configured language and switches to it on its own, live, mid-call. Recognition, voice, and replies all change together.

Setting up a [multilingual agent](/docs/customizations/multilingual-languages-support) tells Bolna which languages to support. This page covers the part that runs on every call: how the agent decides, turn by turn, whether the caller has actually switched languages — and what to expect when it does.

<Info>
  It's best not to write language-switching instructions into your prompt — the system handles switching itself, independently of what your prompt says.
</Info>

***

## What changes on a switch

When the agent decides the caller has moved to a different configured language, three things change together, mid-call:

<CardGroup cols={3}>
  <Card title="Recognition" icon="waveform-lines">
    **Speech-to-text** starts transcribing the new language accurately.
  </Card>

  <Card title="Voice" icon="volume-high">
    **Text-to-speech** speaks in the voice you set for that language.
  </Card>

  <Card title="Replies" icon="comments">
    The agent commits to the new language until the caller clearly moves again.
  </Card>
</CardGroup>

<Tip>
  There's a brief, typically unnoticeable pause — a few hundred milliseconds — while the agent changes languages and voices, only on the turn where the language actually changes.
</Tip>

***

## The decision engine: two listeners, one decision per turn

You don't need the internals to use the feature — see [Setting Up Languages](/docs/customizations/multilingual-languages-support#setting-up-languages) for that — but this model explains almost every "why did, or didn't, it switch?" question.

While your agent talks, two things listen at once:

|                         | What it does                                                          |
| ----------------------- | --------------------------------------------------------------------- |
| **Main recognizer**     | Locked to whichever language the agent is currently speaking.         |
| **Background detector** | Transcribes whatever is actually being spoken, biased toward nothing. |

At the end of each thing the caller says, Bolna compares the two and asks: *is the caller now substantively speaking a different supported language?* If yes, it switches; if it's a stray English word, a "hello", or a phone number, it stays put.

<AccordionGroup>
  <Accordion title="It never gets stuck">
    If a caller says something the current recognizer can't decode and then pauses, the agent still evaluates it using the background detector, instead of waiting forever in the wrong language.
  </Accordion>

  <Accordion title="This is the default 'requested or auto detected' behavior">
    If you set the switch trigger to **"the caller requested for it,"** the background detector still listens, but the agent only switches when the caller *explicitly asks* — directly requesting a language, asking "can you speak X?", or answering the agent's own question about which language to use. Simply speaking another language won't move it.

    Over the API this is the `language_switch_trigger` field: `"requested_or_auto_detected"` (the default, described above) or `"caller_requested"` (explicit-only). See the [Config Reference](/docs/customizations/multilingual-config-reference#top-level-fields) for the full field definition.
  </Accordion>
</AccordionGroup>

***

## What triggers a switch — and what doesn't

The agent is deliberately conservative: it switches when a caller has *genuinely* moved to another language, and ignores the everyday word-mixing of natural speech. *(This describes the default "requested or auto detected" trigger. If you've set the agent to "the caller requested for it," only the explicit requests in the first column below switch it — everything else stays put.)*

<Tabs>
  <Tab title="✅ It switches when…">
    | Signal                                                                     | Example                                                                    |
    | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
    | The caller speaks a **full sentence** in another supported language        | "मेरा order अभी तक क्यों नहीं आया?" → Hindi                                |
    | The caller **asks for a language by name**                                 | "Can you speak in Tamil?", "हिंदी में बात करें"                            |
    | The caller **repeats a language name** with nothing else                   | "Hindi… Hindi" → a request for Hindi                                       |
    | The caller **keeps answering in another language** across turns            | Two+ turns in Marathi in a row — also how a caller corrects a wrong switch |
    | The caller says they **can't understand**, while speaking another language | "मुझे समझ नहीं आ रहा" in Hindi → switch to Hindi                           |
  </Tab>

  <Tab title="❌ It stays put when…">
    | Signal                                                                                                 | Why                                                       |
    | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
    | The caller drops in **one or two borrowed words** ("मेरा order status check करें")                     | Code-mixing is normal — the sentence is still Hindi       |
    | The caller says a **bare greeting or acknowledgment** ("okay", "hello", "haan", "thanks")              | Universal words that don't signal a language              |
    | The caller **reads out numbers, codes, or IDs** — an OTP, an order or phone number, a spelled-out code | That's data, not a language change                        |
    | The caller uses a language **you haven't configured**                                                  | It can only switch among languages you've added           |
    | There isn't **enough clear speech** yet — a half-second fragment                                       | It waits for a clear, substantive phrase — not a fragment |
  </Tab>
</Tabs>

<Info>
  **Closely related languages get extra care.** Look-alike languages — Hindi / Marathi / Urdu, or the Telugu / Tamil / Kannada / Malayalam group — are decided from the grammar of the sentence, not a single word, so the agent doesn't flap back and forth. A switch between two similar languages needs a clearer signal than English → Hindi.
</Info>

***

## Supported languages for automatic detection

The languages *your* agent can switch between are exactly the ones you [add to it](/docs/customizations/multilingual-languages-support#setting-up-languages). Automatic detection itself is tuned for English and the major Indian languages:

| Language  | Code | Language | Code |
| --------- | ---- | -------- | ---- |
| English   | `en` | Marathi  | `mr` |
| Hindi     | `hi` | Bengali  | `bn` |
| Tamil     | `ta` | Gujarati | `gu` |
| Telugu    | `te` | Punjabi  | `pa` |
| Kannada   | `kn` | Urdu     | `ur` |
| Malayalam | `ml` |          |      |

<Info>
  Bolna handles additional languages across the platform (for example French, Spanish, and Dutch — see the [full supported-language list](/docs/customizations/multilingual-languages-support#supported-languages)), but mid-call **auto-switching** is centered on the eleven languages above. Each language you add also needs a [voice and transcription provider](/docs/agent-setup/audio-tab) that supports it — coverage varies by provider, so choose your per-language providers accordingly.
</Info>

***

## Getting the best results

<CardGroup cols={2}>
  <Card title="Set a native voice for every language" icon="microphone">
    The single biggest quality lever. Leaving a secondary language on a default English voice is the most common mistake — a Hindi switch spoken in an English voice sounds wrong.
  </Card>

  <Card title="Write each prompt in its native script" icon="pen-nib">
    With localized examples — not a translated-on-the-fly English prompt.
  </Card>

  <Card title="Add every language callers might use" icon="language">
    The agent can only switch to languages you've configured.
  </Card>

  <Card title="Choose your default language carefully" icon="flag">
    Pick the one most calls open in, so the opening turn is right before any switch.
  </Card>

  <Card title="Cover system messages for every language" icon="comments">
    So a caller who switches doesn't hear an English fallback mid-conversation. See [Auto-Switch Languages](/docs/customizations/auto-switch-multilingual-messages).
  </Card>

  <Card title="Test with real, code-mixed speech" icon="flask">
    A full sentence in the second language (should switch), a sentence with one English word dropped in (should not), and a number read-out (should not).
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="My agent isn't switching">
    Check, in order:

    1. Are **at least two languages** configured on the agent (multilingual enabled)?
    2. Is the language the caller is speaking **added to the agent**, with a voice set?
    3. Is the caller saying a **full phrase** in that language — not just a word or a number?
    4. Is the switch trigger set to **"the caller requested for it"**? In that mode the caller has to **explicitly ask** — just speaking the language won't switch it. Use **"requested or auto detected"** for automatic switching.
  </Accordion>

  <Accordion title="It switched when the caller said only one English word">
    It shouldn't — a single borrowed word is treated as code-mixing and the agent should stay. If it's consistent, report it with the call recording.
  </Accordion>

  <Accordion title="It switched while the caller read out an order number or OTP">
    It shouldn't — numbers, codes, and spelled-out identifiers are ignored as language evidence. Report the call if it happens.
  </Accordion>

  <Accordion title="It keeps flip-flopping between two similar languages">
    Similar languages (e.g. Hindi / Marathi) are the hardest case. Make sure both are configured on the agent with the correct voice and transcription — the agent can only settle on languages you've actually set up.
  </Accordion>

  <Accordion title="Once it switches, will it switch back on its own?">
    Only when the caller clearly moves again. After a switch the agent commits to the new language, so a single stray word won't bounce it back.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Multilingual Support" icon="earth-americas" href="/docs/customizations/multilingual-languages-support">
    Set up languages, prompts, and hand-in messages
  </Card>

  <Card title="Auto-Switch System Messages" icon="shuffle" href="/docs/customizations/auto-switch-multilingual-messages">
    Localize hangup, user-online, and tool-call messages
  </Card>

  <Card title="Config Reference (API)" icon="code" href="/docs/customizations/multilingual-config-reference">
    The `multilingual_config` object and `language_switch_trigger`
  </Card>

  <Card title="Non-English Prompts" icon="language" href="/docs/writing-prompts-in-non-english-languages">
    Write per-language prompts in native scripts
  </Card>
</CardGroup>