Getting started with document translation

What is document translation

Document translation takes an uploaded file and returns a translated file instead of a translated string. Use document translation for content that lives in files rather than strings in a database: manuals, contracts, course materials, and exports.

Supported source uploads are txt, md, html, json, csv, docx, pptx, and born-digital pdf.

The flow at a glance

Document translation runs through the document job endpoints POST /api/v1/translate/documents/jobs and GET /api/v1/translate/documents/jobs/:jobId, documented in the documents docs. The flow has four steps:

1. The user creates a job with the desired translation settings.
2. The user uploads the document to storage through a resumable session.
3. The job is validated and sent for asynchronous processing in the background.
4. The user polls status or waits for a webhook, and then fetches the result as a signed download URL or a stream.

Why the job is created before the upload

Creating the job first provides a durable reference to track before the document upload begins and it keeps large requests off the job creation path, so payload limits never become an issue.

Even if the document upload is interrupted, it can simply be resumed from the tracked state. No need to restart the whole upload.

Create the job

POST /api/v1/translate/documents/jobs creates the job and returns upload instructions. The create payload declares the file and every translation setting up front:

• file.name, file.contentType, and file.sizeBytes declare what is coming, and file.sha256 is an optional checksum for upload integrity validation
• job.callbackUrl or job.webhookProfileId configure completion delivery, and job.resultTtlSeconds sets the result retention window, subject to provider policy limits
• request.request_id traces the job, request.src and request.tgt set the language pair (an empty request.src requests auto-detection), request.glossary_id pins the stored glossary selection at job creation, and request.do_not_translate and request.preserve_placeholders carry protected terms and placeholder detection

The create route only creates metadata and returns upload instructions. The response returns jobId, an initial status of pending_upload, the upload strategy and uploadUrl, and the statusUrl, resultUrl, cancelUrl, and partsUrl you use for the rest of the flow. The create fields are in the documents docs. Document job endpoints accept API keys under the premium quota path, and keys are created in the API keys docs.

Upload the document

Upload the document directly to the returned uploadUrl with PUT, using the content-type from uploadHeaders. The session is resumable, so a large file on a slow connection does not restart from zero when the connection drops.

For chunked uploads, repeat PUT requests with a Content-Range: bytes START-END/TOTAL header until the upload is finalized. If the upload session expires before completion, call partsUrl to create a fresh resumable session for the same pending job.

The job records the declared expectedSizeBytes and the observed uploadedSizeBytes, so you can confirm what arrived against what the create request promised. If you provided file.sha256 at creation, you can verify the uploaded object against the checksum as well; a byte count alone does not catch content that was truncated in place. Error and rate-limit behavior for the API is documented in the errors and rate limits docs.

Upload validation

Once the upload completes and a worker is assigned, several verification steps are ran to confirm that:

• the object exists in storage
• the object size is stable, meaning uploadedSizeBytes matches what the upload declared
• the file type matches what the job declared
• a screening pass runs before any extraction code touches the bytes

This initial validation ensures that later stages are retry-safe, as any retries are run against a known-complete object. A job whose upload never settles stays visible in pending_upload or upload_received, which provides a defined state to inspect rather than a stuck request, and a job in a non-terminal state can be canceled through the cancelUrl returned at creation. Status and summary fields are documented in the documents docs.

Only then does extraction begin. This ordering is what makes a retry safe: the retry re-runs against a known-complete object instead of whatever was partially written last time. Once validated, the job moves through extracting, translating, assembling, and completed, with failed and canceled as additional terminal states.

Extraction and processing through the asynchronous pipeline

Supported source uploads are txt, md, html, json, csv, docx, pptx, and born-digital pdf. TXT, MD, HTML, JSON, and CSV infer their matching content mode and keep their structure. DOCX, PPTX, and PDF are extracted into plain UTF-8 text before translation and come back as translated UTF-8 text files.

Once the text is extracted, it is divided into one or more units, each handled independently, depending on the text length and split_input flag. Each unit is then fed through the same scheduler and execution workers as text-only asynchronous requests. Same queue, retry policy, and quota accounting. Additional details are in the asynchronous docs.

Poll status and fetch the result

Poll GET /api/v1/translate/documents/jobs/:jobId for status and summary: fileName, sourceFormat, targetFormat, expectedSizeBytes, uploadedSizeBytes, inputCharacters, and outputCharacters.

When the job reaches completed, fetch GET /api/v1/translate/documents/jobs/:jobId/result. The response returns a signed downloadUrl with an expiresAt window plus the translated fileName, contentType, and sizeBytes. GET /api/v1/translate/documents/jobs/:jobId/stream streams the completed file directly instead of handing out a URL.

Callbacks cover failures as well as completions. The job status includes callback state such as deliveredAt, lastError, and attempts, so you can tell a translation failure from a delivery failure. Callback fields are described in the async docs.

What the output looks like per format

• TXT, MD, HTML, JSON, CSV: the translated output keeps the matching content mode, and the delivered format matches the source format.
• DOCX, PPTX, PDF: extracted to plain text, translated, and finalized as a translated UTF-8 text file named like support-guide.translated.txt. These formats currently do not reconstruct office or PDF binaries.

Character counts come back in the result as input_characters and output_characters, the same accounting used across the platform (usage docs). Document jobs run under the API key quota path described in the authentication docs. Language tags follow the canonical set in the languages reference. Completion callbacks go to job.callbackUrl or the configured webhook profile (webhooks docs).

What the flow gives you

Failed uploads resume instead of restarting, every job has a visible state, extraction never runs against a half-written object, and document translation uses the same machinery as the rest of your asynchronous traffic. The common outcome is that large documents stop being a special case.