> 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                                  |
| **Cartesia**   | ❌ No (throws `UnsupportedCapability`) |
| **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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ai.ortusbooks.com/main-components/audio/audio-translation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.