Get started with Document Translation

Document Translation is a cloud-based feature of the Azure Translator service that asynchronously translates whole documents in supported languages and various file formats. In this quickstart, you'll learn to use Document Translation with a programming language of your choice to translate a source document into a target language while preserving structure and text formatting.

Prerequisites

Note

  • In most instances, when you create a Cognitive Service resource in the Azure portal, you have the option to create a multi-service key or a single-service key. However, Document Translation is currently supported in the Translator (single-service) resource only, and is not included in the Cognitive Services (multi-service) resource.

  • Document Translation is only supported in the S1 Standard Service Plan (Pay-as-you-go) or in the D3 Volume Discount Plan. See Cognitive Services pricing—Translator.

To get started, you'll need:

  • An active Azure account. If you don't have one, you can create a free account.

  • An Azure blob storage account. You'll create containers to store and organize your blob data within your storage account.

  • A single-service Translator resource (not a multi-service Cognitive Services resource):

    Complete the Translator project and instance details fields as follows:

    1. Subscription. Select one of your available Azure subscriptions.

    2. Resource Group. You can create a new resource group or add your resource to a pre-existing resource group that shares the same lifecycle, permissions, and policies.

    3. 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 non-global region.

    4. Name. Enter the name you have chosen 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 will be the custom domain name parameter for your endpoint.

    5. Pricing tier. Document Translation isn't supported in the free tier. Select Standard S1 to try the service.

    6. Select Review + Create.

    7. Review the service terms and select Create to deploy your resource.

    8. After your resource has successfully deployed, select Go to resource.

Your custom domain name and key

The custom domain endpoint is a URL formatted with your resource name, hostname, and Translator subdirectories and is available in the Azure portal.

Important

  • All API requests to the Document Translation service require a custom domain endpoint.
  • Don't use the Text Translation 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.

Retrieve your key and endpoint

Requests to the Translator service require a read-only key and custom endpoint to authenticate access.

  1. If you've 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.

  2. In the left rail, under Resource Management, select Keys and Endpoint.

  3. 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.

  4. You'll paste it into the code sample to authenticate your request to the Document Translation service.

    Screenshot showing the get your key field in Azure portal.

Create Azure blob storage containers

You'll need to create containers in your Azure blob storage account for source and target files.

  • Source container. This container is where you upload your files for translation (required).
  • Target container. This container is where your translated files will be stored (required).

Required authentication

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.

  • Your source container or blob must have designated read and list access.
  • Your target container or blob must have designated write and list access.
  • Your glossary blob must have designated read and list access.

Tip

  • If you're translating multiple files (blobs) in an operation, delegate SAS access at the container level.
  • If you're translating a single file (blob) in an operation, delegate SAS access at the blob level.
  • As an alternative to SAS tokens, you can use a system-assigned managed identity for authentication.

Sample document

For this project, you'll need a source document uploaded to your source container. You can download our document translation sample document for this quickstart.

HTTP request

A batch Document 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 batch request is created by the service. The translated documents will be listed in your target container.

Headers

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 Cognitive Services resource.
Content-Type Required: Specifies the content type of the payload. Accepted values are application/json or charset=UTF-8.

POST request body

  • The POST request body is a JSON object named inputs.
  • The inputs object contains both sourceURL and targetURL container addresses for your source and target language pairs.
  • The 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.
  • A value for the glossaries field (optional) is applied when the document is being translated.
  • The targetUrl for each target language must be unique.

Set up your C#/.NET environment

For this quickstart, we'll use the latest version of Visual Studio IDE to build and run the application.

  1. Start Visual Studio.

  2. On the Get started page, choose Create a new project.

    Screenshot of Visual Studio 2022 get started window.

  3. On the Create a new project page, enter console in the search box. Choose the Console Application template, then choose Next.

    Screenshot of Visual Studio 2022 create new project page.

  4. In the Configure your new project dialog window, enter document-translation-qs in the Project name box. Then choose Next.

    Screenshot of Visual Studio 2022 configure new project set-up window.

  5. In the Additional information dialog window, select .NET 6.0 (Long-term support), and then select Create.

    Screenshot of Visual Studio 2022 additional information set-up window.

