Erste Schritte: Clientbibliotheken für die Dokumentübersetzung

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 „Hallo Welt“-C#-Projekt mit einer einzigen 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:

dotnet add package Azure.AI.Translation.Document --version 2.0.0-beta

Asynchrones Übersetzen von Dokumenten

1. Für dieses Projekt benötigen Sie ein Quelldokument, das in Ihren Quellcontainer hochgeladen wurde. Für diesen Schnellstart können Sie unser Beispieldokument für die Dokumentübersetzung herunterladen. Die Quellsprache ist Englisch.

2. Öffnen Sie aus dem Projektverzeichnis die Datei Program.cs in Ihrem bevorzugten Editor oder Ihrer bevorzugten IDE. Löschen Sie den bereits vorhandenen Code, einschließlich der Zeile Console.WriteLine("Hello World!").

3. Erstellen Sie in Program.cs der Anwendung Variablen für Ihren Schlüssel und benutzerdefinierten Endpunkt. Weitere Informationen finden Sie unter Abrufen ihres Schlüssels und des Endpunkts für benutzerdefinierte Domänen.

   private static readonly string endpoint = "<your-document-translation-endpoint>";
   private static readonly string key = "<your-key>";
   

4. Rufen Sie die Methode „StartTranslationAsync“ auf, um einen Übersetzungsvorgang für ein einzelnes Dokument oder für mehrere Dokumente in einem einzelnen Blobcontainer zu starten.

5. Zum Aufrufen von StartTranslationAsync muss ein Objekt vom Typ DocumentTranslationInput initialisiert werden, das die Parameter sourceUri, targetUri und targetLanguageCode enthält:

   • Erstellen Sie für die Autorisierung mit verwalteter Identität die folgenden Variablen:

     • sourceUri: Die URL für den Quellcontainer mit den zu übersetzenden Dokumenten.

     • targetUri: Die URL 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.

       Um Ihre Quell- und Ziel-URLs zu finden, navigieren Sie im Azure-Portal zu Ihrem Speicherkonto. Wählen Sie in der linken Randleiste unter Datenspeicher die Option Container aus, und führen Sie die folgenden Schritte aus, um Ihre Quelldokumente und Zielcontainer-URLS abzurufen.

       Quelle	Ziel
       1. Aktivieren Sie das Kontrollkästchen neben dem Quellcontainer.	1. Aktivieren Sie das Kontrollkästchen neben dem Zielcontainer.
       2. Wählen Sie im Hauptfensterbereich eine Datei oder Dokumente zur Übersetzung aus.	2. Wählen Sie rechts die Auslassungspunkte und dann Eigenschaften aus.
       3. Die Quell-URL befindet sich oben in der Liste „Eigenschaften“.	3. Die Ziel-URL befindet sich oben in der Liste „Eigenschaften“.

   • Erstellen Sie für die SAS-Autorisierung (Shared Access Signature) diese Variablen

     • sourceUri: Der SAS-URI, an den ein SAS-Token als Abfragezeichenfolge angefügt ist, für den Quellcontainer, der zu übersetzende Dokumente enthält.
     • targetUri: Der SAS-URI – an den ein SAS-Token als Abfragezeichenfolge angefügt ist –, 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.

Beispielcode für eine asynchrone Übersetzung

Geben Sie das folgende Codebeispiel in die Datei „Program.cs“ Ihrer Anwendung ein:

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

Ausführen der Anwendung

Nachdem Sie das Codebeispiel zu Ihrer Anwendung hinzugefügt haben, führen Sie Ihre Anwendung aus dem Projektverzeichnis aus, indem Sie den folgenden Befehl in Ihr Terminal eingeben:

  dotnet run

Hier sehen Sie einen Codeausschnitt der erwarteten Ausgabe:

Beispielcode für eine synchrone Übersetzung

Für diesen Schnellstart können Sie unser Beispieldokument für die Dokumentübersetzung herunterladen. Die Quellsprache ist Englisch.

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

Einrichten Ihrer C#/.NET-Umgebung

In diesem Schnellstart nutzen wir die neueste Version der Visual Studio-IDE, um die Anwendung zu erstellen und auszuführen.

1. Starten Sie Visual Studio.

2. Wählen Sie auf der Seite Erste Schritte die Option „Neues Projekt erstellen“ aus.

   

