Audio Translation

Translate spoken audio from any language directly into English text using AI providers. aiTranslate() is distinct from text translation — it converts speech to English in a single transcription step.

aiTranslate() converts spoken audio in any language directly into English text. This is distinct from text-to-text language translation — think of it as "transcribe and translate in one step."

🚨 Important: aiTranslate() does NOT translate between arbitrary languages. It always produces English output regardless of the source language. If you need to transcribe audio and preserve the original language, use aiTranscribe() instead.

How It Works

aiTranscribe() vs aiTranslate()

	aiTranscribe()	aiTranslate()
Output language	Same as input audio	Always English
Source audio	Any language	Any language
Use case	Preserve original speech	Understand any-language audio in English
Providers	OpenAI, Groq	OpenAI, Groq

Provider Support

Provider	Supported
OpenAI	✅ Yes
Groq	✅ Yes
Mistral	❌ No
Gemini	❌ No
ElevenLabs	❌ No
Grok / xAI	❌ No

🔧 The aiTranslate() Function

Syntax

aiTranslate( audio, params={}, options={} )

The signature is identical to aiTranscribe(). All parameters, options, and returns are the same.

Parameters

Parameter	Type	Required	Description
audio	string or binary	✅ Yes	File path, URL, or raw binary audio data
params	struct	No	Provider API parameters (model, temperature, etc.)
options	struct	No	Module-level options (provider, returnFormat, responseFormat, etc.)

Options

Option	Type	Default	Description
provider	string	(config)	openai or groq
apiKey	string	(env var)	Provider API key
returnFormat	string	"text"	"text" — plain string; "response" — AiTranscriptionResponse
responseFormat	string	"json"	json, text, verbose_json, srt, vtt
timeout	numeric	30	HTTP timeout in seconds
logRequest	boolean	false	Log requests to the module log file
logRequestToConsole	boolean	false	Print request payload to console
logResponse	boolean	false	Log responses
logResponseToConsole	boolean	false	Print raw provider response to console

The language option does not apply to aiTranslate() — the output language is always English.

💡 Examples

Basic — translate any-language audio to English

english = aiTranslate( "/recordings/french-meeting.mp3" )
println( english )
// "Good morning everyone. Today we will discuss the quarterly results."

Transcribe vs translate — side by side

spanishAudio = "/recordings/hola-mundo.mp3"

// Transcribes — keeps original Spanish
spanish = aiTranscribe( spanishAudio )
println( "Original: #spanish#" )
// "Hola mundo, bienvenido a BoxLang AI."

// Translates — always returns English
english = aiTranslate( spanishAudio )
println( "English: #english#" )
// "Hello world, welcome to BoxLang AI."

Full response object

result = aiTranslate(
    "/recordings/german-presentation.mp3",
    {},
    { returnFormat: "response", responseFormat: "verbose_json" }
)

println( "English text: #result.getText()#" )
println( "Duration: #result.getFormattedDuration()#" )
println( "Words: #result.getWordCount()#" )

Fast translation with Groq

english = aiTranslate(
    "/recordings/japanese-interview.mp3",
    { model: "whisper-large-v3" },
    { provider: "groq" }
)
println( english )

Translate from a URL

english = aiTranslate( "https://cdn.example.com/audio/portuguese-speech.mp3" )
println( english )

Translate binary audio data

binaryAudio = fileReadBinary( "/tmp/upload.m4a" )
english = aiTranslate( binaryAudio )
println( english )

🧱 Fluent Builder API (v3.2.0+)

Calling aiTranslate() with no arguments returns an AiTranscriptionRequest builder object for method chaining. The builder shares the same methods as aiTranscribe() — the only difference is the .translate() terminator.

Basic Builder Usage

english = aiTranslate()
    .file( "/recordings/french-meeting.mp3" )
    .translate()

Fluent Examples

// From URL
english = aiTranslate()
    .url( "https://cdn.example.com/audio/german-speech.mp3" )
    .translate()

// From binary data
english = aiTranslate()
    .data( fileReadBinary( "/tmp/upload.m4a" ) )
    .asText()
    .translate()

// With Groq for speed
english = aiTranslate()
    .file( "/recordings/japanese-interview.mp3" )
    .provider( "groq" )
    .model( "whisper-large-v3" )
    .translate()

// Get full response object
result = aiTranslate()
    .file( "/recordings/german-presentation.mp3" )
    .asVerboseJSON()
    .withOptions( { returnFormat: "response" } )
    .translate()

println( "English text: #result.getText()#" )
println( "Duration: #result.getFormattedDuration()#" )

💡 Backward Compatible: The traditional aiTranslate( audio, params, options ) syntax continues to work unchanged. The fluent builder is an additional option — no migration required.

📡 Events

Event	Data Available
beforeAITranslation	transcriptionRequest, service
afterAITranslation	transcriptionRequest, service, result

BoxRegisterInterceptor( "afterAITranslation", event => {
    println( "Translated #event.result.getWordCount()# English words via #event.service.getName()#" )
})

---

📖 Related Pages

• Audio Overview
• Text-to-Speech
• Speech-to-Text
• aiTranslate BIF Reference