Document Translation client-library SDKs

Document Translation is a cloud-based feature of the Azure Translator service. You can translate entire documents or process batch document translations in various file formats while preserving original document structure and format. In this article, you'll learn how to use the Document Translation service C#/.NET and Python client libraries. For the REST API, see our Quickstart guide.


To get started, you'll need:

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

  • A single-service Translator resource (not a multi-service Cognitive Services resource). Choose Global unless your business or application requires a specific region. Select the Standard S1 pricing tier to get started (document translation isn't supported for the free tier).

  • An Azure blob storage account. You'll create containers in your Azure blob storage account for your 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).
  • You also need to create Shared Access Signature (SAS) tokens for your source and target containers. The sourceUrl and targetUrl , 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.

For more information, see Create SAS tokens.

Client libraries

| Package (NuGet)| Client library | REST API | Product documentation | Samples |

Set up your project

In a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name batch-document-translation. This command creates a simple "Hello World" C# project with a single source file: program.cs.

dotnet new console -n batch-document-translation

Change your directory to the newly created app folder. Build your application with the following command:

dotnet build

The build output should contain no warnings or errors.

Build succeeded.
 0 Warning(s)
 0 Error(s)

Install the client library

Within the application directory, install the Document Translation client library for .NET using one of the following methods:


dotnet add package Azure.AI.Translation.Document --version 1.0.0

NuGet Package Manager

Install-Package Azure.AI.Translation.Document -Version 1.0.0

NuGet PackageReference

    <!-- ... -->
<PackageReference Include="Azure.AI.Translation.Document" Version="1.0.0" />
    <!-- ... -->

From the project directory, open the Program.cs file in your preferred editor or IDE. Add the following using directives:

using Azure;
using Azure.AI.Translation.Document;

using System;
using System.Threading;

In the application's Program class, create variables for your key and custom endpoint. For details, see Custom domain name and key

private static readonly string endpoint = "<your custom endpoint>";
private static readonly string key = "<your key>";

Translate a document or batch files

  • To Start a translation operation for one or more documents in a single blob container, you'll call the StartTranslationAsync method.

  • To call StartTranslationAsync, you need to initialize a DocumentTranslationInput object that contains the following parameters:

  • sourceUri. The SAS URI for the source container containing documents to be translated.

  • targetUri The SAS URI for the target container to which the translated documents will be written.

  • targetLanguageCode. The language code for the translated documents. You can find language codes on our Language support page.

public void StartTranslation() {
  Uri sourceUri = new Uri("<sourceUrl>");
  Uri targetUri = new Uri("<targetUrl>");

  DocumentTranslationClient client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(key));

  DocumentTranslationInput input = new DocumentTranslationInput(sourceUri, targetUri, "es")

  DocumentTranslationOperation operation = await client.StartTranslationAsync(input);

  await operation.WaitForCompletionAsync();

  Console.WriteLine($ "  Status: {operation.Status}");
  Console.WriteLine($ "  Created on: {operation.CreatedOn}");
  Console.WriteLine($ "  Last modified: {operation.LastModified}");
  Console.WriteLine($ "  Total documents: {operation.DocumentsTotal}");
  Console.WriteLine($ "    Succeeded: {operation.DocumentsSucceeded}");
  Console.WriteLine($ "    Failed: {operation.DocumentsFailed}");
  Console.WriteLine($ "    In Progress: {operation.DocumentsInProgress}");
  Console.WriteLine($ "    Not started: {operation.DocumentsNotStarted}");

  await foreach(DocumentStatusResult document in operation.Value) {
    Console.WriteLine($ "Document with Id: {document.DocumentId}");
    Console.WriteLine($ "  Status:{document.Status}");
    if (document.Status == TranslationStatus.Succeeded) {
      Console.WriteLine($ "  Translated Document Uri: {document.TranslatedDocumentUri}");
      Console.WriteLine($ "  Translated to language: {document.TranslatedTo}.");
      Console.WriteLine($ "  Document source Uri: {document.SourceDocumentUri}");
    else {
      Console.WriteLine($ "  Error Code: {document.Error.ErrorCode}");
      Console.WriteLine($ "  Message: {document.Error.Message}");

That's it! You've created a program to translate documents in a storage container using the .NET client library.

Next step