> ## Documentation Index
> Fetch the complete documentation index at: https://hobbyist-e43fa225.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.
# What is Azure Translator document translation?
> Learn about Azure Translator document translation for batch and single-file translation while preserving document structure and formatting.
{/* markdownlint-disable MD051 */}
{/* markdownlint-disable MD036 */}
{/* markdownlint-disable MD001 */}
# What is Azure Translator document translation?
Document translation is a cloud-based machine translation feature of [Azure Translator in Foundry Tools](../overview). Translate multiple and complex documents across all [supported languages and dialects](../language-support) while preserving original document structure and data format. The Document translation API supports two translation processes:
* [Asynchronous batch translation](#key-features) supports the processing of multiple documents and large files. The batch translation process requires an Azure Blob storage account with storage containers for your source and translated documents.
* [Synchronous single file](#key-features) supports the processing of single file translations. The file translation process doesn't require an Azure Blob storage account. The final response contains the translated document and is returned directly to the calling client.
## Prerequisites
### Asynchronous batch translation prerequisites
Before you start, you need:
* An active [Azure subscription](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
* A Translator resource. For resource creation and endpoint/key retrieval steps, see [Use Document translation APIs programmatically](how-to-guides/use-rest-api-programmatically).
* An Azure Blob Storage account with source and target containers. For setup guidance, see [Create Azure Blob Storage containers](how-to-guides/use-rest-api-programmatically#create-azure-blob-storage-containers).
* A way to authorize access to your storage URLs:
* [Shared access signature (SAS) tokens](how-to-guides/create-sas-tokens), or
* [Managed identities for Document translation](how-to-guides/create-use-managed-identities).
### Synchronous translation prerequisites
Before you start, you need:
* An active [Azure subscription](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
* A Translator resource with a custom domain endpoint. For setup and endpoint/key retrieval, see [Use Document translation APIs programmatically](how-to-guides/use-rest-api-programmatically).
Store subscription keys in a secure location such as [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/general/overview), and avoid putting keys in source control.
## Key features
| 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](reference/start-batch-translation#translate-image-files).
• **Supported formats**: `.jpeg`, `.png`, `.bmp`, `.webp`
• **Pricing**: Calculated on a per-image basis. For more information, see [Pricing](https://azure.microsoft.com/pricing/details/cognitive-services/translator). |
| [**Translate image text in Word documents (.docx) and PowerPoint files (.pptx)** 🆕](how-to-guides/use-rest-api-programmatically#translate-images-in-word-documents-docx-and-powerpoint-files-pptx). | This feature is available with the [batch document translation](how-to-guides/use-rest-api-programmatically#translate-images-in-word-documents-docx-and-powerpoint-files-pptx) 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](../custom-translator/concepts/customization#azure-translator-in-foundry-tools-custom-translator) 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. |
| Feature | Description |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Translate single-page files** | The synchronous request accepts only a single document as input. |
| **Preserve source file presentation** | Translate files while preserving the original layout and format. |
| **Apply custom translation** | Translate documents using general and [custom translation](../custom-translator/concepts/customization#azure-translator-in-foundry-tools-custom-translator) models. |
| **Apply custom glossaries** | Translate documents using custom glossaries. For guidance, see [Use glossaries with Document translation](how-to-guides/create-use-glossaries). |
| **Single language translation** | Translate to and from one [supported language](../language-support). |
| **Automatically detect document language** | Let the Document translation service determine the language of the document. |
## How document translation works
Document translation supports two workflows. Choose the approach that matches your scenario.
### Asynchronous (batch)
1. Upload source documents to your source container.
2. Submit a batch translation request.
3. Monitor job and document status.
4. Download translated documents from your target container.
For detailed request/response flows, see the [Document translation REST API reference guide](reference/rest-api-guide).
### Synchronous
1. Send a request that includes one document (and an optional glossary).
2. Receive the translated document in the response.
For request details and examples, see [Synchronous document translation](reference/translate-document).
## Development options
Add document translation to your projects and applications using the following development options.
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](reference/rest-api-guide) 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)](quickstarts/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](https://learn.microsoft.com/dotnet/api/azure.ai.translation.document) and [Python](https://azuresdkdocs.z19.web.core.windows.net/python/azure-ai-translation-document/latest/azure.ai.translation.document.html). |
Use synchronous document translation to translate a single file and return the translated file in the response.
| Development option | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Foundry portal (classic)** | Try synchronous document translation in the Translator playground. In the classic portal, upload your own document and translate it end-to-end. To open the Translator playground, go to [Foundry portal](https://ai.azure.com/), ensure **new Foundry** is not selected, then select **Playgrounds** > **Translator**. |
| **Foundry portal (new)** | The new Foundry portal uses a sample document and translates only into a predefined set of languages. Doesn't support customer-provided documents. For more information, see [What is Microsoft Foundry?](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-foundry). |
| **REST API** | Integrate synchronous document translation into your applications by using the [REST API](reference/translate-document). |
| **Client libraries (SDKs)** | Integrate translation capabilities into your applications by using the [client libraries (SDKs)](quickstarts/client-library-sdks). |
| **Docker container** | • To use the Translator container, complete and submit the [**Gated Services application**](https://aka.ms/csgate-translator) online request form for approval to access the container.
• The [**Translator container image**](https://mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation/about) supports limited features compared to cloud offerings.
For more information, see [Container: Translate Documents](../containers/translate-document-parameters). |
## Supported document and glossary formats
The following tables list the document and glossary file formats supported by each translation method.
### Batch document supported formats
The [Get supported document formats method](reference/get-supported-document-formats) returns a list of document formats supported by the Document translation service. The list includes common file extensions and content types.
| File type | File extension | Description |
| -------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Adobe PDF | `pdf` | Portable document file format. Document translation uses optical character recognition (OCR) technology to extract and translate text in scanned PDF document while retaining the original layout. |
| Comma-Separated Values | `csv` | A comma-delimited raw-data file used by spreadsheet programs. |
| DITA | `dita` | An XML-based open standard for authoring and publishing. |
| HTML | `html`, `htm` | Hyper Text Markup Language. |
| Image (2025-12-01-preview) | `.jpeg`, `.png`, `.bmp`, `.webp` | Files that store digital image data. |
| Markdown | `markdown`, `mdown`, `mkdn`, `md`, `mkd`, `mdwn`, `mdtxt`, `mdtext`, `rmd` | A lightweight markup language for creating formatted text. |
| MHTML | `mhtml`, `mht` | A web page archive format used to combine HTML code and its companion resources. |
| Microsoft Excel | `xls`, `xlsx` | A spreadsheet file for data analysis and documentation. |
| Microsoft Outlook | `msg` | An email message created or saved within Microsoft Outlook. |
| Microsoft PowerPoint | `ppt`, `pptx` | A presentation file used to display content in a slideshow format. |
| Microsoft Word | `doc`, `docx` | A text document file. |
| OpenDocument Presentation | `odp` | An open-source presentation file. |
| OpenDocument Spreadsheet | `ods` | An open-source spreadsheet file. |
| OpenDocument Text | `odt` | An open-source text document file. |
| Rich text format | `rtf` | A text document containing formatting. |
| Tab separated values/TAB | `tsv`/`tab` | A tab-delimited raw-data file used by spreadsheet programs. |
| Text | `txt` | An unformatted text document. |
| XLIFF | `xlf`, `xliff 2.0` | A parallel document format used in translation and localization. |
| XML | `xml` | A markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. |
### Batch Legacy file types
Source file types are preserved during the document translation with the following **exceptions**:
| Source file extension | Translated file extension |
| --------------------- | ------------------------- |
| .doc, .odt, .rtf, | .docx |
| .xls, .ods | .xlsx |
| .ppt, .odp | .pptx |
### Batch glossary supported formats
Document translation supports the following glossary file types:
| File type | File extension | Description |
| ------------------------ | -------------- | ---------------------------------------------------------------- |
| Comma-Separated Values | `csv` | A comma-delimited raw-data file used by spreadsheet programs. |
| XLIFF | `xlf` | A parallel document format used in translation and localization. |
| Tab-Separated Values/TAB | `tsv`, `tab` | A tab-delimited raw-data file used by spreadsheet programs. |
### Synchronous document supported formats
| File type | File extension | Content type | Description |
| ----------------------------- | --------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Plain Text** | `.txt` | `text/plain` | An unformatted text document. |
| **Tab Separated Values** | `.tsv`
`.tab` | `text/tab-separated-values` | A text file format that uses tabs to separate values and newlines to separate records. |
| **Comma Separated Values** | `.csv` | `text/csv` | A text file format that uses commas as a delimiter between values. |
| **HyperText Markup Language** | `.html`
`.htm` | `text/html` | HTML is a standard markup language used to structure web pages and content. |
| **MHTML** | `.mhtml`
`.mht` | `message/rfc822`
`application/x-mimearchive`
`multipart/related` | A web page archive file format. |
| **Microsoft PowerPoint** | `.pptx` | `application/vnd.openxmlformats-officedocument.presentationml.presentation` | An XML-based file format used for PowerPoint slideshow presentations. |
| **Microsoft Excel** | `.xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | An XML-based file format used for Excel spreadsheets. |
| **Microsoft Word** | `.docx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | An XML-based file format used for Word documents. |
| **Microsoft Outlook** | `.msg` | `application/vnd.ms-outlook` | A file format used for stored Outlook mail message objects. |
| **XLIFF** | `.xlf` | `application/xliff+xml` | A standardized XML-based file format widely used in translation and localization software processing. |
### Synchronous glossary supported formats
Document translation supports the following glossary file types:
| File type | File extension | Description |
| -------------------------- | -------------- | ----------------------------------------------------------------------------------------------- |
| **Comma-Separated Values** | `csv` | A comma-delimited raw-data file used by spreadsheet programs. |
| **XLIFF** | `xlf` | An XML-based format designed to standardize how data is passed during the localization process. |
| **Tab-Separated Values** | `tsv`, `tab` | A tab-delimited raw-data file used by spreadsheet programs. |
## Document translation request limits
For detailed information about Translator request limits, see [Document translation request limits](../service-limits#document-translation).
## Document translation data residency
Document translation data residency depends on the Azure region where your Translator resource was created:
✔️ Feature: **Document translation**
✔️ Service endpoint: **Custom domain: `https://.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 |
## Troubleshooting
Use the following checks to diagnose common issues.
### Batch translation
* If translated files don't appear in the target container, check job status using [Get status for a specific translation job](reference/get-translation-status) and document status using [Get status for a specific document](reference/get-document-status).
* If the service can't read from or write to your storage containers, confirm storage authorization:
* If you use SAS tokens, see [Create shared access signature (SAS) tokens for storage containers and blobs](how-to-guides/create-sas-tokens).
* If you use managed identities, see [Create and use managed identities](how-to-guides/create-use-managed-identities).
* If a job fails due to unsupported inputs, confirm the format using [Get supported document formats](reference/get-supported-document-formats).
### Synchronous translation
* If the request fails due to invalid parameters or unsupported file types, review the required parameters and supported formats in [Synchronous document translation](reference/translate-document).
* If you hit rate limits, see [Document translation request limits](../service-limits#document-translation).
## Related content
* [Document translation quickstart](quickstarts/rest-api)
* [Use Document translation APIs programmatically](how-to-guides/use-rest-api-programmatically)
* [Use glossaries with Document translation](how-to-guides/create-use-glossaries)
* [Document translation REST API reference](reference/rest-api-guide)
* [Translator language support](../language-support)