Documentation / Guides / Multilingual switching

Build multilingual switching

Multilingual behavior starts with complete consumer-owned bindings. Detection may request a switch; it cannot invent the target prompt, tools, model, or voice.

Define every target

bindings = (
    LanguageBinding("en-IN", english_profile, english_prompt, english_tools),
    LanguageBinding("hi-IN", hindi_profile, hindi_prompt, hindi_tools),
)
policy = LanguagePolicy(
    initial_language="hi-IN",
    bindings=bindings,
    automatic_switching_preset="multilingual-v42@1",
    detector_route="sarvam",
)

This is a construction snippet; the referenced profiles and tools must be fully constructed.

The current proven Sarvam public route covers the six migration bindings en-IN, hi-IN, ta-IN, te-IN, kn-IN, and ml-IN. Check the provider module's fixed manifest before enabling additional locales.

Explicit switch

A consumer tool can request the complete target binding:

async def switch_language(context, arguments):
    state = context.consumer_state
    target = state["bindings"][arguments["language"]]
    receipt = await context.request_update(
        CallUpdate(
            expected_revision=state["revision"],
            reason=f"caller selected {target.language}",
            boundary=UpdateBoundary.AFTER_CURRENT_REPLY,
            prompt=target.instructions,
            language=target,
            tools=target.tools,
            speech_recognition=target.profile.speech_recognition,
            reasoning=target.profile.reasoning,
            speech_generation=target.profile.speech_generation,
        )
    )
    state["language"] = target.language
    state["revision"] = receipt.new_revision
    return {"language": target.language}

Update consumer state only after the receipt commits. If preparation fails, the old configuration and state must remain active.

Automatic switching

With an approved preset and detector route, VAANI can turn trusted evidence from a completed participant turn into the same atomic update. Partial speech does not commit a switch. Uncertain/unapproved evidence keeps the current language.

The standard behavior:

• permits strong evidence promptly;
• requires confirmation for ambiguity;
• applies cooldown against oscillation;
• switches silently—no automatic announcement;
• replays only the triggering utterance under the new STT route;
• withholds unreliable provisional text if replay fails and uses the consumer's language-specific retry message.

Earlier committed turns are never retranscribed.

Keep tools language-aware

Either bind language-specific tools, or have handlers read the committed language from consumer state. Do not update that state on detection alone. Prompt, tools, and nested conversation state must advance at the same committed revision.

Test the hard edges

Cover:

• all ordered language pairs;
• confidence just below and at the threshold;
• cooldown and repeated evidence;
• a failed target preparation;
• triggering-utterance replay;
• tool visibility at the new revision;
• one terminal result after switches.

Next: live updates and deterministic testing.