Partager via

Bibliothèque cliente De traduction de documents Azure pour Python - version 1.0.0

  • Article

La traduction de documents Azure Cognitive Services est un service cloud qui peut être utilisé pour traduire des documents multiples et complexes dans des langages et des dialectes tout en préservant la structure de document d’origine et le format de données. Utilisez la bibliothèque cliente pour la traduction de documents pour :

  • Traduire de nombreux fichiers volumineux d’un conteneur Stockage Blob Azure vers un conteneur cible dans la langue de votre choix.
  • Vérifiez l’état et la progression de la traduction de chaque document dans l’opération de traduction.
  • Appliquez un modèle de traduction personnalisé ou des glossaires pour adapter la traduction à votre cas spécifique.

| Code sourcePackage (PyPI) | Documentation de référence sur les | API | Documentation produitÉchantillons

Clause d’exclusion de responsabilité

La prise en charge des packages Python du SDK Azure pour Python 2.7 a pris fin le 1er janvier 2022. Pour obtenir plus d’informations et poser des questions, reportez-vous à https://github.com/Azure/azure-sdk-for-python/issues/20691

Prise en main

Prérequis

Installer le package

Installez la bibliothèque cliente De traduction de documents Azure pour Python avec pip :

pip install azure-ai-translation-document

Remarque : Cette version de la bibliothèque cliente utilise par défaut la version v1.0 du service

Créer une ressource pour Translator

La fonctionnalité Traduction de documents prend uniquement en charge l’accès à un seul service . Pour accéder au service, créez une ressource Translator.

Vous pouvez créer la ressource à l’aide de

Option 1 :Portail Azure

Option 2 :Azure CLI. Voici un exemple de création d’une ressource Translator à l’aide de l’interface CLI :

# Create a new resource group to hold the Translator resource -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create document translation
az cognitiveservices account create \
    --name document-translation-resource \
    --custom-domain document-translation-resource \
    --resource-group my-resource-group \
    --kind TextTranslation \
    --sku S1 \
    --location westus2 \
    --yes

Authentifier le client

Pour interagir avec le service de fonctionnalité Traduction de documents, vous devez créer une instance d’un client. Un point de terminaison et des informations d’identification sont nécessaires pour instancier l’objet client.

Recherche du point de terminaison

Vous pouvez trouver le point de terminaison de votre ressource Translator à l’aide du portail Azure.

Notez que le service nécessite un point de terminaison de domaine personnalisé. Suivez les instructions du lien ci-dessus pour mettre en forme votre point de terminaison : https://{NAME-OF-YOUR-RESOURCE}.cognitiveservices.azure.com/

Obtenir la clé API

La clé API se trouve dans le portail Azure ou en exécutant la commande Azure CLI suivante :

az cognitiveservices account keys list --name "resource-name" --resource-group "resource-group-name"

Créer le client avec AzureKeyCredential

Pour utiliser une clé API comme credential paramètre, passez la clé sous forme de chaîne dans une instance d’AzureKeyCredential.

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

endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")
document_translation_client = DocumentTranslationClient(endpoint, credential)

Créer le client avec des informations d’identification Azure Active Directory

AzureKeyCredential l’authentification est utilisée dans les exemples de ce guide de prise en main, mais vous pouvez également vous authentifier auprès d’Azure Active Directory à l’aide de la bibliothèque azure-identity .

Pour utiliser le type DefaultAzureCredential indiqué ci-dessous ou d’autres types d’informations d’identification fournis avec le Kit de développement logiciel (SDK) Azure, installez le azure-identity package :

pip install azure-identity

Vous devez également inscrire une nouvelle application AAD et accorder l’accès à votre ressource Translator en attribuant le "Cognitive Services User" rôle à votre principal de service.

Une fois terminé, définissez les valeurs de l’ID client, de l’ID de locataire et de la clé secrète client de l’application AAD en tant que variables d’environnement : AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

