import { CodeTabs } from '../views/docs/CodeTabs';
import { Callout, NextLink, PropTable } from '../views/docs/prose';
import {
  SET_LANGUAGE_MODE_SIG_PY, SET_LANGUAGE_MODE_SIG_TS,
  SET_LANGUAGE_MODE_EX1_PY, SET_LANGUAGE_MODE_EX1_TS,
  SET_LANGUAGE_MODE_EX2_PY, SET_LANGUAGE_MODE_EX2_TS,
} from './sdk-reference-constants';

## set\_language\_mode()

Configures the voice agent to understand and respond in additional languages beyond English. The agent starts in the primary language and switches to a secondary language when the caller requests it or speaks in that language.

<CodeTabs
  python={{ code: SET_LANGUAGE_MODE_SIG_PY, filename: "signature" }}
  typescript={{ code: SET_LANGUAGE_MODE_SIG_TS, filename: "signature" }}
/>

<PropTable rows={[
  {
    name: "primary",
    type: "Language",
    default: '"english"',
    desc: "The language the agent starts the conversation in.",
  },
  {
    name: "secondary",
    type: "list[Language] | None",
    default: "None",
    desc: "Additional languages the agent can switch to when the caller requests them.",
  },
]} />

The `Language` type is defined as:

```
Literal["english", "spanish", "french", "german", "italian"]
```

**Return value:** `None` / `Promise<void>`

### Example: single secondary language

<CodeTabs
  python={{ code: SET_LANGUAGE_MODE_EX1_PY, filename: "example.py" }}
  typescript={{ code: SET_LANGUAGE_MODE_EX1_TS, filename: "example.ts" }}
/>

### Example: multiple secondary languages

<CodeTabs
  python={{ code: SET_LANGUAGE_MODE_EX2_PY, filename: "example.py" }}
  typescript={{ code: SET_LANGUAGE_MODE_EX2_TS, filename: "example.ts" }}
/>

### Transcript behavior

- There is no auto-translation on the transcript. Each turn appears in the language it was spoken in — if the caller speaks Spanish, that turn is in Spanish; if they speak English, that turn is in English.
- There is currently no per-turn language marker in the transcript.

### Edge cases

- If `secondary` is `None` or empty, the agent operates in `primary` only (the current default behavior).
- When a non-English language is detected during a call, the system automatically switches to a language-specific TTS voice.
- The `grace` voice has clones for Spanish, French, German, and Italian. If no dedicated clone exists for a voice + language combination, the base voice is used.

<Callout>
  <span className="text-primary font-semibold">Compliance:</span> Non-English languages are not currently supported for HITRUST / PCI-compliant deployments. Support is planned.
</Callout>

<NextLink section="field" label="Field" />