For AI agents: a documentation index is available at /llms.txt. Markdown versions of all pages can be requested by appending `.md` to the URL, or by setting the `Accept` header to `text/markdown`.
Skip to main content
Speech to TextFeatures

Translation

Translate your audio into multiple languages with a single API call.

Available in: Batch, Realtime. Not available in Agent STT.

Translate your audio into multiple languages through a single API call, with over 30 languages supported.

Use cases​

  • Translate audio files for international distribution
  • Power live subtitles and captions for global events
  • Build voice assistants or AI agents that communicate in multiple languages

Configuration​

Enable translation when processing a file or in real-time in SaaS and on-prem deployment.

New to Speechmatics? See our guides on transcribing a file or transcribing in real-time. Once set up, add the following configuration to enable translation:

{
  "type": "transcription",
  "transcription_config": {
    "model": "enhanced",
    "language": "en"
  },
  "translation_config": {
    "target_languages": ["es", "de"],
    "enable_partials": true
  }
}

You can configure up to five translation languages at a time.

Batch output​

The returned JSON will include a new property called translations, which contains a list of translated text for each target language requested (using the same ISO language codes as for transcription).

RetrieveTranscriptResponseIn the API reference: Get the transcript for a transcription job
format
string

Speechmatics JSON transcript format version number.

job
JobInfo

Summary information about an ASR job, to support identification and tracking.

metadata
RecognitionMetadata

Summary information about the output from an ASR job, comprising the job type and configuration parameters used when generating the output.

results
RecognitionResult[]

An ASR job output item. The primary item types are word and punctuation. Other item types may be present, for example to provide semantic information of different forms.

speakers
SpeakersResultItem[]
optional

List of unique speaker identifiers detected in the transcript.

translations
Record<string, TranslationSentence[]>
optional

Translations of the transcript into other languages. It is a map of ISO language codes to arrays of translated sentences. Configured using translation_config.

[key: string]
TranslationSentence[]
optional
start_time
number<float>
optional
end_time
number<float>
optional
content
string
optional
speaker
string
optional
channel
string
optional
summary
SummarizationResult
optional

Summary of the transcript, configured using summarization_config.

sentiment_analysis
SentimentAnalysisResult
optional

The main object that holds sentiment analysis data.

topics
TopicDetectionResult
optional

Main object that holds topic detection results.

chapters
AutoChaptersResult
optional

An array of objects that represent summarized chapters of the transcript

audio_events
AudioEventItem[]
optional

Timestamped audio events, only set if audio_events_config is in the config

audio_event_summary
object
optional

Summary statistics per event type, keyed by type, e.g. music

An example of the response is below:

{
    "format": "2.9",
    "job": {
        "created_at": "2023-01-23T19:31:19.354Z",
        "data_name": "example.wav",
        "duration": 15,
        "id": "ggqjaazkqf"
    },
    "metadata": {
        "created_at": "2023-01-23T19:31:44.766Z",
        "type": "transcription",
        "transcription_config": {
            "language": "en",
            "diarization": "speaker"
        },
        "translation_config": {
            "target_languages": [
                "es"
            ]
        }
    },
    "results": [
        {
            "start_time": 0.78,
            "end_time": 1.32,
            "type": "word",
            "alternatives": [
                {
                    "content": "Welcome",
                    "confidence": 1.0,
                    "language": "en",
                    "speaker": "S1"
                }
            ]
        },
        ...
    ],
    "translations": {
        "es": [
            {
                "start_time": 0.78,
                "end_time": 2.58,
                "content": "Bienvenidos a Speechmatics.",
                "speaker": "S1"
            },
            {
                "start_time": 3.0,
                "end_time": 7.94,
                "content": "Esperamos que tengas un gran día.",
                "speaker": "S1"
            },
            ...
        ]
      }
}

Realtime output​

Realtime provides a stream of translation messages per language requested. Translation messages will arrive after transcription messages, but won't delay transcription. Realtime translations have the following schema:

AddTranslationIn the API reference: AddTranslation
message
"AddTranslation"
format
string
optional

Speechmatics JSON output format version number.

language
string

Language translation relates to given as an ISO language code.

results
TranslatedSentence[]

Translations arrive as lower latency partial results and higher latency, more accurate finals.

Partials​

