AI 原生开放教材

外观

Microsoft Agent Skills技能与配置库·英文原文 ↗原件 ↓仓库 ↗

Azure AI Document Translation SDK Acceptance Criteria ​

SDK: azure-ai-translation-documentRepository: https://github.com/Azure/azure-sdk-for-pythonPurpose: Skill testing acceptance criteria for validating generated code correctness

1. Correct Import Patterns ​

1.1 Client Imports ​

✅ CORRECT: Sync Client ​

python
from azure.ai.translation.document import DocumentTranslationClient
from azure.core.credentials import AzureKeyCredential
# OR
from azure.identity import DefaultAzureCredential

✅ CORRECT: Async Client ​

python
from azure.ai.translation.document.aio import DocumentTranslationClient
from azure.identity.aio import DefaultAzureCredential

✅ CORRECT: Single Document Client ​

python
from azure.ai.translation.document import SingleDocumentTranslationClient
from azure.core.credentials import AzureKeyCredential

1.2 Model Imports ​

✅ CORRECT: Input/Output Models ​

python
from azure.ai.translation.document import (
    DocumentTranslationInput,
    TranslationTarget,
)

✅ CORRECT: Glossary Models ​

python
from azure.ai.translation.document import TranslationGlossary

✅ CORRECT: File Purpose Enum ​

python
from azure.ai.translation.document import FilePurpose

1.3 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Wrong import paths ​

python
# WRONG - DocumentTranslationInput is not directly in azure.ai.translation
from azure.ai.translation import DocumentTranslationInput

# WRONG - Trying to import non-existent TranslationDocument
from azure.ai.translation.document import TranslationDocument

❌ INCORRECT: Mixing sync and async imports ​

python
# WRONG - using sync client with async context manager
from azure.ai.translation.document import DocumentTranslationClient
async with DocumentTranslationClient(...) as client:
    ...

The fix: Use the async client from azure.ai.translation.document.aio when using async context managers. Import DocumentTranslationClient from .aio instead of the base module, then use async with for proper async context management.

2. Client Creation Patterns ​

2.1 ✅ CORRECT: Sync Client with Entra ID (Recommended) ​

python
import os
from azure.ai.translation.document import DocumentTranslationClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"]
client = DocumentTranslationClient(endpoint, DefaultAzureCredential())

# Use with context manager for cleanup
with client:
    # Use client
    pass

2.2 ✅ CORRECT: Sync Client with API Key ​

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

endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"]
key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"]

client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))

2.3 ✅ CORRECT: Async Client ​

python
import os
from azure.ai.translation.document.aio import DocumentTranslationClient
from azure.identity.aio import DefaultAzureCredential

endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"]
client = DocumentTranslationClient(endpoint, DefaultAzureCredential())

async with client:
    # Use client
    pass

2.4 ✅ CORRECT: Single Document Client ​

python
from azure.ai.translation.document import SingleDocumentTranslationClient
from azure.core.credentials import AzureKeyCredential

single_client = SingleDocumentTranslationClient(endpoint, AzureKeyCredential(key))

2.5 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Hardcoded credentials ​

python
# WRONG - Never hardcode credentials
client = DocumentTranslationClient("https://example.cognitiveservices.azure.com", AzureKeyCredential("key123"))

❌ INCORRECT: Wrong parameter names ​

python
# WRONG - should be 'endpoint' not 'url'
client = DocumentTranslationClient(url=endpoint, credential=cred)

❌ INCORRECT: Not using context manager ​

python
# WRONG - should close client explicitly or use context manager
client = DocumentTranslationClient(endpoint, credential)
poller = client.begin_translation(...)
# Missing: client.close() or proper cleanup

3. Batch Document Translation Patterns ​

3.1 ✅ CORRECT: Basic Batch Translation ​

python
from azure.ai.translation.document import (
    DocumentTranslationInput,
    TranslationTarget,
)

source_url = os.environ["AZURE_SOURCE_CONTAINER_URL"]
target_url = os.environ["AZURE_TARGET_CONTAINER_URL"]

