Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Document Translation is a cloud-based feature of the Azure AI Translator service. You can use the Document Translation API to asynchronously translate whole documents in supported languages and various file formats while preserving source document structure and text formatting. In this how-to guide, you learn to use Document Translation APIs with a programming language of your choice and the HTTP REST API.
Note
Document Translation is supported in the S1 Standard Service Plan (Pay-as-you-go) and C2, C3, C4, and D3 Volume Discount Plans. See Azure AI services pricing—Translator.
To get started, you need:
An active Azure account. If you don't have one, you can create a free account
An Azure Blob Storage account. You also need to create containers in your Azure Blob Storage account for your source and target files:
Complete the Translator project and instance details fields as follows:
Subscription. Select one of your available Azure subscriptions.
Resource Group. You can create a new resource group or add your resource to an existing resource group that shares the same lifecycle, permissions, and policies.
Resource Region. Choose Global unless your business or application requires a specific region. If you're planning on using a system-assigned managed identity for authentication, choose a geographic region like West US.
Name. Enter the name you chose for your resource. The name you choose must be unique within Azure.
Note
Document Translation requires a custom domain endpoint. The value that you enter in the Name field is the custom domain name parameter for your endpoint.
Pricing tier. Document Translation isn't supported in the free tier. To try the service, select Standard S1.
Select Review + Create.
Review the service terms and select Create to deploy your resource.
After your resource successfully deploys, select Go to resource to retrieve your key and endpoint.
If you created a new resource, after it deploys, select Go to resource. If you have an existing Document Translation resource, navigate directly to your resource page.
In the left rail, under Resource Management, select Keys and Endpoint.
Copy and paste your key
and document translation endpoint
in a convenient location, such as Microsoft Notepad. Only one key is necessary to make an API call.
You key
and document translation endpoint
into the code samples to authenticate your request to the Document Translation service.
Requests to the Translator service require a read-only key for authenticating access.
You need to create containers in your Azure Blob Storage account for source and target files.
Note
Document Translation supports glossaries as blobs in target containers (not separate glossary containers). If you want to include a custom glossary, add it to the target container and include the glossaryUrl
with the request. If the translation language pair isn't present in the glossary, the glossary isn't applied. See Translate documents using a custom glossary
The sourceUrl
, targetUrl
, and optional glossaryUrl
must include a Shared Access Signature (SAS) token, appended as a query string. The token can be assigned to your container or specific blobs. See Create SAS tokens for Document Translation process.
Tip
An asynchronous batch translation request is submitted to your Translator service endpoint via a POST request. If successful, the POST method returns a 202 Accepted
response code and the service creates a batch request. The translated documents are listed in your target container.
For detailed information regarding Azure AI Translator Service request limits, see Document Translation request limits.
The following headers are included with each Document Translation API request:
HTTP header | Description |
---|---|
Ocp-Apim-Subscription-Key | Required: The value is the Azure key for your Translator or Azure AI services resource. |
Content-Type | Required: Specifies the content type of the payload. Accepted values are application/json or charset=UTF-8. |
https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches
.inputs
.inputs
object contains both sourceURL
and targetURL
container addresses for your source and target language pairs.prefix
and suffix
are case-sensitive strings to filter documents in the source path for translation. The prefix
field is often used to delineate subfolders for translation. The suffix
field is most often used for file extensions.glossaries
field (optional) is applied when the document is being translated.targetUrl
for each target language must be unique.Note
If a file with the same name already exists in the destination, the job fails.
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "fr"
}
]
}
]
}
"storageType": "File"
.{
"inputs": [
{
"storageType": "File",
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es"
},
{
"targetUrl": "{targetSASUrl}",
"language": "de"
}
]
}
]
}
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es",
"glossaries": [
{
"glossaryUrl": "{glossaryUrl/en-es.xlf}",
"format": "xliff"
}
]
}
]
}
]
}
Important
For the code samples, hard-code your Shared Access Signature (SAS) URL where indicated. Remember to remove the SAS URL from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like Azure Managed Identity. For more information, see Azure Storage security.
You might need to update the following fields, depending upon the operation:
endpoint
basePath
key
sourceURL
targetURL
glossaryURL
id
(job ID)
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={date} |
id
s.
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
class Program
{
static readonly string route = "?api-version={date}";
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches";
private static readonly string key = "{your-api-key}";
static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\"}, \"targets\": [{\"targetUrl\": \"https://YOUR-TARGET-URL-WITH-WRITE-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"category\": \"general\",\"language\": \"es\"}]}]}");
static async Task Main(string[] args)
{
using HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
StringContent content = new StringContent(json, Encoding.UTF8, "application/json");
request.Method = HttpMethod.Post;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
request.Content = content;
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
if (response.IsSuccessStatusCode)
{
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine();
Console.WriteLine($"Response Headers:");
Console.WriteLine(response.Headers);
}
else
Console.Write("Error");
}
}
}
Retrieve a list of supported file formats. If successful, this method returns a 200 OK
response code.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/formats";
static readonly string route = "?api-version={date}&type=document";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Get the current status for a single job and a summary of all jobs in a Document Translation request. If successful, this method returns a 200 OK
response code.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
}
Retrieve the status for a specific document in a Document Translation request. If successful, this method returns a 200 OK
response code.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{document-translation-endpoint}/translator/document/batches/{id}/documents/{documentId}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Cancel currently processing or queued job. Only documents for which translation isn't started are canceled.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Delete;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
HTTP status code | Description | Possible reason |
---|---|---|
200 | OK | The request was successful. |
400 | Bad Request | A required parameter is missing, empty, or null. Or, the value passed to either a required or optional parameter is invalid. A common issue is a header that is too long. |
401 | Unauthorized | The request isn't authorized. Check to make sure your key or token is valid and in the correct region. |
429 | Too Many Requests | You exceeded the quota or rate of requests allowed for your subscription. |
502 | Bad Gateway | Network or server-side issue. Can also indicate invalid headers. |
Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowTraining
Learning path
Run high-performance computing (HPC) applications on Azure - Training
Azure HPC is a purpose-built cloud capability for HPC & AI workload, using leading-edge processors and HPC-class InfiniBand interconnect, to deliver the best application performance, scalability, and value. Azure HPC enables users to unlock innovation, productivity, and business agility, through a highly available range of HPC & AI technologies that can be dynamically allocated as your business and technical needs change. This learning path is a series of modules that help you get started on Azure HPC - you