Bibliothèques de client Traduction de documentation par lots

Article
02/22/2024

La traduction de documentation est une fonctionnalité cloud du service Azure AI Traducteur qui traduit de manière asynchrone des documents entiers dans des langues prises en charge et dans différents formats de fichiers. Dans ce guide de démarrage rapide, vous apprenez à utiliser la Traduction de documentation avec le langage de programmation de votre choix pour traduire un document source dans une langue cible tout en conservant la structure et la mise en forme du texte.

Important

La traduction de documentation est actuellement prise en charge dans la ressource Translator (service unique) uniquement, et n’est pas incluse dans la ressource Azure AI services (multiservice).
La traduction de documentation est prise en charge dans les niveaux payants. Language Studio prend uniquement en charge les instances de niveaux S1 ou D3. Nous vous suggérons de sélectionner Standard S1 pour essayer la traduction de documentation. ConsultezTarification Azure AI services – Translator.

Prérequis

Pour commencer, vous avez besoin des éléments suivants :

Un compte Azure actif. Si vous n’en avez pas, vous pouvez créer un compte gratuit.
Une ressource Traducteur de service unique (et pas une ressource multiservice Azure AI services). Si vous envisagez d’utiliser la fonctionnalité Traduction de documentations avec une autorisation par identité managée, choisissez une région géographique tel que USA Est. Sélectionnez le niveau Standard S1 ou D3 ou le niveau tarifaire.
Un compte de stockage Blob Azure. Vous devez créer des conteneurs dans votre compte de stockage blob Azure pour les fichiers sources et cibles :
- Conteneur source. Ce conteneur est l’emplacement où vous chargez vos fichiers pour la traduction (obligatoire).
- Conteneur cible. Ce conteneur est l’emplacement où vos fichiers traduits sont stockés (obligatoire).

Autorisation du conteneur de stockage

Vous pouvez choisir l’une des options suivantes pour autoriser l’accès à votre ressource Translator.

✔️ Identité managée. Une identité managée est un principal de service qui crée une identité Microsoft Entra et des autorisations spécifiques pour une ressource managée Azure. Les identités managées vous permettent d’exécuter votre application Translator sans avoir à incorporer des informations d’identification dans votre code. Les identités managées sont un moyen plus sûr d’accorder l’accès aux données de stockage et de remplacer la nécessité d’inclure des jetons de signature d’accès partagé (SAP) avec vos URL source et cible.

Pour en savoir plus, consultezIdentités managées pour la traduction de documentation.

Screenshot of managed identity flow (RBAC).

✔️ Signature d’accès partagé (SAP). Une signature d’accès partagé est une URL qui accorde un accès restreint pendant une période spécifiée à votre service Translator. Pour utiliser cette méthode, vous devez créer des jetons de signature d’accès partagé (SAP) pour vos conteneurs source et cible. sourceUrl et targetUrl doivent inclure un jeton de signature d’accès partagé (SAP), ajouté comme chaîne de requête. Le jeton peut être attribué à votre conteneur ou à des blobs spécifiques.

Votre blob ou conteneur source doit désigner un accès lecture et liste.
Votre blob ou conteneur cible doit désigner un accès écriture et liste.

Pour plus d’informations, consultezCréer des jetons SAP.

Screenshot of a resource URI with a SAS token.

Générer votre application

Plusieurs outils sont disponibles pour créer, générer et exécuter des applications Translator C#/.NET. Ici, nous vous guidons tout au long de l’utilisation de l’interface de ligne de commande (CLI) ou de Visual Studio. Sélectionnez l’un des onglets suivants pour commencer :

CLI .NET
Visual Studio

Configuration de votre projet

Dans une fenêtre de console (par exemple cmd, PowerShell ou Bash), utilisez la commande dotnet new pour créer une application console avec le nom batch-document-translation. Cette commande crée un projet C# « Hello World » simple avec un seul fichier source : Program.cs.

dotnet new console -n batch-document-translation

Déplacez vos répertoires vers le dossier d’application nouvellement créé. Générez votre application à l’aide de la commande suivante :

