Azure Translator Overview

Neural machine translation service for real-time text and document translation across 100+ languages

Azure Translator

Azure Translator is a cloud-based neural machine translation service for translating text and documents across more than 100 languages and dialects. Powered by deep neural networks, Translator provides high-quality, context-aware translations for real-time and batch scenarios.

Key Capabilities

Text Translation

Real-time translation of text between languages

Document Translation

Translate entire documents while preserving formatting

Custom Translator

Train custom models for domain-specific terminology

Text Translation

Translate text in real-time with neural machine translation:

Basic Translation

Translate text between supported languages:

import requests
import uuid

endpoint = "https://api.cognitive.microsofttranslator.com"
path = '/translate?api-version=3.0'
params = '&to=de&to=es'
constructed_url = endpoint + path + params

headers = {
    'Ocp-Apim-Subscription-Key': '<your-key>',
    'Ocp-Apim-Subscription-Region': '<your-region>',
    'Content-type': 'application/json',
    'X-ClientTraceId': str(uuid.uuid4())
}

body = [{
    'text': 'Hello, how are you?'
}]

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

for translation in result[0]['translations']:
    print(f"{translation['to']}: {translation['text']}")

Features

Multiple Languages

Translate to multiple target languages in a single request:

# Translate to German, Spanish, and French
params = '&to=de&to=es&to=fr'

body = [{'text': 'Welcome to Azure Translator'}]
response = requests.post(url, headers=headers, json=body)

for translation in response.json()[0]['translations']:
    print(f"{translation['to']}: {translation['text']}")

Language Detection

Automatically detect source language:

path = '/detect?api-version=3.0'

body = [{
    'text': 'Bonjour, comment allez-vous?'
}]

response = requests.post(url, headers=headers, json=body)
result = response.json()[0]

print(f"Language: {result['language']}")
print(f"Confidence: {result['score']}")

Transliteration

Convert text between scripts (e.g., Chinese to Latin):

path = '/transliterate?api-version=3.0'
params = '&language=zh-Hans&fromScript=Hans&toScript=Latn'

body = [{'text': '你好'}]
response = requests.post(url, headers=headers, json=body)

print(response.json()[0]['text'])  # Output: ni hao

Dictionary Lookup

Get alternate translations and back-translations:

path = '/dictionary/lookup?api-version=3.0'
params = '&from=en&to=es'

body = [{'text': 'happy'}]
response = requests.post(url, headers=headers, json=body)

for translation in response.json()[0]['translations']:
    print(f"{translation['displayTarget']} ({translation['posTag']})")

Advanced Features

Dynamic Dictionary

Specify custom translations for specific terms:

body = [{
    'text': 'The word wordomatic is a custom term.',
    'translation': {
        'text': 'custom term',
        'to': 'es'
    }
}]

Prevent Translation

Mark content that should not be translated:

body = [{
    'text': 'This <mstrans:dictionary translation="custom">word</mstrans:dictionary> is custom.'
}]

Profanity Handling

Control how profanity is handled:

# Mark profanity with tags
params = '&to=de&profanityAction=Marked'

# Delete profanity
params = '&to=de&profanityAction=Deleted'

# No filtering (default)
params = '&to=de&profanityAction=NoAction'

Document Translation

Translate documents while preserving formatting and structure:

Batch Document Translation

Translate multiple documents asynchronously:

from azure.ai.translation.document import DocumentTranslationClient
from azure.core.credentials import AzureKeyCredential

client = DocumentTranslationClient(
    endpoint="https://<resource>.cognitiveservices.azure.com/",
    credential=AzureKeyCredential("<key>")
)

# Start batch translation
poller = client.begin_translation(
    source_url="https://<storage>.blob.core.windows.net/source?<sas>",
    target_url="https://<storage>.blob.core.windows.net/target?<sas>",
    target_language="de"
)

# Wait for completion
result = poller.result()

print(f"Status: {result.status}")
print(f"Documents translated: {result.documents_succeeded_count}")
print(f"Documents failed: {result.documents_failed_count}")

Single Document Translation

Translate individual documents synchronously:

import requests

url = "https://<resource>.cognitiveservices.azure.com/translator/document:translate"
params = {
    'api-version': '2024-05-01',
    'targetLanguage': 'de'
}

headers = {
    'Ocp-Apim-Subscription-Key': '<your-key>'
}

with open('document.pdf', 'rb') as document:
    files = {'document': document}
    response = requests.post(url, params=params, headers=headers, files=files)