3. Geben Sie auf der Seite Neues Projekt erstellen im Suchfeld den Suchbegriff Konsole ein. Wählen Sie die Vorlage Konsolenanwendung und dann Weiter aus.

   

4. Geben Sie im Dialogfeld Neues Projekt konfigurieren im Feld für den Projektnamen den Namen asynchronous-sdk ein. Klicken Sie dann auf Weiter.

   

5. Wählen Sie im Dialogfenster Zusätzliche Informationen die Option .NET 6.0 (Langzeitunterstützung), und wählen Sie dann Erstellen.

   

Installieren der Clientbibliothek mit NuGet

1. Klicken Sie mit der rechten Maustaste auf Ihr Projekt „Translator-text-sdk“, und wählen Sie Manage NuGet Packages... (NuGet-Pakete verwalten...) aus

2. Wählen Sie die Registerkarte Durchsuchen aus, und geben Sie Azure.AI.Translation.Document ein.

   

3. Wählen Sie das Paket aus, und installieren Sie es in Ihrem Projekt.

   

Erstellen Ihrer C#-Anwendung

1. Öffnen Sie die Datei Program.cs.

2. Löschen Sie den bereits vorhandenen Code, einschließlich der Zeile Console.WriteLine("Hello World!").

3. Erstellen Sie in Program.cs der Anwendung Variablen für Ihren Schlüssel und benutzerdefinierten Endpunkt. Weitere Informationen finden Sie unter Abrufen ihres Schlüssels und des Endpunkts für benutzerdefinierte Domänen.

private static readonly string endpoint = "<your-document-translation-endpoint>";
private static readonly string key = "<your-key>";

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

2. Zum Aufrufen von StartTranslationAsync muss ein Objekt vom Typ DocumentTranslationInput initialisiert werden, das die Parameter sourceUri und targetUri enthält:

   • Erstellen Sie für die Autorisierung mit verwalteter Identität die folgenden Variablen:

     • sourceUri: Die URL für den Quellcontainer mit den zu übersetzenden Dokumenten.

     • targetUri: Die URL 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.

       Um Ihre Quell- und Ziel-URLs zu finden, navigieren Sie im Azure-Portal zu Ihrem Speicherkonto. Wählen Sie in der linken Randleiste unter Datenspeicher die Option Container aus, und führen Sie die folgenden Schritte aus, um Ihre Quelldokumente und Zielcontainer-URLS abzurufen.

       Quelle	Ziel
       1. Aktivieren Sie das Kontrollkästchen neben dem Quellcontainer.	1. Aktivieren Sie das Kontrollkästchen neben dem Zielcontainer.
       2. Wählen Sie im Hauptfensterbereich eine Datei oder Dokumente zur Übersetzung aus.	2. Wählen Sie rechts die Auslassungspunkte und dann Eigenschaften aus.
       3. Die Quell-URL befindet sich oben in der Liste „Eigenschaften“.	3. Die Ziel-URL befindet sich oben in der Liste „Eigenschaften“.

   • Erstellen Sie für die SAS-Autorisierung (Shared Access Signature) diese Variablen

     • sourceUri: Der SAS-URI, an den ein SAS-Token als Abfragezeichenfolge angefügt ist, für den Quellcontainer, der zu übersetzende Dokumente enthält.
     • targetUri: Der SAS-URI – an den ein SAS-Token als Abfragezeichenfolge angefügt ist –, 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.

Beispielcode für eine asynchrone Übersetzung

Geben Sie das folgende Codebeispiel in die Datei „Program.cs“ Ihrer Anwendung ein:

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

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 source and target locations and target language 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}");
      }
    }
  }
}

Ausführen der Anwendung

Nachdem Sie Ihrer Anwendung das Codebeispiel hinzugefügt haben, wählen Sie die grüne Schaltfläche Start neben „formRecognizer_quickstart“ aus, um Ihre Programm zu erstellen und auszuführen, oder drücken Sie F5.

Hier sehen Sie einen Codeausschnitt der erwarteten Ausgabe:

Beispielcode für eine synchrone Übersetzung

Für diesen Schnellstart können Sie unser Beispieldokument für die Dokumentübersetzung herunterladen. Die Quellsprache ist Englisch.

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-translation-sample.docx"
    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}");
  }
}