Document Translation - Start Translation

Submit a document translation request to the Document Translation service
Use this API to submit a bulk (batch) translation request to 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 are 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 at the destination, it will be overwritten. The targetUrl for each target language must be unique.

POST {endpoint}/translator/text/batch/v1.0/batches

URI Parameters

Name In Required Type Description
endpoint
path True

string

Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).

Request Header

Media Types: "application/json", "text/json", "application/*+json"

Name Required Type Description
Ocp-Apim-Subscription-Key True

string

Provide your cognitive services subscription key here.

Request Body

Media Types: "application/json", "text/json", "application/*+json"

Name Required Type Description
inputs True

BatchRequest[]

The input list of documents or folders containing documents

Responses

Name Type Description
202 Accepted

Successful request and the batch request is created by the service. The header Operation-Location will indicate a status url with the operation id.

Headers

Operation-Location: string

400 Bad Request

TranslationErrorResponse

Invalid request. Check input parameters

401 Unauthorized

TranslationErrorResponse

Unauthorized. Please check your credentials

500 Internal Server Error

TranslationErrorResponse

Internal Server Error

Other Status Codes

TranslationErrorResponse

Too many requests

Other Status Codes

TranslationErrorResponse

Server temporary unavailable

Security

Ocp-Apim-Subscription-Key

Provide your cognitive services subscription key here.

Type: apiKey
In: header

Examples

Batch Submit

Sample Request

POST {endpoint}/translator/text/batch/v1.0/batches


