Doc Studio

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.

InputOutput (outputFormat)CreditsBilling operation
PDFdocx (default), pdf, epub45 per pagetranslate_text, or ocr_translate with ocr: true
DOCXdocx (default), pdf, epub45 per pagetranslate_text
PPTXpptx (default), pdf45 per slidetranslate_text
Images (uploadIds)docx (default), pdf, epub45 per imageimage_translate

Request Schema

uploadIdstringoptional

Upload ID from POST /v1/uploads of a PDF, DOCX or PPTX. Send either uploadId or uploadIds.

uploadIdsstring[]optional

Instead 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.

targetLanguagestringrequired

Language to translate into, by name (for example Hindi) or code (hi). See Target languages below.

regionalVariantstringoptional

Dialect or locale of the target language, for example Latin America Spanish or es-419. Only for languages listed under Regional variants below.

tonestringoptionaldefault: professional

Writing style of the translation.

Allowed values:
professionaleasy_to_understandcasual
additionalInstructionsstringoptional

Extra guidance for the translator, up to 500 characters, for example Keep product names in English.

targetAudiencestringoptional

Who the text is for. Use a preset or your own description, up to 200 characters.

Allowed values:
generalprofessionaltechnicalchildrenacademicexecutive
translationStylestringoptional

How the text should read. Use a preset or your own description, up to 200 characters.

Allowed values:
standardtechnicalcreativesimplifiedconcise
modelstringoptionaldefault: basic

Translation 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.

Allowed values:
basicpro
ocrbooleanoptionaldefault: false

PDFs only: read the pages with OCR. Use it for scanned PDFs. Images always use OCR; ocr: true on a DOCX or PPTX returns 400.

outputFormatstringoptional

File type of the result. PDF, DOCX and images: docx (default), pdf or epub. PPTX: pptx (default) or pdf.

Allowed values:
docxpptxpdfepub
pageLayoutobjectoptional

PDF 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.

webhookUrlstringoptional

Top-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.

GroupLanguages (code)
EuropeanAlbanian (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)
IndicAssamese (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)
AsianBurmese (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 & AfricanAfrikaans (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)
OtherGuarani (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 languageAccepted regionalVariant values
BosnianLatin Bosnian (bs); Cyrillic Bosnian (bs-Cyrl)
BulgarianStandard Bulgarian; Western Bulgarian
CzechStandard Czech; Moravian Czech
DanishStandard Danish; Jutlandic Danish
DutchNetherlands Dutch (nl); Belgian Dutch (Flemish) (nl-BE)
EnglishUS 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)
FinnishFinland Finnish; Karelian-influenced Finnish
FrenchFrance French (fr); Canadian French (fr-CA); Belgian French; Swiss French (fr-CH)
GermanGermany German; Austrian German; Swiss German
GreekGreece Greek; Cypriot Greek
HungarianHungary Hungarian; Transylvanian Hungarian
ItalianStandard Italian; Swiss Italian
NorwegianStandard Norwegian (no); Norwegian Bokmål (nb)
PolishStandard Polish; Silesian-influenced Polish
PortugueseBrazil Portuguese (pt-BR); Portugal Portuguese (pt-PT); Angola Portuguese
RomanianRomania Romanian; Moldovan Romanian
RussianRussia Russian; Belarus Russian; Kazakhstan Russian
Serbo-CroatianSerbian; Croatian; Bosnian; Montenegrin
SlovakWestern Slovak; Central Slovak; Eastern Slovak
SpanishSpain 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)
SwedishSweden Swedish; Finland Swedish
UkrainianStandard Ukrainian; Western Ukrainian
AssameseStandard Assamese; Goalpariya Assamese
BengaliBangladesh Bengali; West Bengal Bengali (bn-IN)
DogriJammu Dogri; Himachali Dogri
GujaratiStandard Gujarati; Kathiawadi Gujarati; Surti Gujarati
HindiStandard Hindi; Hindustani; Mumbai Hindi; Delhi Hindi
KannadaMysore Kannada; North Karnataka Kannada; Coastal Kannada
KashmiriKashmiri (Perso-Arabic); Kashmiri (Devanagari)
KonkaniGoan Konkani; Mangalorean Konkani; Malvani Konkani
MaithiliBihar Maithili; Nepal Maithili
MalayalamKerala Malayalam; Malabar Malayalam; Travancore Malayalam
ManipuriMeitei (Bengali Script); Meitei Mayek
MarathiStandard Marathi; Varhadi Marathi; Konkani-Marathi
NepaliNepal Nepali; Indian Nepali
OdiaStandard Odia; Sambalpuri Odia
PunjabiIndian Punjabi (Gurmukhi); Pakistani Punjabi (Shahmukhi) (pa-PK); Majhi Punjabi
SantaliOl Chiki Santali; Bengali-script Santali; Odia-script Santali
SindhiArabic-script Sindhi; Devanagari Sindhi
TamilIndia Tamil; Sri Lankan Tamil; Singapore Tamil; Malaysian Tamil
TeluguAndhra Telugu; Telangana Telugu
UrduPakistani Urdu; Indian Urdu
ChineseSimplified 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
ArabicModern Standard Arabic (ar); Saudi Arabic (ar-SA); Gulf Arabic; UAE Arabic; Egyptian Arabic; Levantine Arabic; Iraqi Arabic; Moroccan Arabic
PersianStandard Persian (fa); Iranian Persian

Tones

toneEffect
professionalFormal, precise wording suited to business and official documents. Default.
easy_to_understandPlain, simple wording for a general audience.
casualRelaxed, 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.

201 Created: POST /v1/jobs
{
  "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.

200 OK: GET /v1/jobs/{id} after the job succeeds
{
  "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

HTTPCodeWhen
400invalid_inputMissing 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.
402insufficient_creditsThe wallet can't cover the estimate, or a test key's estimate is above its spend cap.
409conflictThe Idempotency-Key was already used with a different input.