Translation
Translate documents while preserving exact layout, tables, formatting, and fonts.
document.translate runs a multi-pass translation engine that deconstructs PDF, DOCX, or PPTX documents into structural chunks, performs localized contextual translation, and recomposes output files while preserving vector graphics and formatting.
| Input | Output (outputFormat) | Credits | Billing operation |
|---|---|---|---|
| docx (default), pdf, epub | 45 per page | translate_text, or ocr_translate with ocr: true | |
| DOCX | docx (default), pdf, epub | 45 per page | translate_text |
| PPTX | pptx (default), pdf | 45 per slide | translate_text |
| Images (uploadIds) | docx (default), pdf, epub | 45 per image | image_translate |
Request Schema
uploadIdstringoptionalUpload ID from POST /v1/uploads of a PDF, DOCX or PPTX. Send either uploadId or uploadIds.
uploadIdsstring[]optionalInstead of uploadId: up to 50 image uploads (JPG, JPEG, PNG, WEBP), in reading order, translated as one document. No duplicates; PDFs can't be mixed in. Images always use OCR.
targetLanguagestringrequiredLanguage to translate into, by name (for example Hindi) or code (hi). See Target languages below.
regionalVariantstringoptionalDialect or locale of the target language, for example Latin America Spanish or es-419. Only for languages listed under Regional variants below.
tonestringoptionaldefault: professionalWriting style of the translation.
additionalInstructionsstringoptionalExtra guidance for the translator, up to 500 characters, for example Keep product names in English.
targetAudiencestringoptionalWho the text is for. Use a preset or your own description, up to 200 characters.
translationStylestringoptionalHow the text should read. Use a preset or your own description, up to 200 characters.
modelstringoptionaldefault: basicTranslation model. pro uses a stronger model for difficult or high-stakes text; the price is the same. premium is accepted as an alias for pro.
ocrbooleanoptionaldefault: falsePDFs only: read the pages with OCR. Use it for scanned PDFs. Images always use OCR; ocr: true on a DOCX or PPTX returns 400.
outputFormatstringoptionalFile type of the result. PDF, DOCX and images: docx (default), pdf or epub. PPTX: pptx (default) or pdf.
pageLayoutobjectoptionalPDF and DOCX only: page size and print area of the output, in inches. pageWidthIn and pageHeightIn (above 1, up to 40), matterWidthIn and matterHeightIn (above 0.5, up to 40), and optional matterLeftIn and matterTopIn offsets from the top-left corner (centred when left out). The print area must fit inside the page.
webhookUrlstringoptionalTop-level field, next to operation and input. HTTPS URL that receives a signed POST when the job starts running, succeeds or fails. Private and internal hosts are rejected; up to 2048 characters.
Target languages
targetLanguage accepts any of these 118 languages, by name (case-insensitive) or by the code in brackets. Anything else returns 400 invalid_input.
| Group | Languages (code) |
|---|---|
| European | Albanian (sq), Basque (eu), Belarusian (be), Bosnian (bs), Bulgarian (bg), Catalan (ca), Corsican (co), Croatian (hr), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), Frisian (fy), French (fr), Galician (gl), German (de), Greek (el), Hungarian (hu), Icelandic (is), Irish (ga), Italian (it), Latin (la), Latvian (lv), Lithuanian (lt), Luxembourgish (lb), Macedonian (mk), Maltese (mt), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Scots Gaelic (gd), Serbo-Croatian (sh), Serbian (sr), Slovak (sk), Slovenian (sl), Spanish (es), Swedish (sv), Ukrainian (uk), Welsh (cy), Yiddish (yi) |
| Indic | Assamese (as), Bengali (bn), Bhojpuri (bho), Dogri (doi), Gujarati (gu), Hindi (hi), Kannada (kn), Kashmiri (ks), Konkani (kok), Maithili (mai), Malayalam (ml), Manipuri (mni), Marathi (mr), Nepali (ne), Odia (or), Punjabi (pa), Sanskrit (sa), Santali (sat), Sindhi (sd), Tamil (ta), Telugu (te), Urdu (ur) |
| Asian | Burmese (my), Cebuano (ceb), Chinese (zh), Filipino (fil), Hawaiian (haw), Hmong (hmn), Indonesian (id), Japanese (ja), Javanese (jv), Kazakh (kk), Khmer (km), Korean (ko), Kyrgyz (ky), Lao (lo), Malay (ms), Maori (mi), Mongolian (mn), Pashto (ps), Samoan (sm), Sinhala (si), Sundanese (su), Tajik (tg), Thai (th), Turkmen (tk), Uzbek (uz), Vietnamese (vi) |
| Middle Eastern & African | Afrikaans (af), Amharic (am), Arabic (ar), Armenian (hy), Azerbaijani (az), Chichewa (ny), Georgian (ka), Hausa (ha), Hebrew (he), Igbo (ig), Kinyarwanda (rw), Lingala (ln), Malagasy (mg), Oromo (om), Persian (fa), Sesotho (st), Shona (sn), Somali (so), Swahili (sw), Tigrinya (ti), Turkish (tr), Xhosa (xh), Yoruba (yo), Zulu (zu) |
| Other | Guarani (gn) |
Regional variants
regionalVariant is optional and only applies to the languages below. Pass the variant name exactly as written, or the code in brackets where one is shown. A variant that doesn't belong to the chosen targetLanguage returns 400 invalid_input. Leave it out to use the language's standard form.
| Target language | Accepted regionalVariant values |
|---|---|
| Bosnian | Latin Bosnian (bs); Cyrillic Bosnian (bs-Cyrl) |
| Bulgarian | Standard Bulgarian; Western Bulgarian |
| Czech | Standard Czech; Moravian Czech |
| Danish | Standard Danish; Jutlandic Danish |
| Dutch | Netherlands Dutch (nl); Belgian Dutch (Flemish) (nl-BE) |
| English | US English (en-US); UK English (en-GB); Indian English (en-IN); Australian English (en-AU); Canadian English (en-CA); South African English (en-ZA); Philippines English (en-PH); New Zealand English (en-NZ) |
| Finnish | Finland Finnish; Karelian-influenced Finnish |
| French | France French (fr); Canadian French (fr-CA); Belgian French; Swiss French (fr-CH) |
| German | Germany German; Austrian German; Swiss German |
| Greek | Greece Greek; Cypriot Greek |
| Hungarian | Hungary Hungarian; Transylvanian Hungarian |
| Italian | Standard Italian; Swiss Italian |
| Norwegian | Standard Norwegian (no); Norwegian Bokmål (nb) |
| Polish | Standard Polish; Silesian-influenced Polish |
| Portuguese | Brazil Portuguese (pt-BR); Portugal Portuguese (pt-PT); Angola Portuguese |
| Romanian | Romania Romanian; Moldovan Romanian |
| Russian | Russia Russian; Belarus Russian; Kazakhstan Russian |
| Serbo-Croatian | Serbian; Croatian; Bosnian; Montenegrin |
| Slovak | Western Slovak; Central Slovak; Eastern Slovak |
| Spanish | Spain Spanish (es-ES); Mexican Spanish (es-MX); Argentine Spanish (es-AR); Colombian Spanish (es-CO); Chilean Spanish (es-CL); Peruvian Spanish (es-PE); US Spanish (es-US); Latin America Spanish (es-419) |
| Swedish | Sweden Swedish; Finland Swedish |
| Ukrainian | Standard Ukrainian; Western Ukrainian |
| Assamese | Standard Assamese; Goalpariya Assamese |
| Bengali | Bangladesh Bengali; West Bengal Bengali (bn-IN) |
| Dogri | Jammu Dogri; Himachali Dogri |
| Gujarati | Standard Gujarati; Kathiawadi Gujarati; Surti Gujarati |
| Hindi | Standard Hindi; Hindustani; Mumbai Hindi; Delhi Hindi |
| Kannada | Mysore Kannada; North Karnataka Kannada; Coastal Kannada |
| Kashmiri | Kashmiri (Perso-Arabic); Kashmiri (Devanagari) |
| Konkani | Goan Konkani; Mangalorean Konkani; Malvani Konkani |
| Maithili | Bihar Maithili; Nepal Maithili |
| Malayalam | Kerala Malayalam; Malabar Malayalam; Travancore Malayalam |
| Manipuri | Meitei (Bengali Script); Meitei Mayek |
| Marathi | Standard Marathi; Varhadi Marathi; Konkani-Marathi |
| Nepali | Nepal Nepali; Indian Nepali |
| Odia | Standard Odia; Sambalpuri Odia |
| Punjabi | Indian Punjabi (Gurmukhi); Pakistani Punjabi (Shahmukhi) (pa-PK); Majhi Punjabi |
| Santali | Ol Chiki Santali; Bengali-script Santali; Odia-script Santali |
| Sindhi | Arabic-script Sindhi; Devanagari Sindhi |
| Tamil | India Tamil; Sri Lankan Tamil; Singapore Tamil; Malaysian Tamil |
| Telugu | Andhra Telugu; Telangana Telugu |
| Urdu | Pakistani Urdu; Indian Urdu |
| Chinese | Simplified Chinese (zh-Hans); Traditional Chinese (zh-Hant); Mainland China Mandarin (Simplified) (zh-CN); Taiwan Mandarin (Traditional) (zh-TW); Hong Kong Chinese (zh-HK); Singapore Mandarin |
| Arabic | Modern Standard Arabic (ar); Saudi Arabic (ar-SA); Gulf Arabic; UAE Arabic; Egyptian Arabic; Levantine Arabic; Iraqi Arabic; Moroccan Arabic |
| Persian | Standard Persian (fa); Iranian Persian |
Tones
| tone | Effect |
|---|---|
| professional | Formal, precise wording suited to business and official documents. Default. |
| easy_to_understand | Plain, simple wording for a general audience. |
| casual | Relaxed, conversational wording. |
Unrecognised tone values fall back to professional.
Code Example
curl -X POST https://api.transpera.io/v1/jobs \
-H "authorization: Bearer tp_test_..." \
-H "content-type: application/json" \
-H "idempotency-key: $(uuidgen)" \
-d '{
"operation": "document.translate",
"input": {
"uploadId": "c3a9f0b2-1d4e-4f6a-8b2c-9e1d3f5a7b9c",
"targetLanguage": "Spanish",
"regionalVariant": "Latin America Spanish",
"tone": "professional",
"targetAudience": "executive",
"model": "pro",
"outputFormat": "pdf"
},
"webhookUrl": "https://api.yourdomain.com/webhooks/transpera"
}'Response
POST /v1/jobs answers 201 Created with the new job. status moves from queued to running to succeeded or failed; poll GET /v1/jobs/{id} or use webhookUrl. If the job could not be handed to the worker, it comes back already failed with errorCode enqueue_failed and nothing is charged.
{
"job": {
"id": "8f1c2d3e-4b5a-6789-abcd-ef0123456789",
"operation": "document.translate",
"status": "queued",
"createdAt": "2026-11-20T09:30:00.000Z",
"errorCode": null,
"chargedCredits": null
}
}Result
When status is succeeded, result is a file. url is a signed download link valid for one hour; fetch the job again for a fresh link. GET /v1/jobs (the list) never includes result. The file type is the requested outputFormat: by default DOCX, or PPTX for PPTX sources.
{
"job": {
"id": "8f1c2d3e-4b5a-6789-abcd-ef0123456789",
"operation": "document.translate",
"status": "succeeded",
"createdAt": "2026-11-20T09:30:00.000Z",
"errorCode": null,
"chargedCredits": 450,
"result": {
"type": "file",
"fileName": "report_es.docx",
"url": "https://storage.googleapis.com/...",
"expiresAt": "2026-11-20T10:45:00.000Z"
}
}
}Errors
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_input | Missing targetLanguage, both or neither of uploadId and uploadIds, an unknown language or regional variant, an upload that isn't PDF, DOCX, PPTX or an image, an upload from another key, an outputFormat the source can't produce, ocr on a DOCX or PPTX, pageLayout on slides or images or a print area that doesn't fit, an unknown model, text over its length limit, or a non-HTTPS webhookUrl. |
| 402 | insufficient_credits | The wallet can't cover the estimate, or a test key's estimate is above its spend cap. |
| 409 | conflict | The Idempotency-Key was already used with a different input. |