from azure.identity import DefaultAzureCredential
from azure.ai.translation.document import DocumentTranslationClient
credential = DefaultAzureCredential()

document_translation_client = DocumentTranslationClient(
    endpoint="https://<resource-name>.cognitiveservices.azure.com/",
    credential=credential
)

Concepts clés

Le service De traduction de documents vous demande de charger vos fichiers dans un conteneur source Stockage Blob Azure et de fournir un conteneur cible dans lequel les documents traduits peuvent être écrits. Pour plus d’informations sur cette configuration, consultez la documentation du service :

DocumentTranslationClient

L’interaction avec la bibliothèque cliente de traduction de documents commence par une instance du DocumentTranslationClient. Le client fournit des opérations pour :

  • Création d’une opération de traduction pour traduire des documents dans vos conteneurs sources et écrire les résultats dans les conteneurs cibles.
  • Vérification de l’état des documents individuels dans l’opération de traduction et surveillance de la progression de chaque document.
  • Énumération de toutes les opérations de traduction passées et actuelles.
  • Identification des formats de glossaire et de document pris en charge.

Entrée de traduction

L’entrée dans la begin_translation méthode cliente peut être fournie de deux manières différentes :

  1. Un conteneur source unique contenant des documents peut être traduit dans une autre langue :
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

document_translation_client = DocumentTranslationClient("<endpoint>", AzureKeyCredential("<api_key>"))
poller = document_translation_client.begin_translation("<sas_url_to_source>", "<sas_url_to_target>", "<target_language>")
  1. Ou plusieurs sources différentes peuvent être fournies chacune avec leurs propres cibles.
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient, DocumentTranslationInput, TranslationTarget

my_input = [
    DocumentTranslationInput(
        source_url="<sas_url_to_source_A>",
        targets=[
            TranslationTarget(target_url="<sas_url_to_target_fr>", language="fr"),
            TranslationTarget(target_url="<sas_url_to_target_de>", language="de")
        ]
    ),
    DocumentTranslationInput(
        source_url="<sas_url_to_source_B>",
        targets=[
            TranslationTarget(target_url="<sas_url_to_target_fr>", language="fr"),
            TranslationTarget(target_url="<sas_url_to_target_de>", language="de")
        ]
    ),
    DocumentTranslationInput(
        source_url="<sas_url_to_source_C>",
        targets=[
            TranslationTarget(target_url="<sas_url_to_target_fr>", language="fr"),
            TranslationTarget(target_url="<sas_url_to_target_de>", language="de")
        ]
    )
]

document_translation_client = DocumentTranslationClient("<endpoint>", AzureKeyCredential("<api_key>"))
poller = document_translation_client.begin_translation(my_input)

Remarque : la target_url pour chaque langue cible doit être unique.

Pour traduire des documents sous un dossier ou traduire uniquement certains documents, consultez sample_begin_translation_with_filters.py. Consultez la documentation du service pour toutes les langues prises en charge.

opérations Long-Running

Les opérations de longue durée sont des opérations qui consistent en une demande initiale envoyée au service pour démarrer une opération, suivie d’un interrogation du service à intervalles réguliers pour déterminer si l’opération s’est terminée ou échouée, et si elle a réussi, pour obtenir le résultat.

Les méthodes qui traduisent des documents sont modélisées comme des opérations de longue durée. Le client expose une begin_<method-name> méthode qui retourne un DocumentTranslationLROPoller ou AsyncDocumentTranslationLROPoller. Les appelants doivent attendre que l’opération se termine en appelant result() sur l’objet poller retourné par la begin_<method-name> méthode. Des exemples d’extraits de code sont fournis pour illustrer l’utilisation d’opérations de longue durée ci-dessous.

Exemples

La section suivante fournit plusieurs extraits de code couvrant certaines des tâches de traduction de documents les plus courantes, notamment :

