> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luminpdf.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Translate Document
> Translate a PDF document into a target language while preserving the original formatting, layout, and images.
When `output_format` is `html`, sanitize the returned content before injecting it into a DOM. Use a trusted HTML sanitizer such as [DOMPurify](https://github.com/cure53/DOMPurify) to prevent XSS.
This endpoint requires the following scope:
`pdf:files`
## OpenAPI
````yaml tabs/api-reference/lumin-openapi.yaml POST /documents/translate
openapi: 3.1.0
info:
version: 1.0.0
title: Lumin API Reference
description: >
The Lumin API Reference provides a comprehensive set of tools to integrate
document workflows — including editing, eSignatures, and automation — into
your applications.
Useful links:
- [Document Repository](https://github.com/luminpdf/luminsign-docs)
- [API
Definition](https://github.com/luminpdf/luminsign-docs/blob/main/openapi.yaml)
- [Authentication Guide](/tabs/guides/authentication/overview)
termsOfService: https://www.luminpdf.com/terms-of-use/
contact:
name: API Support
email: integration@luminpdf.com
url: https://help.luminpdf.com
servers:
- url: https://api.luminpdf.com/v1
description: Production server
security: []
tags:
- name: Signature Requests
description: Everything about Signature Requests
- name: Users
description: Everything about Users
- name: Templates
description: Everything about Templates
- name: Documents
description: Everything about Documents
- name: Workspaces
description: Everything about Workspaces
- name: Agreements
description: Everything about Agreements
paths:
/documents/translate:
post:
tags:
- Documents
summary: Translate Document
description: >
Translate a PDF document into a target language while preserving the
original formatting, layout, and images.
The API auto-detects the source language, translates the text content,
and returns a temporary download URL for the translated file. The
document can be specified by a Lumin document ID or by a publicly
accessible file URL.
**Supported file type:** PDF only.
**Page limit:** Maximum 40 pages per translation request. Optionally
specify a page range to translate a subset.
**Rate limit:** 20 translation requests per user per day.
**Concurrency:** One document at a time per user. If a translation is
already in progress, subsequent requests are rejected.
**Output formats:** `pdf` (default), `html`.
**Security note:** When `output_format` is `html`, the returned content
must be sanitized before injecting into a DOM. Use a trusted HTML
sanitizer (e.g. [DOMPurify](https://github.com/cure53/DOMPurify)) to
prevent XSS.
Password-protected documents cannot be translated.
**File URL restrictions:** Only URLs from allowed domains are accepted
(`api.luminpdf.com`, `*.s3.amazonaws.com`, `*.s3.*.amazonaws.com`).
Redirecting URLs are not supported.
**Input priority:** If both `document_id` and `file_url` are provided,
`document_id` takes priority and `file_url` is ignored.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentTranslateRequest'
examples:
full-document:
summary: Translate entire document
value:
document_id: 695dd6880d951f4de70a7c5d
target_language: vi
page-range:
summary: Translate specific pages to HTML
value:
document_id: 695dd6880d951f4de70a7c5d
target_language: ja
pages: 1-5,8,12-15
output_format: html
document_name: Contract_Japanese
responses:
'200':
description: Returns a temporary download URL for the translated file.
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentTranslateResponse'
example:
signed_url: >-
https://files.luminpdf.com/download/translate-abc123?token=xyz789
expires_at: 1755526530000
output_format: pdf
detected_language: en
target_language: vi
document_name: vi_rental_agreement.pdf
page_count: 12
remaining_requests: 17
4XX:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- ApiKey: []
- BearerAuth:
- pdf:files
components:
schemas:
DocumentTranslateRequest:
type: object
required:
- target_language
properties:
document_id:
type: string
description: >
Lumin document ID of the PDF to translate.
Required when `file_url` is not provided. Takes priority if both are
provided.
To obtain a document ID, upload the file to Lumin first using
[Upload
Document](/tabs/api-reference/api/documents/create-document).
file_url:
type: string
format: uri
description: >
Publicly accessible URL of the PDF file to translate.
Required when `document_id` is not provided. Ignored if
`document_id` is also provided.
target_language:
type: string
description: >
ISO language code for the target language (e.g., `vi`, `fr`, `ja`,
`zh-hans`).
Supported codes: `ar`, `bn`, `bg`, `ca`, `zh-hans`, `zh-hant`, `hr`,
`cs`, `da`, `nl`, `en`, `et`, `fa`, `fi`, `fr`, `de`, `el`, `gu`,
`he`, `hi`, `hu`, `id`, `it`, `ja`, `kn`, `ko`, `lv`, `lt`, `ms`,
`ml`, `mr`, `no`, `pl`, `pt`, `ro`, `ru`, `sr`, `sk`, `sl`, `es`,
`sw`, `sv`, `ta`, `te`, `th`, `tr`, `uk`, `ur`, `vi`.
pages:
type: string
description: >
Page range to translate. Accepts comma-separated pages and ranges
(e.g., `1-10`, `1,3,5-8`).
If omitted, all pages are translated (up to the 40-page limit).
output_format:
type: string
enum:
- pdf
- html
default: pdf
description: Output file format.
document_name:
type: string
description: >-
Custom name for the translated file (without extension). Default is
`{target_language}_{original_name}`.
DocumentTranslateResponse:
type: object
required:
- signed_url
- expires_at
- output_format
- detected_language
- target_language
- document_name
- page_count
- remaining_requests
properties:
signed_url:
type: string
format: uri
description: Temporary URL to download the translated file.
expires_at:
type: integer
format: unix-epoch
description: >-
Unix epoch timestamp (in milliseconds) when the `signed_url`
expires.
output_format:
type: string
enum:
- pdf
- html
description: Format of the output file.
detected_language:
type: string
description: ISO language code of the auto-detected source language.
target_language:
type: string
description: ISO language code of the target language.
document_name:
type: string
description: Name of the translated output file (with extension).
page_count:
type: integer
description: Number of pages that were translated.
remaining_requests:
type: integer
description: Number of translation requests the user has remaining for today.
Error:
type: object
required:
- error_code
- error_message
properties:
error_code:
type: string
description: The system error code.
error_message:
type: string
description: The human-readable error message.
securitySchemes:
ApiKey:
type: apiKey
in: header
name: X-API-Key
description: >
Provide your API key in the `X-API-Key` header, e.g., `X-API-Key:
YOUR_API_KEY`.
BearerAuth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.luminpdf.com/oauth2/auth
tokenUrl: https://auth.luminpdf.com/oauth2/token
scopes:
openid: >-
Retrieve basic identity details (username, email, profile
picture).
offline_access: Request a refresh token for long-lived access. Private apps only.
profile.read: View basic user profile information.
workspaces: View and manage Workspaces and Spaces.
workspaces.read: View information about the authenticated user's Workspace.
templates: View and manage templates in a Workspace.
pdf:files: Create, edit, and delete PDF files in a Workspace.
pdf:files.read: Retrieve PDF documents stored in a Workspace.
sign:requests: Create, update, or view signature requests.
sign:requests.read: Retrieve signature requests.
agreements: Create, update, or delete AgreementGen documents.
description: >
OAuth 2.0 authorization code flow. Provide your access token in the
`Authorization` header, e.g., `Authorization: Bearer `. See the
[OAuth 2.0 guide](/tabs/guides/authentication/oauth2) for details.
````