dotnet build

La sortie de génération ne doit contenir aucun avertissement ni erreur.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

Installer la bibliothèque de client

Dans le répertoire de l’application, installez la bibliothèque de client de traduction de documentation pour .NET :

dotnet add package Azure.AI.Translation.Document --version 1.0.0

Traduire un document ou des fichiers par lot

Pour ce projet, vous avez besoin d’un document source chargé dans votre conteneur source. Pour ce guide de démarrage rapide, vous pouvez télécharger notre exemple de document Traduction de documentation. La langue source est l’anglais.
À partir du répertoire de projet, ouvrez le fichier Program.cs dans votre éditeur ou votre IDE favori. Supprimez le code préexistant, y compris la ligne Console.WriteLine("Hello World!").
Dans Program.cs de l’application, créez des variables pour votre clé et votre point de terminaison personnalisé. Pour plus d’informations, consultezRécupérer votre clé et votre point de terminaison du domaine personnalisé.
```
private static readonly string endpoint = "<your-document-translation-endpoint>";
private static readonly string key = "<your-key>";
```
Appelez la méthode StartTranslationAsync pour démarrer une opération de traduction pour un ou plusieurs documents dans un seul conteneur d’objets blob.

Pour appeler StartTranslationAsync, vous devez initialiser un objet DocumentTranslationInput qui contient les paramètres sourceUri, targetUri et targetLanguageCode :

Pour Autorisation d’identité managée, créez ces variables :

sourceUri. L’URL du conteneur source contenant les documents à traduire.
targetUri L’URL du conteneur cible dans lequel les documents traduits sont écrits.

targetLanguageCode. Le code de langue pour les documents traduits. Vous pouvez trouver les codes de langue sur notre page Support multilingue.

Pour rechercher vos URL source et cible, accédez à votre compte de stockage dans le portail Azure. Dans la barre latérale gauche, sous Stockage de données, sélectionnez Conteneurs et suivez ces étapes pour récupérer vos documents sources et URLS de conteneur cible.

Source	Cible
1. Cochez la case à côté du conteneur source.	1. Cochez la case à côté du conteneur cible.
2. Dans la fenêtre principale, sélectionnez un fichier ou des documents à traduire.	2. Sélectionnez les points de suspension situés à droite, puis choisissez Propriétés.
3. L’URL source se trouve en haut de la liste Propriétés.	3. L’URL cible se trouve en haut de la liste Propriétés.

Pour Autorisation de signature d’accès partagé (SAP), créez ces variables
- sourceUri. URI SAP, avec un jeton SAP ajouté en tant que chaîne de requête, pour le conteneur source contenant des documents à traduire.
- targetUri URI SAP, avec un jeton SAP ajouté en tant que chaîne de requête, pour le conteneur cible dans lequel les documents traduits sont écrits.
- targetLanguageCode. Le code de langue pour les documents traduits. Vous pouvez trouver les codes de langue sur notre page Support multilingue.

Exemple de code

Important

N’oubliez pas de supprimer la clé de votre code une fois que vous avez terminé, et ne la postez jamais publiquement. Pour la production, utilisez un moyen sécurisé de stocker et d’accéder à vos informations d’identification comme Azure Key Vault. Si vous souhaitez en savoir plus, veuillez consulter la rubriqueSécurité Azure AI services.

Entrez l’exemple de code suivant dans le fichier Program.cs de votre application :


using Azure;
using Azure.AI.Translation.Document;
using System;
using System.Threading;
using System.Text;

class Program {

  // create variables for your custom endpoint and resource key
  private static readonly string endpoint = "<your-document-translation-endpoint>";
  private static readonly string key = "<your-key>";

  static async Task Main(string[] args) {

    // create variables for your sourceUrl, targetUrl, and targetLanguageCode
    Uri sourceUri = new Uri("<sourceUrl>");
    Uri targetUri = new Uri("<targetUrl>");
    string targetLanguage = "<targetLanguageCode>"

    // initialize a new instance  of the DocumentTranslationClient object to interact with the Document Translation feature
    DocumentTranslationClient client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(key));

