Azure AI Translation Text Py

1---
2name: azure-ai-translation-text-py
3description: |
4  Azure AI Text Translation SDK for real-time text translation, transliteration, language detection, and dictionary lookup. Use for translating text content in applications.
5  Triggers: "text translation", "translator", "translate text", "transliterate", "TextTranslationClient".
6package: azure-ai-translation-text
7---
8 
9# Azure AI Text Translation SDK for Python
10 
11Client library for Azure AI Translator text translation service for real-time text translation, transliteration, and language operations.
12 
13## Installation
14 
15```bash
16pip install azure-ai-translation-text
17```
18 
19## Environment Variables
20 
21```bash
22AZURE_TRANSLATOR_KEY=<your-api-key>
23AZURE_TRANSLATOR_REGION=<your-region>  # e.g., eastus, westus2
24# Or use custom endpoint
25AZURE_TRANSLATOR_ENDPOINT=https://<resource>.cognitiveservices.azure.com
26```
27 
28## Authentication
29 
30### API Key with Region
31 
32```python
33import os
34from azure.ai.translation.text import TextTranslationClient
35from azure.core.credentials import AzureKeyCredential
36 
37key = os.environ["AZURE_TRANSLATOR_KEY"]
38region = os.environ["AZURE_TRANSLATOR_REGION"]
39 
40# Create credential with region
41credential = AzureKeyCredential(key)
42client = TextTranslationClient(credential=credential, region=region)
43```
44 
45### API Key with Custom Endpoint
46 
47```python
48endpoint = os.environ["AZURE_TRANSLATOR_ENDPOINT"]
49 
50client = TextTranslationClient(
51    credential=AzureKeyCredential(key),
52    endpoint=endpoint
53)
54```
55 
56### Entra ID (Recommended)
57 
58```python
59from azure.ai.translation.text import TextTranslationClient
60from azure.identity import DefaultAzureCredential
61 
62client = TextTranslationClient(
63    credential=DefaultAzureCredential(),
64    endpoint=os.environ["AZURE_TRANSLATOR_ENDPOINT"]
65)
66```
67 
68## Basic Translation
69 
70```python
71# Translate to a single language
72result = client.translate(
73    body=["Hello, how are you?", "Welcome to Azure!"],
74    to=["es"]  # Spanish
75)
76 
77for item in result:
78    for translation in item.translations:
79        print(f"Translated: {translation.text}")
80        print(f"Target language: {translation.to}")
81```
82 
83## Translate to Multiple Languages
84 
85```python
86result = client.translate(
87    body=["Hello, world!"],
88    to=["es", "fr", "de", "ja"]  # Spanish, French, German, Japanese
89)
90 
91for item in result:
92    print(f"Source: {item.detected_language.language if item.detected_language else 'unknown'}")
93    for translation in item.translations:
94        print(f"  {translation.to}: {translation.text}")
95```
96 
97## Specify Source Language
98 
99```python
100result = client.translate(
101    body=["Bonjour le monde"],
102    from_parameter="fr",  # Source is French
103    to=["en", "es"]
104)
105```
106 
107## Language Detection
108 
109```python
110result = client.translate(
111    body=["Hola, como estas?"],
112    to=["en"]
113)
114 
115for item in result:
116    if item.detected_language:
117        print(f"Detected language: {item.detected_language.language}")
118        print(f"Confidence: {item.detected_language.score:.2f}")
119```
120 
121## Transliteration
122 
123Convert text from one script to another:
124 
125```python
126result = client.transliterate(
127    body=["konnichiwa"],
128    language="ja",
129    from_script="Latn",  # From Latin script
130    to_script="Jpan"      # To Japanese script
131)
132 
133for item in result:
134    print(f"Transliterated: {item.text}")
135    print(f"Script: {item.script}")
136```
137 
138## Dictionary Lookup
139 
140Find alternate translations and definitions:
141 
142```python
143result = client.lookup_dictionary_entries(
144    body=["fly"],
145    from_parameter="en",
146    to="es"
147)
148 
149for item in result:
150    print(f"Source: {item.normalized_source} ({item.display_source})")
151    for translation in item.translations:
152        print(f"  Translation: {translation.normalized_target}")
153        print(f"  Part of speech: {translation.pos_tag}")
154        print(f"  Confidence: {translation.confidence:.2f}")
155```
156 
157## Dictionary Examples
158 
159Get usage examples for translations:
160 
161```python
162from azure.ai.translation.text.models import DictionaryExampleTextItem
163 
164result = client.lookup_dictionary_examples(
165    body=[DictionaryExampleTextItem(text="fly", translation="volar")],
166    from_parameter="en",
167    to="es"
168)
169 
170for item in result:
171    for example in item.examples:
172        print(f"Source: {example.source_prefix}{example.source_term}{example.source_suffix}")
173        print(f"Target: {example.target_prefix}{example.target_term}{example.target_suffix}")
174```
175 
176## Get Supported Languages
177 
178```python
179# Get all supported languages
180languages = client.get_supported_languages()
181 
182# Translation languages
183print("Translation languages:")
184for code, lang in languages.translation.items():
185    print(f"  {code}: {lang.name} ({lang.native_name})")
186 
187# Transliteration languages
188print("\nTransliteration languages:")
189for code, lang in languages.transliteration.items():
190    print(f"  {code}: {lang.name}")
191    for script in lang.scripts:
192        print(f"    {script.code} -> {[t.code for t in script.to_scripts]}")
193 
194# Dictionary languages
195print("\nDictionary languages:")
196for code, lang in languages.dictionary.items():
197    print(f"  {code}: {lang.name}")
198```
199 
200## Break Sentence
201 
202Identify sentence boundaries:
203 
204```python
205result = client.find_sentence_boundaries(
206    body=["Hello! How are you? I hope you are well."],
207    language="en"
208)
209 
210for item in result:
211    print(f"Sentence lengths: {item.sent_len}")
212```
213 
214## Translation Options
215 
216```python
217result = client.translate(
218    body=["Hello, world!"],
219    to=["de"],
220    text_type="html",           # "plain" or "html"
221    profanity_action="Marked",  # "NoAction", "Deleted", "Marked"
222    profanity_marker="Asterisk", # "Asterisk", "Tag"
223    include_alignment=True,      # Include word alignment
224    include_sentence_length=True # Include sentence boundaries
225)
226 
227for item in result:
228    translation = item.translations[0]
229    print(f"Translated: {translation.text}")
230    if translation.alignment:
231        print(f"Alignment: {translation.alignment.proj}")
232    if translation.sent_len:
233        print(f"Sentence lengths: {translation.sent_len.src_sent_len}")
234```
235 
236## Async Client
237 
238```python
239from azure.ai.translation.text.aio import TextTranslationClient
240from azure.core.credentials import AzureKeyCredential
241 
242async def translate_text():
243    async with TextTranslationClient(
244        credential=AzureKeyCredential(key),
245        region=region
246    ) as client:
247        result = await client.translate(
248            body=["Hello, world!"],
249            to=["es"]
250        )
251        print(result[0].translations[0].text)
252```
253 
254## Client Methods
255 
256| Method | Description |
257|--------|-------------|
258| `translate` | Translate text to one or more languages |
259| `transliterate` | Convert text between scripts |
260| `detect` | Detect language of text |
261| `find_sentence_boundaries` | Identify sentence boundaries |
262| `lookup_dictionary_entries` | Dictionary lookup for translations |
263| `lookup_dictionary_examples` | Get usage examples |
264| `get_supported_languages` | List supported languages |
265 
266## Best Practices
267 
2681. **Batch translations** — Send multiple texts in one request (up to 100)
2692. **Specify source language** when known to improve accuracy
2703. **Use async client** for high-throughput scenarios
2714. **Cache language list** — Supported languages don't change frequently
2725. **Handle profanity** appropriately for your application
2736. **Use html text_type** when translating HTML content
2747. **Include alignment** for applications needing word mapping
275