Install Newtonsoft.Json

  1. Right-click on your document-translation-qs project and select Manage NuGet Packages... .

    Screenshot of select NuGet package window in Visual Studio.

  2. Select the Browse tab and type NewtonsoftJson.

    Screenshot of select pre-release NuGet package in Visual Studio.

  3. Select the latest stable version from the dropdown menu and install the package in your project.

    Screenshot of install selected NuGet package window.

Translate all documents in a storage container

Note

  • Starting with .NET 6, new projects using the console template generate a new program style that differs from previous versions.
  • The new output uses recent C# features that simplify the code you need to write.
  • When you use the newer version, you only need to write the body of the Main method. You don't need to include top-level statements, global using directives, or implicit using directives.
  • For more information, see New C# templates generate top-level statements.
  1. Open the Program.cs file.

  2. Delete the pre-existing code, including the line Console.Writeline("Hello World!").

  3. Copy and paste the document translation code sample into the Program.cs file.

    • Update {your-document-translation-endpoint} and {your-key} with values from your Azure portal Translator instance.

    • Update {your-source-container-SAS-URL} and {your-target-container-SAS-URL} with values from your Azure portal Storage account containers instance.

Code sample

Important

Remember to remove the key 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 Key Vault. For more information, see Cognitive Services security.


using System.Text;

class Program
{
    private static readonly string endpoint = "{your-document-translator-endpoint}/translator/text/batch/v1.0";

    private static readonly string key = "{your-key}";

    static readonly string route = "/batches";
    static readonly string sourceURL = "\" {your-source-container-SAS-URL}\"";
    static readonly string targetURL = " \"{your-target-container-SAS-URL}\"";


    static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\":"+sourceURL+" ,\"storageSource\": \"AzureBlob\",\"language\": \"en\"}, \"targets\": [{\"targetUrl\":"+targetURL+",\"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(endpoint + 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");

        }

    }

}

Run your application

  • Once you've added a code sample to your application, choose the green Start button next to document-translation-qs to build and run your program, or press F5.

    Screenshot: run your Visual Studio program.

  • The successful POST method returns a 202 Accepted response code indicating that the batch request was created by the service.

  • The POST request also returns response headers including Operation-Location that provides a value used in subsequent GET requests.

  • The translated documents will be listed in your target container.

Set up your Go environment

You can use any text editor to write Go applications. We recommend using the latest version of Visual Studio Code and the Go extension.

Tip

If you're new to Go, try the Get started with Go Learn module.

  1. If you haven't already done so, download and install Go.

    • Download the Go version for your operating system.

    • Once the download is complete, run the installer.

    • Open a command prompt and enter the following to confirm Go was installed:

        go version
      

Translate all documents in a storage container

  1. In a console window (such as cmd, PowerShell, or Bash), create a new directory for your app called document-translation-qs, and navigate to it.

  2. Create a new Go file named document-translation.go in the document-translation-qs directory.

  3. Copy and paste the document translation code sample into your document-translation.go file.

    • Update {your-document-translation-endpoint} and {your-key} with values from your Azure portal Translator instance.

    • Update the {your-source-container-SAS-URL} and {your-target-container-SAS-URL} with values from your Azure portal Storage account containers instance.

Code sample

Important

Remember to remove the key 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 Key Vault. For more information, see Cognitive Services security.


package main

import (
    "bytes"
  "encoding/json"
    "fmt"
    "net/http"
)

func main() {

    httpposturl := "{your-document-translation-endpoint}/translator/text/batch/v1.0/batches"
    fmt.Println("Response", httpposturl)

    var jsonData = []byte(`{
    "inputs": [
        {
            "source": {
                "sourceUrl": "{your-source-container-SAS-URL}"
            },
            "targets": [
                {
                    "{your-target-container-SAS-URL}",
                    "language": "fr"
                }
            ]
        }
    ]
}`)

    request, error := http.NewRequest("POST", httpposturl, bytes.NewBuffer(jsonData))
    request.Header.Set("Content-Type", "application/json")
    request.Header.Set("Ocp-Apim-Subscription-Key", "{your-key}")

    client := &http.Client{}
    response, error := client.Do(request)
    if error != nil {
        panic(error)
    }
    defer response.Body.Close()

    fmt.Println("response Status:", response.Status)
    //fmt.Println("response Headers:", response.Header)
  var printHeader = (response.Header)
    //body, _ := ioutil.ReadAll(response.body)
    prettyJSON, _ := json.MarshalIndent(printHeader, "", "  ")
    fmt.Printf("%s\n", prettyJSON)
  }


