Registry /
azure / azure-ai-translation-text
Install & Compatibility
Where this runs
tested against v2.0.0b1 · 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.940 runs
installs and imports cleanly · install 0.0s · import 0.429s · 24.5MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 2.4s · import 0.386s · 25MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TextTranslationClient
✓ from azure.ai.translation.text import TextTranslationClient
The main client for interacting with the Azure AI Text Translation service.
AzureKeyCredential
✓ from azure.core.credentials import AzureKeyCredential
Required for API key-based authentication.
InputTextItem
✓ from azure.ai.translation.text.models import InputTextItem
Used to specify the text and optional source language for translation requests.
This quickstart demonstrates how to initialize the `TextTranslationClient` using an API key and region, then perform a simple text translation from English to Spanish and German. Ensure you replace the placeholder values for `TRANSLATOR_ENDPOINT`, `TRANSLATOR_KEY`, and `TRANSLATOR_REGION` with your actual Azure Translator resource details, preferably via environment variables for security.
import os
from azure.ai.translation.text import TextTranslationClient, InputTextItem
from azure.core.credentials import AzureKeyCredential
# --- Configuration (replace with your Azure Translator resource details) ---
# Get these values from your Azure Translator resource in the Azure Portal:
# Endpoint: typically 'https://<your-resource-name>.cognitiveservices.azure.com/' for regional or custom domain
# or 'https://api.cognitive.microsofttranslator.com/' for global.
# Key: One of the subscription keys for your Translator resource.
# Region: The region where your Translator resource is deployed (e.g., 'eastus', 'global').
endpoint = os.environ.get('TRANSLATOR_ENDPOINT', 'YOUR_TRANSLATOR_ENDPOINT')
key = os.environ.get('TRANSLATOR_KEY', 'YOUR_TRANSLATOR_KEY')
region = os.environ.get('TRANSLATOR_REGION', 'YOUR_TRANSLATOR_REGION')
if 'YOUR_TRANSLATOR_ENDPOINT' in endpoint or 'YOUR_TRANSLATOR_KEY' in key or 'YOUR_TRANSLATOR_REGION' in region:
print("Please set the 'TRANSLATOR_ENDPOINT', 'TRANSLATOR_KEY', and 'TRANSLATOR_REGION' environment variables or replace placeholders.")
exit(1)
def translate_text():
try:
credential = AzureKeyCredential(key)
# Note: 'region' is required for TextTranslationClient when using an API key with a regional endpoint.
# It can be omitted for the global endpoint ('https://api.cognitive.microsofttranslator.com/')
# or if using a custom subdomain endpoint (where region is part of the endpoint URL).
text_translator_client = TextTranslationClient(endpoint=endpoint, credential=credential, region=region)
source_text_items = [
InputTextItem(text="Hello, how are you?"),
InputTextItem(text="I am fine, thank you.")
]
# Translate from English to Spanish and German
target_languages = ["es", "de"]
response = text_translator_client.translate(content=source_text_items, to=target_languages)
for translation_group in response:
for translation in translation_group.translations:
print(f"Text: '{translation_group.source_text.text}', Translated to '{translation.to}': '{translation.text}'")
except Exception as e:
print(f"An error occurred: {e}")
if __name__ == "__main__":
translate_text()
Errors
Common errors & fixes
azure.core.exceptions.ClientAuthenticationError: Authentication failed.
Incorrect API key, endpoint, or region provided, or a mismatch between them. Also, the region parameter might be missing for regional endpoints.
fixVerify that `TRANSLATOR_KEY`, `TRANSLATOR_ENDPOINT`, and `TRANSLATOR_REGION` (if applicable) are correct and match your Azure Translator resource configuration in the Azure portal. Ensure the `region` parameter is passed to `TextTranslationClient` if using a regional resource.
Translation failed. Please try again later.
This generic error often indicates an issue on the service side, such as temporary outages, throttling (exceeding transaction limits), or misconfigurations like private endpoints interfering with access.
fixCheck the Azure service health dashboard for Translator for any ongoing incidents. Review your resource's pricing tier and usage to ensure you're not being throttled. Implement retry mechanisms. If using private endpoints, ensure they are correctly configured and not blocking communication.
TypeError: TextTranslationClient.__init__() got an unexpected keyword argument 'subscription_key'
Attempting to use an older `subscription_key` parameter for authentication, which is not supported by `azure-ai-translation-text`. The current SDK uses `credential` and `region` (for API key) or `credential` (for AAD).
fixUse `credential=AzureKeyCredential(key)` for API key authentication, and pass the `region` parameter separately if needed: `TextTranslationClient(endpoint=endpoint, credential=AzureKeyCredential(key), region=region)`.
Upgrade
Version history
2.0.0latest on PyPI · released May 29, 2026
Audit
Dependencies
azure-corerequiredCore utilities for Azure SDK client libraries. Automatically installed as a dependency.