{"id":6315,"library":"azure-ai-translation-document","title":"Azure AI Translation Document Client Library for Python","description":"The Azure AI Translation Document client library for Python is part of Microsoft's Azure SDK, providing functionality to integrate Document Translation capabilities into applications. It allows translation of whole documents across multiple languages and dialects while preserving the original structure and formatting. The library supports both asynchronous batch translation for multiple and complex files stored in Azure Blob Storage, and synchronous single-file translation. The current stable version is 1.1.0.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/translation/azure-ai-translation-document","tags":["azure","ai","translation","document","cloud"],"install":[{"cmd":"pip install azure-ai-translation-document","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides shared primitives, abstractions, and helpers for Azure SDK client libraries.","package":"azure-core","optional":false},{"reason":"Required for Azure Active Directory authentication.","package":"azure-identity","optional":true},{"reason":"Required for interacting with Azure Blob Storage, especially for batch document translation operations.","package":"azure-storage-blob","optional":true}],"imports":[{"symbol":"DocumentTranslationClient","correct":"from azure.ai.translation.document import DocumentTranslationClient"},{"note":"Used for synchronous, single document translation.","symbol":"SingleDocumentTranslationClient","correct":"from azure.ai.translation.document import SingleDocumentTranslationClient"},{"symbol":"DocumentTranslationInput","correct":"from azure.ai.translation.document import DocumentTranslationInput"},{"symbol":"TranslationTarget","correct":"from azure.ai.translation.document import TranslationTarget"},{"symbol":"AzureKeyCredential","correct":"from azure.core.credentials import AzureKeyCredential"}],"quickstart":{"code":"import os\nfrom azure.core.credentials import AzureKeyCredential\nfrom azure.ai.translation.document import DocumentTranslationClient, DocumentTranslationInput, TranslationTarget\n\n# Set up environment variables for endpoint, key, and container URLs\nendpoint = os.environ.get(\"AZURE_DOCUMENT_TRANSLATION_ENDPOINT\", \"https://YOUR_TRANSLATOR_RESOURCE_NAME.cognitiveservices.azure.com/\")\nkey = os.environ.get(\"AZURE_DOCUMENT_TRANSLATION_KEY\", \"YOUR_API_KEY\")\nsource_container_url = os.environ.get(\"AZURE_SOURCE_CONTAINER_URL\", \"https://YOUR_STORAGE_ACCOUNT.blob.core.windows.net/source?sas_token\")\ntarget_container_url = os.environ.get(\"AZURE_TARGET_CONTAINER_URL\", \"https://YOUR_STORAGE_ACCOUNT.blob.core.windows.net/target?sas_token\")\ntarget_language = \"es\"\n\n# Ensure environment variables are set or provide placeholders\nif not all([endpoint, key, source_container_url, target_container_url]):\n    print(\"Please set the environment variables: AZURE_DOCUMENT_TRANSLATION_ENDPOINT, AZURE_DOCUMENT_TRANSLATION_KEY, AZURE_SOURCE_CONTAINER_URL, AZURE_TARGET_CONTAINER_URL\")\n    exit(1)\n\ndef begin_batch_translation():\n    client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))\n\n    inputs = [\n        DocumentTranslationInput(\n            source_url=source_container_url,\n            targets=[\n                TranslationTarget(\n                    target_url=target_container_url,\n                    language_code=target_language\n                )\n            ]\n        )\n    ]\n\n    print(\"Submitting batch translation job...\")\n    poller = client.begin_translation(inputs)\n    \n    print(f\"Job ID: {poller.id}\")\n    print(f\"Job status: {poller.status}\")\n\n    # Wait for the job to complete\n    result = poller.result()\n\n    print(\"Translation job completed. Document statuses:\")\n    for document_status in result:\n        print(f\"Document ID: {document_status.id}\")\n        print(f\"  Source document path: {document_status.source_document_path}\")\n        print(f\"  Translated document path: {document_status.translated_document_path}\")\n        print(f\"  Status: {document_status.status}\")\n        if document_status.error:\n            print(f\"  Error: {document_status.error.code} - {document_status.error.message}\")\n\nif __name__ == '__main__':\n    begin_batch_translation()","lang":"python","description":"This quickstart demonstrates how to perform an asynchronous batch document translation using the `DocumentTranslationClient`. It translates all documents from a specified source Azure Blob Storage container to a target container in the desired language. Ensure your Azure Translator resource is configured with a system-assigned managed identity and granted 'Storage Blob Data Contributor' role to access your storage account, or use SAS tokens with appropriate permissions."},"warnings":[{"fix":"Ensure your client library is updated to the latest stable version. When initializing the client, consider specifying `api_version` explicitly if targeting specific service behaviors, although the SDK defaults to the latest supported version.","message":"The Document Translation service transitioned to date-based API versioning. Service behavior for v1.0 is now aligned with the `2024-05-01` API version. Using older SDK versions or implicitly relying on v1.0 behavior without specifying the API version may lead to unexpected results.","severity":"breaking","affected_versions":"<=1.0.0b4, stable 1.0.0"},{"fix":"Update your code to call `client.translate(...)` instead of `client.document_translate(...)` when using the `SingleDocumentTranslationClient`.","message":"In version 2.0.0 (released 2024-11-15 for other languages, implied for Python SDK around similar time), the `document_translate` method of `SingleDocumentTranslationClient` was renamed to `translate`.","severity":"breaking","affected_versions":"Likely `2.0.0` and above (preview or stable)"},{"fix":"When creating your Azure Translator resource, select a single-service Translator type in a supported region (e.g., East US, West US 2) and ensure you choose a paid pricing tier (e.g., S1 Standard or D3 Volume Discount).","message":"Document Translation is only supported in *single-service* Translator resources, not multi-service Azure AI services resources. Also, it's not available in all Azure regions, and the Free (F0) tier does not support this feature.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify that your SAS tokens have the correct permissions (Read/List for source, Write/List for target) and are not expired. If using a managed identity, ensure it has the 'Storage Blob Data Contributor' role assigned to the relevant Azure Blob Storage accounts.","message":"Common errors like `HttpResponseError: (InvalidDocumentAccessLevel)` or `Cannot access source document location with the current permissions` indicate issues with storage access. This usually means the SAS tokens are incorrect or expired, or the managed identity assigned to the Translator resource lacks the 'Storage Blob Data Contributor' role on the source/target storage accounts.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Pass `storage_type=\"File\"` (or `StorageInputType.FILE` if imported) in your `DocumentTranslationInput` constructor when providing a SAS URL to a single document.","message":"When translating single files using SAS URLs, especially if experiencing issues, explicitly set the `storage_type` parameter to `StorageInputType.FILE` in `DocumentTranslationInput`. The service might not correctly infer the storage type in all scenarios.","severity":"gotcha","affected_versions":"All versions"},{"fix":"While there isn't a direct fix within the SDK, review the translated documents for critical formatting. Consider pre-processing PDFs to convert them to more text-friendly formats or post-processing the translated output to correct formatting issues if exact preservation of complex layouts like bullet points is crucial.","message":"Users have reported issues with bullet points missing or being improperly formatted in translated PDF documents, indicating the service might not perfectly preserve all formatting elements for certain document types.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}