{"slug":"azure-ai-translation-document-py","title":"azure-ai-translation-document-py","summary":"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. Triggers: \"document translation\", \"batch translation\", \"translate documents\", \"DocumentTranslation","platform":"GitHub Copilot","tags":[],"authorName":"Ciza","authorSlug":"ciza","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-08-12T21:05:05.603765Z","repo":{"url":"https://github.com/microsoft/skills","stars":3052,"forks":351,"license":"MIT","updatedAt":"2026-09-24T16:38:17Z"},"bodyHtml":"
\n

name: azure-ai-translation-document-py\ndescription: |\nAzure 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.\nTriggers: \"document translation\", \"batch translation\", \"translate documents\", \"DocumentTranslationClient\".\nlicense: MIT\nmetadata:\nauthor: Microsoft\nversion: \"1.0.0\"\npackage: azure-ai-translation-document

\n

Azure AI Document Translation SDK for Python

\n

Client library for Azure AI Translator document translation service for batch document translation with format preservation.

\n

Installation

\n
pip install azure-ai-translation-document\n
\n

Environment Variables

\n
AZURE_DOCUMENT_TRANSLATION_ENDPOINT=https://<resource>.cognitiveservices.azure.com  # Required for all auth methods\n# Storage for source and target documents\nAZURE_SOURCE_CONTAINER_URL=https://<storage>.blob.core.windows.net/<container>?<sas>  # Required for all auth methods\nAZURE_TARGET_CONTAINER_URL=https://<storage>.blob.core.windows.net/<container>?<sas>  # Required for all auth methods\nAZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production\nAZURE_DOCUMENT_TRANSLATION_KEY=<your-api-key>  # Only required for the legacy API-key auth path below\n
\n

Authentication & Lifecycle

\n
\n

\uD83D\uDD11 Two rules apply to every code sample below:

\n
    \n
  1. Prefer DefaultAzureCredential. It works locally (Azure CLI / VS Code / Developer CLI) and in Azure (managed identity, workload identity) with no code change. Avoid connection strings, account/API keys — they bypass Entra audit and rotation.\n
      \n
    • Local dev: DefaultAzureCredential works as-is.
      • \n
    • Production: set AZURE_TOKEN_CREDENTIALS=prod (or AZURE_TOKEN_CREDENTIALS=<specific_credential>) to constrain the credential chain to production-safe credentials.
      • \n
    \n
    2. \n
  2. Wrap every client in a context manager so HTTP transports, sockets, and token caches are released deterministically:\n
      \n
    • Sync: with <Client>(...) as client:
      • \n
    • Async: async with <Client>(...) as client: and async with DefaultAzureCredential() as credential: (from azure.identity.aio)
      • \n
    \n
    3. \n
\n

Snippets may abbreviate this setup, but production code should always follow both rules.

\n
\n
import os\nfrom azure.identity import DefaultAzureCredential, ManagedIdentityCredential\nfrom azure.ai.translation.document import DocumentTranslationClient\n\n# Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>\ncredential = DefaultAzureCredential()\n# Or use a specific credential directly in production:\n# See https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes\n# credential = ManagedIdentityCredential()\n\nwith DocumentTranslationClient(\n    endpoint=os.environ[\"AZURE_DOCUMENT_TRANSLATION_ENDPOINT\"],\n    credential=credential,\n) as client:\n    statuses = list(client.list_translation_statuses())\n
\n

Legacy: API Key (existing keyed deployments)

\n

New code should use DefaultAzureCredential above. Use AzureKeyCredential only if you have an existing keyed deployment that hasn't been migrated to Entra ID yet — for example, regulated environments still completing their Entra rollout.

\n
import os\nfrom azure.core.credentials import AzureKeyCredential\nfrom azure.ai.translation.document import DocumentTranslationClient, SingleDocumentTranslationClient\n\nwith DocumentTranslationClient(\n    endpoint=os.environ[\"AZURE_DOCUMENT_TRANSLATION_ENDPOINT\"],\n    credential=AzureKeyCredential(os.environ[\"AZURE_DOCUMENT_TRANSLATION_KEY\"]),\n) as client:\n    statuses = list(client.list_translation_statuses())\n\n# SingleDocumentTranslationClient accepts the same key-based credential.\n
\n

Basic Document Translation

\n
import os\nfrom azure.ai.translation.document import DocumentTranslationClient, DocumentTranslationInput, TranslationTarget\nfrom azure.core.exceptions import HttpResponseError\nfrom azure.identity import DefaultAzureCredential\n\ncredential = DefaultAzureCredential()\n\nwith DocumentTranslationClient(\n    endpoint=os.environ[\"AZURE_DOCUMENT_TRANSLATION_ENDPOINT\"],\n    credential=credential,\n) as client:\n    source_url = os.environ[\"AZURE_SOURCE_CONTAINER_URL\"]\n    target_url = os.environ[\"AZURE_TARGET_CONTAINER_URL\"]\n\n    try:\n        # Start translation job\n        poller = client.begin_translation(\n            inputs=[\n                DocumentTranslationInput(\n                    source_url=source_url,\n                    targets=[\n                        TranslationTarget(\n                            target_url=target_url,\n                            language=\"es\"  # Translate to Spanish\n                        )\n                    ]\n                )\n            ]\n        )\n\n        # Wait for completion\n        result = poller.result()\n\n        print(f\"Status: {poller.status()}\")\n        print(f\"Documents translated: {poller.details.documents_succeeded_count}\")\n        print(f\"Documents failed: {poller.details.documents_failed_count}\")\n    except HttpResponseError as e:\n        print(f\"Translation failed: {e.message}\")\n        raise\n
\n

Multiple Target Languages

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

Translate Single Document

\n
from azure.ai.translation.document import SingleDocumentTranslationClient\nfrom azure.identity import DefaultAzureCredential\n\nwith open(\"document.docx\", \"rb\") as f:\n    document_content = f.read()\n\nwith SingleDocumentTranslationClient(endpoint, DefaultAzureCredential()) as single_client:\n    result = single_client.translate(\n        body=document_content,\n        target_language=\"es\",\n        content_type=\"application/vnd.openxmlformats-officedocument.wordprocessingml.document\"\n    )\n\n# Save translated document\nwith open(\"document_es.docx\", \"wb\") as f:\n    f.write(result)\n
\n

Check Translation Status

\n
# Get all translation operations\noperations = client.list_translation_statuses()\n\nfor op in operations:\n    print(f\"Operation ID: {op.id}\")\n    print(f\"Status: {op.status}\")\n    print(f\"Created: {op.created_on}\")\n    print(f\"Total documents: {op.documents_total_count}\")\n    print(f\"Succeeded: {op.documents_succeeded_count}\")\n    print(f\"Failed: {op.documents_failed_count}\")\n
\n

List Document Statuses

\n
# Get status of individual documents in a job\noperation_id = poller.id\ndocument_statuses = client.list_document_statuses(operation_id)\n\nfor doc in document_statuses:\n    print(f\"Document: {doc.source_document_url}\")\n    print(f\"  Status: {doc.status}\")\n    print(f\"  Translated to: {doc.translated_to}\")\n    if doc.error:\n        print(f\"  Error: {doc.error.message}\")\n
\n

Cancel Translation

\n
# Cancel a running translation\nclient.cancel_translation(operation_id)\n
\n

Using Glossary

\n
from azure.ai.translation.document import TranslationGlossary\n\npoller = client.begin_translation(\n    inputs=[\n        DocumentTranslationInput(\n            source_url=source_url,\n            targets=[\n                TranslationTarget(\n                    target_url=target_url,\n                    language=\"es\",\n                    glossaries=[\n                        TranslationGlossary(\n                            glossary_url=\"https://<storage>.blob.core.windows.net/glossary/terms.csv?<sas>\",\n                            file_format=\"csv\"\n                        )\n                    ]\n                )\n            ]\n        )\n    ]\n)\n
\n

Supported Document Formats

\n
# Get supported formats\nformats = client.get_supported_document_formats()\n\nfor fmt in formats:\n    print(f\"Format: {fmt.format}\")\n    print(f\"  Extensions: {fmt.file_extensions}\")\n    print(f\"  Content types: {fmt.content_types}\")\n
\n

Supported Languages

\n
# Get supported languages\nlanguages = client.get_supported_languages()\n\nfor lang in languages:\n    print(f\"Language: {lang.name} ({lang.code})\")\n
\n

Async Client

\n
from azure.ai.translation.document.aio import DocumentTranslationClient\nfrom azure.identity.aio import DefaultAzureCredential\n\nasync def translate_documents():\n    async with DefaultAzureCredential() as credential:\n        async with DocumentTranslationClient(\n            endpoint=endpoint,\n            credential=credential,\n        ) as client:\n            poller = await client.begin_translation(inputs=[...])\n            result = await poller.result()\n
\n

Supported Formats

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CategoryFormats
DocumentsDOCX, PDF, PPTX, XLSX, HTML, TXT, RTF
StructuredCSV, TSV, JSON, XML
LocalizationXLIFF, XLF, MHTML
\n

Storage Requirements

\n\n

Best Practices

\n
    \n
  1. Pick sync OR async and stay consistent. Do not mix azure.xxx sync clients with azure.xxx.aio async clients in the same call path. Choose one mode per module.
    2. \n
  2. Always use context managers for clients and async credentials. Wrap every client in with Client(...) as client: (sync) or async with Client(...) as client: (async). For async DefaultAzureCredential from azure.identity.aio, also use async with credential: so tokens and transports are cleaned up.
    3. \n
  3. Use SAS tokens with minimal required permissions
    4. \n
  4. Monitor long-running operations with poller.status()
    5. \n
  5. Handle document-level errors by iterating document statuses
    6. \n
  6. Use glossaries for domain-specific terminology
    7. \n
  7. Separate target containers for each language
    8. \n
  8. Use async client for multiple concurrent jobs
    9. \n
  9. Check supported formats before submitting documents
    10. \n
\n

Reference Files

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FileContents
references/capabilities.mdAdditional non-hero capabilities, operation-group coverage, and production checklists.
references/non-hero-scenarios.mdDedicated non-hero examples for secondary/advanced scenarios.
\n","files":[{"path":"references/capabilities.md","sizeBytes":2334,"isText":true},{"path":"references/non-hero-scenarios.md","sizeBytes":3275,"isText":true},{"path":"SKILL.md","sizeBytes":10514,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-08-12T21:49:45.311515Z","sha256":"C28446C9B46C9928B1B34D82E7E87A464F2633290BBF620019F98F56109A05C5","sizeBytes":5729},"review":null,"source":{"repositoryUrl":"https://github.com/microsoft/skills","path":".github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py","license":"MIT","commit":"23d0dac5f83f268166a17f0bc7dc6c73dc348a33","subtreeSha":"E793A7843D258DC425B4EE489D6D9EB273EF9CF1E8CEA5D8863701D79D226545","lastSyncedAt":"2026-09-25T06:48:53.330584Z"},"reviewedAt":"2026-08-12T21:52:01.682306Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install microsoft-skills@llmmart"},{"target":"git","command":"git clone https://github.com/microsoft/skills.git"}]}