    // initialize a new instance of the `DocumentTranslationInput` object to provide the location of input for the translation operation
    DocumentTranslationInput input = new DocumentTranslationInput(sourceUri, targetUri, targetLanguage);

    // initialize a new instance of the DocumentTranslationOperation class to track the status of the translation operation
    DocumentTranslationOperation operation = await client.StartTranslationAsync(input);

    await operation.WaitForCompletionAsync();

    Console.WriteLine($"  Status: {operation.Status}");
    Console.WriteLine($"  Created on: {operation.CreatedOn}");
    Console.WriteLine($"  Last modified: {operation.LastModified}");
    Console.WriteLine($"  Total documents: {operation.DocumentsTotal}");
    Console.WriteLine($"    Succeeded: {operation.DocumentsSucceeded}");
    Console.WriteLine($"    Failed: {operation.DocumentsFailed}");
    Console.WriteLine($"    In Progress: {operation.DocumentsInProgress}");
    Console.WriteLine($"    Not started: {operation.DocumentsNotStarted}");

    await foreach(DocumentStatusResult document in operation.Value) {
      Console.WriteLine($"Document with Id: {document.Id}");
      Console.WriteLine($"  Status:{document.Status}");
      if (document.Status == DocumentTranslationStatus.Succeeded) {
        Console.WriteLine($"  Translated Document Uri: {document.TranslatedDocumentUri}");
        Console.WriteLine($"  Translated to language: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
      } else {
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
      }
    }
  }
}

Exécuter votre application

Une fois que vous avez ajouté l’exemple de code à votre application, exécutez votre application à partir du répertoire du projet en tapant la commande suivante dans votre terminal :

  dotnet run

Voici un extrait de la sortie attendue :

Screenshot of the Visual Studio Code output in the terminal window.

Configurer votre environnement C#/.NET

Pour ce guide de démarrage rapide, nous utilisons la dernière version de l’IDE Visual Studio pour générer et exécuter l’application.

Démarrez Visual Studio.
Dans la page Démarrer, choisissez Créer un projet.
Dans la page Créer un nouveau projet, entrez console dans la zone de recherche. Choisissez le modèle Application console, puis choisissez Suivant.
Dans la fenêtre de dialogue Configurer votre nouveau projet, entrez asynchronous-sdk dans la zone Nom de projet. Ensuite, choisissez Suivant.
Dans la fenêtre de dialogue Informations supplémentaires, sélectionnez .NET 6.0 (Actuel), puis sélectionnez Créer.

Installer la bibliothèque de client avec NuGet

Cliquez avec le bouton droit sur votre projet Translator-text-sdk et sélectionnez Gérer les packages NuGet...
Sélectionnez l’onglet Parcourir et tapez Azure.AI.Translation.Document.
Sélectionnez et installez le package dans votre projet.

Générer votre application C#

Notes

À compter de .NET 6, de nouveaux projets utilisant le modèle console génèrent un nouveau style de programme qui diffère des versions précédentes.
La nouvelle sortie utilise des fonctionnalités C# récentes qui simplifient le code que vous devez écrire.
Lorsque vous utilisez la version la plus récente, vous devez uniquement écrire le corps de la Main méthode. Vous n’avez pas besoin d’inclure des instructions de niveau supérieur, des directives globales à l’aide de directives ou des directives implicites.
Pour plus d’informations, consulteznouveaux modèles C# générer des instructions de niveau supérieur.

Ouvrez le fichier Program.cs.
Supprimez le code préexistant, y compris la ligne Console.WriteLine("Hello World!").
Dans Program.cs de l’application, créez des variables pour votre clé et votre point de terminaison personnalisé. Pour plus d’informations, consultezRécupérer votre clé et votre point de terminaison du domaine personnalisé.

private static readonly string endpoint = "<your-document-translation-endpoint>";
private static readonly string key = "<your-key>";

Afin de démarrer une opération de traduction pour un ou plusieurs documents d’un conteneur blob, appelez la méthode StartTranslationAsync.

