> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voxnexus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Translation Guide

> Complete guide to using VoxNexus Text Translation API

## Overview

The Translation API translates text between languages. The `/v1/translate` endpoint translates one or more texts into a single target language.

Source language is auto-detected when not specified, or you can force it explicitly.

## Translate

The `/v1/translate` endpoint translates a group of texts into a single target language.

### Basic Usage

<RequestExample>
  ```bash theme={null}
  curl -X POST "https://api.voxnexus.ai/v1/translate" \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "texts": ["第一句", "第二句"],
      "source_language": "zho_Hans",
      "target_language": "eng_Latn",
      "model_id": "vn-translate-basic"
    }'
  ```
</RequestExample>

### Request Body

<ParamField path="texts" type="array" required>
  Texts to translate. Maximum 100 items or 50,000 characters total.
</ParamField>

<ParamField path="target_language" type="string" required>
  Target language code in `<ISO 639-3>_<Script>` format, e.g. `eng_Latn`, `jpn_Jpan`, `zho_Hans`. See [Language Codes](/api-reference/translation/languages) for accepted spellings, and [Get Model Details](/api-reference/models/get-model-details) for the languages each model supports.
</ParamField>

<ParamField path="model_id" type="string" required>
  Translation model ID, e.g. `vn-translate-basic`. Use the `/v1/models?capability_type=translate` endpoint to browse available translation models.
</ParamField>

<ParamField path="source_language" type="string">
  Source language code (same format as `target_language`). Omit it, or send an empty string or `auto`, for automatic detection; providing a language forces the source language.
</ParamField>

### Response

The response is an array of translated items, in the same order as the input `texts`.

<ResponseExample>
  ```json theme={null}
  [
    {
      "text": "First sentence",
      "detected_source_language": "zho_Hans"
    },
    {
      "text": "Second sentence",
      "detected_source_language": "zho_Hans"
    }
  ]
  ```
</ResponseExample>

<ResponseField name="text" type="string">
  Translated text.
</ResponseField>

<ResponseField name="detected_source_language" type="string">
  Your `source_language` as sent, or the detected language code (e.g. `zho_Hans`) when `source_language` is omitted, empty or `auto`. See [Responses](/api-reference/translation/languages#responses).
</ResponseField>

### Response Headers

* `X-Request-ID`: Request identifier

## Discovering Translation Models

Translation models expose their routing capabilities through the `/v1/models/{model_id}` endpoint. The `translate_capability` object describes:

* `supports_auto_detect`: whether `source_language` can be omitted.
* `target_languages`: target languages reachable via auto-detection / wildcard routing.
* `source_routes`: explicit per-source-language target routes, when configured.

Language codes in these fields use the `<ISO 639-3>_<Script>` format, e.g. `eng_Latn`, `zho_Hans`.

```bash theme={null}
curl "https://api.voxnexus.ai/v1/models/vn-translate-basic" \
  -H "X-Api-Key: YOUR_API_KEY"
```

## Best Practices

### Language Codes

Use codes in the `<ISO 639-3>_<Script>` format, such as `eng_Latn` or `zho_Hans`; see [Language Codes](/api-reference/translation/languages) for the rules, and [Get Model Details](/api-reference/models/get-model-details) for the languages each model supports. When the source language is known, specifying `source_language` avoids detection overhead and improves consistency.

### Error Handling

Implement retry logic with exponential backoff for `429` responses. A `502` indicates a translation provider error, and `503` means no translation provider is currently available — both are typically transient and safe to retry.

```javascript theme={null}
async function translateTexts(texts, targetLanguage) {
  try {
    const response = await fetch('https://api.voxnexus.ai/v1/translate', {
      method: 'POST',
      headers: {
        'X-Api-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        texts,
        target_language: targetLanguage,
        model_id: 'vn-translate-basic'
      })
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error || `HTTP ${response.status}`);
    }

    const results = await response.json();
    return results.map(item => item.text);
  } catch (error) {
    console.error('Translation Error:', error);
    throw error;
  }
}
```