Bibliothèque client Azure Document Translation pour JavaScript - version 1.0.0

La traduction de documents est une fonctionnalité de traduction automatique basée sur le cloud du service Azure AI Traducteur. Vous pouvez traduire plusieurs documents complexes dans toutes les langues et dialectes pris en charge tout en préservant la structure originale du document et le format des données. L’API Traduction de documents prend en charge deux processus de traduction :

La traduction par lots asynchrone prend en charge le traitement de plusieurs documents et fichiers volumineux. Le processus de traduction par lots nécessite un compte Stockage Blob Azure avec des conteneurs de stockage pour vos documents sources et traduits.

La traduction synchrone de fichier unique permet le traitement des traductions de fichiers uniques. Le processus de traduction de fichiers ne nécessite pas de compte de stockage Blob Azure. La réponse finale contient le document traduit et est retournée directement au client appelant.

Les opérations suivantes sont prises en charge par la fonctionnalité de traduction de documents :

  • Traduction synchrone de documents : Utilisée pour traduire de manière synchrone un seul document. La méthode ne nécessite pas de compte de stockage d’objets blob Azure.
  • Démarrer la traduction par lots : Utilisé pour exécuter une requête de traduction batch asynchrone. La méthode nécessite un compte de stockage Blob Azure avec des conteneurs de stockage pour vos documents sources et traduits.
  • Obtenir le statut pour tous les emplois de traduction : utilisé pour demander une liste et le statut de tous les travaux de traduction soumis par l’utilisateur (associés à la ressource).
  • Obtenir le statut d’un poste de traduction spécifique : utilisé pour demander le statut d’un poste de traduction spécifique. La réponse inclut l’état global du travail et l’état des documents traduits dans le cadre de ce travail.
  • Obtenir le statut de tous les documents : Utilisé pour demander le statut de tous les documents dans un poste de traduction.
  • Obtenir le statut d’un document spécifique : Retourne le statut d’un document spécifique dans un poste indiqué dans la requête par les paramètres de requête id et documentId.
  • Annuler la traduction : Annule un travail de traduction actuellement en cours de traitement ou en file d’attente (en attente). Une opération n’est pas annulée si elle est déjà terminée, a échoué ou est toujours annulée.
  • Obtenir des formats pris en charge : Retourne une liste de formats de documents ou de glossaires supportés par la fonctionnalité de traduction de documents.

Liens clés :

Premiers pas

Environnements actuellement pris en charge

Pour plus d’informations, consultez notre de stratégie de support .

Prerequisites

Installer le package @azure/ai-translation-document

Installez la bibliothèque client Azure Document Translation pour JavaScript avec npm:

npm install @azure/ai-translation-document

Set up Stockage Blob Azure account

La traduction batch nécessite un compte Stockage Blob Azure. Pour plus d’informations sur la création d’un compte Stockage Blob Azure, consultez ici. Pour créer des conteneurs pour vos fichiers source et cible, voir ici. Assurez-vous d’autoriser votre accès au stockage des ressources de traduction, plus d’informations ici.

Lorsque « Autoriser l’accès à la clé du compte de stockage » est désactivé sur le compte de stockage, que l’identité gérée est activée sur la ressource traductrice, et qu’elle est attribuée au rôle « Contributeur de données de stockage de blob » sur le compte de stockage, vous pouvez alors utiliser directement les URL du conteneur sans qu’aucune URI SAS ne soit nécessaire.

Authentifier le client

Cette bibliothèque expose deux clients :

  • DocumentTranslationClient pour la traduction par lots et les opérations de statut de traduction.
  • SingleDocumentTranslationClient pour la traduction synchrone d’un seul document.

Les deux clients peuvent s’authentifier avec une identifiante Microsoft Entra ou une clé API.

Utilisation d’une certification Microsoft Entra

Vous pouvez vous authentifier avec Microsoft Entra ID en utilisant un identifiant de la bibliothèque @azure/identity. Pour utiliser le fournisseur DefaultAzureCredential indiqué ci-dessous ou d’autres fournisseurs d’informations d’identification fournis avec le Kit de développement logiciel (SDK) Azure, installez le package :

