Azure AI Translation Document Py

1---
2name: azure-ai-translation-document-py
3description: |
4  Azure AI Document Translation SDK for batch translation of documents with format preservation. Use for translating Word, PDF, Excel, PowerPoint, and other document formats at scale.
5  Triggers: "document translation", "batch translation", "translate documents", "DocumentTranslationClient".
6package: azure-ai-translation-document
7---
8 
9# Azure AI Document Translation SDK for Python
10 
11Client library for Azure AI Translator document translation service for batch document translation with format preservation.
12 
13## Installation
14 
15```bash
16pip install azure-ai-translation-document
17```
18 
19## Environment Variables
20 
21```bash
22AZURE_DOCUMENT_TRANSLATION_ENDPOINT=https://<resource>.cognitiveservices.azure.com
23AZURE_DOCUMENT_TRANSLATION_KEY=<your-api-key>  # If using API key
24 
25# Storage for source and target documents
26AZURE_SOURCE_CONTAINER_URL=https://<storage>.blob.core.windows.net/<container>?<sas>
27AZURE_TARGET_CONTAINER_URL=https://<storage>.blob.core.windows.net/<container>?<sas>
28```
29 
30## Authentication
31 
32### API Key
33 
34```python
35import os
36from azure.ai.translation.document import DocumentTranslationClient
37from azure.core.credentials import AzureKeyCredential
38 
39endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"]
40key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"]
41 
42client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))
43```
44 
45### Entra ID (Recommended)
46 
47```python
48from azure.ai.translation.document import DocumentTranslationClient
49from azure.identity import DefaultAzureCredential
50 
51client = DocumentTranslationClient(
52    endpoint=os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"],
53    credential=DefaultAzureCredential()
54)
55```
56 
57## Basic Document Translation
58 
59```python
60from azure.ai.translation.document import DocumentTranslationInput, TranslationTarget
61 
62source_url = os.environ["AZURE_SOURCE_CONTAINER_URL"]
63target_url = os.environ["AZURE_TARGET_CONTAINER_URL"]
64 
65# Start translation job
66poller = client.begin_translation(
67    inputs=[
68        DocumentTranslationInput(
69            source_url=source_url,
70            targets=[
71                TranslationTarget(
72                    target_url=target_url,
73                    language="es"  # Translate to Spanish
74                )
75            ]
76        )
77    ]
78)
79 
80# Wait for completion
81result = poller.result()
82 
83print(f"Status: {poller.status()}")
84print(f"Documents translated: {poller.details.documents_succeeded_count}")
85print(f"Documents failed: {poller.details.documents_failed_count}")
86```
87 
88## Multiple Target Languages
89 
90```python
91poller = client.begin_translation(
92    inputs=[
93        DocumentTranslationInput(
94            source_url=source_url,
95            targets=[
96                TranslationTarget(target_url=target_url_es, language="es"),
97                TranslationTarget(target_url=target_url_fr, language="fr"),
98                TranslationTarget(target_url=target_url_de, language="de")
99            ]
100        )
101    ]
102)
103```
104 
105## Translate Single Document
106 
107```python
108from azure.ai.translation.document import SingleDocumentTranslationClient
109 
110single_client = SingleDocumentTranslationClient(endpoint, AzureKeyCredential(key))
111 
112with open("document.docx", "rb") as f:
113    document_content = f.read()
114 
115result = single_client.translate(
116    body=document_content,
117    target_language="es",
118    content_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document"
119)
120 
121# Save translated document
122with open("document_es.docx", "wb") as f:
123    f.write(result)
124```
125 
126## Check Translation Status
127 
128```python
129# Get all translation operations
130operations = client.list_translation_statuses()
131 
132for op in operations:
133    print(f"Operation ID: {op.id}")
134    print(f"Status: {op.status}")
135    print(f"Created: {op.created_on}")
136    print(f"Total documents: {op.documents_total_count}")
137    print(f"Succeeded: {op.documents_succeeded_count}")
138    print(f"Failed: {op.documents_failed_count}")
139```
140 
141## List Document Statuses
142 
143```python
144# Get status of individual documents in a job
145operation_id = poller.id
146document_statuses = client.list_document_statuses(operation_id)
147 
148for doc in document_statuses:
149    print(f"Document: {doc.source_document_url}")
150    print(f"  Status: {doc.status}")
151    print(f"  Translated to: {doc.translated_to}")
152    if doc.error:
153        print(f"  Error: {doc.error.message}")
154```
155 
156## Cancel Translation
157 
158```python
159# Cancel a running translation
160client.cancel_translation(operation_id)
161```
162 
163## Using Glossary
164 
165```python
166from azure.ai.translation.document import TranslationGlossary
167 
168poller = client.begin_translation(
169    inputs=[
170        DocumentTranslationInput(
171            source_url=source_url,
172            targets=[
173                TranslationTarget(
174                    target_url=target_url,
175                    language="es",
176                    glossaries=[
177                        TranslationGlossary(
178                            glossary_url="https://<storage>.blob.core.windows.net/glossary/terms.csv?<sas>",
179                            file_format="csv"
180                        )
181                    ]
182                )
183            ]
184        )
185    ]
186)
187```
188 
189## Supported Document Formats
190 
191```python
192# Get supported formats
193formats = client.get_supported_document_formats()
194 
195for fmt in formats:
196    print(f"Format: {fmt.format}")
197    print(f"  Extensions: {fmt.file_extensions}")
198    print(f"  Content types: {fmt.content_types}")
199```
200 
201## Supported Languages
202 
203```python
204# Get supported languages
205languages = client.get_supported_languages()
206 
207for lang in languages:
208    print(f"Language: {lang.name} ({lang.code})")
209```
210 
211## Async Client
212 
213```python
214from azure.ai.translation.document.aio import DocumentTranslationClient
215from azure.identity.aio import DefaultAzureCredential
216 
217async def translate_documents():
218    async with DocumentTranslationClient(
219        endpoint=endpoint,
220        credential=DefaultAzureCredential()
221    ) as client:
222        poller = await client.begin_translation(inputs=[...])
223        result = await poller.result()
224```
225 
226## Supported Formats
227 
228| Category | Formats |
229|----------|---------|
230| Documents | DOCX, PDF, PPTX, XLSX, HTML, TXT, RTF |
231| Structured | CSV, TSV, JSON, XML |
232| Localization | XLIFF, XLF, MHTML |
233 
234## Storage Requirements
235 
236- Source and target containers must be Azure Blob Storage
237- Use SAS tokens with appropriate permissions:
238  - Source: Read, List
239  - Target: Write, List
240 
241## Best Practices
242 
2431. **Use SAS tokens** with minimal required permissions
2442. **Monitor long-running operations** with `poller.status()`
2453. **Handle document-level errors** by iterating document statuses
2464. **Use glossaries** for domain-specific terminology
2475. **Separate target containers** for each language
2486. **Use async client** for multiple concurrent jobs
2497. **Check supported formats** before submitting documents
250