Multi-language sessions

Run Scenaro voice sessions in multiple languages by aligning Cockpit configuration, frontend language tags, and UI translations.

Frontend language tag

Pass a BCP-47 language tag to useScenaroSession:

// French session
useScenaroSession({ scenario: SCENARIO_UUID, language: 'fr-FR' });

// English session
useScenaroSession({ scenario: SCENARIO_UUID, language: 'en-US' });

This sets language on POST /v1/public/session and configures STT/TTS for the session.

language is optional. If you omit it, the session uses the language configured on the scenario in Cockpit — the SDK no longer defaults to fr-FR. Only pass a tag when the user explicitly picks a language.

Cockpit setup

For each language:

Create or duplicate the scenario with a localized system prompt
Publish a separate publication UUID per language (or use dynamic language if supported)
Configure voice stack voices appropriate for the target language

Frontend i18n

Feature components should use your app’s i18n system:

import { useTranslation } from '../hooks/useTranslation';

export function SearchFeature({ toolState }) {
  const { t } = useTranslation();
  const items = toolState.items ?? [];

  return (
    <div>
      <h3>{t('search.results_title')}</h3>
      {items.length === 0 && <p>{t('search.no_results')}</p>}
      {items.map((item) => <ProductRow key={item.id} item={item} />)}
    </div>
  );
}

Language selector pattern

const LANGUAGES = [
  { tag: 'fr-FR', label: 'Français' },
  { tag: 'en-US', label: 'English' },
  { tag: 'de-DE', label: 'Deutsch' },
];

function LanguageSelector({ onSelect }) {
  return (
    <select onChange={(e) => onSelect(e.target.value)}>
      {LANGUAGES.map((lang) => (
        <option key={lang.tag} value={lang.tag}>{lang.label}</option>
      ))}
    </select>
  );
}

// In your widget — undefined means "use the scenario's language":
const [language, setLanguage] = useState<string | undefined>();
const { start } = useScenaroSession({ scenario: SCENARIO_UUID, language });

<LanguageSelector onSelect={setLanguage} />
<button onClick={() => start()}>Start</button>

Prompt guidelines per language

Rule	Reason
Write the system prompt in the target language	LLM responds in the prompt language
Keep tool names in English	Tool names are code identifiers, not spoken
Localize feature `name` fields in Cockpit	Agent uses feature names in conversation
Test STT with native accents	Recognition quality varies by provider and locale

Text input for non-voice contexts

For accessibility or noisy environments, disable the microphone and send text instead:

const { start, sendText, setMicrophoneEnabled } = useScenaroSession({
  scenario: SCENARIO_UUID,
  language: 'fr-FR',
});

await start();
setMicrophoneEnabled(false);
sendText('Bonjour !');

Experience reference

experiences/urbansider supports multiple languages with useTranslation hooks and per-locale Cockpit scenarios.

​Frontend language tag

​Cockpit setup

​Frontend i18n

​Language selector pattern

​Prompt guidelines per language

​Text input for non-voice contexts

​Experience reference

Frontend language tag

Cockpit setup

Frontend i18n

Language selector pattern

Prompt guidelines per language

Text input for non-voice contexts

Experience reference