Edit

Start translation

  • Article

Reference
Service: Azure AI Document Translation
API Version: v1.1

Use this API to start a translation request with the Document Translation service. Each request can contain multiple documents and must contain a source and destination container for each document.

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

Glossaries / Translation memory can be included in the request and applied by the service when the document is translated.

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 destination, the job fails. The targetUrl for each target language must be unique.

Request URL

Send a POST request to:

POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches

Learn how to find your custom domain name.

Important

  • All API requests to the Document Translation service require a custom domain endpoint.
  • You can't use the endpoint found on your Azure portal resource Keys and Endpoint page nor the global translator endpoint—api.cognitive.microsofttranslator.com—to make HTTP requests to Document Translation.

Request headers

Request headers are:

Headers Description
Ocp-Apim-Subscription-Key Required request header

BatchRequest (body)

Definition for the input batch translation request. 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.


{
  "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.tsv",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
  "options": {
    "experimental": true
  }
}

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.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr"
                }
            ]
        }
    ]
}

Translating all documents in a container applying glossaries

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=BsciG3NWoOoRjOYesTaUmxlXzyjsX4AgVkt2AsxJ9to%3D",
                            "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.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "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.windows.net/source-en/source-english.docx?sv=2019-12-12&st=2021-01-26T18%3A30%3A20Z&se=2021-02-05T18%3A30%3A00Z&sr=c&sp=rl&sig=d7PZKyQsIeE6xb%2B1M4Yb56I%2FEEKoNIF65D%2Fs0IFsYcE%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "de"
                }
            ]
        }
    ]
}

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
• Server temporary unavailable

Error response

Key parameter Type Description
code string Enums containing high-level error codes. Possible values:
  • 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.

Examples

Example successful response

The following information is returned in a successful response.

You can find the job ID in the POST method's response Header Operation-Location URL value. The last parameter of the URL is the operation's job ID (the string following "/operation/").

Operation-Location: https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55

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