Start batch translation

Article
10/08/2024

Reference
Feature: Azure AI Translator → Document Translation
API Version: 2024-05-01
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

Important

All API requests to the Document Translation feature require a custom domain endpoint that is located on your resource overview page in the Azure portal.

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

Request headers

Request headers are:

Headers	Description	Condition
Ocp-Apim-Subscription-Key	Your Translator service API key from the Azure portal.	Required
Ocp-Apim-Subscription-Region	The region where your resource was created.	Required when using a regional (geographic) resource like China North. &bullet.
Content-Type	The content type of the payload. The accepted value is application/json or charset=UTF-8.	Required

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.chinacloudapi.cn/Container/",
        "filter": {
          "prefix": "FolderA",
          "suffix": ".txt"
        },
        "language": "en",
        "storageSource": "AzureBlob"
      },
      "targets": [
        {
          "targetUrl": "https://myblob.blob.core.chinacloudapi.cn/TargetUrl/",
          "category": "general",
          "language": "fr",
          "glossaries": [
            {
              "glossaryUrl": "https://myblob.blob.core.chinacloudapi.cn/Container/myglossary.xlf",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
}

Inputs

Definition for the input batch translation request.

Key parameter	Type	Required	Request parameters	Description
inputs	`array`	True	• source (object) • targets (array) • storageType (string)	Input source data.

inputs.source

Definition for the source data.

Key parameter	Type	Required	Request parameters	Description
inputs.source	`object`	True	• sourceUrl (string) • filter (object) • language (string) • storageSource (string)	Source data for input documents.
inputs.source.sourceUrl	`string`	True	• string	Container location for the source file or folder.
inputs.source.filter	`object`	False	• prefix (string) • suffix (string)	Case-sensitive strings to filter documents in the source path.
inputs.source.filter.prefix	`string`	False	• string	Case-sensitive prefix string to filter documents in the source path for translation. Often used to designate subfolders for translation. Example: "FolderA".
inputs.source.filter.suffix	`string`	False	• string	Case-sensitive suffix string to filter documents in the source path for translation. Most often used for file extensions. Example: ".txt"
inputs.source.language	`string`	False	• string	The language code for the source documents. If not specified, autodetect is implemented.
inputs.source.storageSource	`string`	False	• string	Storage source for inputs. Defaults to `AzureBlob`.

inputs.targets

Definition for target and glossaries data.

Key parameter	Type	Required	Request parameters	Description
inputs.targets	`array`	True	• targetUrl (string) • category (string) • language (string) • glossaries (array) • storageSource (string)	Targets and glossaries data for translated documents.
inputs.targets.targetUrl	`string`	True	• string	Location of the container location for translated documents.
inputs.targets.category	`string`	False	• string	Classification or category for the translation request. Example: general.
inputs.targets.language	`string`	True	• string	Target language code. Example: "fr".
inputs.targets.glossaries	`array`	False	• glossaryUrl (string) • format (string) • version (string) • storageSource (string)	See Create and use glossaries
inputs.targets.glossaries.glossaryUrl	`string`	True (if using glossaries)	• string	Location of the glossary. The file extension is used to extract the formatting if the format parameter isn't supplied. If the translation language pair isn't present in the glossary, it isn't applied.
inputs.targets.glossaries.format	`string`	False	• string	Specified file format for glossary. To check if your file format is supported, see Get supported glossary formats.
inputs.targets.glossaries.version	`string`	False	• string	Version indicator. Example: "2.0".
inputs.targets.glossaries.storageSource	`string`	False	• string	Storage source for glossaries. Defaults to `_AzureBlob_`.
inputs.targets.storageSource	`string`	False	• string	Storage source for targets.defaults to `_AzureBlob_`.

inputs.storageType

Definition of the storage entity for input documents.

Key parameter	Type	Required	Request parameters	Description
inputs.storageType	`string`	False	•`Folder` • `File`	Storage type of the input documents source string. Only "Folder" or "File" are valid values.

Options

Definition for the input batch translation request.

Key parameter	Type	Required	Request parameters	Description
options	`object`	False	Source information for input documents.
options.experimental	`boolean`	False	•`true` • `false`	Indicates whether the request includes an experimental feature (if applicable). Only the booleans `true` or `false` are valid values.

Example request

The following are examples of batch requests.

Note

In the following examples, limited access has been granted to the contents of an Azure Storage container using a shared access signature(SAS) token.

Translating all documents in a container

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

Translating all documents in a container applying glossaries

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

                }
            ]
        }
    ]
}

Translating 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.chinacloudapi.cn/source-en?{SAS-token-query-string}",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.chinacloudapi.cn/target-fr?{SAS-token-query-string}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Translating 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.chinacloudapi.cn/source-en/source-english.docx?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.chinacloudapi.cn/target/try/Target-Spanish.docx?{SAS-token-query-string}",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.chinacloudapi.cn/target/try/Target-German.docx?{SAS-token-query-string}",
                    "language": "de"
                }
            ]
        }
    ]
}

Tip

This method returns the job id parameter for the get-translation-status, get-documents-status, get-document-status, and cancel-translation request query strings.

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.

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

Response status codes

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

Status Code	Description
202	Accepted. Successful request and the batch request created. The header Operation-Location indicates a status url with the operation ID.HeadersOperation-Location: string
400	Bad Request. Invalid request. Check input parameters.
401	Unauthorized. Check your credentials.
429	Request rate is too high.
500	Internal Server Error.
503	Service is currently unavailable. Try again later.
Other Status Codes	• Too many requests. The server is temporary unavailable

Error response

Key parameter	Type	Description
code	`string`	Enums containing high-level error codes. Possible values:</br/>• InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • Unauthorized
message	`string`	Gets high-level error message.
innerError	InnerTranslationError	New Inner Error format that conforms to Azure AI services API Guidelines. This error message contains required properties: ErrorCode, message, and optional properties target, details(key value pair), and inner error(it can be nested).
inner.Errorcode	`string`	Gets code error string.
innerError.message	`string`	Gets high-level error message.
innerError.target	`string`	Gets the source of the error. For example, it would be `documents` or `document id` if the document is invalid.

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.

Get started with Document Translation