Pour appeler StartTranslationAsync, vous devez initialiser un objet DocumentTranslationInput qui contient les paramètres sourceUri et targetUri :

Pour Autorisation d’identité managée, créez ces variables :

sourceUri. L’URL du conteneur source contenant les documents à traduire.
targetUri L’URL du conteneur cible dans lequel les documents traduits sont écrits.

targetLanguageCode. Le code de langue pour les documents traduits. Vous pouvez trouver les codes de langue sur notre page Support multilingue.

Source	Cible
1. Cochez la case à côté du conteneur source.	1. Cochez la case à côté du conteneur cible.
2. Dans la fenêtre principale, sélectionnez un fichier ou des documents à traduire.	2. Sélectionnez les points de suspension situés à droite, puis choisissez Propriétés.
3. L’URL source se trouve en haut de la liste Propriétés.	3. L’URL cible se trouve en haut de la liste Propriétés.

Pour Autorisation de signature d’accès partagé (SAP), créez ces variables
- sourceUri. URI SAP, avec un jeton SAP ajouté en tant que chaîne de requête, pour le conteneur source contenant des documents à traduire.
- targetUri URI SAP, avec un jeton SAP ajouté en tant que chaîne de requête, pour le conteneur cible dans lequel les documents traduits sont écrits.
- targetLanguageCode. Le code de langue pour les documents traduits. Vous pouvez trouver les codes de langue sur notre page Support multilingue.

Exemple de code

Important

Entrez l’exemple de code suivant dans le fichier Program.cs de votre application :


using Azure;
using Azure.AI.Translation.Document;

class Program {

  // create variables for your custom endpoint and resource key
  private static readonly string endpoint = "<your-document-translation-endpoint>";
  private static readonly string key = "<your-key>";

  static async Task Main(string[] args) {

    // create variables for your sourceUrl, targetUrl, and targetLanguageCode
    Uri sourceUri = new Uri("<sourceUrl>");
    Uri targetUri = new Uri("<targetUrl>");
    string targetLanguage = "<targetLanguageCode>";

    // initialize a new instance  of the DocumentTranslationClient object to interact with the Document Translation feature
    DocumentTranslationClient client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(key));

    // initialize a new instance of the `DocumentTranslationInput` object to provide source and target locations and target language for the translation operation
    DocumentTranslationInput input = new DocumentTranslationInput(sourceUri, targetUri, targetLanguage);

    // initialize a new instance of the DocumentTranslationOperation class to track the status of the translation operation
    DocumentTranslationOperation operation = await client.StartTranslationAsync(input);

    await operation.WaitForCompletionAsync();

    Console.WriteLine($"  Status: {operation.Status}");
    Console.WriteLine($"  Created on: {operation.CreatedOn}");
    Console.WriteLine($"  Last modified: {operation.LastModified}");
    Console.WriteLine($"  Total documents: {operation.DocumentsTotal}");
    Console.WriteLine($"    Succeeded: {operation.DocumentsSucceeded}");
    Console.WriteLine($"    Failed: {operation.DocumentsFailed}");
    Console.WriteLine($"    In Progress: {operation.DocumentsInProgress}");
    Console.WriteLine($"    Not started: {operation.DocumentsNotStarted}");

    await foreach(DocumentStatusResult document in operation.Value) {
      Console.WriteLine($"Document with Id: {document.Id}");
      Console.WriteLine($"  Status:{document.Status}");
      if (document.Status == DocumentTranslationStatus.Succeeded) {
        Console.WriteLine($"  Translated Document Uri: {document.TranslatedDocumentUri}");
        Console.WriteLine($"  Translated to language: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
      } else {
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
      }
    }
  }
}

Exécuter votre application

Une fois que vous avez ajouté l’exemple de code à votre application, choisissez le bouton de démarrage vert à côté de formRecognizer_quickstart pour générer et exécuter votre programme, ou appuyez sur F5.

Screenshot: run your Visual Studio program.

Voici un extrait de la sortie attendue :

