Azure Document Translation client library per JavaScript - versione 1.0.0

La traduzione documentale è una funzione di traduzione automatica basata su cloud del servizio Traduttore per Azure AI. Puoi tradurre più documenti complessi in tutte le lingue e dialetti supportati preservando la struttura originale del documento e il formato dei dati. L'API Traduzione documenti supporta due processi di traduzione:

La traduzione batch asincrona supporta l'elaborazione di più documenti e file di grandi dimensioni. Il processo di traduzione batch richiede un account di Archiviazione BLOB di Azure con contenitori di archiviazione per i documenti di origine e tradotti.

La traduzione sincrona di file singolo supporta l'elaborazione di traduzioni di file singoli. Il processo di conversione dei file non richiede un account di archiviazione BLOB di Azure. La risposta finale contiene il documento tradotto e viene restituita direttamente al client chiamante.

Le seguenti operazioni sono supportate dalla funzione Traduzione dei Documenti:

  • Traduzione sincrona di documenti: Utilizzata per tradurre sincronamente un singolo documento. Il metodo non richiede un account di archiviazione BLOB di Azure.
  • Avvia la traduzione batch: Utilizzato per eseguire una richiesta di traduzione batch asincrona. Il metodo richiede un account di archiviazione BLOB di Azure con contenitori di archiviazione per i documenti di origine e tradotti.
  • Ottieni lo stato per tutti i lavori di traduzione: Usato per richiedere una lista e lo stato di tutti i lavori di traduzione inviati dall'utente (associati alla risorsa).
  • Ottieni lo status per un lavoro di traduzione specifico: Usato per richiedere lo status di un lavoro di traduzione specifico. La risposta include lo stato complessivo del processo e lo stato dei documenti che vengono tradotti come parte di tale processo.
  • Ottenere lo stato di tutti i documenti: Usato per richiedere lo stato di tutti i documenti in un lavoro di traduzione.
  • Ottieni lo stato di un documento specifico: restituisce lo stato di un documento specifico in un lavoro come indicato nella richiesta dai parametri di query id e documentId.
  • Annulla traduzione: Annulla un lavoro di traduzione attualmente in fase di elaborazione o in coda (in attesa). Un'operazione non viene annullata se è già stata completata, non è riuscita o viene comunque annullata.
  • Ottieni formati supportati: restituisce un elenco di formati di documento o glossario supportati dalla funzione Traduzione del Documento.

Collegamenti chiave:

Come iniziare

Ambienti attualmente supportati

Per altri dettagli, vedere i criteri di supporto .

Prerequisiti

Installare il pacchetto @azure/ai-translation-document

Installa la libreria client Azure Document Translation per JavaScript con npm:

npm install @azure/ai-translation-document

Set up Archiviazione BLOB di Azure account

La traduzione batch richiede un account Archiviazione BLOB di Azure. Per maggiori informazioni sulla creazione di un account Archiviazione BLOB di Azure vedi qui. Per creare contenitori per i file sorgente e target vedi qui. Assicurati di autorizzare l'accesso alla tua memoria delle risorse di traduzione, maggiori informazioni qui.

Quando "Consentire l'accesso alla chiave dell'account di archiviazione" è disabilitato sull'account di archiviazione, l'Identità Gestita è abilitata sulla risorsa del traduttore e le viene assegnato il ruolo "Contributore dati del blob di stoccaggio" sull'account di archiviazione, allora puoi usare direttamente gli URL del container e non sarà necessario generare URI SAS.

Autenticare il client

Questa libreria espone due clienti:

  • DocumentTranslationClient per le operazioni di traduzione batch e stato di traduzione.
  • SingleDocumentTranslationClient per la traduzione sincrona a singolo documento.

Entrambi i client possono autenticarsi con una credenziale Microsoft Entra o una chiave API.

Utilizzo di una credenziale Microsoft Entra

Puoi autenticarti con Microsoft Entra ID usando una credenziale dalla libreria @azure/identity. Per usare il provider DefaultAzureCredential illustrato di seguito o altri provider di credenziali forniti con Azure SDK, installare il pacchetto :

npm install @azure/identity

Dovrai inoltre registrare una nuova applicazione Microsoft Entra e concedere l'accesso alla risorsa Traduttore assegnando un ruolo adatto al tuo responsabile del servizio.

Utilizzando ambienti Node.js e simili a Node, puoi usare la DefaultAzureCredential classe per autenticare il 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());

Per gli ambienti browser, usa il InteractiveBrowserCredential pacchetto from @azure/identity the package per autenticare:

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);

Utilizzo di una chiave API

Puoi anche autenticarti con la chiave API della risorsa usando un 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);

Pacchetto JavaScript

Per usare questa libreria client nel browser, è prima necessario usare un bundler. Per informazioni dettagliate su come eseguire questa operazione, vedere la documentazione di creazione di bundle .

Concetti chiave

DocumentTranslationClient

DocumentTranslationClient è l'interfaccia per la traduzione batch asincrona e per l'interrogazione della traduzione e dello stato dei documenti. La traduzione batch richiede un account Archiviazione BLOB di Azure con contenitori per i tuoi documenti sorgente e tradotti.

SingleDocumentTranslationClient

SingleDocumentTranslationClient è l'interfaccia per la traduzione sincrona di un singolo documento. Non richiede un account Archiviazione BLOB di Azure; il documento tradotto viene restituito direttamente nella risposta.

Examples

La sezione seguente fornisce diversi frammenti di codice che coprono le principali caratteristiche di questa libreria client.

Traduzione sincrona di documenti

Usato per tradurre sincronamente un singolo documento. Il metodo non richiede un account di archiviazione BLOB di 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);
}

Traduzione batch dei documenti

Utilizzato per eseguire una richiesta di traduzione batch asincrona. Il metodo richiede un account di archiviazione BLOB di Azure con contenitori di archiviazione per i documenti di origine e tradotti. Fornire gli URL del container sorgente e target (con token SAS se necessario) e interrogare fino al completamento dell'operazione.

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}`);

Ottieni formati supportati

Restituisce un elenco dei formati di documento supportati dalla funzione Traduzione Documenti.

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);
}

Risoluzione dei problemi

Registrazione

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel nel @azure/logger:

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

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto @azure/logger.

Contribuire

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.

  • Last updated on