agedwell-document-translate-batch-python-sample-code

Sample Python code that runs the Azure AI Document Translation batch (asynchronous) API to translate every document in a source Azure Blob Storage container and write the results into a target container.

Authentication model

Plane	Auth
Translator / Foundry endpoint	Key-based (AzureKeyCredential)
Source & target storage	Managed Identity (RBAC) on the Translator resource — no SAS tokens

The Translator (or Azure AI Foundry / multi-service) resource must have a managed identity with these role assignments:

• Source container → Storage Blob Data Reader (or Contributor)
• Target container → Storage Blob Data Contributor

Once those are granted, the service uses its own identity to read and write blobs, so the request only carries plain container URLs.

Prerequisites

• Python 3.9+
• An Azure AI Translator (or Foundry / multi-service) resource — note its endpoint and key, and ensure its managed identity has the storage RBAC roles listed above.
• Two Azure Blob Storage containers (source + target).

Setup

git clone https://github.com/<your-org>/agedwell-document-translate-batch-python-sample-code.git
cd agedwell-document-translate-batch-python-sample-code
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.sample .env
# then edit .env and fill in your endpoint, key, and storage container URLs

Configure environment variables

All configuration is via environment variables. You can either export them in your shell or put them in a .env file (loaded automatically via python-dotenv).

Variable	Required	Description
AZURE_TRANSLATOR_ENDPOINT	yes	Translator/Foundry endpoint, e.g. https://<name>.cognitiveservices.azure.com/
AZURE_TRANSLATOR_KEY	yes	Access key for the resource above
AZURE_SOURCE_STORAGE_URL	yes	https://<account>.blob.core.windows.net/<container> for source docs (no SAS)
AZURE_TARGET_STORAGE_URL	yes	https://<account>.blob.core.windows.net/<container> for output (no SAS)
AZURE_TARGET_LANGUAGE	no	Target BCP-47 code (default en)
AZURE_SOURCE_LANGUAGE	no	Source BCP-47 code; omit to auto-detect

Where to update for your own environment: edit .env (preferred for local dev) or set the variables in your CI/CD secret store / container environment. Do not commit real keys — .env is in .gitignore.

Run

python translate_batch.py

The script submits the batch job, polls until completion, then prints a per-document summary including the translated blob URLs.

Troubleshooting

• Forbidden / AuthorizationPermissionMismatch from storage usually means the Translator resource's managed identity is missing the required role on the source or target container. Check Container → Access control (IAM) → Role assignments.
• Role assignments can take a few minutes to propagate after being added.
• The target container should be empty (or use a unique sub-folder) — the service will not overwrite existing blobs by default.