poller = client.begin_translation(
    inputs=[
        DocumentTranslationInput(
            source_url=source_url,
            targets=[
                TranslationTarget(
                    target_url=target_url,
                    language="es"
                )
            ]
        )
    ]
)

# Wait for completion
result = poller.result()

3.2 ✅ CORRECT: Multiple Target Languages ​

python
poller = client.begin_translation(
    inputs=[
        DocumentTranslationInput(
            source_url=source_url,
            targets=[
                TranslationTarget(target_url=target_url_es, language="es"),
                TranslationTarget(target_url=target_url_fr, language="fr"),
                TranslationTarget(target_url=target_url_de, language="de"),
            ]
        )
    ]
)

3.3 ✅ CORRECT: Batch with Glossary ​

python
from azure.ai.translation.document import TranslationGlossary

poller = client.begin_translation(
    inputs=[
        DocumentTranslationInput(
            source_url=source_url,
            targets=[
                TranslationTarget(
                    target_url=target_url,
                    language="es",
                    glossaries=[
                        TranslationGlossary(
                            glossary_url="https://<storage>.blob.core.windows.net/glossary/terms.csv",
                            file_format="csv"
                        )
                    ]
                )
            ]
        )
    ]
)

3.4 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Inline blob URLs without SAS ​

python
# WRONG - blob URLs need SAS tokens for security
poller = client.begin_translation(
    inputs=[
        DocumentTranslationInput(
            source_url="https://storage.blob.core.windows.net/container/",  # Missing SAS
            targets=[...]
        )
    ]
)

❌ INCORRECT: Wrong parameter names ​

python
# WRONG - should use 'inputs' not 'documents'
poller = client.begin_translation(
    documents=[DocumentTranslationInput(...)]  # Wrong
)

4. Single Document Translation ​

4.1 ✅ CORRECT: Translate Single Document ​

python
from azure.ai.translation.document import SingleDocumentTranslationClient

single_client = SingleDocumentTranslationClient(endpoint, AzureKeyCredential(key))

with open("document.docx", "rb") as f:
    document_content = f.read()

result = single_client.translate(
    body=document_content,
    target_language="es",
    content_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document"
)

# Save result
with open("document_es.docx", "wb") as f:
    f.write(result)

4.2 ✅ CORRECT: Single Document with Glossary ​

python
result = single_client.translate(
    body=document_content,
    target_language="es",
    content_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    glossary_url="https://<storage>.blob.core.windows.net/glossary/terms.csv"
)

4.3 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Using batch client for single document ​

python
# WRONG - use SingleDocumentTranslationClient instead
client = DocumentTranslationClient(...)
result = client.translate(...)  # DocumentTranslationClient doesn't have translate method

5. Status Polling & Monitoring ​

5.1 ✅ CORRECT: Check Translation Status ​

python
# After begin_translation, check status
poller = client.begin_translation(inputs=[...])

# Check overall status
print(f"Status: {poller.status()}")
print(f"Succeeded: {poller.details.documents_succeeded_count}")
print(f"Failed: {poller.details.documents_failed_count}")

# Wait for completion
result = poller.result()

5.2 ✅ CORRECT: List Translation Operations ​

python
operations = client.list_translation_statuses()

for op in operations:
    print(f"Operation ID: {op.id}")
    print(f"Status: {op.status}")
    print(f"Total documents: {op.documents_total_count}")
    print(f"Succeeded: {op.documents_succeeded_count}")
    print(f"Failed: {op.documents_failed_count}")

5.3 ✅ CORRECT: List Document Statuses in Job ​

python
operation_id = poller.id
document_statuses = client.list_document_statuses(operation_id)

for doc in document_statuses:
    print(f"Document: {doc.source_document_url}")
    print(f"Status: {doc.status}")
    print(f"Translated to: {doc.translated_to}")
    if doc.error:
        print(f"Error: {doc.error.message}")

5.4 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Not checking for errors ​

python
# WRONG - not handling failed documents
operations = client.list_translation_statuses()
for op in operations:
    # Not checking if documents_failed_count > 0
    pass

❌ INCORRECT: Wrong status enum values ​

python
# WRONG - status strings vary, should check actual enum
if op.status == "completed":  # May not match actual status string
    pass

6. Async Patterns ​

