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
Language Detection
Transliteration
Dictionary Lookup

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

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

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

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

Prepare Data

Create parallel documents (source and target language pairs)

Create Project

Set up a project in Custom Translator portal

Upload Documents

Upload training, tuning, and testing documents

Train Model

Train a custom model on your data

Test Model

Evaluate model performance with test data

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

Create Resource

Create a Translator resource in the Azure Portal

Get Credentials

Retrieve your subscription key and region

Choose API

Select text translation, document translation, or custom translator

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.

Overview

Vision

Language

Speech

Decision

Content Understanding

​Azure Translator

​Key Capabilities

Text Translation

Document Translation

Custom Translator

​Text Translation

​Basic Translation

​Features

​Advanced Features

​Dynamic Dictionary

​Prevent Translation

​Profanity Handling

​Document Translation

​Batch Document Translation

​Single Document Translation

​Supported Document Formats

​Custom Translator

​Use Cases

​Training Process

​Using Custom Models

​Dictionary Features

​Language Support

​Popular Languages

​Use Cases

​API Versions

​Text Translation v3 (Stable)

​Text Translation 2025-10-01-preview

​SDK Support

Python

C#

Java

JavaScript

​Input Requirements

​Text Translation

​Document Translation

​Containers

​Pricing

​Text Translation

​Document Translation

​Getting Started

​Best Practices

​Regional Availability

​Next Steps

Build docs developers (and LLMs) love

Azure Translator

Key Capabilities

Text Translation

Basic Translation

Features

Advanced Features

Dynamic Dictionary

Prevent Translation

Profanity Handling

Document Translation

Batch Document Translation

Single Document Translation

Supported Document Formats

Custom Translator

Use Cases

Training Process

Using Custom Models

Dictionary Features

Language Support

Popular Languages

Use Cases

API Versions

Text Translation v3 (Stable)

Text Translation 2025-10-01-preview

SDK Support

Input Requirements

Text Translation

Document Translation

Containers

Pricing

Text Translation

Document Translation

Getting Started

Best Practices

Regional Availability

Next Steps