Translating Documents with Azure AI Translator's sync API

The Azure AI Translator service offers two approaches for document translation: asynchronous batch processing and synchronous single-document translation. While the asynchronous approach is well-documented and widely used for large-scale operations, the synchronous API for single documents is a powerful yet underutilized feature that deserves more attention.

In this guide, I will talk a bit more on when to use the synchronous API and show you how you can implement it in your applications.

What is synchronous document translation?

The synchronous document translation API allows you to translate a single document in real-time without requiring Azure Blob Storage. Unlike the asynchronous batch translation that processes multiple documents and requires storage containers, the synchronous API:

• Processes one document at a time - Perfect for on-demand translations
• Returns results immediately - No polling required
• Requires no storage setup - The translated document is returned directly in the HTTP response
• Maintains document formatting - Preserves the original layout and structure

When to use synchronous vs asynchronous translation

When To use synchronous translation when:

• You need immediate results for single documents
• Working with smaller files (under 10MB file size limits)
• Building interactive applications where users upload and receive translated documents instantly
• You want to avoid Azure Storage complexity and costs
• Processing user-generated content in real-time

When to use asynchronous translation:

• Translating multiple documents simultaneously
• Working with large files or batch operations
• Building background processing systems
• You need to translate entire document collections

How to use the synchronous API

In the official documentation, you can find the details about the query parameters and the request body structure, but not a lot of examples, that is why I thought it would be useful to provide a practical example of how to use the synchronous API in a web application.

1
async function translateDocument(
2
  file,
3
  sourceLanguage,
4
  targetLanguage,
5
  subscriptionKey,
6
  endpoint
7
) {
8
  const url = new URL(`${endpoint}/translator/document:translate`);
9
  url.searchParams.append("targetLanguage", targetLanguage);
10
  if (sourceLanguage) {
11
    url.searchParams.append("sourceLanguage", sourceLanguage);
12
  }
13
  url.searchParams.append("api-version", "2024-05-01");
14

15
  const formData = new FormData();
16
  formData.append("document", file, file.name);
17

18
  try {
19
    const response = await fetch(url.toString(), {
20
      method: "POST",
21
      headers: {
22
        "Ocp-Apim-Subscription-Key": subscriptionKey,
23
      },
24
      body: formData,
25
    });
26

27
    if (!response.ok) {
28
      const errorText = await response.text();
29
      throw new Error(`Translation failed: ${response.status} ${errorText}`);
30
    }
31

32
    const blob = await response.blob();
33
    return blob;
34
  } catch (error) {
35
    console.error("Translation error:", error);
36
    throw error;
37
  }
38
}
39

40
// Use a file input like: <input type="file" id="fileInput" accept=".docx,.pdf,.txt,.html,.htm,.rtf,.odt,.xlsx,.pptx">
41
const fileInput = document.getElementById("fileInput");
42
if (!fileInput.files.length) {
43
  console.error("No file selected");
44
  return;
45
}
46

47
const file = fileInput.files[0];
48
const translatedBlob = await translateDocument(
49
  file,
50
  "en",
51
  "es",
52
  "YOUR_SUBSCRIPTION_KEY",
53
  "https://your-resource.cognitiveservices.azure.com"
54
);
55

56
// Create download link
57
const link = document.createElement("a");
58
link.href = URL.createObjectURL(translatedBlob);
59
link.download = `translated-${file.name}`;
60
link.click();

This example demonstrates how to use the synchronous API to translate a document selected by the user. The function translateDocument takes the file, source and target languages, subscription key, and endpoint as parameters. It constructs the request URL, prepares the form data, and sends the POST request to the Azure Translator service.

The response is returned as a Blob, which can be used to create a download link for the translated document.

Conclusion

The synchronous document translation API in Azure AI Translator is a powerful tool for real-time, single-document translations. It simplifies the translation process by eliminating the need for storage and allowing immediate results, making it ideal for interactive applications and user-generated content.