SDK de traduction de texte Azure AI pour Python

Bibliothèque cliente pour le service de traduction de texte Azure AI Translator, offrant des fonctionnalités de traduction de texte en temps réel, de translittération et d'opérations linguistiques.

Installation

pip install azure-ai-translation-text

Variables d'environnement

AZURE_TRANSLATOR_ENDPOINT=https://<resource>.cognitiveservices.azure.com  # Obligatoire pour l'authentification Entra ID (doit être un point de terminaison de sous-domaine personnalisé)
AZURE_TOKEN_CREDENTIALS=prod # Obligatoire uniquement si DefaultAzureCredential est utilisé en production
# Uniquement requis pour le chemin d'authentification par clé d'API hérité ci-dessous :
AZURE_TRANSLATOR_KEY=<your-api-key>
AZURE_TRANSLATOR_REGION=<your-region>  # Par exemple, eastus, westus2 ; requis lors de l'authentification par clé contre le point de terminaison mondial
</your-region></your-api-key></resource>

Authentification et cycle de vie

🔑 Deux règles s'appliquent à chaque exemple de code ci-dessous :

1. Privilégiez DefaultAzureCredential. Il fonctionne localement (Azure CLI / VS Code / Developer CLI) et dans Azure (identité managée, identité de charge de travail) sans modification de code. Évitez les chaînes de connexion, les comptes ou les clés API, car ils contournent l'audit et la rotation d'Entra.
   • Développement local : DefaultAzureCredential fonctionne tel quel.
   • Production : définissez AZURE_TOKEN_CREDENTIALS=prod (ou AZURE_TOKEN_CREDENTIALS=<specific_credential></specific_credential>) pour limiter la chaîne d'identification aux identifiants sécurisés pour la production.
2. Enveloppez chaque client dans un gestionnaire de contexte afin que les transports HTTP, les sockets et les caches de jetons soient libérés de manière déterministe :
   • Synchrone : with <client>(...) as client:</client>
   • Asynchrone : async with <client>(...) as client:</client> et async with DefaultAzureCredential() as credential: (de azure.identity.aio)

Les extraits de code peuvent abréger cette configuration, mais le code de production doit toujours respecter ces deux règles.

import os
from azure.identity import DefaultAzureCredential, ManagedIdentityCredential
from azure.ai.translation.text import TextTranslationClient

# Développement local : DefaultAzureCredential. Production : définissez AZURE_TOKEN_CREDENTIALS=prod ou AZURE_TOKEN_CREDENTIALS=<specific_credential>
credential = DefaultAzureCredential(require_envvar=True)
# Ou utilisez un identifiant spécifique directement en production :
# Voir https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes
# credential = ManagedIdentityCredential()

with TextTranslationClient(
    endpoint=os.environ["AZURE_TRANSLATOR_ENDPOINT"],
    credential=credential,
) as client:
    result = client.translate(body=["Hello, world!"], to=["es"])
</specific_credential>

Hérité : Clé d'API (déploiements existants avec clé)

Les nouveaux codes doivent utiliser DefaultAzureCredential ci-dessus. Le service Translator présente deux particularités qui rendent l'authentification par clé d'API encore courante dans les déploiements existants :

