> For the complete documentation index, see [llms.txt](https://ai.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai.ortusbooks.com/main-components/audio/audio-translation.md). # 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()`](/main-components/audio/speech-to-text.md) instead. ## How It Works ```mermaid flowchart LR A["🎤 Audio\n(any language)"] --> B["aiTranslate()"] B --> C["📝 English Text"] style A fill:#4a90d9,color:#fff style B fill:#7b68ee,color:#fff style C fill:#27ae60,color:#fff ``` ## `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 ```javascript aiTranslate( audio, params={}, options={} ) ``` The signature is identical to [`aiTranscribe()`](/main-components/audio/speech-to-text.md). 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 ```javascript english = aiTranslate( "/recordings/french-meeting.mp3" ) println( english ) // "Good morning everyone. Today we will discuss the quarterly results." ``` ### Transcribe vs translate — side by side ```javascript 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 ```javascript 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 ```javascript english = aiTranslate( "/recordings/japanese-interview.mp3", { model: "whisper-large-v3" }, { provider: "groq" } ) println( english ) ``` ### Translate from a URL ```javascript english = aiTranslate( "https://cdn.example.com/audio/portuguese-speech.mp3" ) println( english ) ``` ### Translate binary audio data ```javascript 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 ```javascript english = aiTranslate() .file( "/recordings/french-meeting.mp3" ) .translate() ``` ### Fluent Examples ```javascript // 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` | ```javascript BoxRegisterInterceptor( "afterAITranslation", event => { println( "Translated #event.result.getWordCount()# English words via #event.service.getName()#" ) }) ``` *** ## 📖 Related Pages * [Audio Overview](/main-components/audio.md) * [Text-to-Speech](/main-components/audio/text-to-speech.md) * [Speech-to-Text](/main-components/audio/speech-to-text.md) * [aiTranslate BIF Reference](/advanced/reference/built-in-functions/aitranslate.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai.ortusbooks.com/main-components/audio/audio-translation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.