Run your Go application

  • Once you've added a code sample to your application, your Go program can be executed in a command or terminal prompt. Make sure your prompt's path is set to the document-translation-qs folder and use the following command:

     go run document-translation.go
    
  • The successful POST method returns a 202 Accepted response code indicating that the batch request was created by the service.

  • The POST request also returns response headers including Operation-Location that provides a value used in subsequent GET requests.

  • The translated documents will be listed in your target container.

Set up your Java environment

For this quickstart, we'll use the Gradle build automation tool to create and run the application.

  • You should have the latest version of Visual Studio Code or your preferred IDE. See Java in Visual Studio Code.

    Tip

    • Visual Studio Code offers a Coding Pack for Java for Windows and macOS.The coding pack is a bundle of VS Code, the Java Development Kit (JDK), and a collection of suggested extensions by Microsoft. The Coding Pack can also be used to fix an existing development environment.
    • If you are using VS Code and the Coding Pack For Java, install the Gradle for Java extension.
  • If you aren't using VS Code, make sure you have the following installed in your development environment:

Create a new Gradle project

  1. In console window (such as cmd, PowerShell, or Bash), create a new directory for your app called document-translation, and navigate to it.

    mkdir document-translation && document-translation
    
     mkdir document-translation; cd document-translation
    
  2. Run the gradle init command from the document-translation directory. This command will create essential build files for Gradle, including build.gradle.kts, which is used at runtime to create and configure your application.

    gradle init --type basic
    
  3. When prompted to choose a DSL, select Kotlin.

  4. Accept the default project name (document-translation) by selecting Return or Enter.

    Note

    It may take a few minutes for the entire application to be created, but soon you should see several folders and files including build-gradle.kts.

  5. Update build.gradle.kts with the following code:

plugins {
  java
  application
}
application {
  mainClass.set("DocumentTranslation")
}
repositories {
  mavenCentral()
}
dependencies {
  implementation("com.squareup.okhttp3:okhttp:4.10.0")
  implementation("com.google.code.gson:gson:2.9.0")
}

Translate all documents in a storage container

  1. From the document-translation directory, run the following command:

    mkdir -p src/main/java
    

    You'll create the following directory structure:

    Screenshot: Java directory structure.

  2. Navigate to the java directory and create a file named DocumentTranslation.java.

    Tip

    • You can create a new file using PowerShell.

    • Open a PowerShell window in your project directory by holding down the Shift key and right-clicking the folder.

    • Type the following command New-Item DocumentTranslation.java.

    • You can also create a new file in your IDE named DocumentTranslation.java and save it to the java directory.

  3. Copy and paste the document translation code sample into your DocumentTranslation.java file.

    • Update {your-document-translation-endpoint} and {your-key} with values from your Azure portal Translator instance.

    • Update the {your-source-container-SAS-URL} and {your-target-container-SAS-URL} with values from your Azure portal Storage account containers instance.

Code sample

Important

Remember to remove the key 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 Key Vault. For more information, see Cognitive Services security.

import java.io.*;
import java.net.*;
import java.util.*;
import okhttp3.*;

public class DocumentTranslation {
    String key = "{your-key}";

    String endpoint = "{your-document-translation-endpoint}/translator/text/batch/v1.0";

    String path = endpoint + "/batches";

    String sourceSASUrl = "{your-source-container-SAS-URL}";

    String targetSASUrl = "{your-target-container-SAS-URL}";

    String jsonInputString = (String.format("{\"inputs\":[{\"source\":{\"sourceUrl\":\"%s\"},\"targets\":[{\"targetUrl\":\"%s\",\"language\":\"fr\"}]}]}", sourceSASUrl, targetSASUrl));

    OkHttpClient client = new OkHttpClient();

    public void post() throws IOException {
        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType,  jsonInputString);
        Request request = new Request.Builder()
                .url(path).post(body)
                .addHeader("Ocp-Apim-Subscription-Key", key)
                .addHeader("Content-type", "application/json")
                .build();
        Response response = client.newCall(request).execute();
        System.out.println(response.code());
        System.out.println(response.headers());
    }

  public static void main(String[] args) {
        try {
            DocumentTranslation sampleRequest = new DocumentTranslation();
            sampleRequest.post();
        } catch (Exception e) {
            System.out.println(e);
        }
    }
}

