SDK Azure AI pour la traduction de documents en Python

Bibliothèque cliente pour le service de traduction de documents Azure AI Translator, permettant la traduction par lots de documents tout en conservant leur format.

Installation

pip install azure-ai-translation-document

Variables d'environnement

AZURE_DOCUMENT_TRANSLATION_ENDPOINT=https://.cognitiveservices.azure.com  # Requis pour toutes les méthodes d'authentification
# Stockage des documents source et cible
AZURE_SOURCE_CONTAINER_URL=https://.blob.core.windows.net/? # Requis pour toutes les méthodes d’authentification
AZURE_TARGET_CONTAINER_URL=https://.blob.core.windows.net/? # Requis pour toutes les méthodes d’authentification
AZURE_TOKEN_CREDENTIALS=prod # Obligatoire uniquement si DefaultAzureCredential est utilisé en production
AZURE_DOCUMENT_TRANSLATION_KEY= # Obligatoire uniquement pour le chemin d'authentification par clé API hérité ci-dessous

Authentification et cycle de vie

🔑 Deux règles s’appliquent à tous les exemples de code ci-dessous :

1. Privilégiez DefaultAzureCredential. Elle fonctionne en local (CLI Azure / VS Code / CLI développeur) et dans Azure (identité gérée, identité de charge de travail) sans modification du code. Évitez les chaînes de connexion, les identifiants de compte et les clés API : ils contournent l’audit et la rotation Entra.
   • Développement local : DefaultAzureCredential fonctionne tel quel.
   • En production : définissez AZURE_TOKEN_CREDENTIALS=prod (ou AZURE_TOKEN_CREDENTIALS=) pour limiter la chaîne d’identifiants 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 : avec ` (...)` comme client :
   • Asynchrone : async avec (...) comme client : et async avec DefaultAzureCredential() comme identifiant : (de azure.identity.aio)

Les extraits de code peuvent simplifier 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.document import DocumentTranslationClient

# Développement local : DefaultAzureCredential. Production : définissez AZURE_TOKEN_CREDENTIALS=prod ou AZURE_TOKEN_CREDENTIALS=
credential = DefaultAzureCredential(require_envvar=True)
# Ou utilisez directement des informations d'identification spécifiques en production :
# Voir https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes
# credential = ManagedIdentityCredential()

with DocumentTranslationClient(
    endpoint=os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"],
    credential=credential,
) as client:
    statuses = list(client.list_translation_statuses())

Ancien système : clé API (déploiements existants avec clé)

Le nouveau code doit utiliser DefaultAzureCredential ci-dessus. N’utilisez AzureKeyCredential que si vous disposez d’un déploiement existant utilisant une clé qui n’a pas encore été migré vers Entra ID — par exemple, les environnements réglementés qui sont encore en cours de déploiement d’Entra.

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient, SingleDocumentTranslationClient

