SDK Azure AI Document Translation pour Python

Bibliothèque client pour le service de traduction de documents Azure AI Translator permettant la traduction par lot de documents avec préservation du format.

Installation

pip install azure-ai-translation-document

Variables d'environnement

AZURE_DOCUMENT_TRANSLATION_ENDPOINT=https://<resource>.cognitiveservices.azure.com  # Requis pour toutes les méthodes d'authentification
AZURE_DOCUMENT_TRANSLATION_KEY=<your-api-key>  # Requis uniquement pour l'authentification AzureKeyCredential
# Stockage des documents source et cible
AZURE_SOURCE_CONTAINER_URL=https://<storage>.blob.core.windows.net/<container>?<sas>  # Requis pour toutes les méthodes d'authentification
AZURE_TARGET_CONTAINER_URL=https://<storage>.blob.core.windows.net/<container>?<sas>  # Requis pour toutes les méthodes d'authentification
AZURE_TOKEN_CREDENTIALS=prod # Requis uniquement si DefaultAzureCredential est utilisé en production

Authentification

Clé API

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

endpoint = os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"]
key = os.environ["AZURE_DOCUMENT_TRANSLATION_KEY"]

client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))

Entra ID (Recommandé)

from azure.ai.translation.document import DocumentTranslationClient
from azure.identity import DefaultAzureCredential, ManagedIdentityCredential

# Développement local : DefaultAzureCredential. Production : définir AZURE_TOKEN_CREDENTIALS=prod ou AZURE_TOKEN_CREDENTIALS=<specific_credential>
credential = DefaultAzureCredential(require_envvar=True)
# Ou utiliser directement une credential spécifique en production :
# Voir https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes
# credential = ManagedIdentityCredential()
client = DocumentTranslationClient(
    endpoint=os.environ["AZURE_DOCUMENT_TRANSLATION_ENDPOINT"],
    credential=credential
)

Traduction de documents basique

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

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

# Démarrer une 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
result = poller.result()

print(f"Status: {poller.status()}")
print(f"Documents traduits: {poller.details.documents_succeeded_count}")
print(f"Documents échoués: {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

single_client = SingleDocumentTranslationClient(endpoint, AzureKeyCredential(key))

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

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 le statut de la traduction

# Obtenir toutes les opérations de traduction
operations = client.list_translation_statuses()

for op in operations:
    print(f"ID opération: {op.id}")
    print(f"Status: {op.status}")
    print(f"Créé: {op.created_on}")
    print(f"Total de documents: {op.documents_total_count}")
    print(f"Réussis: {op.documents_succeeded_count}")
    print(f"Échoués: {op.documents_failed_count}")

Lister les statuts des documents

# Obtenir le statut de documents individuels dans 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"  Status: {doc.status}")
    print(f"  Traduit en: {doc.translated_to}")
    if doc.error:
        print(f"  Erreur: {doc.error.message}")

Annuler une traduction

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

Utiliser un 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://<storage>.blob.core.windows.net/glossary/terms.csv?<sas>",
                            file_format="csv"
                        )
                    ]
                )
            ]
        )
    ]
)

Formats de documents pris en charge

# Obtenir 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

# Obtenir 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 DocumentTranslationClient(
        endpoint=endpoint,
        credential=DefaultAzureCredential()
    ) 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 du stockage Blob Azure
• Utiliser des tokens SAS avec les autorisations appropriées :
  • Source : Lecture, Liste
  • Cible : Écriture, Liste

Bonnes pratiques

1. Utiliser des tokens SAS avec les autorisations minimales requises
2. Surveiller les opérations longues avec poller.status()
3. Gérer les erreurs au niveau du document en itérant sur les statuts des documents
4. Utiliser des glossaires pour la terminologie spécifique à un domaine
5. Séparer les conteneurs cibles pour chaque langue
6. Utiliser le client asynchrone pour plusieurs tâches concurrentes
7. Vérifier les formats pris en charge avant de soumettre des documents