6.1 ✅ CORRECT: Async Batch Translation ​

python
import asyncio
from azure.ai.translation.document.aio import DocumentTranslationClient
from azure.identity.aio import DefaultAzureCredential

async def translate_documents():
    async with DocumentTranslationClient(
        endpoint=os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"],
        credential=DefaultAzureCredential()
    ) as client:
        poller = await client.begin_translation(
            inputs=[
                DocumentTranslationInput(
                    source_url=source_url,
                    targets=[TranslationTarget(target_url=target_url, language="es")]
                )
            ]
        )
        
        result = await poller.result()
        return result

asyncio.run(translate_documents())

6.2 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Sync client in async function ​

python
# WRONG - using sync client in async context
async def bad_example():
    from azure.ai.translation.document import DocumentTranslationClient
    async with DocumentTranslationClient(...) as client:  # Won't work, not async
        ...

The fix: Import the async variant from azure.ai.translation.document.aio instead. The sync DocumentTranslationClient is not compatible with async context managers (async with). Always use the .aio module when working in async functions.

❌ INCORRECT: Missing await ​

python
# WRONG - missing await for async operations
async def bad():
    poller = client.begin_translation(...)  # Missing await
    result = poller.result()  # Missing await

7. Format Preservation & Supported Formats ​

7.1 ✅ CORRECT: Get Supported Document Formats ​

python
formats = client.get_supported_document_formats()

for fmt in formats:
    print(f"Format: {fmt.format}")
    print(f"Extensions: {fmt.file_extensions}")
    print(f"Content types: {fmt.content_types}")

7.2 ✅ CORRECT: Get Supported Languages ​

python
languages = client.get_supported_languages()

for lang in languages:
    print(f"Language: {lang.name} ({lang.code})")
    print(f"Direction: {lang.direction}")

7.3 ✅ CORRECT: Common Content Types ​

python
# For single document translation, specify content type
content_types = {
    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx",
    "application/vnd.openxmlformats-officedocument.presentationml.presentation": "pptx",
    "application/pdf": "pdf",
    "text/html": "html",
    "text/plain": "txt",
}

result = single_client.translate(
    body=document_content,
    target_language="es",
    content_type=content_types["application/pdf"]
)

7.4 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Wrong file format ​

python
# WRONG - passing wrong content type for file type
with open("document.docx", "rb") as f:
    result = single_client.translate(
        body=f.read(),
        target_language="es",
        content_type="application/pdf"  # Wrong! File is DOCX
    )

8. Error Handling & Cancellation ​

8.1 ✅ CORRECT: Check Document-Level Errors ​

python
operation_id = poller.id
document_statuses = client.list_document_statuses(operation_id)

failed_docs = []
for doc in document_statuses:
    if doc.status == "failed":
        failed_docs.append({
            "url": doc.source_document_url,
            "error": doc.error.message if doc.error else "Unknown error"
        })

if failed_docs:
    print(f"Failed documents: {len(failed_docs)}")
    for doc in failed_docs:
        print(f"  - {doc['url']}: {doc['error']}")

8.2 ✅ CORRECT: Cancel Translation ​

python
poller = client.begin_translation(inputs=[...])

# Cancel the operation
client.cancel_translation(poller.id)

# Verify cancellation
result = poller.result()
if result.status == "cancelled":
    print("Translation cancelled successfully")

8.3 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Ignoring error details ​

python
# WRONG - not extracting error messages
for doc in document_statuses:
    if doc.status == "failed":
        print("Translation failed")  # No context

❌ INCORRECT: Not validating SAS permissions ​

python
# WRONG - container URLs don't have proper permissions
source_url = "https://storage.blob.core.windows.net/source/"  # Missing SAS, no Read/List perms
target_url = "https://storage.blob.core.windows.net/target/"  # Missing SAS, no Write/List perms

poller = client.begin_translation(
    inputs=[DocumentTranslationInput(source_url=source_url, targets=[...])]
)

9. Environment Variables ​

✅ CORRECT: Required Configuration ​

bash
AZURE_DOCUMENT_TRANSLATION_ENDPOINT=https://<resource>.cognitiveservices.azure.com