Translate Document

POST /v1/translate/document

Upload a document file via multipart form data and receive the fully translated document back. The original file structure, formatting, and layout are preserved. Supports 16 file formats including localization standards (XLIFF, PO, JSON, YAML) and office documents (DOCX).

Request (multipart/form-data)

Field	Type	Description
`file`	`file`	The document file to translate. See supported formats for accepted types and size limits (5–20 MB).
`source_lang`	`string`	Source language code (ISO 639-1).
`target_lang`	`string`	Target language code.
`glossary_ids`	`string`	JSON-encoded array of glossary IDs. Example: `["gloss_abc123", "gloss_def456"]`
`brand_voice_id`	`string`	Brand voice profile ID for tone/style alignment.
`tm_id`	`string`	Translation memory ID for leveraging past translations.

Response

Field	Type	Description
`data.download_url`	`string`	Pre-signed S3 URL to download the translated file. Valid for 24 hours.
`data.filename`	`string`	Original filename of the uploaded document.
`data.source_lang`	`string`	Source language code.
`data.target_lang`	`string`	Target language code.
`data.character_count`	`integer`	Total output characters translated.
`data.credits_used`	`integer`	Credits deducted for this translation.
`data.quality_score`	`integer \| null`	Average quality score across all segments (`0`–`100`). `null` if scoring is unavailable.
`data.file_data`	`string`	Base64-encoded translated file content for immediate use.
`meta.request_id`	`string`	Unique request identifier (UUID).

Error responses

Status	Code	Description
`400`	`bad_request`	Missing file, unsupported format, empty `source_lang` or `target_lang`
`400`	`unsupported_format`	File extension not in supported formats
`402`	`insufficient_credits`	Not enough credits
`429`	`rate_limit_exceeded`	Plan rate limit hit

Request examples

curl -X POST https://api.flixu.ai/v1/translate/document \
  -H "Authorization: Bearer flx_your_api_key" \
  -F "file=@localization.xliff" \
  -F "source_lang=en" \
  -F "target_lang=de" \
  -F "tm_id=tm_abc123"

const formData = new FormData();
formData.append('file', fs.createReadStream('localization.xliff'));
formData.append('source_lang', 'en');
formData.append('target_lang', 'de');
formData.append('tm_id', 'tm_abc123');

const response = await fetch('https://api.flixu.ai/v1/translate/document', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer flx_your_api_key',
  },
  body: formData,
});

const { data } = await response.json();
console.log(`Translated ${data.character_count} chars, score: ${data.quality_score}`);

// Decode and save the translated file
const buffer = Buffer.from(data.file_data, 'base64');
fs.writeFileSync('localization_de.xliff', buffer);

import requests
import base64

with open('localization.xliff', 'rb') as f:
    response = requests.post(
        'https://api.flixu.ai/v1/translate/document',
        headers={'Authorization': 'Bearer flx_your_api_key'},
        files={'file': ('localization.xliff', f)},
        data={
            'source_lang': 'en',
            'target_lang': 'de',
            'tm_id': 'tm_abc123',
        },
    )

result = response.json()
print(f"Quality: {result['data']['quality_score']}")

# Save the translated file
file_bytes = base64.b64decode(result['data']['file_data'])
with open('localization_de.xliff', 'wb') as out:
    out.write(file_bytes)

Response example

{
  "data": {
    "download_url": "https://s3.amazonaws.com/flixu-translations/abc-localization.xliff?...",
    "filename": "localization.xliff",
    "source_lang": "en",
    "target_lang": "de",
    "character_count": 12450,
    "credits_used": 12450,
    "quality_score": 91,
    "file_data": "PD94bWwgdmVyc2lvbj0i..."
  },
  "meta": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "credits_used": 12450,
    "processing_time_ms": 8340
  }
}