Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Document translation (2026-03-01 GA) is a cloud-based feature of Azure Translator and part of the Foundry Tools family of REST APIs. It provides:
- Translation across all supported languages and dialects.
- Preservation of the original document structure and data format.
- Neural machine translation (NMT) engine support for standard translations (default).
The Document Translation API supports two translation processes:
Asynchronous batch translation: Translate multiple documents or large files in parallel. Upload documents to Blob Storage, submit a batch job, poll for status, then download translated output from your target container. Requires an Azure Blob Storage account with source and target containers. For a full walkthrough, see Quickstart: asynchronous document translation and End-to-end batch translation workflow.
Synchronous single-file translation: POST a single document and receive the translated output directly in the response. No Azure Blob Storage required. For a full walkthrough, see Quickstart: synchronous document translation.
What's new in version 2026-03-01
API version 2026-03-01 introduces the following capabilities for Document Translation:
Image translation: Translate text within standalone image files (
.jpeg,.png,.bmp,.webp), with translated content rendered back into the image.PDF translation with Azure Document Intelligence (batch only): Translate PDF files using Azure Document Intelligence to preserve layout and structure in the translated output.
Image translation in Office documents (batch only): Translate text embedded in images within Word (
.docx) and PowerPoint (.pptx) documents while preserving overall document structure.
Before you begin
Prerequisites differ by translation method:
- Asynchronous batch translation: Requires an Azure Blob Storage account and storage authorization (SAS tokens or managed identity).
- Synchronous single-file translation: Requires only a Translator resource with a custom domain endpoint.
For the full prerequisites list, see Prerequisites and setup.
Key features
Document Translation supports different features for each translation method. Select the tab for your scenario.
| Feature | Description |
|---|---|
| Translate large files | Translate whole documents asynchronously. |
| Translate numerous files | Translate multiple files across all supported languages and dialects while preserving document structure and data format. |
| Translate image file formats 🆕 | • Translate text within an image while maintaining the original design and layout. • Supported formats: .jpeg, .png, .bmp, .webp• Pricing: Calculated on a per-image basis. For more information, see Pricing. |
| Translate image text in Word documents (.docx) and PowerPoint files (.pptx) 🆕. | This feature is available with the batch document translation API for .docx and .pptx file formats. |
| Preserve source file presentation | Translate files while preserving the original layout and format. |
| Apply custom translation | Translate documents using general and custom translation models. |
| Apply custom glossaries | Translate documents using custom glossaries. |
| Automatically detect document language | Let the Document translation service determine the language of the document. |
| Translate documents with content in multiple languages | Use the autodetect feature to translate documents with content in multiple languages into your target language. |
Language support
For the full list of languages supported for document translation features, see Language support.
Development options
Add document translation to your projects and applications using the following development options.
Note
Foundry portal currently supports synchronous (single-file) document translation only. Use the REST API or client libraries for asynchronous batch document translation.
Use asynchronous workflows to translate multiple documents and large files.
| Development option | Description |
|---|---|
| REST API | The REST API is a language agnostic interface that enables you to create HTTP requests and authorization headers to translate documents. |
| Client libraries (SDKs) | The client-library (SDKs) are language-specific classes, objects, methods, and code that you can quickly use by adding a reference in your project. Currently Document translation has programming language support for C#/.NET and Python. |
Supported document and glossary formats
Document translation supports a broad range of file formats for both translation input and glossary files. Supported formats differ slightly between asynchronous batch and synchronous translation.
To query supported formats at runtime:
- Document formats: Use the Get supported document formats API.
- Glossary formats: Use the Get supported glossary formats API.
For a complete list of supported formats by method, see Supported document formats.
Document translation request limits
Document translation enforces limits on request size, document count, file size, and concurrent operations. Familiarizing yourself with these limits helps you plan batch jobs effectively and prevent throttling errors. For detailed information, see Document translation request limits.
Document translation data residency
Data residency determines where your document content is processed and temporarily stored during translation. For document translation, the Azure region where you created your Translator resource determines the processing location. The following table maps resource regions to their corresponding request processing data centers:
✔️ Feature: Document translation
✔️ Service endpoint: Custom domain: https://<your-resource-name>.cognitiveservices.azure.com
| Resource created region | Request processing data center |
|---|---|
| Global | Closest available data center. |
| Americas | East US 2 • West US 2 |
| Asia Pacific | Japan East • Southeast Asia |
| Europe (except Switzerland) | France Central • West Europe |
| Switzerland | Switzerland North • Switzerland West |
Service limits and troubleshooting
If you encounter unexpected behavior, errors, or performance issues, the following resources can help you diagnose and resolve them:
Service limits: See Document translation request limits.
Translation errors and known issues: See Known issues.
Pricing
- Document translations using NMT models are billed by the number of characters or images in the source document. For more information, see Azure Translator pricing.