Partager via

Bien démarrer : Bibliothèques de client Traduction de documentation

  • Article

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 en charge les instances de niveaux S1 ou D3. Nous vous suggérons de sélectionner Standard S1 pour essayer la traduction de documentation. Consultez tarification—des services Azure AI Translator.
  • Les mises en production de préversion publique Traduction de documentation fournissent un accès anticipé aux fonctionnalités en cours de développement actif. Les fonctionnalités, approches et processus peuvent changer, avant la disponibilité générale (GA), en fonction des commentaires des utilisateurs.
  • La préversion publique des bibliothèques de client Traduction de documentation utilisent par défaut la version de l’API REST2024-05-01.

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 plan de service standard S1 Standard (paiement à l’utilisation) ou C2, C3, C4 ou les plans de remise en volume D3.

  • 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, consultez l’article Identités managées pour la traduction de documentation.

Capture d’écran du flux d’identité managée (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 en savoir plus, consultez l’article Créer des jetons SAP.

Capture d’écran d’un URI de ressource avec un jeton SAP.

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 :

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 2.0.0-beta

Traduire des documentations de façon asynchrone

  1. 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.

  2. À 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!").

  3. Dans Program.cs de l’application, créez des variables pour votre clé et votre point de terminaison personnalisé. Pour plus d’informations, consultez la section Ré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>";

  4. 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.

  5. 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 l’URI SAP, avec un jeton SAS ajouté en tant que chaîne de requête, pour le conteneur cible dans lequel les documentations traduites sont écrites.
      • targetLanguageCode. Le code de langue pour les documents traduits. Vous pouvez trouver les codes de langue sur notre page Support multilingue.

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.

Exemple de code de traduction asynchrone

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 :

Capture d’écran de la sortie Visual Studio Code de la fenêtre de terminal.

Exemple de code de traduction synchrone

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.



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

class Program {

  string endpoint = "{your-document-translation-endpoint}";
  string apiKey = "{your-api-key}";
  SingleDocumentTranslationClient client = new SingleDocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(apiKey));

  try
  {
    string filePath = @"C:\{folder}\document.txt"
    using Stream fileStream = File.OpenRead(filePath);

    // MultipartFormFileData (string name, System.IO.Stream content, string contentType);
    var sourceDocument = new MultipartFormFileData(Path.GetFileName(filePath), fileStream, "application/vnd.openxmlformats-officedocument.wordprocessingml.document");

    DocumentTranslateContent content = new DocumentTranslateContent(sourceDocument);

    // DocumentTranslate (string targetLanguage, Azure.AI.Translation.Document.DocumentTranslateContent documentTranslateContent, string sourceLanguage = default, string category = default, bool? allowFallback = default, System.Threading.CancellationToken cancellationToken = default);
    var response = client.DocumentTranslate("de", content);

    Console.WriteLine($"Request string for translation: {requestString}");
    Console.WriteLine($"Response string after translation: {responseString}");
  }
    catch (RequestFailedException exception) {
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
  }
}

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.1.0b1

Traduire des fichiers par lots

  1. 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.

  2. 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, consultez la section Récupérer votre clé et votre point de terminaison du domaine personnalisé.

key = "{your-api-key}"
endpoint = "{your-document-translation-endpoint}"

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

  2. 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.

        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 l’URI SAP, avec un jeton SAS ajouté en tant que chaîne de requête, pour le conteneur cible dans lequel les documentations traduites sont écrites.
      • targetLanguageCode. Le code de langue pour les documents traduits. Vous pouvez trouver les codes de langue sur notre page Support multilingue.

Exemple de code de traduction asynchrone

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 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-api-key}'
endpoint = '{your-document-translation-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 asynchronous 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 :

Capture d’écran de la sortie Python de la fenêtre de terminal.

Exemple de code de traduction synchrone

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.

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import SingleDocumentTranslationClient
from azure.ai.translation.document.models import DocumentTranslateContent


def sample_single_document_translation():

    # create variables for your resource api key, document translation endpoint, and target language
    key = "<your-api-key>"
    endpoint = "<your-document-translation-endpoint>"
    target_language = "{target-language-code}"

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

    # absolute path to your document
    file_path = "C:/{your-file-path}/document-translation-sample.docx"
    file_name = os.path.path.basename(file_path)
    file_type = (
        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    )
    print(f"File for translation: {file_name}")

    with open(file_name, "r") as file:
        file_contents = file.read()

    document_content = (file_name, file_contents, file_type)
    document_translate_content = DocumentTranslateContent(document=document_content)

    response_stream = client.document_translate(
        body=document_translate_content, target_language=target_language
    )
    translated_response = response_stream.decode("utf-8-sig")  # type: ignore[attr-defined]
    print(f"Translated response: {translated_response}")


if __name__ == "__main__":
    sample_single_document_translation()

Et voilà ! Vous venez de créer un programme pour traduire des documents de façon asynchrone et de façon synchrone en utilisant la bibliothèque de client Python.

Étape suivante

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