{
  "inputs": [
    {
      "source": {
        "sourceUrl": "https://myblob.blob.core.windows.net/sourceContainer",
        "filter": {
          "prefix": "pre",
          "suffix": ".txt"
        },
        "language": "en",
        "storageSource": "AzureBlob"
      },
      "targets": [
        {
          "targetUrl": "https://myblob.blob.core.windows.net/destinationContainer1",
          "category": "general",
          "language": "fr",
          "glossaries": [
            {
              "glossaryUrl": "https://myblob.blob.core.windows.net/myglossary/en_fr_glossary.xlf",
              "storageSource": "AzureBlob",
              "format": "XLIFF"
            }
          ],
          "storageSource": "AzureBlob"
        },
        {
          "targetUrl": "https://myblob.blob.core.windows.net/destinationContainer2",
          "category": "general",
          "language": "es",
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ]
}

Sample Response

{
  "error": {
    "code": "Unauthorized",
    "message": "User is not authorized",
    "innerError": {
      "code": "Unauthorized",
      "message": "Operation is not authorized"
    }
  }
}
{
  "error": {
    "code": "RequestRateTooHigh",
    "message": "User's request rate is too high",
    "innerError": {
      "code": "RateTooHigh",
      "message": "Request rate is too high"
    }
  }
}
{
  "error": {
    "code": "InternalServerError",
    "message": "Internal Server Error",
    "innerError": {
      "code": "InternalServerError",
      "message": "Unexpected internal server error has occurred"
    }
  }
}
{
  "error": {
    "code": "ServiceUnavailable",
    "message": "Service is temporary unavailable",
    "innerError": {
      "code": "ServiceTemporaryUnavailable",
      "message": "Service is currently unavailable.  Please try again later"
    }
  }
}
Operation-Location: https://westus.cognitiveservices.azure.com/translator/text/batch/v1.0/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55
{
  "error": {
    "code": "InvalidRequest",
    "message": "Some argument is incorrect",
    "innerError": {
      "code": "SASTokenInvalid",
      "message": "SAS token for storage is invalid"
    }
  }
}

Definitions

Name Description
BatchRequest

Definition for the input batch translation request

DocumentFilter
Glossary

Glossary / translation memory for the request

InnerTranslationError

New Inner Error format which conforms to Cognitive Services API Guidelines which is available at https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow. This contains required properties ErrorCode, message and optional properties target, details(key value pair), inner error(this can be nested).

SourceInput

Source of the input documents

StartTranslationDetails

Translation job submission batch request

StorageInputType

Storage type of the input documents source string

StorageSource

Storage Source

TargetInput

Destination for the finished translated documents

TranslationError

This contains an outer error with error code, message, details, target and an inner error with more descriptive details.

TranslationErrorCode

Enums containing high level error codes.

TranslationErrorResponse

Contains unified error information used for HTTP responses across any Cognitive Service. Instances can be created either through Microsoft.CloudAI.Containers.HttpStatusExceptionV2 or by returning it directly from a controller.

BatchRequest

Definition for the input batch translation request

Name Type Description
source

SourceInput

Source of the input documents

storageType

StorageInputType

Storage type of the input documents source string

targets

TargetInput[]

Location of the destination for the output

DocumentFilter

Name Type Description
prefix

string

A case-sensitive prefix string to filter documents in the source path for translation. For example, when using a Azure storage blob Uri, use the prefix to restrict sub folders for translation.

suffix

string

A case-sensitive suffix string to filter documents in the source path for translation. This is most often use for file extensions

Glossary

Glossary / translation memory for the request

Name Type Description
format

string

Format

glossaryUrl

string

Location of the glossary. We will use the file extension to extract the formatting if the format parameter is not supplied.

If the translation language pair is not present in the glossary, it will not be applied

storageSource

StorageSource

Storage Source

version

string

Optional Version. If not specified, default is used.

InnerTranslationError

New Inner Error format which conforms to Cognitive Services API Guidelines which is available at https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow. This contains required properties ErrorCode, message and optional properties target, details(key value pair), inner error(this can be nested).

Name Type Description
code

string

Gets code error string.

innerError

InnerTranslationError

New Inner Error format which conforms to Cognitive Services API Guidelines which is available at https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow. This contains required properties ErrorCode, message and optional properties target, details(key value pair), inner error(this can be nested).

message

string

Gets high level error message.

target

string

Gets the source of the error. For example it would be "documents" or "document id" in case of invalid document.

SourceInput

Source of the input documents

Name Type Description
filter

DocumentFilter

language

string

Language code If none is specified, we will perform auto detect on the document

sourceUrl

string

Location of the folder / container or single file with your documents

storageSource

StorageSource

Storage Source

StartTranslationDetails

Translation job submission batch request

Name Type Description
inputs

BatchRequest[]

The input list of documents or folders containing documents

StorageInputType

Storage type of the input documents source string

Name Type Description
File

string

Folder

string

StorageSource

Storage Source

Name Type Description
AzureBlob

string

TargetInput

Destination for the finished translated documents

Name Type Description
category

string

Category / custom system for translation request

glossaries

Glossary[]

List of Glossary

language

string

Target Language

storageSource

StorageSource

Storage Source

targetUrl

string

Location of the folder / container with your documents

TranslationError

This contains an outer error with error code, message, details, target and an inner error with more descriptive details.

Name Type Description
code

TranslationErrorCode

Enums containing high level error codes.

innerError

InnerTranslationError

New Inner Error format which conforms to Cognitive Services API Guidelines which is available at https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow. This contains required properties ErrorCode, message and optional properties target, details(key value pair), inner error(this can be nested).

message

string

Gets high level error message.

target

string

Gets the source of the error. For example it would be "documents" or "document id" in case of invalid document.

TranslationErrorCode

Enums containing high level error codes.

Name Type Description
InternalServerError

string

InvalidArgument

string

InvalidRequest

string

RequestRateTooHigh

string

ResourceNotFound

string

ServiceUnavailable

string

Unauthorized

string

TranslationErrorResponse

Contains unified error information used for HTTP responses across any Cognitive Service. Instances can be created either through Microsoft.CloudAI.Containers.HttpStatusExceptionV2 or by returning it directly from a controller.

Name Type Description
error

TranslationError

This contains an outer error with error code, message, details, target and an inner error with more descriptive details.