Get started with Document Translation

For this quickstart, we 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.

   

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

   

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

   

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

   

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

   

2. Select the Browse tab and type NewtonsoftJson.

   

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

   

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.

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");

        }

    }

}

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.

:::image type="content" source="../../media/visual-studio/run-visual-studio.png" alt-text="Screenshot: run your Visual Studio program.":::

Upon successful completion:

• The translated documents can be found in your target container.
• The successful POST method returns a 202 Accepted response code indicating that the service created the batch request.
• The POST request also returns response headers including Operation-Location that provides a value used in subsequent GET requests.

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

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

1. Download the Go version for your operating system.

2. Once the download is complete, run the installer.

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

    ```console
      go version
    ```
   

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.

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)
    var printHeader = (response.Header)
    prettyJSON, _ := json.MarshalIndent(printHeader, "", "  ")
    fmt.Printf("%s\n", prettyJSON)
}

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:

```console
 go run document-translation.go
```

Upon successful completion:

• The translated documents can be found in your target container.
• The successful POST method returns a 202 Accepted response code indicating that the service created the batch request.
• The POST request also returns response headers including Operation-Location that provides a value used in subsequent GET requests.

For this quickstart, we 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 Visual Studio Code, make sure you have the following installed in your development environment:

  • A Java Development Kit (OpenJDK) version 8 or later.

  • Gradle, version 6.8 or later.

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 creates 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")
}

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

   mkdir -p src/main/java
   

   The command creates the following 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.

   • Enter 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.

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);
        }
    }
}

• 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
     

Upon successful completion:

• The translated documents can be found in your target container.
• The successful POST method returns a 202 Accepted response code indicating that the service created the batch request.
• The POST request also returns response headers including Operation-Location that provides a value used in subsequent GET requests.

For this quickstart, we 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
   

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.

   • Enter 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.

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 = "{your-source-container-SAS-URL}";
let targetSASUrl = "{your-target-container-SAS-URL}"

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);
});

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

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

2. Enter and run the following command in your terminal:

   node index.js
   

Upon successful completion:

• The translated documents can be found in your target container.
• The successful POST method returns a 202 Accepted response code indicating that the service created the batch request.
• The POST request also returns response headers including Operation-Location that provides a value used in subsequent GET requests.

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
   

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.

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)

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

1. Navigate to your document-translation directory.

2. Enter and run the following command in your console:

   python document-translation.py
   

Upon successful completion:

• The translated documents can be found in your target container.
• The successful POST method returns a 202 Accepted response code indicating that the service created the batch request.
• The POST request also returns response headers including Operation-Location that provides a value used in subsequent GET requests.

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

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

• Windows.
• Mac or Linux.

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"
           }
         ]
       }
     ]
   }
   

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.

PowerShell

cmd /c curl "{your-document-translator-endpoint}/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-document-translator-endpoint}/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"

Upon successful completion:

• The translated documents can be found in your target container.
• The successful POST method returns a 202 Accepted response code indicating that the service created the batch request.
• The POST request also returns response headers including Operation-Location that provides a value used in subsequent GET requests.