---
name: docsrtl
description: Translate DOCX, DOC, ODT, RTF, and PDF documents into Hebrew, Arabic, Persian, or Urdu (or 35 other LTR languages) while preserving fonts, paragraph styles, nested tables, hyperlinks, headers, and footers. Use when a user needs a formatted document translation - not just plain text - and especially when the target is right-to-left and layout fidelity matters. Powered by the DocsRTL REST API at https://docsrtl.com/v1.
---

# DocsRTL - RTL document translation

DocsRTL translates Word documents into right-to-left languages (Hebrew, Arabic, Persian, Urdu) and 35 LTR languages while keeping the document visually identical to the source. Fonts, styles, tables, hyperlinks, headers, and footers all survive the round trip. Output is a valid `.docx` file ready to open in Word or Google Docs.

Use this skill when the user wants to translate a document file (not a string) and cares about formatting. Plain machine translation tools flatten layout; DocsRTL does not.

## When to use

- "Translate this contract to Hebrew and keep the formatting"
- "Convert this PDF report to Arabic"
- "I need this Word document in Persian by tomorrow"
- "Translate the attached file - tables and styles must stay intact"

Skip this skill for short strings, chat messages, or anything where formatting does not matter - those are better handled by direct LLM translation.

## Setup

Set your API key as an environment variable. Pro plan or higher is required for API access. Get a key at https://docsrtl.com/api-keys.

```bash
export DOCSRTL_API_KEY=drtl_your_key_here
```

The base URL is `https://docsrtl.com/v1`. Authentication uses the `X-API-Key` header.

## Supported formats and languages

**Input formats:** `.docx`, `.doc`, `.odt`, `.rtf`, `.pdf` (max 50 MB)

**RTL target languages (full layout reversal):**

| Language | Value to send |
|----------|---------------|
| Hebrew   | `Hebrew`      |
| Arabic   | `Arabic`      |
| Persian  | `Persian`     |
| Urdu     | `Urdu`        |

**LTR target languages also supported:** English, French, Spanish, German, Italian, Portuguese, Dutch, Russian, Polish, Ukrainian, Romanian, Hungarian, Czech, Slovak, Bulgarian, Croatian, Greek, Swedish, Danish, Finnish, Norwegian, Turkish, Indonesian, Malay, Vietnamese, Thai, Chinese (Simplified and Traditional), Japanese, Korean, Hindi, Bengali, Tamil, Swahili, Amharic.

For the live list, fetch `GET https://docsrtl.com/v1/languages`.

## Workflow

The translation API is asynchronous. Three steps: submit, poll, download.

### 1. Submit a document

Upload a file with multipart/form-data:

```bash
curl -X POST https://docsrtl.com/v1/translate \
  -H "X-API-Key: $DOCSRTL_API_KEY" \
  -F "file=@/path/to/contract.docx" \
  -F "target_lang=Arabic"
```

Response (HTTP 202):

```json
{ "job_id": "abc123-...", "status": "pending" }
```

Optional form fields:

- `source_lang` - default `auto`. Specify when auto-detection is unreliable.
- `translation_mode` - `professional` (default) or `casual`.

### 2. Poll for completion

```bash
curl https://docsrtl.com/v1/jobs/abc123 \
  -H "X-API-Key: $DOCSRTL_API_KEY"
```

Response shapes:

```json
{ "job_id": "abc123", "status": "processing" }
```

```json
{
  "job_id": "abc123",
  "status": "completed",
  "source_lang": "English",
  "target_lang": "Arabic",
  "download_url": "/v1/jobs/abc123/download",
  "rtl_fidelity": { "status": "full", "warnings": [] }
}
```

```json
{ "job_id": "abc123", "status": "failed", "error": "..." }
```

Poll roughly every 3-5 seconds. Most jobs finish within 10-60 seconds; large documents can take a few minutes.

### 3. Download the translated file

```bash
curl https://docsrtl.com/v1/jobs/abc123/download \
  -H "X-API-Key: $DOCSRTL_API_KEY" \
  -o translated.docx
```

The translated file is retained for 10 minutes after completion, then deleted. Download promptly.

## Translate from a URL (no upload)

When you cannot upload a binary - for example from a sandboxed agent runtime - submit a publicly reachable HTTPS URL instead:

```bash
curl -X POST https://docsrtl.com/v1/translate-url \
  -H "X-API-Key: $DOCSRTL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/contract.docx",
    "target_lang": "Hebrew"
  }'
```

The URL must be over HTTPS and serve a supported format. The file is fetched server-side, then the same poll + download flow applies.

## Reference Python implementation

```python
import os
import time
import httpx

API_KEY = os.environ["DOCSRTL_API_KEY"]
BASE_URL = "https://docsrtl.com/v1"
HEADERS = {"X-API-Key": API_KEY}


def translate_document(path: str, target_lang: str, output_path: str) -> dict:
    """Submit a document, wait for translation, save the result.

    Args:
        path: Local path to the source document.
        target_lang: One of Hebrew, Arabic, Persian, Urdu, or any
            supported LTR language name.
        output_path: Where to write the translated .docx.

    Returns:
        The final job status payload.
    """
    with httpx.Client(timeout=60.0) as client:
        with open(path, "rb") as fh:
            r = client.post(
                f"{BASE_URL}/translate",
                headers=HEADERS,
                files={"file": (os.path.basename(path), fh)},
                data={"target_lang": target_lang},
            )
        r.raise_for_status()
        job_id = r.json()["job_id"]

        while True:
            r = client.get(f"{BASE_URL}/jobs/{job_id}", headers=HEADERS)
            r.raise_for_status()
            job = r.json()
            if job["status"] == "completed":
                break
            if job["status"] == "failed":
                raise RuntimeError(job.get("error", "translation failed"))
            time.sleep(3)

        r = client.get(f"{BASE_URL}/jobs/{job_id}/download", headers=HEADERS)
        r.raise_for_status()
        with open(output_path, "wb") as out:
            out.write(r.content)

    return job


if __name__ == "__main__":
    job = translate_document("contract.docx", "Hebrew", "contract_he.docx")
    print(job)
```

## Webhooks (avoid polling)

For long jobs or batch workflows, register a webhook URL and DocsRTL will POST to it on completion. See https://docsrtl.com/docs/webhooks for the HMAC verification recipe.

## Errors

All error responses use the same shape:

```json
{ "detail": { "error": "human message", "code": "machine_code" } }
```

Common codes:

- `invalid_language` - target language not supported. Fetch `/v1/languages`.
- `unsupported_format` - input is not `.docx`, `.doc`, `.odt`, `.rtf`, or `.pdf`.
- `magic_mismatch` - file extension does not match its actual content.
- `file_too_large` - source file exceeds 50 MB.
- `job_not_found` - job id is wrong or has expired.
- `not_ready` - tried to download before status was `completed`.
- `file_expired` - more than 10 minutes since completion; resubmit.

HTTP 401 means the API key is missing or invalid. HTTP 402 means the user is on a plan without API access - direct them to https://docsrtl.com/pricing to upgrade.

## Useful links

- Landing page for agents: https://docsrtl.com/for-agents
- API reference: https://docsrtl.com/docs/api
- OpenAPI spec: https://docsrtl.com/v1/openapi.json
- Function calling spec (OpenAI tools): https://docsrtl.com/v1/openapi-functions.json
- GPT Actions spec: https://docsrtl.com/v1/openapi-gpt-actions.json
- Pricing and API access: https://docsrtl.com/pricing