Async translation with Node SDK

Soniox Node SDK supports asynchronous speech translation through client.stt.translate. It creates an async transcription job with translation enabled, then reshapes the completed transcript into a structured translation result.

Use async translation when you want to translate uploaded files, public audio URLs, or previously uploaded files without maintaining a live connection.

This method is just a syntactic sugar on top of client.stt.transcribe. Use transcribe if you need more low level control on the output.

Quickstart

For simple one-way translation, provide to and one audio source:

const job = await client.stt.translate({
  audio_url: 'https://soniox.com/media/examples/coffee_shop.mp3',
  to: 'es',
  wait: true,
});

console.log(job.translation?.translation_text);

Translation modes

One-way translation

Use to to translate any detected source language to a target language.

const job = await client.stt.translate({
  file: audio,
  filename: 'meeting.mp3',
  to: 'es',
  wait: true,
});

const translation = job.translation;
console.log(translation?.original_text);
console.log(translation?.translation_text);

If you know the source language, provide from. The SDK forwards it as a language hint for the underlying async transcription job.

const job = await client.stt.translate({
  audio_url: 'https://soniox.com/media/examples/coffee_shop.mp3',
  from: 'en',
  to: 'es',
  wait: true,
});

Two-way translation

Use between for bidirectional translation between two languages. This is useful for conversations where either language can appear in the audio.

const job = await client.stt.translate({
  file: audio,
  filename: 'conversation.mp3',
  between: ['en', 'es'],
  enable_speaker_diarization: true,
  wait: true,
});

for (const segment of job.translation?.segments ?? []) {
  console.log(`[${segment.from}] ${segment.original_text}`);
  if (segment.translation_text) {
    console.log(`  -> [${segment.to}] ${segment.translation_text}`);
  }
}

Wait later

If you do not want to block until the job completes, omit wait and call wait or fetchTranslation later.

const job = await client.stt.translate({
  audio_url: 'https://soniox.com/media/examples/coffee_shop.mp3',
  to: 'es',
});

const completed = await job.wait();
const translation = await completed.fetchTranslation();
console.log(translation?.translation_text);

Use with webhooks

Async translation jobs are regular async transcription jobs with translation enabled, so you can use the same webhooks flow.

const job = await client.stt.translate({
  file_id: file.id,
  to: 'es',
  webhook_url: 'https://example.com/webhook',
});

In the webhook handler, fetch the transcript and reshape it with translateFromTranscript.

import { translateFromTranscript } from '@soniox/node';

const transcript = await client.stt.getTranscript(event.id);
if (transcript) {
  const translation = translateFromTranscript(transcript, {
    type: 'one_way',
    to: 'es',
  });
  console.log(translation.translation_text);
}

Fetch transcript instead of translation

translate() also keeps access to the underlying transcript. This is useful when you need both the original token stream and the reshaped translation.

const job = await client.stt.translate({
  file: audio,
  filename: 'meeting.mp3',
  to: 'es',
  wait: true,
});

const transcript = await job.getTranscript();
const translation = await job.getTranslation();

Translation tokens do not carry timestamps, so TranscriptToken.start_ms, TranscriptToken.end_ms, and matching segment timestamps can be undefined for translation-only tokens.