Registry /
azure / azure-ai-translation-document
Install & Compatibility
Where this runs
tested against v1.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.443s · 24.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.6s · import 0.404s · 25MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DocumentTranslationClient
✓ from azure.ai.translation.document import DocumentTranslationClient
SingleDocumentTranslationClient
✓ from azure.ai.translation.document import SingleDocumentTranslationClient
Used for synchronous, single document translation.
DocumentTranslationInput
✓ from azure.ai.translation.document import DocumentTranslationInput
TranslationTarget
✓ from azure.ai.translation.document import TranslationTarget
AzureKeyCredential
✓ from azure.core.credentials import AzureKeyCredential
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.
import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient, DocumentTranslationInput, TranslationTarget
# Set up environment variables for endpoint, key, and container URLs
endpoint = os.environ.get("AZURE_DOCUMENT_TRANSLATION_ENDPOINT", "https://YOUR_TRANSLATOR_RESOURCE_NAME.cognitiveservices.azure.com/")
key = os.environ.get("AZURE_DOCUMENT_TRANSLATION_KEY", "YOUR_API_KEY")
source_container_url = os.environ.get("AZURE_SOURCE_CONTAINER_URL", "https://YOUR_STORAGE_ACCOUNT.blob.core.windows.net/source?sas_token")
target_container_url = os.environ.get("AZURE_TARGET_CONTAINER_URL", "https://YOUR_STORAGE_ACCOUNT.blob.core.windows.net/target?sas_token")
target_language = "es"
# Ensure environment variables are set or provide placeholders
if not all([endpoint, key, source_container_url, target_container_url]):
print("Please set the environment variables: AZURE_DOCUMENT_TRANSLATION_ENDPOINT, AZURE_DOCUMENT_TRANSLATION_KEY, AZURE_SOURCE_CONTAINER_URL, AZURE_TARGET_CONTAINER_URL")
exit(1)
def begin_batch_translation():
client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))
inputs = [
DocumentTranslationInput(
source_url=source_container_url,
targets=[
TranslationTarget(
target_url=target_container_url,
language_code=target_language
)
]
)
]
print("Submitting batch translation job...")
poller = client.begin_translation(inputs)
print(f"Job ID: {poller.id}")
print(f"Job status: {poller.status}")
# Wait for the job to complete
result = poller.result()
print("Translation job completed. Document statuses:")
for document_status in result:
print(f"Document ID: {document_status.id}")
print(f" Source document path: {document_status.source_document_path}")
print(f" Translated document path: {document_status.translated_document_path}")
print(f" Status: {document_status.status}")
if document_status.error:
print(f" Error: {document_status.error.code} - {document_status.error.message}")
if __name__ == '__main__':
begin_batch_translation()
Debug
Known issues
breakingThe 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.fixEnsure 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.
affects: <=1.0.0b4, stable 1.0.0
breakingIn 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`.fixUpdate your code to call `client.translate(...)` instead of `client.document_translate(...)` when using the `SingleDocumentTranslationClient`.
affects: Likely `2.0.0` and above (preview or stable)
gotchaDocument 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.fixWhen 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).
affects: All versions
gotchaCommon 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.fixVerify 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.
affects: All versions
gotchaWhen 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.fixPass `storage_type="File"` (or `StorageInputType.FILE` if imported) in your `DocumentTranslationInput` constructor when providing a SAS URL to a single document.
affects: All versions
gotchaUsers 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.fixWhile 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azure.ai'
The 'azure-ai-translation-document' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install azure-ai-translation-document'.
ImportError: cannot import name 'DocumentTranslationClient' from 'azure.ai.translation.document'
The 'DocumentTranslationClient' class is not available in the installed version of the 'azure-ai-translation-document' package.
fixEnsure you have the latest version installed: 'pip install --upgrade azure-ai-translation-document'.
AttributeError: module 'azure.ai.translation.document' has no attribute 'DocumentTranslationClient'
The 'DocumentTranslationClient' class is not defined in the 'azure.ai.translation.document' module.
fixVerify the correct import statement: 'from azure.ai.translation.document import DocumentTranslationClient'.
ImportError: No module named 'azure.ai.translation.document'
The 'azure-ai-translation-document' package is not installed or not found in the Python environment.
fixInstall the package using pip: 'pip install azure-ai-translation-document'.
ModuleNotFoundError: No module named 'azure'
The 'azure' package is not installed in the Python environment.
fixInstall the Azure SDK for Python: 'pip install azure'.
Upgrade
Version history
1.1.0latest on PyPI · released Nov 12, 2024
Audit
Dependencies
azure-corerequiredProvides shared primitives, abstractions, and helpers for Azure SDK client libraries.
azure-identityoptionalRequired for Azure Active Directory authentication.
azure-storage-bloboptionalRequired for interacting with Azure Blob Storage, especially for batch document translation operations.