Traduire vos documents

Traduire tous les documents de votre conteneur source dans le conteneur cible. Pour traduire des documents sous un dossier ou traduire uniquement certains documents, consultez sample_begin_translation_with_filters.py.

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

endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")
source_container_sas_url_en = "<sas-url-en>"
target_container_sas_url_es = "<sas-url-es>"

document_translation_client = DocumentTranslationClient(endpoint, credential)

poller = document_translation_client.begin_translation(source_container_sas_url_en, target_container_sas_url_es, "es")

result = poller.result()

print(f"Status: {poller.status()}")
print(f"Created on: {poller.details.created_on}")
print(f"Last updated on: {poller.details.last_updated_on}")
print(f"Total number of translations on documents: {poller.details.documents_total_count}")

print("\nOf total documents...")
print(f"{poller.details.documents_failed_count} failed")
print(f"{poller.details.documents_succeeded_count} succeeded")

for document in result:
    print(f"Document ID: {document.id}")
    print(f"Document status: {document.status}")
    if document.status == "Succeeded":
        print(f"Source document location: {document.source_document_url}")
        print(f"Translated document location: {document.translated_document_url}")
        print(f"Translated to language: {document.translated_to}\n")
    else:
        print(f"Error Code: {document.error.code}, Message: {document.error.message}\n")

Traduire plusieurs entrées

Commencez à traduire des documents dans plusieurs conteneurs sources vers plusieurs conteneurs cibles dans différentes langues.

from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient, DocumentTranslationInput, TranslationTarget

endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")
source_container_sas_url_de = "<sas-url-de>"
source_container_sas_url_en = "<sas-url-en>"
target_container_sas_url_es = "<sas-url-es>"
target_container_sas_url_fr = "<sas-url-fr>"
target_container_sas_url_ar = "<sas-url-ar>"

document_translation_client = DocumentTranslationClient(endpoint, credential)

poller = document_translation_client.begin_translation(
    [
        DocumentTranslationInput(
            source_url=source_container_sas_url_en,
            targets=[
                TranslationTarget(target_url=target_container_sas_url_es, language="es"),
                TranslationTarget(target_url=target_container_sas_url_fr, language="fr"),
            ],
        ),
        DocumentTranslationInput(
            source_url=source_container_sas_url_de,
            targets=[
                TranslationTarget(target_url=target_container_sas_url_ar, language="ar"),
            ],
        )
    ]
)

result = poller.result()

for document in result:
    print(f"Document ID: {document.id}")
    print(f"Document status: {document.status}")
    if document.status == "Succeeded":
        print(f"Source document location: {document.source_document_url}")
        print(f"Translated document location: {document.translated_document_url}")
        print(f"Translated to language: {document.translated_to}\n")
    else:
        print(f"Error Code: {document.error.code}, Message: {document.error.message}\n")

Opérations de traduction de liste

Énumérez les opérations de traduction envoyées pour la ressource.

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

endpoint = "https://<resource-name>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")

document_translation_client = DocumentTranslationClient(endpoint, credential)

operations = document_translation_client.list_translation_statuses()  # type: ItemPaged[TranslationStatus]

for operation in operations:
    print(f"\nID: {operation.id}")
    print(f"Status: {operation.status}")
    print(f"Created on: {operation.created_on}")
    print(f"Last updated on: {operation.last_updated_on}")
    print(f"Total number of translations on documents: {operation.documents_total_count}")
    print(f"Total number of characters charged: {operation.total_characters_charged}")

    print("Of total documents...")
    print(f"{operation.documents_failed_count} failed")
    print(f"{operation.documents_succeeded_count} succeeded")
    print(f"{operation.documents_canceled_count} canceled")

Pour savoir comment utiliser la bibliothèque cliente traduction de documents avec l’objet blob stockage Azure pour charger des documents, créer des jetons SAP pour vos conteneurs et télécharger les documents traduits terminés, consultez cet exemple. Notez que vous devez installer la bibliothèque azure-storage-blob pour exécuter cet exemple.