with DocumentTranslationClient(
    endpoint=os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"],
    credential=AzureKeyCredential(os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"]),
) as client:
    statuses = list(client.list_translation_statuses())

# SingleDocumentTranslationClient accepte les mêmes informations d’identification basées sur une clé.

Traduction de document de base

from azure.ai.translation.document import DocumentTranslationInput, TranslationTarget

source_url = os.environ["AZURE_SOURCE_CONTAINER_URL"]
target_url = os.environ["AZURE_TARGET_CONTAINER_URL"]

# Lancer la tâche de traduction
poller = client.begin_translation(
    inputs=[
        DocumentTranslationInput(
            source_url=source_url,
            targets=[
                TranslationTarget(
                    target_url=target_url,
                    language="es"  # Traduire en espagnol
                )
            ]
        )
    ]
)

# Attendre la fin du traitement
result = poller.result()

print(f"Statut : {poller.status()}")
print(f"Documents traduits : {poller.details.documents_succeeded_count}")
print(f"Documents ayant échoué : {poller.details.documents_failed_count}")

Plusieurs langues cibles

poller = client.begin_translation(
    inputs=[
        DocumentTranslationInput(
            source_url=source_url,
            targets=[
                TranslationTarget(target_url=target_url_es, language="es"),
                TranslationTarget(target_url=target_url_fr, language="fr"),
                TranslationTarget(target_url=target_url_de, language="de")
            ]
        )
    ]
)

Traduire un document unique

from azure.ai.translation.document import SingleDocumentTranslationClient
from azure.identity import DefaultAzureCredential

with open("document.docx", "rb") as f:
    document_content = f.read()

with SingleDocumentTranslationClient(endpoint, DefaultAzureCredential()) as single_client:
    result = single_client.translate(
        body=document_content,
        target_language="es",
        content_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    )

# Enregistrer le document traduit
with open("document_es.docx", "wb") as f:
    f.write(result)

Vérifier l'état de la traduction

# Récupérer toutes les opérations de traduction
operations = client.list_translation_statuses()

for op in operations:
    print(f"ID de l'opération : {op.id}")
    print(f"Statut : {op.status}")
    print(f"Créé le : {op.created_on}")
    print(f"Nombre total de documents : {op.documents_total_count}")
    print(f"Réussies : {op.documents_succeeded_count}")
    print(f"Échouées : {op.documents_failed_count}")

Liste des statuts des documents

# Récupérer le statut de chaque document d’une tâche
operation_id = poller.id
document_statuses = client.list_document_statuses(operation_id)

for doc in document_statuses:
    print(f"Document : {doc.source_document_url}")
    print(f"  Statut : {doc.status}")
    print(f"  Traduit vers : {doc.translated_to}")
    if doc.error:
        print(f"  Erreur : {doc.error.message}")

Annuler la traduction

# Annuler une traduction en cours
client.cancel_translation(operation_id)

Utilisation du glossaire

from azure.ai.translation.document import TranslationGlossary

poller = client.begin_translation(
    inputs=[
        DocumentTranslationInput(
            source_url=source_url,
            targets=[
                TranslationTarget(
                    target_url=target_url,
                    language="es",
                    glossaries=[
                        TranslationGlossary(
                            glossary_url="https://.blob.core.windows.net/glossary/terms.csv?",
                            file_format="csv"
                        )
                    ]
                )
            ]
        )
    ]
)

Formats de documents pris en charge

# Récupérer les formats pris en charge
formats = client.get_supported_document_formats()

for fmt in formats:
    print(f"Format : {fmt.format}")
    print(f"  Extensions : {fmt.file_extensions}")
    print(f"  Types de contenu : {fmt.content_types}")

Langues prises en charge

# Récupérer les langues prises en charge
languages = client.get_supported_languages()

for lang in languages:
    print(f"Langue : {lang.name} ({lang.code})")

Client asynchrone

from azure.ai.translation.document.aio import DocumentTranslationClient
from azure.identity.aio import DefaultAzureCredential

async def translate_documents():
    async with DefaultAzureCredential() as credential:
        async with DocumentTranslationClient(
            endpoint=endpoint,
            credential=credential,
        ) as client:
            poller = await client.begin_translation(inputs=[...])
            result = await poller.result()

Formats pris en charge

Exigences de stockage

• Les conteneurs source et cible doivent être hébergés sur Azure Blob Storage
• Utilisez des jetons SAS dotés des autorisations appropriées :
  • Source : lecture, liste
  • Cible : Écriture, Liste

Bonnes pratiques

1. Optez pour 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 un même chemin d’appel. Choisissez un seul mode par module.
2. Utilisez toujours des gestionnaires de contexte pour les clients et les informations d’identification asynchrones. Enveloppez chaque client avec `Client(...)` en tant que client : (synchrone) ou asynchrone avec `Client(...)` en tant que client : (asynchrone). Pour les identifiants asynchrones DefaultAzureCredential de azure.identity.aio, utilisez également « async » avec « credential: » afin que les jetons et les transports soient nettoyés.
3. Utilisez des jetons SAS avec le minimum d’autorisations requises
4. Surveillez les opérations de longue durée à l’aide de ` poller.status()`
5. Gérez les erreurs au niveau des documents en parcourant les statuts des documents
6. Utilisez des glossaires pour la terminologie spécifique à un domaine
7. Prévoyezdes conteneurs cibles distincts pour chaque langue
8. Utilisez le client asynchrone pour plusieurs tâches simultanées
9. Vérifiez les formats pris en charge avant de soumettre des documents