Azure Document Translation Client-Bibliothek für JavaScript - Version 1.0.0

Dokumentenübersetzung ist eine cloudbasierte maschinelle Übersetzungsfunktion des Azure KI Übersetzer-Dienstes. Du kannst mehrere und komplexe Dokumente in allen unterstützten Sprachen und Dialekten übersetzen und dabei die ursprüngliche Dokumentstruktur und das Datenformat erhalten. Die Dokumentübersetzungs-API unterstützt zwei Übersetzungsprozesse:

Die asynchrone Batchübersetzung unterstützt die Verarbeitung mehrerer Dokumente und großer Dateien. Für den Batchübersetzungsprozess ist ein Azure Blob-Speicherkonto mit Speichercontainern für Ihre Quell- und übersetzten Dokumente erforderlich.

Synchrone Einzeldatei-Übersetzung unterstützt die Verarbeitung von Einzeldatei-Übersetzungen. Für den Dateiübersetzungsprozess ist kein Azure Blob Storage-Konto erforderlich. Die endgültige Antwort enthält das übersetzte Dokument und wird direkt an den aufrufenden Client zurückgegeben.

Die folgenden Operationen werden durch die Dokumentenübersetzungsfunktion unterstützt:

  • Synchrone Dokumentenübersetzung: Wird verwendet, um ein einzelnes Dokument synchron zu übersetzen. Für die Methode ist kein Azure Blob-Speicherkonto erforderlich.
  • Start-Batch-Übersetzung: Wird verwendet, um eine asynchrone Batch-Übersetzungsanfrage auszuführen. Die Methode erfordert ein Azure Blob Storage-Konto mit Speichercontainern für Ihre Quell- und übersetzten Dokumente.
  • Status für alle Übersetzungsaufträge erhalten: Wird verwendet, um eine Liste und den Status aller vom Benutzer eingereichten Übersetzungsaufträge (mit der Ressource verbunden) anzufordern.
  • Status für einen bestimmten Übersetzungsauftrag erhalten: Wird verwendet, um den Status eines bestimmten Übersetzungsjobs anzufragen. Die Antwort enthält den Gesamtauftragsstatus und den Status für Dokumente, die als Teil dieses Auftrags übersetzt werden.
  • Status aller Dokumente erhalten: Wird verwendet, um den Status aller Dokumente in einem Übersetzungsjob anzufordern.
  • Status für ein bestimmtes Dokument abrufen: Gibt den Status eines bestimmten Dokuments in einem Job zurück, wie in der Anfrage durch die id- und documentID-Abfrageparameter angegeben.
  • Übersetzung abbrechen: Hebt einen Übersetzungsauftrag ab, der gerade verarbeitet oder in der Warteschlange (ausstehend) ist. Ein Vorgang wird nicht abgebrochen, wenn bereits abgeschlossen, fehlgeschlagen oder noch abgebrochen wird.
  • Unterstützte Formate erhalten: Gibt eine Liste der Dokument- oder Glossarformate zurück, die von der Dokumentenübersetzungsfunktion unterstützt werden.

Wichtige Links:

Erste Schritte

Derzeit unterstützte Umgebungen

Weitere Informationen finden Sie in unserer Supportrichtlinie.

Voraussetzungen

Installieren Sie das @azure/ai-translation-document-Paket

Installiere die Azure Document Translation Client-Bibliothek für JavaScript mitnpm:

npm install @azure/ai-translation-document

Set up Azure Blob Storage account

Batch-Übersetzung erfordert ein Azure Blob Storage-Konto. Weitere Informationen zur Erstellung eines Azure Blob Storage-Kontos finden Sie hier. Um Container für Ihre Quell- und Zieldateien zu erstellen, siehe hier. Stellen Sie sicher, dass Sie den Zugriff auf die Speicherung Ihrer Übersetzungsressourcen autorisieren, weitere Informationen finden Sie hier.

Wenn "Zugriff auf Speicherkontoschlüssel erlauben" auf dem Speicherkonto deaktiviert ist, wird Managed Identity auf der Übersetzerressource aktiviert und erhält die Rolle "Storage Blob Data Contributor" im Speicherkonto, dann können Sie die Container-URLs direkt verwenden und es müssen keine SAS-URIs generiert werden.

Authentifizieren des Clients

Diese Bibliothek stellt zwei Clients frei:

  • DocumentTranslationClient für Batch-Übersetzungen und Übersetzungsstatusoperationen.
  • SingleDocumentTranslationClient für synchrone Übersetzung eines einzelnen Dokuments.

Beide Clients können sich mit einer Microsoft Entra-Credential oder einem API-Schlüssel authentifizieren.

Verwendung eines Microsoft Entra-Zugangs

Sie können sich mit der Microsoft Entra ID authentifizieren, indem Sie eine Zugangsdaten aus der @azure/identity-Bibliothek verwenden. Um den unten gezeigten DefaultAzureCredential Anbieter oder andere Anmeldeinformationsanbieter zu verwenden, die mit dem Azure SDK bereitgestellt werden, installieren Sie bitte das @azure/identity Paket:

npm install @azure/identity

Sie müssen außerdem eine neue Microsoft Entra-Anwendung registrieren und Zugang zur Übersetzer-Ressource gewähren, indem Sie Ihrem Service Principal eine geeignete Rolle zuweisen.

Mit Node.js und knotenähnlichen Umgebungen können Sie die DefaultAzureCredential Klasse nutzen, um den Client zu authentifizieren:

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

Für Browserumgebungen verwenden Sie das InteractiveBrowserCredential from the @azure/identity package zur Authentifizierung:

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

Verwendung eines API-Schlüssels

Sie können sich auch mit dem API-Schlüssel KeyCredentialder Ressource authentifizieren:

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

JavaScript-Bündel

Um diese Clientbibliothek im Browser zu verwenden, müssen Sie zuerst einen Bundler verwenden. Ausführliche Informationen dazu finden Sie in unserer Bündelungsdokumentation.

Zentrale Konzepte

DocumentTranslationClient

DocumentTranslationClient ist die Schnittstelle für asynchrone Batch-Übersetzung sowie für Abfragen von Übersetzung und Dokumentstatus. Batch-Übersetzung erfordert ein Azure Blob Storage-Konto mit Containern für Ihre Quell- und übersetzten Dokumente.

SingleDocumentTranslationClient

SingleDocumentTranslationClient ist die Schnittstelle für synchrone Einzeldokument-Übersetzung. Es erfordert kein Azure Blob Storage-Konto; das übersetzte Dokument wird direkt in der Antwort zurückgegeben.

Examples

Der folgende Abschnitt enthält mehrere Codeschnipsel, die die Hauptmerkmale dieser Client-Bibliothek abdecken.

Synchrone Dokumentübersetzung

Wird verwendet, um ein einzelnes Dokument synchron zu übersetzen. Für die Methode ist kein Azure Blob-Speicherkonto erforderlich.

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

Batch-Dokumentenübersetzung

Wird verwendet, um eine asynchrone Batch-Übersetzungsanfrage auszuführen. Die Methode erfordert ein Azure Blob Storage-Konto mit Speichercontainern für Ihre Quell- und übersetzten Dokumente. Stellen Sie Quell- und Zielcontainer-URLs bereit (bei Bedarf mit SAS-Tokens) und pollen Sie, bis die Operation abgeschlossen ist.

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

Erhalten Sie unterstützte Formate

Gibt eine Liste der von der Dokumentübersetzungsfunktion unterstützten Dokumentformate zurück.

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

Problembehandlung

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in den @azure/Logger-Paketdokumenten.

Contributing

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.

  • Last updated on