Build and run your Java application

  • Once you've added a code sample to your application, navigate back to your main project directory, document-translation, open a console window, and enter the following commands:

    1. Build your application with the build command:

      gradle build
      
    2. Run your application with the run command:

      gradle run
      
  • The successful POST method returns a 202 Accepted response code indicating that the batch request was created by the service.

  • The POST request also returns response headers including Operation-Location that provides a value used in subsequent GET requests.

  • The translated documents will be listed in your target container.

Set up your Node.js environment

For this quickstart, we'll use the Node.js JavaScript runtime environment to create and run the application.

  1. If you haven't done so already, install the latest version of Node.js. Node Package Manager (npm) is included with the Node.js installation.

    Tip

    If you're new to Node.js, try the Introduction to Node.js Learn module.

  2. In a console window (such as cmd, PowerShell, or Bash), create and navigate to a new directory for your app named document-translation.

        mkdir document-translation && cd document-translation
    
      mkdir document-translation; cd document-translation
    
  3. Run the npm init command to initialize the application and scaffold your project.

       npm init
    
  4. Specify your project's attributes by accepting the prompts presented in the terminal.

    • The most important attributes are name, version number, and entry point.
    • We recommend keeping index.js for the entry point name. The description, test command, GitHub repository, keywords, author, and license information are optional attributes—they can be skipped for this project.
    • Accept the suggestions in parentheses by selecting Return or Enter.
    • After you've completed the prompts, a package.json file will be created in your document-translation directory.
  5. Use npm to install the axios HTTP library and uuid package in your document-translation app directory:

       npm install axios uuid
    

Translate all documents in a storage container

  1. Create the index.js file in the app directory.

    Tip

    • You can create a new file using PowerShell.

    • Open a PowerShell window in your project directory by holding down the Shift key and right-clicking the folder.

    • Type the following command New-Item index.js.

    • You can also create a new file named index.js in your IDE and save it to the document-translation directory.

  2. Copy and paste the document translation code sample into your index.js file.

    • Update {your-document-translation-endpoint} and {your-key} with values from your Azure portal Translator instance.

    • Update the {your-source-container-SAS-URL} and {your-target-container-SAS-URL} with values from your Azure portal Storage account containers instance.

Code sample

Important

Remember to remove the key 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 Key Vault. For more information, see Cognitive Services security.

const axios = require('axios').default;

let endpoint = '{your-document-translation-endpoint}/translator/text/batch/v1.0';
let route = '/batches';
let key = '{your-key}';
let sourceSASUrl = "https://januaristorage.blob.core.windows.net/source-doc-translator?sp=rwl&st=2022-12-16T21:02:29Z&se=2022-12-17T05:02:29Z&spr=https&sv=2021-06-08&sr=c&sig=iL%2BAFVloS4cchKs0SCoq54umv7V2UnDJd8g7URhfmpA%3D";
let targetSASUrl = "https://januaristorage.blob.core.windows.net/target-doc-translator?sp=rwl&st=2022-12-16T21:03:34Z&se=2022-12-17T05:03:34Z&spr=https&sv=2021-06-08&sr=c&sig=B2MOzqQxHf64AEOy4mk%2F3XVx43zG3p5VICvFXV335qY%3D"

let data = JSON.stringify({"inputs": [
  {
      "source": {
          "sourceUrl": sourceSASUrl,
          "storageSource": "AzureBlob",
          "language": "en"
      },
      "targets": [
          {
              "targetUrl": targetSASUrl,
              "storageSource": "AzureBlob",
              "category": "general",
              "language": "es"}]}]});

let config = {
  method: 'post',
  baseURL: endpoint,
  url: route,
  headers: {
    'Ocp-Apim-Subscription-Key': key,
    'Content-Type': 'application/json'
  },
  data: data
};

axios(config)
.then(function (response) {
  let result = { statusText: response.statusText, statusCode: response.status, headers: response.headers };
  console.log()
  console.log(JSON.stringify(result, null, 2));
})
.catch(function (error) {
  console.log(error);
});

Run your JavaScript application

  • Once you've added the code sample to your application, run your program:

    1. Navigate to your application directory (document-translation).

    2. Type the following command in your terminal:

      node index.js
      
  • The successful POST method returns a 202 Accepted response code indicating that the batch request was created by the service.

  • The POST request also returns response headers including Operation-Location that provides a value used in subsequent GET requests.

  • The translated documents will be listed in your target container.

