Clientbibliothek-SDKs für die Dokumentübersetzung

Die Dokumentübersetzung ist ein cloudbasiertes Feature des Azure-Textübersetzungsdiensts. Sie können ganze Dokumente übersetzen oder Batchdokumentübersetzungen in verschiedenen Dateiformaten verarbeiten und dabei die ursprüngliche Dokumentstruktur und das ursprüngliche Format beibehalten. In diesem Artikel erfahren Sie, wie Sie die C#/.NET- und Python-Clientbibliotheken des Dokumentübersetzungsdiensts verwenden. Informationen zur REST-API finden Sie in unserer Schnellstartanleitung.

Voraussetzungen

Zunächst benötigen Sie Folgendes:

  • Ein aktives Azure-Konto. Falls Sie noch kein Konto haben, können Sie ein kostenloses Konto erstellen.

  • Eine Textübersetzungsressource in Form eines einzelnen Diensts (keine Cognitive Services-Ressource mit mehreren Diensten) Wählen Sie die Option Global aus, es sei denn, Ihr Unternehmen oder Ihre Anwendung erfordert eine spezifische Region. Wählen Sie die Preisstufe Standard S1 aus, um zu beginnen (Dokumentübersetzung wird für die kostenlose Stufe nicht unterstützt).

  • Ein Azure Blob Storage-Konto. Für Quell- und Zieldateien müssen Sie in Ihrem Azure-Blobspeicherkonto Container erstellen.

    • Quellcontainer: In diesen Container laden Sie Ihre Dateien für die Übersetzung hoch (erforderlich).
    • Zielcontainer: In diesem Container werden Ihre übersetzten Dateien gespeichert (erforderlich).
  • Außerdem müssen SAS-Token (Shared Access Signature) für Ihre Quell- und Zielcontainer erstellt werden. sourceUrl und targetUrl müssen ein als Abfragezeichenfolge angefügtes SAS-Token (Shared Access Signature) enthalten. Das Token kann Ihrem Container oder bestimmten Blobs zugewiesen sein. SieheErstellen von SAS-Token für die Verarbeitung der Dokumentübersetzung.

    • Ihr Quellcontainer oder Blob muss über Zugriff vom Typ Lesen und Auflisten verfügen.
    • Ihr Zielcontainer oder Blob muss über Zugriff vom Typ Schreiben und Auflisten verfügen.

Weitere Informationen finden Sie unter Erstellen von SAS-Token.

Clientbibliotheken

| Paket (NuGet)| Clientbibliothek | REST-API | Produktdokumentation | Beispiele |

Einrichten des Projekts

Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) den Befehl dotnet new zum Erstellen einer neuen Konsolen-App mit dem Namen batch-document-translation. Dieser Befehl erstellt ein einfaches C#-Projekt vom Typ „Hallo Welt“ mit einer einzelnen Quelldatei: program.cs.

dotnet new console -n batch-document-translation

Wechseln Sie zum Ordner der neu erstellten App. Erstellen Sie Ihre Anwendung mithilfe des folgenden Befehls:

dotnet build

Die Buildausgabe sollte keine Warnungen oder Fehler enthalten.

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

Installieren der Clientbibliothek

Installieren Sie im Anwendungsverzeichnis die Clientbibliothek für die Dokumentübersetzung für .NET mithilfe einer der folgenden Methoden:

.NET CLI

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

NuGet-Paket-Manager

Install-Package Azure.AI.Translation.Document -Version 1.0.0

NuGet PackageReference

<ItemGroup>
    <!-- ... -->
<PackageReference Include="Azure.AI.Translation.Document" Version="1.0.0" />
    <!-- ... -->
</ItemGroup>

Öffnen Sie aus dem Projektverzeichnis die Datei Program.cs in Ihrem bevorzugten Editor oder Ihrer bevorzugten IDE. Fügen Sie die folgenden using-Direktiven hinzu:

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

using System;
using System.Threading;

Erstellen Sie in der Program-Klasse der Anwendung Variablen für Ihren Schlüssel und benutzerdefinierten Endpunkt. Ausführliche Informationen dazu finden Sie unter Custom domain name and key (Benutzerdefinierter Domänenname und Schlüssel).

private static readonly string endpoint = "<your custom endpoint>";
private static readonly string key = "<your key>";

Übersetzen von einzelnen Dokumenten oder Batchdateien

  • Um einen Übersetzungsvorgang für ein einzelnes Dokument oder für mehrere Dokumente in einem einzelnen Blobcontainer zu starten, wird die Methode StartTranslationAsync aufgerufen.

  • Zum Aufrufen von StartTranslationAsync muss ein Objekt vom Typ DocumentTranslationInput initialisiert werden, das die folgenden Parameter enthält:

  • sourceUri: Der SAS-URI für den Quellcontainer mit den zu übersetzenden Dokumenten.

  • targetUri: Der SAS-URI für den Zielcontainer, in den die übersetzten Dokumente geschrieben werden.

  • targetLanguageCode: Der Sprachcode für die übersetzten Dokumente. Sprachcodes finden Sie auf der Seite Sprachunterstützung für Text- und Sprachübersetzung.


public void StartTranslation() {
  Uri sourceUri = new Uri("<sourceUrl>");
  Uri targetUri = new Uri("<targetUrl>");

  DocumentTranslationClient client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(key));

  DocumentTranslationInput input = new DocumentTranslationInput(sourceUri, targetUri, "es")

  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.DocumentId}");
    Console.WriteLine($ "  Status:{document.Status}");
    if (document.Status == TranslationStatus.Succeeded) {
      Console.WriteLine($ "  Translated Document Uri: {document.TranslatedDocumentUri}");
      Console.WriteLine($ "  Translated to language: {document.TranslatedTo}.");
      Console.WriteLine($ "  Document source Uri: {document.SourceDocumentUri}");
    }
    else {
      Console.WriteLine($ "  Error Code: {document.Error.ErrorCode}");
      Console.WriteLine($ "  Message: {document.Error.Message}");
    }
  }
}

Das ist alles! Sie haben mithilfe der .NET-Clientbibliothek ein Programm zum Übersetzen von Dokumenten in einem Speichercontainer erstellt.

Nächster Schritt