npm install @azure/identity

Vous devrez également enregistrer une nouvelle application Microsoft Entra et accorder l’accès à la ressource Traducteur en attribuant un rôle approprié à votre responsable de service.

En utilisant des environnements Node.js et de type Node, vous pouvez utiliser la DefaultAzureCredential classe pour authentifier le client :

import { DocumentTranslationClient } from "@azure/ai-translation-document";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const client = new DocumentTranslationClient(endpoint, new DefaultAzureCredential());

Pour les environnements de navigateur, utilisez le InteractiveBrowserCredential package from @azure/identity pour authentifier :

import { InteractiveBrowserCredential } from "@azure/identity";
import { DocumentTranslationClient } from "@azure/ai-translation-document";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const client = new DocumentTranslationClient("<endpoint>", credential);

Utilisation d’une clé API

Vous pouvez également authentifier avec la clé API de la ressource en utilisant :KeyCredential

import { KeyCredential } from "@azure/core-auth";
import { DocumentTranslationClient } from "@azure/ai-translation-document";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const credential: KeyCredential = { key: "YOUR_SUBSCRIPTION_KEY" };
const client = new DocumentTranslationClient(endpoint, credential);

Offre groupée JavaScript

Pour utiliser cette bibliothèque cliente dans le navigateur, vous devez d’abord utiliser un bundler. Pour plus d’informations sur la procédure à suivre, reportez-vous à notre documentation de regroupement .

Concepts clés

ClientTraductionDocumentaire

DocumentTranslationClient est l’interface pour la traduction asynchrone par lots ainsi que pour interroger la traduction et le statut des documents. La traduction par lots nécessite un compte Stockage Blob Azure avec des conteneurs pour vos documents sources et traduits.

ClientSingleDocumentTraduction

SingleDocumentTranslationClient est l’interface pour la traduction synchrone d’un seul document. Il ne nécessite pas de compte Stockage Blob Azure ; le document traduit est retourné directement dans la réponse.

Exemples

La section suivante fournit plusieurs extraits de code couvrant les principales fonctionnalités de cette bibliothèque cliente.

Traduction de documentation synchrone

Utilisé pour traduire de manière synchrone un seul document. La méthode ne nécessite pas de compte de stockage d’objets blob Azure.

import { SingleDocumentTranslationClient } from "@azure/ai-translation-document";
import { DefaultAzureCredential } from "@azure/identity";
import { writeFile } from "node:fs/promises";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const client = new SingleDocumentTranslationClient(endpoint, new DefaultAzureCredential());
const response = await client.translate("hi", {
  document: {
    contents: "This is a test.",
    contentType: "text/html",
    filename: "test-input.txt",
  },
});
if (response.readableStreamBody) {
  await writeFile("test-output.txt", response.readableStreamBody);
}

Traduction par lots de documents

Utilisé pour exécuter une requête de traduction batch asynchrone. La méthode nécessite un compte de stockage Blob Azure avec des conteneurs de stockage pour vos documents sources et traduits. Fournir les URL du conteneur source et cible (avec des jetons SAS si nécessaire) et interroger jusqu’à la fin de l’opération.

import { DocumentTranslationClient } from "@azure/ai-translation-document";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const client = new DocumentTranslationClient(endpoint, new DefaultAzureCredential());
const poller = client.startTranslation({
  inputs: [
    {
      source: { sourceUrl: "<source container SAS URL>" },
      targets: [{ targetUrl: "<target container SAS URL>", language: "fr" }],
    },
  ],
});
const result = await poller.pollUntilDone();
console.log(`Translation status: ${result.status}`);

Obtenez des formats pris en charge

Retourne une liste des formats de documents pris en charge par la fonction Traduction de documents.

import { DocumentTranslationClient } from "@azure/ai-translation-document";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const client = new DocumentTranslationClient(endpoint, new DefaultAzureCredential());
const formats = await client.getSupportedFormats("Document");
for (const format of formats.value) {
  console.log(format.format);
}

Résolution des problèmes

Logging

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans la @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, vous pouvez consulter la documentationdu package @azure/enregistreur d’événements.

Contribuer

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

  • Dernière mise à jour :