Set up your Python project

  1. If you haven't done so already, install the latest version of Python 3.x. The Python installer package (pip) is included with the Python installation.

    Tip

    If you're new to Python, try the Introduction to Python Learn module.

  2. Open a terminal window and use pip to install the Requests library and uuid0 package:

       pip install requests uuid
    

    Note

    We will also use a Python built-in package called json. It's used to work with JSON data.

Translate all documents in a storage container

  1. Using your preferred editor or IDE, create a new directory for your app named document-translation.

  2. Create a new Python file called document-translation.py in your document-translation directory.

  3. Copy and paste the document translation code sample into your document-translation.py file.

    • Update {your-document-translation-endpoint} and {your-key} with values from your Azure portal Translator instance.

    • Update the {your-source-container-SAS-URL} and {your-target-container-SAS-URL} with values from your Azure portal Storage account containers instance.

Code sample

Important

Remember to remove the key 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 Key Vault. For more information, see Cognitive Services security.

import requests

endpoint = '{your-document-translation-endpoint}'
key =  '{your-key}'
path = 'translator/text/batch/v1.0/batches'
constructed_url = endpoint + path

sourceSASUrl = '{your-source-container-SAS-URL}'

targetSASUrl = '{your-target-container-SAS-URL}'

body= {
    "inputs": [
        {
            "source": {
                "sourceUrl": sourceSASUrl,
                "storageSource": "AzureBlob",
                "language": "en"
            },
            "targets": [
                {
                    "targetUrl": targetSASUrl,
                    "storageSource": "AzureBlob",
                    "category": "general",
                    "language": "es"
                }
            ]
        }
    ]
}
headers = {
  'Ocp-Apim-Subscription-Key': key,
  'Content-Type': 'application/json',
}

response = requests.post(constructed_url, headers=headers, json=body)
response_headers = response.headers

print(f'response status code: {response.status_code}\nresponse status: {response.reason}\n\nresponse headers:\n')

for key, value in response_headers.items():
    print(key, ":", value)

Run your Python application

  • Once you've added a code sample to your application, build and run your program:

    1. Navigate to your document-translation directory.

    2. Type the following command in your console:

      python document-translation.py
      
      
  • The successful POST method returns a 202 Accepted response code indicating that the batch request was created by the service.

  • The POST request also returns response headers including Operation-Location that provides a value used in subsequent GET requests.

  • The translated documents will be listed in your target container.

Set up your programming environment

In this quickstart we'll, use the cURL command line tool to make Document Translation REST API calls.

Note

The cURL package is pre-installed on most Windows 10 and Windows 11 and most macOS and Linux distributions. You can check the package version with the following commands: Windows: curl.exe -V. macOS curl -V Linux: curl --version

If you don't have cURL installed, here are links for your platform:

Translate documents (POST Request)

  1. Using your preferred editor or IDE, create a new directory for your app named document-translation.

  2. Create a new json file called document-translation.json in your document-translation directory.

  3. Copy and paste the document translation request sample into your document-translation.json file. Replace {your-source-container-SAS-URL} and {your-target-container-SAS-URL} with values from your Azure portal Storage account containers instance.

    **Request sample**

    {
      "inputs":[
        {
          "source":{
            "sourceUrl":"{your-source-container-SAS-URL}"
          },
          "targets":[
            {
              "targetUrl":"{your-target-container-SAS-URL}",
              "language":"fr"
            }
          ]
        }
      ]
    }
    

Build and run the POST request

Before you run the POST request, replace {your-source-container-SAS-URL} and {your-key} with the endpoint value from your Azure portal Translator instance.

Important

Remember to remove the key 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 Key Vault. For more information, see Cognitive Services security.

PowerShell

    cmd /c curl "{your-source-container-SAS-URL}/translator/text/batch/v1.0/batches" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-translation.json"

command prompt / terminal

    curl "{your-source-container-SAS-URL}/translator/text/batch/v1.0/batches" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-translation.json"
  • The successful POST method returns a 202 Accepted response code indicating that the batch request was created by the service.

  • The POST request also returns response headers including Operation-Location that provides a value used in subsequent GET requests.

  • The translated documents will be listed in your target container.

That's it, congratulations! In this quickstart, you used Document Translation to translate a document while preserving it's original structure and data format.

Next steps

Learn more about Document Translation: