Teilen über

Erste Schritte: Clientbibliotheken für die Dokumentübersetzung

  • Artikel

Die Dokumentübersetzung ist ein cloudbasiertes Feature des Azure KI Übersetzer-Diensts, das asynchron vollständige Dokumente in unterstützte Sprachen und verschiedene Dateiformate übersetzt. In diesem Schnellstart erfahren Sie, wie Sie die Dokumentübersetzung mit einer Programmiersprache Ihrer Wahl nutzen, um ein Quelldokument in eine Zielsprache zu übersetzen und dabei Struktur und Textformatierung beizubehalten.

Wichtig

  • Die Dokumentübersetzung wird derzeit nur für die Übersetzer-Ressource (einzelner Dienst) unterstützt und ist nicht in der Azure KI Services-Ressource (mehrere Dienste) enthalten.
  • Die Dokumentübersetzung wird in kostenpflichtigen Tarifen unterstützt. Das Language Studio unterstützt die S1- oder D3-Instanzebenen. Es wird empfohlen, Standard S1 auszuwählen, um die Dokumentübersetzung auszuprobieren. Siehe Preise für Azure KI Services – Translator.
  • Public Preview-Releases der Dokumentübersetzung bieten frühzeitigen Zugriff auf Features, die sich in der aktiven Entwicklung befinden. Features, Ansätze und Prozesse können sich aufgrund von Benutzerfeedback vor der allgemeinen Verfügbarkeit (General Availability, GA) ändern.
  • Die öffentliche Vorschauversion der Clientbibliotheken für die Dokumentübersetzung entspricht standardmäßig der REST-API-Version 2024-05-01.

Voraussetzungen

Zunächst benötigen Sie Folgendes:

Speichercontainerautorisierung

Sie können eine der folgenden Optionen auswählen, um den Zugriff auf Ihre Übersetzerressource zu autorisieren.

✔️ Verwaltete Identität. Eine verwaltete Identität ist ein Dienstprinzipal, der eine Microsoft Entra-Identität und bestimmte Berechtigungen für von Azure verwaltete Ressourcen erstellt. Mit verwalteten Identitäten können Sie Ihre Übersetzeranwendung ausführen, ohne Anmeldeinformationen in Ihren Code einbetten zu müssen. Verwaltete Identitäten sind eine sicherere Möglichkeit, Zugriff auf Speicherdaten zu gewähren, und ersetzen die Anforderung, dass Sie SAS-Token (Shared Access Signature Token) in Ihre Quell- und Ziel-URLs einschließen müssen.

Weitere Informationen finden Sie unter Verwaltete Identitäten für die Dokumentübersetzung.

Screenshot: Flow einer verwalteten Identität (RBAC)

✔️ Shared Access Signature (SAS). Eine Shared Access Signature ist eine URL, die Ihrem Übersetzerdienst für einen bestimmten Zeitraum eingeschränkten Zugriff gewährt. Um diese Methode verwenden zu können, 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.

  • 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.

Screenshot eines Ressourcen-URI mit einem SAS-Token.

Erstellen Ihrer Anwendung

Es stehen mehrere Tools zum Erstellen und Ausführen von Übersetzer C#/.NET-Anwendungen zur Verfügung. Hier erfahren Sie, wie Sie entweder die Befehlszeilenschnittstelle (CLI) oder Visual Studio verwenden. Wählen Sie zunächst eine der folgenden Registerkarten aus:

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.

Wichtig

Denken Sie daran, den Schlüssel aus Ihrem Code zu entfernen, wenn Sie fertig sind, und ihn niemals zu veröffentlichen. Verwenden Sie für die Produktion eine sichere Art der Speicherung und des Zugriffs auf Ihre Anmeldeinformationen wie Azure Key Vault. Weitere Informationen finden Sie unter Azure KI Services-Sicherheit.

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:

Screenshot der Visual Studio Code-Ausgabe im Terminalfenster.

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

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

Einrichten des Projekts

Stellen Sie sicher, dass die neueste Version von Python installiert ist.

Installieren der Clientbibliothek

Installieren Sie die neueste Version der Clientbibliothek für die Dokumentübersetzung:

  pip install azure-ai-translation-document==1.1.0b1

Übersetzen von Batchdateien

  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. Erstellen Sie in Ihrer Python-Anwendungsdatei Variablen für Ihren Ressourcenschlüssel und benutzerdefinierten Endpunkt. Weitere Informationen finden Sie unter Abrufen ihres Schlüssels und des Endpunkts für benutzerdefinierte Domänen.

key = "{your-api-key}"
endpoint = "{your-document-translation-endpoint}"

  1. Initialisieren Sie ein DocumentTranslationClient-Objekt, das die Parameter endpoint und key enthält.

  2. Rufen Sie die begin_translation-Methode auf, und übergeben Sie die Parameter sourceUri, targetUriund targetLanguageCode.

    • 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

Wichtig

Denken Sie daran, den Schlüssel aus Ihrem Code zu entfernen, wenn Sie fertig sind, und ihn niemals zu veröffentlichen. Verwenden Sie für die Produktion eine sichere Art der Speicherung und des Zugriffs auf Ihre Anmeldeinformationen wie Azure Key Vault. Für weitere Informationen lesen Sie Azure KI Services-Sicherheit.

Geben Sie das folgende Codebeispiel in Ihre Python-Anwendung ein:


#  import libraries
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

# create variables for your resource key, custom endpoint, sourceUrl, targetUrl, and targetLanguage
key = '{your-api-key}'
endpoint = '{your-document-translation-endpoint}'
sourceUri = '<your-container-sourceUrl>'
targetUri = '<your-container-targetUrl>'
targetLanguage = '<target-language-code>'


# initialize a new instance of the DocumentTranslationClient object to interact with the asynchronous Document Translation feature
client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))

# include source and target locations and target language code for the begin translation operation
poller = client.begin_translation(sourceUri, targetUri, targetLanguage)
result = poller.result()

print('Status: {}'.format(poller.status()))
print('Created on: {}'.format(poller.details.created_on))
print('Last updated on: {}'.format(poller.details.last_updated_on))
print(
    'Total number of translations on documents: {}'.format(
        poller.details.documents_total_count
    )
)

print('\nOf total documents...')
print('{} failed'.format(poller.details.documents_failed_count))
print('{} succeeded'.format(poller.details.documents_succeeded_count))

for document in result:
    print('Document ID: {}'.format(document.id))
    print('Document status: {}'.format(document.status))
    if document.status == 'Succeeded':
        print('Source document location: {}'.format(document.source_document_url))
        print(
            'Translated document location: {}'.format(document.translated_document_url)
        )
        print('Translated to language: {}\n'.format(document.translated_to))
    else:
        print(
            'Error Code: {}, Message: {}\n'.format(
                document.error.code, document.error.message
            )
        )

Ausführen der Anwendung

Nachdem Sie Ihrer Anwendung das Codebeispiel hinzugefügt haben, geben Sie den folgenden Befehl in Ihr Terminal ein:

python asynchronous-sdk.py

Hier sehen Sie einen Codeausschnitt der erwarteten Ausgabe:

Screenshot der Python-Ausgabe im Terminalfenster.

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.

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import SingleDocumentTranslationClient
from azure.ai.translation.document.models import DocumentTranslateContent


def sample_single_document_translation():

    # create variables for your resource api key, document translation endpoint, and target language
    key = "<your-api-key>"
    endpoint = "<your-document-translation-endpoint>"
    target_language = "{target-language-code}"

    # initialize a new instance of the SingleDocumentTranslationClient object to interact with the synchronous Document Translation feature
    client = SingleDocumentTranslationClient(endpoint, AzureKeyCredential(key))

    # absolute path to your document
    file_path = "C:/{your-file-path}/document-translation-sample.docx"
    file_name = os.path.path.basename(file_path)
    file_type = (
        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    )
    print(f"File for translation: {file_name}")

    with open(file_name, "r") as file:
        file_contents = file.read()

    document_content = (file_name, file_contents, file_type)
    document_translate_content = DocumentTranslateContent(document=document_content)

    response_stream = client.document_translate(
        body=document_translate_content, target_language=target_language
    )
    translated_response = response_stream.decode("utf-8-sig")  # type: ignore[attr-defined]
    print(f"Translated response: {translated_response}")


if __name__ == "__main__":
    sample_single_document_translation()

Das ist alles! Sie haben gerade ein Programm erstellt, um Dokumente mithilfe der Python-Clientbibliothek asynchron und synchron zu übersetzen.

Nächster Schritt

Weitere Informationen zur Dokumentübersetzungsvorgängen