aiTranslate
Translate audio from any language directly into English text using an AI provider.
Translate audio from any language directly into English text using an AI provider. Unlike aiTranscribe(), the output language is always English regardless of the source audio language.
Syntax
aiTranslate( audio, params={}, options={} )Note:
aiTranslate()performs speech-to-English-text translation in one step. It does not perform text-to-text translation between arbitrary languages. For audio transcription that preserves the original language, useaiTranscribe().
Parameters
audio
string or binary
✅ Yes
Audio source: local file path, public URL, or raw binary data
params
struct
No
Provider API parameters sent directly to the AI provider (e.g. model, temperature)
options
struct
No
Module-level behavior options (provider, return format, etc.)
Audio Input Detection
File path
String ending with an audio extension (.mp3, .wav, .m4a, .webm, .ogg, .flac, etc.)
URL
String starting with http:// or https://
Binary data
BoxLang binary / Java byte[] value
Params
model
string
(config default)
Translation model to use (e.g. whisper-1, whisper-large-v3)
inputFormat
string
(auto)
Audio format of binary input: mp3, wav, flac, webm, ogg, m4a, etc. Only required when passing raw byte[] data — file paths are auto-detected from their extension. Auto-seeded from audio.defaultOutputFormat in your module config when not specified
Options
provider
string
(config default)
AI provider: openai, groq
apiKey
string
(env var)
Provider API key. Falls back to <PROVIDER>_API_KEY environment variable
returnFormat
string
"text"
"text" — returns plain English string; "response" — returns AiTranscriptionResponse
responseFormat
string
"json"
Provider-level format: json, text, verbose_json, srt, vtt
timeout
numeric
90
HTTP request timeout in seconds
logRequest
boolean
false
Log request to the module log file
logRequestToConsole
boolean
false
Print request payload to the console
logResponse
boolean
false
Log response to the module log file
logResponseToConsole
boolean
false
Print raw provider response to the console
The
languageoption does not apply toaiTranslate(). The output is always English.
Provider Support
OpenAI
✅ Yes
Groq
✅ Yes
Mistral
❌ No
Gemini
❌ No
ElevenLabs
❌ No
Grok / xAI
❌ No
Returns
returnFormat: "text" (default)
string — English text
returnFormat: "response"
AiTranscriptionResponse — full response object
The returned AiTranscriptionResponse is the same object as returned by aiTranscribe(). See aiTranscribe for the full method reference.
Events Fired
beforeAITranslation
Before the translation request is sent to the provider
afterAITranslation
After the translation response is received
Examples
Basic — translate any-language audio to English
Transcribe vs translate side-by-side
Full response object
Fast translation with Groq
Translate from a URL
Translate binary audio data
See Also
Last updated