Rubriques avancées

La section suivante fournit des informations sur certaines fonctionnalités de traduction avancées telles que les glossaires et les modèles de traduction personnalisés.

Glossaires

Les glossaires sont des dictionnaires spécifiques à un domaine. Par exemple, si vous souhaitez traduire certains documents médicaux, vous aurez peut-être besoin d’une prise en charge des nombreux mots, terminologies et idiomes dans le domaine médical que vous ne trouvez pas dans le dictionnaire de traduction standard, ou vous avez simplement besoin d’une traduction spécifique. C’est pourquoi la traduction de documents prend en charge les glossaires.

Comment créer un fichier de glossaire

La traduction de documents prend en charge les glossaires dans les formats suivants :

Type de fichier Extension Description Exemples
Valeurs séparées par des tabulations/TAB .tsv, .tab En savoir plus sur wikipédia glossary_sample.tsv
Valeurs séparées par des virgules .csv En savoir plus sur wikipédia glossary_sample.csv
Format du fichier d’échange de localisation .xlf, .xliff En savoir plus sur wikipédia glossary_sample.xlf

Affichez tous les formats pris en charge ici.

Utilisation des glossaires dans la traduction de documents

Pour utiliser des glossaires avec la traduction de documents, vous devez d’abord charger votre fichier de glossaire dans un conteneur d’objets blob, puis fournir l’URL SAS au fichier comme dans les exemples de code sample_translation_with_glossaries.py.

Modèles de traduction personnalisés

Au lieu d’utiliser le moteur de traduction de documents pour la traduction, vous pouvez utiliser votre propre modèle azure machine/deep learning personnalisé.

Comment créer un modèle de traduction personnalisé

Pour plus d’informations sur la création, l’approvisionnement et le déploiement de votre propre modèle de traduction Azure personnalisé, suivez les instructions ici : Créer, déployer et utiliser un modèle personnalisé pour la traduction

Comment utiliser un modèle de traduction personnalisé avec la traduction de documents

Pour utiliser un modèle de traduction personnalisé avec la traduction de documents, vous devez d’abord créer et déployer votre modèle, puis suivre l’exemple de code sample_translation_with_custom_model.py à utiliser avec la traduction de documents.

Dépannage

Général

La bibliothèque cliente de traduction de documents génère des exceptions définies dans Azure Core.

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation.

Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au INFO niveau.

La journalisation détaillée DEBUG de niveau, y compris les corps de requête/réponse et les en-têtes non expurgés , peut être activée sur le client ou par opération avec l’argument de logging_enable mot clé.

Consultez la documentation complète sur la journalisation du KIT de développement logiciel (SDK) avec des exemples ici.

Configuration facultative

Les arguments de mot clé facultatifs peuvent être transmis au niveau du client et par opération. La documentation de référence azure-core décrit les configurations disponibles pour les nouvelles tentatives, la journalisation, les protocoles de transport, etc.

Étapes suivantes

La section suivante fournit plusieurs extraits de code illustrant les modèles courants utilisés dans la bibliothèque cliente Python de traduction de documents. Vous trouverez d’autres exemples sous le répertoire des exemples .

Autres exemples de code

Ces exemples de code illustrent les opérations de scénario courantes avec la bibliothèque cliente Azure Document Translation.

Exemples asynchrones

Cette bibliothèque comprend également un ensemble complet d’API asynchrones. Pour les utiliser, vous devez d’abord installer un transport asynchrone, tel que aiohttp. Les clients asynchrones se trouvent sous l’espace de azure.ai.translation.document.aio noms.

Documentation complémentaire

Pour obtenir une documentation plus complète sur la traduction de documents Azure Cognitive Services, consultez la documentation relative à la traduction de documents sur docs.microsoft.com.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.