• L'authentification par jeton d'identification nécessite un point de terminaison de sous-domaine personnalisé (https://<resource>.cognitiveservices.azure.com</resource>). Si vous ne disposez que du point de terminaison mondial (https://api.cognitive.microsofttranslator.com), vous devez soit provisionner un sous-domaine personnalisé, soit rester sur le chemin basé sur la clé jusqu'à ce que vous le fassiez.
• Clé + région est la configuration canonique contre le point de terminaison mondial. La région est envoyée en tant qu'en-tête Ocp-Apim-Subscription-Region et est requise chaque fois que vous utilisez une clé Translator multi-service ou mondiale.

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.text import TextTranslationClient

# Clé + région contre le point de terminaison mondial (configuration cléée la plus courante)
with TextTranslationClient(
    credential=AzureKeyCredential(os.environ["AZURE_TRANSLATOR_KEY"]),
    region=os.environ["AZURE_TRANSLATOR_REGION"],
) as client:
    result = client.translate(body=["Hello, world!"], to=["es"])

# Clé contre un point de terminaison de sous-domaine personnalisé (aucune région requise)
with TextTranslationClient(
    endpoint=os.environ["AZURE_TRANSLATOR_ENDPOINT"],
    credential=AzureKeyCredential(os.environ["AZURE_TRANSLATOR_KEY"]),
) as client:
    result = client.translate(body=["Hello, world!"], to=["es"])

Traduction de base

# Traduire vers une seule langue
result = client.translate(
    body=["Hello, how are you?", "Welcome to Azure!"],
    to=["es"]  # Espagnol
)

for item in result:
    for translation in item.translations:
        print(f"Traduit : {translation.text}")
        print(f"Langue cible : {translation.to}")

Traduction vers plusieurs langues

result = client.translate(
    body=["Hello, world!"],
    to=["es", "fr", "de", "ja"]  # Espagnol, Français, Allemand, Japonais
)

for item in result:
    print(f"Source : {item.detected_language.language if item.detected_language else 'inconnu'}")
    for translation in item.translations:
        print(f"  {translation.to} : {translation.text}")

Spécifier la langue source

result = client.translate(
    body=["Bonjour le monde"],
    from_parameter="fr",  # La source est le français
    to=["en", "es"]
)

Détection de langue

result = client.translate(
    body=["Hola, como estas?"],
    to=["en"]
)

for item in result:
    if item.detected_language:
        print(f"Langue détectée : {item.detected_language.language}")
        print(f"Confiance : {item.detected_language.score:.2f}")

Translittération

Convertir le texte d'un script à un autre :

result = client.transliterate(
    body=["konnichiwa"],
    language="ja",
    from_script="Latn",  # Depuis le script latin
    to_script="Jpan"      # Vers le script japonais
)

for item in result:
    print(f"Translittéré : {item.text}")
    print(f"Script : {item.script}")

Recherche dans le dictionnaire

Trouver des traductions alternatives et des définitions :

result = client.lookup_dictionary_entries(
    body=["fly"],
    from_parameter="en",
    to="es"
)

for item in result:
    print(f"Source : {item.normalized_source} ({item.display_source})")
    for translation in item.translations:
        print(f"  Traduction : {translation.normalized_target}")
        print(f"  Catégorie grammaticale : {translation.pos_tag}")
        print(f"  Confiance : {translation.confidence:.2f}")

Exemples de dictionnaire

Obtenir des exemples d'utilisation pour les traductions :

from azure.ai.translation.text.models import DictionaryExampleTextItem

result = client.lookup_dictionary_examples(
    body=[DictionaryExampleTextItem(text="fly", translation="volar")],
    from_parameter="en",
    to="es"
)

for item in result:
    for example in item.examples:
        print(f"Source : {example.source_prefix}{example.source_term}{example.source_suffix}")
        print(f"Cible : {example.target_prefix}{example.target_term}{example.target_suffix}")

Obtenir les langues prises en charge

# Obtenir toutes les langues prises en charge
languages = client.get_supported_languages()

# Langues de traduction
print("Langues de traduction :")
for code, lang in languages.translation.items():
    print(f"  {code} : {lang.name} ({lang.native_name})")

# Langues de translittération
print("\nLangues de translittération :")
for code, lang in languages.transliteration.items():
    print(f"  {code} : {lang.name}")
    for script in lang.scripts:
        print(f"    {script.code} -> {[t.code for t in script.to_scripts]}")

# Langues de dictionnaire
print("\nLangues de dictionnaire :")
for code, lang in languages.dictionary.items():
    print(f"  {code} : {lang.name}")

Découpage de phrase

Identifier les limites des phrases :

result = client.find_sentence_boundaries(
    body=["Hello! How are you? I hope you are well."],
    language="en"
)

for item in result:
    print(f"Longueurs des phrases : {item.sent_len}")

Options de traduction

result = client.translate(
    body=["Hello, world!"],
    to=["de"],
    text_type="html",           # "plain" ou "html"
    profanity_action="Marked",  # "NoAction", "Deleted", "Marked"
    profanity_marker="Asterisk", # "Asterisk", "Tag"
    include_alignment=True,      # Inclure l'alignement des mots
    include_sentence_length=True # Inclure les limites des phrases
)

for item in result:
    translation = item.translations[0]
    print(f"Traduit : {translation.text}")
    if translation.alignment:
        print(f"Alignement : {translation.alignment.proj}")
    if translation.sent_len:
        print(f"Longueurs des phrases : {translation.sent_len.src_sent_len}")

Client asynchrone

from azure.ai.translation.text.aio import TextTranslationClient
from azure.identity.aio import DefaultAzureCredential

async def translate_text():
    async with DefaultAzureCredential() as credential:
        async with TextTranslationClient(
            credential=credential,
            endpoint=endpoint,
        ) as client:
            result = await client.translate(
                body=["Hello, world!"],
                to=["es"]
            )
            print(result[0].translations[0].text)

Méthodes du client

Meilleures pratiques

1. Choisissez le mode synchrone OU asynchrone et restez cohérent. Ne mélangez pas les clients synchrones azure.xxx avec les clients asynchrones azure.xxx.aio dans le même chemin d'appel. Choisissez un mode par module.
2. Utilisez toujours des gestionnaires de contexte pour les clients et les identifiants asynchrones. Enveloppez chaque client dans with Client(...) as client: (synchrone) ou async with Client(...) as client: (asynchrone). Pour DefaultAzureCredential asynchrone de azure.identity.aio, utilisez également async with credential: afin que les jetons et les transports soient nettoyés correctement.
3. Traductions par lots — Envoyez plusieurs textes dans une seule requête (jusqu'à 100)
4. Spécifiez la langue source lorsqu'elle est connue pour améliorer la précision
5. Utilisez le client asynchrone pour les scénarios à haut débit
6. Mettez en cache la liste des langues — Les langues prises en charge ne changent pas fréquemment
7. Gérez les vulgarités de manière appropriée pour votre application
8. Utilisez le type de texte html lors de la traduction de contenu HTML
9. Incluez l'alignement pour les applications nécessitant une correspondance des mots