Azure AI Text Translation SDK pour Python

Bibliothèque cliente pour le service de traduction de texte Azure AI Translator pour la traduction de texte en temps réel, la translittération et les opérations linguistiques.

Installation

pip install azure-ai-translation-text

Variables d'environnement

AZURE_TRANSLATOR_KEY=<your-api-key>  # Obligatoire uniquement pour l'authentification AzureKeyCredential
AZURE_TRANSLATOR_REGION=<your-region>  # Par exemple, eastus, westus2 ; obligatoire avec l'authentification par clé API
# Ou utilisez un point de terminaison personnalisé
AZURE_TRANSLATOR_ENDPOINT=https://<resource>.cognitiveservices.azure.com  # Obligatoire pour l'authentification Entra ID
AZURE_TOKEN_CREDENTIALS=prod # Obligatoire uniquement si DefaultAzureCredential est utilisé en production

Authentification

Clé API avec région

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

key = os.environ["AZURE_TRANSLATOR_KEY"]
region = os.environ["AZURE_TRANSLATOR_REGION"]

# Créer les identifiants avec la région
credential = AzureKeyCredential(key)
client = TextTranslationClient(credential=credential, region=region)

Clé API avec point de terminaison personnalisé

endpoint = os.environ["AZURE_TRANSLATOR_ENDPOINT"]

client = TextTranslationClient(
    credential=AzureKeyCredential(key),
    endpoint=endpoint
)

Entra ID (recommandé)

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

# Dev local : DefaultAzureCredential. Production : définissez AZURE_TOKEN_CREDENTIALS=prod ou AZURE_TOKEN_CREDENTIALS=<specific_credential>
credential = DefaultAzureCredential(require_envvar=True)
# Ou utilisez directement des identifiants spécifiques en production :
# Consultez https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes
# credential = ManagedIdentityCredential()

client = TextTranslationClient(
    credential=credential,
    endpoint=os.environ["AZURE_TRANSLATOR_ENDPOINT"]
)

Traduction basique

# Traduire dans 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"Translated: {translation.text}")
        print(f"Target language: {translation.to}")

Traduire dans 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 'unknown'}")
    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"Detected language: {item.detected_language.language}")
        print(f"Confidence: {item.detected_language.score:.2f}")

Translittération

Convertir du texte d'un script à un autre :

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

for item in result:
    print(f"Transliterated: {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"  Translation: {translation.normalized_target}")
        print(f"  Part of speech: {translation.pos_tag}")
        print(f"  Confidence: {translation.confidence:.2f}")

Exemples du 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"Target: {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("Translation languages:")
for code, lang in languages.translation.items():
    print(f"  {code}: {lang.name} ({lang.native_name})")

# Langues de translittération
print("\nTransliteration languages:")
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 du dictionnaire
print("\nDictionary languages:")
for code, lang in languages.dictionary.items():
    print(f"  {code}: {lang.name}")

Identifier les limites de phrases

Identifier les limites de phrases :

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

for item in result:
    print(f"Sentence lengths: {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 de phrases
)

for item in result:
    translation = item.translations[0]
    print(f"Translated: {translation.text}")
    if translation.alignment:
        print(f"Alignment: {translation.alignment.proj}")
    if translation.sent_len:
        print(f"Sentence lengths: {translation.sent_len.src_sent_len}")

Client asynchrone

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

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

Méthodes du client

Bonnes pratiques

1. Traductions par lot — Envoyer plusieurs textes dans une seule requête (jusqu'à 100)
2. Spécifier la langue source quand elle est connue pour améliorer la précision
3. Utiliser le client asynchrone pour les scénarios de haut débit
4. Mettre en cache la liste des langues — Les langues prises en charge ne changent pas fréquemment
5. Gérer les profanités de manière appropriée pour votre application
6. Utiliser html text_type lors de la traduction de contenu HTML
7. Inclure l'alignement pour les applications nécessitant un mappage des mots