Synchronous document translation
Reference
Feature: Azure AI Translator → Document Translation
API Version: 2024-05-01
HTTP method: POST
- Use the
translate documentmethod to synchronously translate a single document. - The method doesn't require an Azure Blob storage account.
- The final response contains the translated document and is returned directly to the calling client.
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.
Request URL
curl -i -X POST "{your-document-translation-endpoint}/translator/document:translate?sourceLanguage=en&targetLanguage=hi&api-version={date}" -H "Ocp-Apim-Subscription-Key:{your-key}" -F "document={path-to-your-document-with-file-extension};type={ContentType}/{file-extension}" -F "glossary={path-to-your-glossary-with-file-extension};type={ContentType}/{file-extension}" -o "{path-to-output-file}"
Request headers
To call the synchronous translation feature via the REST API, include the following headers with each request.
| Header | Value | Condition |
|---|---|---|
| Ocp-Apim-Subscription-Key | Your Translator service key from the Azure portal. | • Required |
Request parameters
Query string parameters:
Required parameters
| Query parameter | Description |
|---|---|
| api-version | Required parameter. Version of the API requested by the client. Current value is 2024-05-01. |
| targetLanguage | Required parameter. Specifies the language of the output document. The target language must be one of the supported languages included in the translation scope. |
| • document= • type= |
Required parameters. • Path to the file location for your source document and file format type. • Ex: "document=@C:\Test\Test-file.txt;type=text/html |
| --output | Required parameter. • File path for the target file location. Your translated file is printed to the output file. • Ex: "C:\Test\Test-file-output.txt". The file extension should be the same as the source file. |
Optional parameters
| Query parameter | Description |
|---|---|
| sourceLanguage | Specifies the language of the input document. If the sourceLanguage parameter isn't specified, automatic language detection is applied to determine the source language. |
| • glossary= • type= |
• Path to the file location for your custom glossary and file format type. • Ex:"glossary=@D:\Test\SDT\test-simple-glossary.csv;type=text/csv |
| allowFallback | • A boolean specifying that the service is allowed to fall back to a generalnn system when a custom system doesn't exist. Possible values are: true (default) or false. • allowFallback=false specifies that the translation should only use systems trained for the category specified by the request.• If no system is found with the specific category, the request returns a 400 status code. • allowFallback=true specifies that the service is allowed to fall back to a generalnn system when a custom system doesn't exist. |
| category | A string specifying the category (domain) for the translation. This parameter is used to get translations from a customized system built with Custom Translator. To use your deployed customized system for synchronous document translation, add the Category ID from your Custom Translator project details to the category parameter. The default value is: generalnn. |
Request Body
| Name | Description | Content Type | Condition |
|---|---|---|---|
| document | Source document to be translated. | Any one of the supported document formats. | Required |
| glossary | Document containing a list of terms with definitions to use during the translation process. | Any one of the supported glossary formats. | Optional |