Registry / azure / azure-ai-translation-text

azure-ai-translation-text

JSON →
library2.0.0pypypi✓ verified 85d ago

The Azure AI Translation Text client library for Python is a cloud-based REST API feature of the Translator service. It uses neural machine translation technology for quick and accurate source-to-target text translation. It allows listing supported languages, performing text translation, and transliteration in real-time. The current stable version is 1.0.1, with a 2.0.0-beta.1 also available with new features and breaking changes.

pip install azure-ai-translation-text
INSTALL
IMPORT
SIG · AZURE-AI-TRANSLATI
A
azure-ai-translation-text
azurepythonv2.0.0
Install
2.4s avg
Import
408ms
Disk
23MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.940 runs
installs and imports cleanly · install 0.0s · import 0.429s · 24.5MB
glibc
py 3.103.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()
Debug
Known issues
breakingVersion 2.0.0-beta.1 (January 2026) introduced significant breaking changes. Properties like `TargetLanguage` became `Language` in `TranslationText`, and `Confidence` became `Score` in `DetectedLanguage`. The `GetLanguages` method was renamed to `GetSupportedLanguages`. Features such as dictionary lookup, sentence boundaries, and text alignments were deprecated or removed. Source and transliteration properties were also removed from translation responses.
fix
Review the official migration guide and changelog. Update method calls and property names in your code to align with the new API surface. Avoid using deprecated features.
affects: >=2.0.0-beta.1
gotchaWhen authenticating with an API key, the `region` parameter is crucial for `TextTranslationClient` instantiation if you are using a regional Translator service endpoint (e.g., `https://<your-resource-name>.cognitiveservices.azure.com/`). Omitting it for regional endpoints can lead to authentication failures or incorrect routing. The `region` parameter can typically be omitted for the global endpoint (`https://api.cognitive.microsofttranslator.com/`) or when using an Azure Active Directory (AAD) `TokenCredential` with a custom subdomain.
fix
Always provide the `region` parameter (e.g., `'eastus'`) to the `TextTranslationClient` constructor if your Azure Translator resource is regional and you are authenticating with `AzureKeyCredential`.
affects: All versions
gotchaUsers sometimes encounter intermittent '401 Unauthorized' errors even with seemingly valid credentials, which can be difficult to diagnose. This can be caused by regional token propagation delays or temporary service disruptions.
fix
Implement retry logic with exponential backoff for API calls. Consider using the 'Global' region for your Translator resource if intermittent failures persist, as it can sometimes offer better stability. Ensure your resource is not hitting its Transactions Per Second (TPS) quota.
affects: All versions
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.
fix
Verify 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.
fix
Check 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).
fix
Use `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.
Agent activity
35 hits · last 30 days
node
28
OpenAI (training)
1
Resources
azure-ai-translation-text — pip install azure-ai-translation-text · libregistry