Screenshot of the Visual Studio Code output in the terminal window.

Et voilà ! Vous venez de créer un programme pour traduire des documents dans un conteneur de stockage à l’aide de la bibliothèque de client .NET.

Configuration de votre projet

Vérifiez que la dernière version de Python est installée.

Installer la bibliothèque de client

Installez la dernière version de la bibliothèque de client Traduction de documentation :

pip install azure-ai-translation-document==1.0.0

Traduire un document ou des fichiers par lot

Pour ce projet, vous avez besoin d’un document source chargé dans votre conteneur source. Pour ce guide de démarrage rapide, vous pouvez télécharger notre exemple de document Traduction de documentation. La langue source est l’anglais.
Dans votre fichier d’application Python, créez des variables pour votre clé de ressource et votre point de terminaison personnalisé. Pour plus d’informations, consultezRécupérer votre clé et votre point de terminaison du domaine personnalisé.

key = "<your-key>"
endpoint = "<your-custom-endpoint>"

Initialisez un objet DocumentTranslationClient qui contient vos paramètres endpoint et key.

Appelez la méthode begin_translation et transmettez les paramètres sourceUri, targetUri et targetLanguageCode.

Pour Autorisation d’identité managée, créez ces variables :

sourceUri. L’URL du conteneur source contenant les documents à traduire.
targetUri L’URL du conteneur cible dans lequel les documents traduits sont écrits.

targetLanguageCode. Le code de langue pour les documents traduits. Vous pouvez trouver les codes de langue sur notre page Support multilingue.

Source	Cible
1. Cochez la case à côté du conteneur source.	1. Cochez la case à côté du conteneur cible.
2. Dans la fenêtre principale, sélectionnez un fichier ou des documents à traduire.	2. Sélectionnez les points de suspension situés à droite, puis choisissez Propriétés.
3. L’URL source se trouve en haut de la liste Propriétés.	3. L’URL cible se trouve en haut de la liste Propriétés.

Pour Autorisation de signature d’accès partagé (SAP), créez ces variables
- sourceUri. URI SAP, avec un jeton SAP ajouté en tant que chaîne de requête, pour le conteneur source contenant des documents à traduire.
- targetUri URI SAP, avec un jeton SAP ajouté en tant que chaîne de requête, pour le conteneur cible dans lequel les documents traduits sont écrits.
- targetLanguageCode. Le code de langue pour les documents traduits. Vous pouvez trouver les codes de langue sur notre page Support multilingue.

Exemple de code

Important

Entrez l’exemple de code suivant dans votre application Python :


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

# create variables for your resource key, custom endpoint, sourceUrl, targetUrl, and targetLanguage
key = "<your-key>"
endpoint = "<your-custom-endpoint>"
sourceUri = "<your-container-sourceUrl>"
targetUri = "<your-container-targetUrl>"
targetLanguage = "<target-language-code>"


# initialize a new instance of the DocumentTranslationClient object to interact with the Document Translation feature
client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))

# include source and target locations and target language code for the begin translation operation
poller = client.begin_translation(sourceUri, targetUri, targetLanguage)
result = poller.result()

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

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

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

Exécuter votre application

Une fois que vous avez ajouté l’exemple de code à votre application, tapez la commande suivante dans votre terminal :

python asynchronous-sdk.py

Voici un extrait de la sortie attendue :

Screenshot of the Python output in the terminal window.

Et voilà ! Vous venez de créer un programme pour traduire des documents dans un conteneur de stockage en utilisant la bibliothèque de client Python.

Étape suivante

En savoir plus sur les opérations de traduction de documentation

Bibliothèques de client Traduction de documentation par lots

Prérequis

Autorisation du conteneur de stockage

Générer votre application

Configuration de votre projet

Installer la bibliothèque de client

Traduire un document ou des fichiers par lot

Exemple de code

Exécuter votre application

Configuration de votre projet

Installer la bibliothèque de client

Traduire un document ou des fichiers par lot

Exemple de code

Exécuter votre application

Étape suivante

Ressources supplémentaires