Start batch translation

Reference
Feature: Azure Translator → Document translation
API Version (GA): 2024-05-01
API Version (preview): 2025-12-01-preview—adds support for image file translation.
HTTP method: POST

• Use the Start Translation method to execute an asynchronous batch translation request.
• The method requires an Azure Blob storage account with storage containers for your source and translated documents.

Request URL

  curl -i -X POST "{document-translation-endpoint}/translator/document/batches?api-version={date}"

Request headers

Request headers are:

BatchRequest (body)

• Each request can contain multiple documents and must contain a source and target container for each document. Source media types: application/json, text/json, application/*+json.

• The prefix and suffix filter (if supplied) are used to filter folders. The prefix is applied to the subpath after the container name.

• Glossaries can be included in the request. If the glossary is invalid or unreachable during translation, an error is indicated in the document status.

• If a file with the same name already exists in the target destination, the job fails.

• The targetUrl for each target language must be unique.

{
  "inputs": [
    {
      "source": {
        "sourceUrl": "https://myblob.blob.core.windows.net/Container/",
        "filter": {
          "prefix": "FolderA",
          "suffix": ".txt"
        },
        "language": "en",
        "storageSource": "AzureBlob"
      },
      "targets": [
        {
          "targetUrl": "https://myblob.blob.core.windows.net/TargetUrl/",
          "category": "general",
          "language": "fr",
          "glossaries": [
            {
              "glossaryUrl": "https://myblob.blob.core.windows.net/Container/myglossary.xlf",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
}

Inputs

Definition for the input batch translation request.

inputs.source

Definition for the source data.

inputs.targets

Definition for target and glossaries data.

inputs.storageType

Definition of the storage entity for input documents.

Options

Definition for the input batch translation request.

Example request

The following are examples of batch requests.

Translate all documents in a container

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Translate a specific document in a container

• Specify "storageType": File.
• Create source URL & SAS token for the specific blob/document.
• Specify the target filename as part of the target URL – though the SAS token is still for the container.

This sample request shows a single document translated into two target languages.

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?{SAS-token-query-string}",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?{SAS-token-query-string}",
                    "language": "de"
                }
            ]
        }
    ]
}

• You can find the job id in the POST start-batch-translation method response Header Operation-Location URL value. The alphanumeric string following the /document/ parameter is the operation's job id:

  Response header	Response URL
  Operation-Location	{document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version=2024-05-01

• You can also use a get-translations-status request to retrieve a list of translation jobs and their ids.

Translate all documents in a container applying glossaries

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?{SAS-token-query-string}",
                            "format": "xliff",
                            "version": "1.2"
                        }
                    ]

                }
            ]
        }
    ]
}

Translate a specific folder in a container

Make sure you specify the folder name (case sensitive) as prefix in filter.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Translate image files

Request configuration (image files)

For image files translation, submit your image via a standard batch Document Translation REST API call, specifying API version 2025-12-01-preview. No further configuration is required.

Supported formats (image files)

Supported languages (image files)

For details on supported languages, see Document Translation language support.

Response status codes

The following are the possible HTTP status codes that a request returns.

Error response

Example error response

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "Service is temporary unavailable",
    "innerError": {
      "code": "ServiceTemporaryUnavailable",
      "message": "Service is currently unavailable.  Please try again later"
    }
  }
}

Next steps

Follow our quickstart to learn more about using Document translation and the client library.