Azure Document Translation for Python
Batch-translate Azure Blob Storage documents in Python while preserving their original formats.
The documentation prefers DefaultAzureCredential, constrains production credential chains, and specifies least-privilege SAS permissions while exposing the source/target Blob URLs and API-key configuration. Points are deducted because it does not clearly address sensitive-document handling, cross-border/third-party transfer, user confirmation, SAS leakage protection, or rollback; the cancellation example also lacks impact-scope guidance.
The skill covers batch, single-document, status, and async paths, and its references explicitly call for checking the current API. Points are deducted because key snippets lack complete context (for example, some imports and endpoint definitions), the main document incorrectly shows get_supported_languages() on DocumentTranslationClient while the reference corrects it, and abnormal-input, retry, timeout, and exception guidance is thin.
Trigger phrases, Python SDK scope, batch document translation, format preservation, and major formats are reasonably clear. Points are deducted because non-fit scenarios, regional/network requirements, cost, and quotas are under-specified; the core service depends on Azure, while mainland-China reachability, data residency, and Chinese-language coverage are not established.
The skill has front-matter metadata, installation and environment-variable notes, authentication/lifecycle guidance, layered references, examples, format/storage requirements, MIT licensing, and version 1.0.0 metadata. Points are deducted for no changelog, SDK version pinning, explicit maintenance/update path, or systematic FAQ; advanced scenarios are terse and the main and reference documents are inconsistent.
It can directly guide common batch, multi-target, single-document, status, and glossary workflows, with a clear core benefit. Points are deducted because several snippets require completion of imports, variables, and environment setup; the incorrect language-discovery example can cause rework, and production error handling, result validation, and recovery are incomplete.
The skill provides auditable code, configuration names, API calls, and reference files; the repository materials also show CI, evaluation workflows, and harness tests. Points are deducted because the supplied material shows no skill-specific test suite, real execution output, or independent corroboration; generic CI and harness evidence cannot statically verify this skill's key paths.
- Do not copy every snippet directly into production: correct the language-discovery API and complete imports, endpoints, variables, and dependencies first.
- Source and translated documents are transferred through Azure Blob/SAS; confirm sensitive-data handling, region, network reachability, SAS lifetime/permissions, and organizational compliance before deployment.
- Cancellation, target-container writes, and multi-language batch jobs have external side effects; confirm scope and add handling for exceptions, polling timeouts, partial failures, and recovery.
What it does & when to use it
This skill guides Python developers using the Azure AI Document Translation SDK for batch and single-document translation. It covers document formats including DOCX, PDF, XLSX, and PPTX, along with Blob Storage configuration, authentication, and SAS permissions. Examples include multiple target languages, status monitoring, document-level failures, cancellation, glossaries, supported-format and language discovery, and synchronous or asynchronous clients. It is best suited to Python applications already using Azure AI Translator and Azure Blob Storage.
Shows how to install azure-ai-translation-document, configure the document translation endpoint and source and target container URLs, and submit jobs with DocumentTranslationClient or SingleDocumentTranslationClient. It demonstrates translating DOCX, PDF, PPTX, XLSX, HTML, TXT, RTF, CSV, TSV, JSON, XML, XLIFF, XLF, and MHTML files; waiting for batch completion; inspecting operation and document statuses; handling document errors; cancelling jobs; applying glossaries; and querying supported formats and languages.
- A Python developer needs to batch-translate DOCX, PDF, or Excel files stored in Azure Blob Storage into one or more languages.
- An application team needs format-preserving translation for business documents at scale.
- A developer needs to translate one local DOCX file and save the translated output.
- An engineering team needs to monitor long-running jobs and count succeeded and failed documents.
- A localization team needs glossary-based terminology consistency for domain-specific translations.
Pros & cons
- Covers batch translation, single-document translation, multiple target languages, glossaries, and job management.
- Clearly recommends DefaultAzureCredential and explains local-development and production configuration.
- Provides both synchronous and asynchronous client examples.
- Documents the required Blob Storage SAS permissions.
- Requires an Azure AI Document Translation endpoint and Azure Blob Storage source and target containers.
- Batch translation depends on SAS URLs for storage access, adding deployment and permission-management work.
- The source provides no pricing, quota, or service-limit information.
- The referenced references/capabilities.md and references/non-hero-scenarios.md files were not supplied, so their additional coverage cannot be assessed.
How to install
Install the collection for the coding agent by running npx skills add microsoft/skills and selecting this skill in the wizard; the collection is installed in the selected agent's skills directory. Then install the Python package with pip install azure-ai-translation-document. The source does not specify a required Python version.
How to use
Prompt a coding agent with one of the documented triggers, such as: Use the azure-ai-translation-document-py skill to create an async batch translation job from Azure Blob Storage to Spanish and French. Set AZURE_DOCUMENT_TRANSLATION_ENDPOINT, AZURE_SOURCE_CONTAINER_URL, and AZURE_TARGET_CONTAINER_URL. Prefer DefaultAzureCredential, use client context managers, submit the job, wait for the poller, and inspect document-level statuses.