Partial translations typically correspond to unfinished sentences and have lower latency than final translations. By default, only final translations are produced. Enable partials using the enable_partials property in translation_config for the session. For example:

{
  "format": "2.9",
  "message": "AddPartialTranslation",
  "language": "es",
  "results": [
    {
      "start_time": 5.45999987795949,
      "end_time": 5.889999870583415,
      "content": "Bienvenidos a",
      "speaker": "S1"
    }
  ]
}

Finals​

Final translations are the most accurate and complete translations, usually at the end of a sentence. These translations are considered final and will not be updated afterwards. For example:

{
  "format": "2.9",
  "message": "AddTranslation",
  "language": "es",
  "results": [
    {
      "start_time": 5.45999987795949,
      "end_time": 6.189999870583415,
      "content": "Bienvenidos a Speechmatics.",
      "speaker": "S1"
    }
  ]
}

Examples​

Python client example to translate a file for batch.

from speechmatics.models import ConnectionSettings
from speechmatics.batch_client import BatchClient
from httpx import HTTPStatusError

API_KEY = "YOUR_API_KEY"
PATH_TO_FILE = "example.wav"
LANGUAGE = "en" # Transcription language
TRANSLATION_LANGUAGES = ["es","de"]

settings = ConnectionSettings(
    url="https://eu1.asr.api.speechmatics.com/v2",
    auth_token=API_KEY,
)

# Define transcription parameters
conf = {
    "type": "transcription",
    "transcription_config": {
        "language": LANGUAGE,
        "model": "enhanced"
    },
    "translation_config": {
        "target_languages":TRANSLATION_LANGUAGES
    }
}

# Open the client using a context manager
with BatchClient(settings) as client:
    try:
        job_id = client.submit_job(
            audio=PATH_TO_FILE,
            transcription_config=conf,
        )
        print(f'job {job_id} submitted successfully, waiting for transcript')

        # Note that in production, you should set up notifications instead of polling.
        # Notifications are described here: https://docs.speechmatics.com/features-other/notifications
        transcript = client.wait_for_completion(job_id, transcription_format='json-v2')
        for language in TRANSLATION_LANGUAGES:
          # Print the translation for each language from the JSON
          print(f"Translation for {language}")
          translation = ""
          for translated_segment in transcript["translations"][language]:
              translation += translated_segment["content"] + " "
          print(translation)
    except HTTPStatusError as e:
        if e.response.status_code == 401:
            print('Invalid API key - Check your API_KEY at the top of the code!')
        elif e.response.status_code == 400:
            print(e.response.json()['detail'])
        else:
            raise e

Languages​

The following languages can be translated to and from English in realtime and batch:

  • Bulgarian (bg)
  • Catalan (ca)
  • Mandarin (cmn)
  • Czech (cs)
  • Danish (da)
  • German (de)
  • Greek (el)
  • Spanish (es)
  • Estonian (et)
  • Finnish (fi)
  • French (fr)
  • Galician (gl)
  • Hindi (hi)
  • Croatian (hr)
  • Hungarian (hu)
  • Indonesian (id)
  • Italian (it)
  • Japanese (ja)
  • Korean (ko)
  • Lithuanian (lt)
  • Latvian (lv)
  • Malay (ms)
  • Dutch (nl)
  • Norwegian (no)
  • Polish (pl)
  • Portuguese (pt)
  • Romanian (ro)
  • Russian (ru)
  • Slovakian (sk)
  • Slovenian (sl)
  • Swedish (sv)
  • Turkish (tr)
  • Ukrainian (uk)
  • Vietnamese (vi)

In batch, you can also translate from Norwegian Bokmål to Nynorsk.

Best practices​

Follow these guidelines to achieve optimal translation results:

  • Use the enhanced model — Higher transcription accuracy directly leads to better translations
  • Keep punctuation enabled — Maintain all punctuation settings at default levels for optimal translation quality
  • Consider processing times — Each additional target language increases processing time in batch jobs
  • Plan for connection closing — Realtime sessions may have a 5-second delay when finalizing translations

Be aware of these limitations:

  • Language limit — Maximum 5 target languages per transcription
  • Format restrictions — Only JSON format includes translations (text and SRT formats contain source language only)
  • Reduced metadata — Certain features (timestamps, confidence scores, word tagging, and regional spelling) are only available in the original language

Next Steps​