Azure AI Translation Text Client Library

1.0.1 · active · verified Thu Apr 16

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.

Common errors

```
azure.core.exceptions.ClientAuthenticationError: Authentication failed.
```
cause 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.
```
cause 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'
```
cause 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)`.

Warnings

breaking Version 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.
gotcha When 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`.
gotcha Users 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.

Install

pip install azure-ai-translation-text Install stable version
pip install azure-ai-translation-text --pre Install preview version (2.0.0-beta.1+)

Imports

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.

Quickstart

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()

view raw JSON →