> ## 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 updates

> Add languages, update language-specific knowledge and voices, and manage pronunciation rules per language.

Maintain multilingual capabilities by adding languages, updating language-specific knowledge and voices, and managing pronunciation rules. Keep translations and behavior rules up-to-date as your business expands to new markets.

## Quick reference

| I need to...                         | Action                                                                                                        |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| Add a new language                   | **Configure > General** → Additional languages                                                                |
| Update language-specific knowledge   | Edit topics with language variants or use `<language:xx>` tags                                                |
| Change voice for a language          | **Channels > Voice > Agent Voice** → select language card                                                     |
| Fix a translation issue              | **Channels > Response Control > [Translations](/response-control/translations)** → edit the card              |
| Add language-specific pronunciations | **Channels > Response Control > [Pronunciations](/response-control/pronunciations)** → add rules per language |
| Test language switching              | Agent Chat → select language from dropdown                                                                    |

## Adding or removing languages

### Adding a new language

1. Go to **Configure > General** and add the language under **Additional languages**
2. Configure a voice for the new language in **Channels > Voice > Agent Voice**
3. Add language-specific knowledge (see below)
4. Add any necessary [translation overrides](/response-control/translations)
5. Update [behavior rules](/agent-settings/rules) for the new language – use `<language:xx>` tags to scope rules to specific languages
6. Add [pronunciation rules](/response-control/pronunciations) for the new language
7. Test in Agent Chat using the language dropdown, then publish

<Tip>Use a multilingual voice model (such as ElevenLabs multilingual or Cartesia sonic) for proper pronunciation across languages. See [Voice](/tools/classes/voice) for available providers including ElevenLabs, Cartesia, Hume, Rime, Minimax, PlayHT, and Google TTS.</Tip>

### Removing a language

Remove the language from **Configure > General** under **Additional languages**, then update any language-specific knowledge, translations, pronunciation rules, and functions. The agent will fall back to the main language for callers speaking the removed language.

## Language-specific knowledge

### Managed Topics with language variants

1. Go to **Build > Knowledge > Managed Topics**
2. Create or edit a topic
3. Add **language variants** for each supported language with translated or culturally-appropriate content
4. Translate both sample questions and content for each variant
5. Save and test

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

### Conditional content with `<language:xx>` tags

For content where you don't need full language variants, use `<language:xx>` tags to serve language-specific content in a single prompt:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
<language:en>
Please hold while I check your account.
</language>
<language:es>
Por favor espere mientras reviso su cuenta.
</language>
```

This works in [behavior rules](/agent-settings/rules), [Managed Topics](/managed-topics/introduction) content, [flow steps](/flows/introduction), and [function](/tools/introduction) descriptions.

### Connected Knowledge per language

Add separate sources per language:

* **URL sources** – add the language-specific version of your website
* **File sources** – upload language-specific documents
* **Integration sources** – configure integrations (such as [Zendesk](/integrations/zendesk) or [Gladly](/integrations/gladly)) to return language-specific content

### Shared vs. language-specific knowledge

| Use shared knowledge when...                        | Use language-specific knowledge when... |
| --------------------------------------------------- | --------------------------------------- |
| Information is universal (phone numbers, addresses) | Content needs translation               |
| Data is language-agnostic (product IDs, prices)     | Cultural context matters                |
| Maintaining multiple versions is impractical        | Local regulations differ by region      |

## Updating voices per language

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

## Language detection and switching

By default, the agent detects the caller's language automatically through ASR and responds in that language.

If detection is too aggressive or not sensitive enough, adjust in [behavior rules](/agent-settings/rules) – for example, instruct the agent to only switch after the caller has spoken consistently in a different language for multiple turns.

For explicit selection, create a Managed Topic that lets callers choose their language and use a function to set it:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def set_language(language_code):
    conv.set_language(language_code)
    return {"utterance": f"Switching to {language_code}."}
```

<div className="developer-only">
  ## Language-specific functions

  ### Accessing the current language

  Access the current language in functions with `conv.language`:

  ```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"}
  ```

  ### Using translation cards in functions

  For hard-coded utterances that need language-specific versions, use the `conv.translations` object instead of if/else branching. Create a [translation card](/response-control/translations), then reference it by key:

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

  For translation keys with special characters:

  ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  getattr(conv.translations, "key with special chars")
  ```
</div>

## What to translate

Not all project content needs translation. See the full reference table in [Multi-language setup](/agent-settings/multilingual#what-to-translate). Key rules:

* Keep **instructions** in English (e.g., "Ask for the user's phone number")
* Translate **example utterances** and scripted responses
* If content is directed at the **agent**, keep it in English. If it will be spoken aloud to the customer, translate it.
* Topic names, actions, function names, and Python code should stay in English.

## Fixing translation issues

| Issue                 | Solution                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------ |
| Awkward phrasing      | Add a manual override on the [Translations](/response-control/translations) page           |
| Cultural mismatches   | Use culturally-appropriate equivalents for idioms                                          |
| Incorrect terminology | Use domain-specific terms with a glossary                                                  |
| Formatting issues     | Localize date/time/number formats per language                                             |
| Pronunciation issues  | Add language-specific rules on the [Pronunciations](/response-control/pronunciations) page |

For content where auto-translation isn't sufficient, use the [Translations](/response-control/translations) page to create manual overrides. For bulk updates to Managed Topics, export as CSV, translate the content, then re-import.

## Testing

1. Open Agent Chat and select a language
2. Verify the agent responds correctly
3. Switch languages mid-conversation and confirm detection works
4. Test with native speakers for naturalness and cultural appropriateness

## Maintenance checklist

* **Monthly:** Audit content parity across languages
* **Quarterly:** Review voices for naturalness
* **Ongoing:** Update all languages together – don't let translations lag behind

## Related pages

* [Multi-language setup](/agent-settings/multilingual) – configure language support and see the full "what to translate" reference
* [Translations](/response-control/translations) – manage manual translation overrides
* [Pronunciations](/response-control/pronunciations) – configure language-specific pronunciation rules
* [Voice Library](/voice/voice-library) – browse and select voices per language
* [Managed Topics](/managed-topics/introduction) – add language variants
* [Voice](/tools/classes/voice) – programmatic voice configuration with provider classes