Realtime
Recorded
Concepts
Guides
API Reference
Build a bilingual caption UI that shows source text and translation side by side.
Realtime translation is available. Declare target_languages before audio; the target set is fixed for the session. Each target language arrives as its own live.translation.completed event.
Enable translation
ws.send(JSON.stringify({
type: 'session.update',
language: 'zh',
target_languages: ['en'],
}));The gateway confirms the applied state with session.updated. Send this before the first audio frame.
Layout

Implementation
Keep a map of utterances so the source and each translation can be rendered independently:
const utterances = new Map();
function entryFor(index) {
let entry = utterances.get(index);
if (!entry) {
entry = document.createElement('div');
entry.className = 'translation-entry';
utterances.set(index, entry);
container.appendChild(entry);
}
return entry;
}
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.type === 'conversation.item.input_audio_transcription.completed') {
const entry = entryFor(data.utterance_index);
const source = document.createElement('div');
source.className = 'source-text';
source.textContent = data.text;
entry.prepend(source);
}
if (data.type === 'live.translation.completed') {
const entry = entryFor(data.utterance_index);
const translated = document.createElement('div');
translated.className = 'translated-text';
translated.dataset.language = data.language;
translated.textContent = data.text;
entry.appendChild(translated);
}
container.scrollTop = container.scrollHeight;
};CSS
.translation-entry {
margin: 0.5em 0;
padding: 0.5em;
border-left: 3px solid #4f46e5;
}
.source-text {
font-weight: 500;
}
.translated-text {
margin-top: 0.25em;
opacity: 0.85;
font-style: italic;
}Language switching
When the user switches the source language, update the session:
function switchLanguage(lang) {
ws.send(JSON.stringify({
type: 'session.update',
language: lang,
}));
}New utterances after the switch use the new source language. Translation targets cannot change mid-session; start a new session if the target languages change.
Related
- Live Translation — translation concepts
- Realtime Translation — API details
- Build a Stable Caption UI — caption UI patterns