with open('translated.pdf', 'wb') as output:
    output.write(response.content)

Supported Document Formats

• Text: TXT, HTML, HTM, MARKDOWN, MD
• Documents: DOCX, XLSX, PPTX, PDF
• Structured: JSON, TSV, CSV, XML
• Localization: XLIFF, TMX, XLF

Custom Translator

Train custom translation models for domain-specific terminology:

Use Cases

• Industry-specific terminology
• Brand names and product terms
• Legal and medical documents
• Technical documentation
• Consistent translation style

Training Process

1. Prepare Data

   Create parallel documents (source and target language pairs)

2. Create Project

   Set up a project in Custom Translator portal

3. Upload Documents

   Upload training, tuning, and testing documents

4. Train Model

   Train a custom model on your data

5. Test Model

   Evaluate model performance with test data

6. Deploy Model

   Publish model for use via API

Using Custom Models

# Use custom model in translation
params = '&to=de&category=<your-category-id>'

body = [{
    'text': 'Technical term specific to our industry'
}]

response = requests.post(url, params=params, headers=headers, json=body)

Dictionary Features

Create phrase and sentence dictionaries for custom models:

• Phrase Dictionary: Single-word or phrase translations
• Sentence Dictionary: Complete sentence translations (always used)
• Override base model translations
• Ensure consistent terminology

Language Support

Translator supports:

• 100+ languages for neural translation
• 90+ languages for text-to-speech
• 20+ writing systems for transliteration
• Endangered languages preservation support

Popular Languages

• English, Spanish, French, German, Italian
• Chinese (Simplified & Traditional), Japanese, Korean
• Arabic, Russian, Portuguese, Hindi
• And 90+ more languages

Use Cases

Global Communication

• Translate customer emails and support tickets
• Localize marketing content
• Enable multilingual chat and messaging
• Translate social media posts

Content Localization

• Localize websites and applications
• Translate documentation and help content
• Localize e-learning materials
• Translate video subtitles

Document Processing

• Translate contracts and legal documents
• Localize technical manuals
• Translate research papers
• Process multilingual invoices

E-commerce

• Translate product descriptions
• Localize product catalogs
• Translate customer reviews
• Support international customers

API Versions

Text Translation v3 (Stable)

• Real-time text translation
• Language detection
• Transliteration
• Dictionary features
• Widely adopted and stable

Text Translation 2025-10-01-preview

• LLM-based translation models
• Adaptive custom translation
• Enhanced context understanding
• Expanded request parameters

SDK Support

Python

pip install azure-ai-translation-text
pip install azure-ai-translation-document

C#

dotnet add package Azure.AI.Translation.Text
dotnet add package Azure.AI.Translation.Document

Java

Maven packages for text and document translation

JavaScript

npm install @azure-rest/ai-translation-text
npm install @azure-rest/ai-translation-document

Input Requirements

Text Translation

• Maximum request size: 50,000 characters
• Maximum array elements: 100
• Request rate limits: Varies by tier

Document Translation

• Maximum file size: 40 MB per document
• Maximum batch size: 1000 documents
• Total batch size: 250 MB
• Maximum concurrent batches: 5

Containers

Run Translator on-premises or at the edge:

• Text Translation container: Translate text offline
• Document Translation container: Process documents locally
• Maintain data privacy and compliance
• Low-latency local processing

Pricing

Text Translation

• Free Tier (F0): 2M characters per month
• Standard Tier (S1): Pay per million characters
• Custom models: Additional training and hosting costs

Document Translation

• Free Tier (F0): 2M characters per month
• Standard Tier (S1): Pay per million characters
• Storage costs for source and target documents

Getting Started

1. Create Resource

   Create a Translator resource in the Azure Portal

2. Get Credentials

   Retrieve your subscription key and region

3. Choose API

   Select text translation, document translation, or custom translator

4. Make Requests

   Use REST API or SDK to translate content

Best Practices

• Use language detection for unknown source languages
• Batch multiple texts in single requests for efficiency
• Implement caching for repeated translations
• Use custom models for domain-specific content
• Handle profanity based on your use case
• Monitor translation quality and costs
• Implement retry logic for transient failures

Regional Availability

Translator is available globally in all Azure regions that support Cognitive Services.

Next Steps

• View Text Translation Quickstart
• Learn about Document Translation
• Explore Custom Translator
• View Language Support