{"id":7029,"library":"azure-ai-translation-text","title":"Azure AI Translation Text Client Library","description":"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.","status":"active","version":"1.0.1","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/translation/azure-ai-translation-text","tags":["Azure","AI","Translation","Text","Microsoft","NLP"],"install":[{"cmd":"pip install azure-ai-translation-text","lang":"bash","label":"Install stable version"},{"cmd":"pip install azure-ai-translation-text --pre","lang":"bash","label":"Install preview version (2.0.0-beta.1+)"}],"dependencies":[{"reason":"Core utilities for Azure SDK client libraries. Automatically installed as a dependency.","package":"azure-core","optional":false}],"imports":[{"note":"The main client for interacting with the Azure AI Text Translation service.","symbol":"TextTranslationClient","correct":"from azure.ai.translation.text import TextTranslationClient"},{"note":"Required for API key-based authentication.","symbol":"AzureKeyCredential","correct":"from azure.core.credentials import AzureKeyCredential"},{"note":"Used to specify the text and optional source language for translation requests.","symbol":"InputTextItem","correct":"from azure.ai.translation.text.models import InputTextItem"}],"quickstart":{"code":"import os\nfrom azure.ai.translation.text import TextTranslationClient, InputTextItem\nfrom azure.core.credentials import AzureKeyCredential\n\n# --- Configuration (replace with your Azure Translator resource details) ---\n# Get these values from your Azure Translator resource in the Azure Portal:\n# Endpoint: typically 'https://<your-resource-name>.cognitiveservices.azure.com/' for regional or custom domain\n#           or 'https://api.cognitive.microsofttranslator.com/' for global.\n# Key: One of the subscription keys for your Translator resource.\n# Region: The region where your Translator resource is deployed (e.g., 'eastus', 'global').\n\nendpoint = os.environ.get('TRANSLATOR_ENDPOINT', 'YOUR_TRANSLATOR_ENDPOINT')\nkey = os.environ.get('TRANSLATOR_KEY', 'YOUR_TRANSLATOR_KEY')\nregion = os.environ.get('TRANSLATOR_REGION', 'YOUR_TRANSLATOR_REGION')\n\nif 'YOUR_TRANSLATOR_ENDPOINT' in endpoint or 'YOUR_TRANSLATOR_KEY' in key or 'YOUR_TRANSLATOR_REGION' in region:\n    print(\"Please set the 'TRANSLATOR_ENDPOINT', 'TRANSLATOR_KEY', and 'TRANSLATOR_REGION' environment variables or replace placeholders.\")\n    exit(1)\n\ndef translate_text():\n    try:\n        credential = AzureKeyCredential(key)\n        # Note: 'region' is required for TextTranslationClient when using an API key with a regional endpoint.\n        # It can be omitted for the global endpoint ('https://api.cognitive.microsofttranslator.com/')\n        # or if using a custom subdomain endpoint (where region is part of the endpoint URL).\n        text_translator_client = TextTranslationClient(endpoint=endpoint, credential=credential, region=region)\n\n        source_text_items = [\n            InputTextItem(text=\"Hello, how are you?\"),\n            InputTextItem(text=\"I am fine, thank you.\")\n        ]\n\n        # Translate from English to Spanish and German\n        target_languages = [\"es\", \"de\"]\n        response = text_translator_client.translate(content=source_text_items, to=target_languages)\n\n        for translation_group in response:\n            for translation in translation_group.translations:\n                print(f\"Text: '{translation_group.source_text.text}', Translated to '{translation.to}': '{translation.text}'\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n\nif __name__ == \"__main__\":\n    translate_text()\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0-beta.1"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"Incorrect API key, endpoint, or region provided, or a mismatch between them. Also, the region parameter might be missing for regional endpoints.","error":"azure.core.exceptions.ClientAuthenticationError: Authentication failed."},{"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.","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.","error":"Translation failed. Please try again later."},{"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)`.","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).","error":"TypeError: TextTranslationClient.__init__() got an unexpected keyword argument 'subscription_key'"}]}