Container: Text übersetzen

Artikel
05/04/2024

Übersetzen Sie Text.

Anfrage-URL

Sendet eine POST-Anforderung an:

POST http://localhost:{port}/translate?api-version=3.0&&from={from}&to={to}

Beispielanforderung

curl -x POST "https:localhost:5000/translate?api-version=3.0&from=en&to=es" -H "Content-Type: application/json" -d "[{
'Text': 'I would really like to drive your car.'}]"

Beispielantwort

[
  {
    "translations": [
      {
        "text": "Realmente me gustaría conducir su coche.",
        "to": "es"
      }
    ]
  }
]

Anforderungsparameter

Die folgenden Anforderungsparameter werden in der Abfragezeichenfolge übergeben:

Erforderliche Parameter

Query parameter (Abfrageparameter)	Beschreibung	Bedingung
api-version	Die vom Client angeforderte Version der API. Der Wert muss `3.0` sein.	Erforderlicher Parameter
Von	Gibt die Sprache des Eingabetexts an.	Erforderlicher Parameter
Bis	Gibt die Sprache des Ausgabetexts an. Verwenden Sie z.B. `to=de` für die Übersetzung ins Deutsche. Durch Wiederholen des Parameters in der Abfragezeichenfolge ist es möglich, in mehrere Sprachen gleichzeitig zu übersetzen. Verwenden Sie z.B. `to=de&to=it` für die Übersetzung ins Deutsche und Italienische.	Erforderlicher Parameter

Sie können den Dienst nach translation unterstützten Sprachen abfragen.
Siehe auchSprachunterstützung für Transliteration.

Optionale Parameter

Query parameter (Abfrageparameter)	BESCHREIBUNG
textType	Optionaler Parameter. Definiert, ob es sich bei dem zu übersetzenden Text um Nur-Text oder um HTML-Text handelt. Jede HTML muss ein wohlgeformtes vollständiges Element sein. Mögliche Werte sind: `plain` (Standard) oder `html`.
includeSentenceLength	Optionaler Parameter. Gibt an, ob Satzgrenzen für den eingegebenen und den übersetzten Text verwendet werden. Mögliche Werte sind: `true` oder `false` (Standard).

Anforderungsheader

Header	Beschreibung	Bedingung
Authentifizierungsheader	Weitere Informationen finden Sie unterden verfügbaren Optionen für die Authentifizierung.	Erforderlicher Anforderungsheader
Inhaltsart	Gibt den Inhaltstyp der Nutzlast an. Der zulässige Wert ist `application/json; charset=UTF-8`.	Erforderlicher Anforderungsheader
Content-Length	Die Länge des Anforderungstexts.	Optional
X-ClientTraceId	Eine vom Client erstellte GUID zur eindeutigen Identifizierung der Anforderung. Sie können diesen Header nur weglassen, wenn Sie die Ablaufverfolgungs-ID in die Abfragezeichenfolge über einen Abfrageparameter namens `ClientTraceId` einschließen.	Optional

Anforderungstext

Der Anforderungstext ist ein JSON-Array. Jedes Arrayelement ist ein JSON-Objekt mit einer Zeichenfolgeneigenschaft namens Text, die die zu suchende Zeichenfolge repräsentiert.

[
    {"Text":"I would really like to drive your car around the block a few times."}
]

Es gelten die folgenden Einschränkungen:

Das Array kann höchstens über 100 Elemente verfügen.
Der gesamte Anforderungstext darf nicht mehr als 10.000 Zeichen enthalten (einschließlich Leerzeichen).

Antworttext

Eine erfolgreiche Antwort ist ein JSON-Array mit einem Ergebnis für jede Zeichenfolge im Eingabearray. Ein Ergebnisobjekt enthält die folgenden Eigenschaften:

translations: Ein Array von Übersetzungsergebnissen. Die Größe des Arrays entspricht der Anzahl der durch den to-Abfrageparameter angegebenen Zielsprachen. Jedes Element im Array enthält:
to: Eine Zeichenfolge, die den Sprachcode der Zielsprache darstellt.
text: Eine Zeichenfolge, die den übersetzten Text enthält.
sentLen: Ein Objekt, das Satzgrenzen in den Eingabe- und Ausgabetexten zurückgibt.
srcSentLen: Ein Integer-Array, das die Länge der Sätze im Eingabetext darstellt. Die Länge des Arrays stellt die Anzahl von Sätzen dar, und die Werte stehen jeweils für die Länge der einzelnen Sätze.
transSentLen:Ein Integer-Array, das die Länge der Sätze im übersetzten Text darstellt. Die Länge des Arrays stellt die Anzahl von Sätzen dar, und die Werte stehen jeweils für die Länge der einzelnen Sätze.

Satzgrenzen sind nur enthalten, wenn der Anforderungsparameter includeSentenceLengthtrue ist.
- sourceText: Ein Objekt mit einer einzelnen Zeichenfolgeneigenschaft namens text, das den Eingabetext im Standardskript der Quellsprache bereitstellt. Die Eigenschaft sourceText ist nur vorhanden, wenn die Eingabe in einem Skript ausgedrückt wird, das nicht das übliche Skript für die Sprache ist. Wenn die Eingabe z.B. ein arabischer Text ist, der im lateinischen Skript verfasst wurde, würde sourceText.text diesen arabischen Text in das arabische Skript konvertieren.

Antwortheader

Header	BESCHREIBUNG
X-RequestId	Vom Dienst generierter Wert, um die Anforderung zu identifizieren und für Problembehandlungszwecke verwendet zu werden.
X-MT-System	Gibt den Systemtyp an, der für jede zur Übersetzung angeforderte Zielsprache für die Übersetzung verwendet wurde. Bei dem Wert handelt es sich um eine durch Trennzeichen getrennte Liste von Zeichenfolgen. Jede Zeichenfolge gibt einen Typ an: ▪ Benutzerdefiniert – Anforderung enthält ein benutzerdefiniertes System und mindestens ein benutzerdefiniertes System wurde während der Übersetzung verwendet. ▪ Team – Alle anderen Anforderungen

Header

BESCHREIBUNG

X-RequestId

Vom Dienst generierter Wert, um die Anforderung zu identifizieren und für Problembehandlungszwecke verwendet zu werden.

X-MT-System

Gibt den Systemtyp an, der für jede zur Übersetzung angeforderte Zielsprache für die Übersetzung verwendet wurde. Bei dem Wert handelt es sich um eine durch Trennzeichen getrennte Liste von Zeichenfolgen. Jede Zeichenfolge gibt einen Typ an:

▪ Benutzerdefiniert – Anforderung enthält ein benutzerdefiniertes System und mindestens ein benutzerdefiniertes System wurde während der Übersetzung verwendet.
▪ Team – Alle anderen Anforderungen

Antwortstatuscodes

Sollte ein Fehler auftreten, gibt die Anforderung eine JSON-Fehlerantwort zurück. Der Fehlercode ist eine 6-stellige Zahl, die aus dem 3-stelligen HTTP-Statuscode gefolgt von einer 3-stelligen Zahl zur Kategorisierung des Fehlers besteht. Häufige Fehlercodes finden Sie in der Referenz zu Version 3 von Translator.

Codebeispiele: Übersetzen von Text

Hinweis

Jedes Beispiel wird für das localhost mit dem docker run Befehl angegebene Beispiel ausgeführt.
Zeigt während der Ausführung localhost des Containers auf den Container selbst.
Sie müssen nicht verwenden localhost:5000. Sie können jeden Port verwenden, der in Ihrer Hostumgebung noch nicht verwendet wird.

Übersetzen einer einzelnen Eingabe

Dieses Beispiel zeigt, wie ein einzelner Satz aus dem Englischen ins Chinesische (vereinfacht) übersetzt wird.

curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

Der Antworttext lautet:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    }
]

Das translations Array enthält ein Element, das die Übersetzung des einzelnen Textausschnitts in der Eingabe bereitstellt.

Azure AI Übersetzer-Endpunkt abfragen (Text)

Hier ist ein Beispiel für eine cURL-HTTP-Anforderung mit localhost:5000, die Sie mit dem docker run Befehl angegeben haben:

  curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-HANS"
    -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

Hinweis

Wenn Sie die cURL POST-Anforderung ausführen, bevor der Container bereit ist, erhalten Sie eine Antwort vom Typ Der Dienst ist vorübergehend nicht verfügbar. Warten Sie, bis der Container bereit ist, und versuchen Sie es dann erneut.

Übersetzen von Text mithilfe der Swagger-API

Englisch ↔ Deutsch

Navigieren Sie zur Seite "Swagger": http://localhost:5000/swagger/index.html
Wählen Sie POST /translate aus.
Klicken Sie auf Try it out (Ausprobieren).
Geben Sie für den From-Parameter den Wert en ein.
Geben Sie für den To-Parameter den Wert de ein.
Geben Sie für den api-version-Parameter den Wert 3.0 ein.
Ersetzen Sie unter texts den folgenden string-Wert durch den unten folgenden JSON-Code:

  [
        {
            "text": "hello, how are you"
        }
  ]

Klicken Sie auf Execute (Ausführen). Die Übersetzungen werden im Response Body (Antworttext) ausgegeben. Daraufhin sollte die folgende Antwort angezeigt werden:

"translations": [
      {
          "text": "hallo, wie geht es dir",
          "to": "de"
      }
    ]

Übersetzen von Text mit Python

Englisch ↔ Französisch

import requests, json

url = 'http://localhost:5000/translate?api-version=3.0&from=en&to=fr'
headers = { 'Content-Type': 'application/json' }
body = [{ 'text': 'Hello, how are you' }]

request = requests.post(url, headers=headers, json=body)
response = request.json()

print(json.dumps(
    response,
    sort_keys=True,
     indent=4,
     ensure_ascii=False,
     separators=(',', ': ')))

Übersetzen von Text mit der C#/.NET-Konsolen-App

Englisch Spanisch ↔

Starten Sie Visual Studio, und erstellen Sie eine neue Konsolenanwendung. Bearbeiten Sie die *.csproj-Datei, um den <LangVersion>7.1</LangVersion>-Knoten hinzuzufügen – hiermit wird C# 7.1 angegeben. Fügen Sie das Newtoonsoft.Json NuGet-Paket, Version 11.0.2, hinzu.

Ersetzen Sie in Program.cs den gesamten vorhandenen Code durch das folgende Skript:

using Newtonsoft.Json;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace TranslateContainer
{
    class Program
    {
        const string ApiHostEndpoint = "http://localhost:5000";
        const string TranslateApi = "/translate?api-version=3.0&from=en&to=es";

        static async Task Main(string[] args)
        {
            var textToTranslate = "Sunny day in Seattle";
            var result = await TranslateTextAsync(textToTranslate);

            Console.WriteLine(result);
            Console.ReadLine();
        }

        static async Task<string> TranslateTextAsync(string textToTranslate)
        {
            var body = new object[] { new { Text = textToTranslate } };
            var requestBody = JsonConvert.SerializeObject(body);

            var client = new HttpClient();
            using (var request =
                new HttpRequestMessage
                {
                    Method = HttpMethod.Post,
                    RequestUri = new Uri($"{ApiHostEndpoint}{TranslateApi}"),
                    Content = new StringContent(requestBody, Encoding.UTF8, "application/json")
                })
            {
                // Send the request and await a response.
                var response = await client.SendAsync(request);

                return await response.Content.ReadAsStringAsync();
            }
        }
    }
}

Übersetzen mehrerer Zeichenfolgen

Um mehrere Strings gleichzeitig zu übersetzen, muss lediglich ein Array von Zeichenfolgen im Anforderungstext angegeben werden.

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}, {'Text':'I am fine, thank you.'}]"

Die Antwort enthält die Übersetzung aller Textteile in exakt derselben Reihenfolge wie in der Anforderung. Der Antworttext lautet:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    },
    {
        "translations":[
            {"text":"我很好，谢谢你。","to":"zh-Hans"}
        ]
    }
]

Übersetzen in mehrere Sprachen

Dieses Beispiel zeigt, wie in einer Anforderung ein- und dieselbe Eingabe in mehrere Sprachen übersetzt wird.

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

Der Antworttext lautet:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"},
            {"text":"Hallo, was ist dein Name?","to":"de"}
        ]
    }
]

Übersetzen von Inhalten mit Markup und Angeben von übersetzten Inhalten

Häufig werden Inhalte mit Markup übersetzt, wie z. B. Inhalte einer HTML-Seite oder eines XML-Dokuments. Beziehen Sie textType=html-Abfrageparameter beim Übersetzen von Inhalten mit Tags ein. Manchmal ist es auch sinnvoll, bestimmten Inhalt von der Übersetzung auszuschließen. Sie können das Attribut class=notranslate verwenden, um Inhalt anzugeben, der in der Originalsprache übernommen werden soll. Im folgenden Beispiel wird der Inhalt im ersten div-Element nicht übersetzt, während der Inhalt im zweiten div-Element übersetzt wird.

<div class="notranslate">This will not be translated.</div>
<div>This will be translated. </div>

Zur Veranschaulichung finden Sie nachfolgend ein Beispiel einer Anforderung.

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans&textType=html" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'<div class=\"notranslate\">This will not be translated.</div><div>This will be translated.</div>'}]"

Die Antwort lautet:

[
    {
        "translations":[
            {"text":"<div class=\"notranslate\">This will not be translated.</div><div>这将被翻译。</div>","to":"zh-Hans"}
        ]
    }
]

Übersetzen mit dynamischem Wörterbuch

Wenn Ihnen die Übersetzung eines Worts oder eines Ausdrucks bereits bekannt ist, können Sie diese als Markup in der Anforderung angeben. Das dynamische Wörterbuch ist nur für Eigennamen wie Personen- und Produktnamen sicher.

Das anzugebende Markup verwendet die folgende Syntax.

<mstrans:dictionary translation="translation of phrase">phrase</mstrans:dictionary>

Betrachten Sie beispielsweise den englischen Satz "Das Wort wordomatic ist ein Wörterbucheintrag". Um das Wort wordomatic in der Übersetzung zu erhalten, senden Sie die Anforderung:

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The word <mstrans:dictionary translation=\"wordomatic\">word or phrase</mstrans:dictionary> is a dictionary entry.'}]"

Es wird folgendes Ergebnis ausgegeben:

[
    {
        "translations":[
            {"text":"Das Wort \"wordomatic\" ist ein Wörterbucheintrag.","to":"de"}
        ]
    }
]

Diese Funktion lässt sich gleichermaßen mit textType=text und ohne textType=html ausführen. Sie sollte in Maßen eingesetzt werden. Für die Anpassung einer Übersetzung ist Custom Translator deutlich besser geeignet. Custom Translator nutzt den Kontext und statistische Wahrscheinlichkeiten in vollem Umfang. Wenn Sie Schulungsdaten erstellt haben, die Ihre Arbeit oder Ihren Ausdruck im Kontext anzeigen, erhalten Sie bessere Ergebnisse. Hier finden Sie weitere Informationen zu Custom Translator.

Anforderungsgrenzwerte

Jede Übersetzungsanforderung ist auf 10.000 Zeichen in allen von Ihnen verwendeten Zielsprachen beschränkt. Beispiel: Das Senden einer Übersetzungsanforderung von 3.000 Zeichen für die Übersetzung in drei verschiedene Sprachen ergibt eine Anforderungsgröße von 3.000 × 3 = 9.000 Zeichen. Dies liegt unterhalb des Anforderungsgrenzwerts. Die Abrechnung erfolgt nach der Anzahl der Zeichen, nicht nach der Anzahl der Anforderungen. Wir empfehlen, kürzere Anforderungen zu senden.

In der folgenden Tabelle sind Arrayelement- und Zeichengrenzwerte für den Übersetzervorgang translation aufgeführt.

Vorgang	Maximale Größe des Arrayelements	Maximale Anzahl von Arrayelementen	Maximale Anforderungsgröße (Zeichen)
translate	10.000	100	10.000

Verwenden von Docker Compose: Übersetzer mit unterstützenden Containern

Docker Compose ist ein Tool, mit dem Sie Anwendungen mit mehreren Containern mithilfe einer einzigen YAML-Datei konfigurieren können, die normalerweise als "YaML" bezeichnet wird compose.yaml. Verwenden Sie den Befehl docker compose up, um Ihre Containeranwendung zu starten, und den Befehl docker compose down, um Ihre Container zu beenden und zu entfernen.

Wenn Sie die Docker Desktop-CLI installiert haben, verfügen Sie bereits über Docker Compose und die erforderlichen Komponenten. Wenn Sie nicht über Docker Desktop verfügen, finden Sie weitere Informationen in der Installationsübersicht für Docker Compose.

In der folgenden Tabelle sind die erforderlichen Hilfscontainer für Ihre Text- und Dokumentübersetzungsvorgänge aufgeführt. Der Übersetzer-Container sendet Abrechnungsinformationen über die Azure KI Übersetzer-Ressource in Ihrem Azure-Konto an Azure.

Vorgang	Anforderungsabfrage	Belegtyp	Hilfscontainer
• Textübersetzung • Dokumentübersetzung	`from` angegeben.	Office-Dokumente	Keine
• Textübersetzung • Dokumentübersetzung	`from` nicht angegeben. Erfordert automatische Spracherkennung zur Bestimmung der Ausgangssprache.	Office-Dokumente	✔️ Container Textanalyse: Sprache
• Textübersetzung • Dokumentübersetzung	`from` angegeben.	Gescannte PDF-Dokumente	✔️ Container Vision: Lesen
• Textübersetzung • Dokumentübersetzung	`from` nicht angegeben. Erfordert automatische Spracherkennung zur Bestimmung der Ausgangssprache.	Gescannte PDF-Dokumente	✔️ Container Textanalyse: Sprache ✔️ Container Vision: Lesen

Containerimages und Tags

Die Containerimages von Azure KI Services finden Sie im Katalog der Microsoft-Artefaktregistrierung. In der folgenden Tabelle ist der vollqualifizierte Imagespeicherort für die Text- und Dokumentübersetzung aufgeführt:

Container	Imagespeicherort	Hinweise
Übersetzer: Textübersetzung	`mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest`	Die vollständige Liste der Versionstags der Textübersetzung von Azure KI Services finden Sie in der Microsoft-Containerregistrierung.
Übersetzer: Dokumentübersetzung	TODO	TODO
Textanalyse: Sprache	`mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest`	Die vollständige Liste der Versionstags der Textanalyse (Sprache) von Azure KI Services finden Sie in der Microsoft-Containerregistrierung.
Vision: Lesen	`mcr.microsoft.com/azure-cognitive-services/vision/read:latest`	Die vollständige Liste der Versionstags des maschinellen Sehens (Lesen, `OCR`) von Azure KI Services finden Sie in der Microsoft-Containerregistrierung.

Erstellen Ihrer Anwendung

Erstellen Sie mit Ihrem bevorzugten Editor oder Ihrer bevorzugten IDE ein neues Verzeichnis für Ihre App, und nennen Sie es container-environment, oder verwenden Sie einen Namen Ihrer Wahl.
Erstellen Sie eine neue YAML-Datei mit dem Namen compose.yaml. Für die Datei compose kann sowohl die Erweiterung „.yml“ als auch die Erweiterung „.yaml“ verwendet werden.
Kopieren Sie das folgende YAML-Codebeispiel, und fügen Sie es in die Datei compose.yaml ein. Ersetzen Sie {TRANSLATOR_KEY} und {TRANSLATOR_ENDPOINT_URI} durch den Schlüssel- bzw. Endpunktwert Ihrer Übersetzer-Instanz aus dem Azure-Portal. Stellen Sie sicher, dass Sie die document translation endpoint.
Der Name der obersten Ebene (azure-ai-translator, azure-ai-language, azure-ai-read) ist der Parameter, den Sie angeben.

container_name ist ein optionaler Parameter, der einen Namen für den Container festlegt, wenn dieser ausgeführt wird, anstatt docker compose einen Namen generieren zu lassen.

services:
  azure-ai-translator:
    container_name: azure-ai-translator
    image: mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation:latest
    environment:
        - EULA=accept
        - billing={TRANSLATOR_ENDPOINT_URI}
        - apiKey={TRANSLATOR_KEY}
        - AzureAiLanguageHost=http://azure-ai-language:5000
        - AzureAiReadHost=http://azure-ai-read:5000
    ports:
          - "5000:5000"
    azure-ai-language:
      container_name: azure-ai-language
      image:  mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest
      environment:
          - EULA=accept
          - billing={TRANSLATOR_ENDPOINT_URI}
          - apiKey={TRANSLATOR_KEY}
    azure-ai-read:
      container_name: azure-ai-read
      image:  mcr.microsoft.com/azure-cognitive-services/vision/read:latest
      environment:
          - EULA=accept
          - billing={TRANSLATOR_ENDPOINT_URI}
          - apiKey={TRANSLATOR_KEY}

Öffnen Sie ein Terminal, navigieren Sie zum Ordner container-environment, und starten Sie die Container mit dem folgenden docker-compose-Befehl:
```
docker compose up
```
Zum Beenden des Containers verwenden Sie den folgenden Befehl:
```
docker compose down
```
Tipp

docker compose Befehle:
- docker compose pause hält ausgeführte Container an.
- docker compose unpause {your-container-name} setzt angehaltene Container fort.
- docker compose restart startet alle beendeten und ausgeführten Container neu, wobei alle vorherigen Änderungen erhalten bleiben. Wenn Sie Änderungen an Ihrer compose.yaml-Konfiguration vornehmen, werden diese Änderungen mit dem Befehl docker compose restart nicht aktualisiert. Sie müssen den Befehl docker compose up verwenden, um Aktualisierungen und Änderungen in der Datei compose.yaml zu übernehmen.
- docker compose ps -a listet alle Container auf (auch beendete Container).
- docker compose exec ermöglicht das Ausführen von Befehlen zum Trennen oder Festlegen von Umgebungsvariablen in einem ausgeführten Container.
Weitere Informationen finden Sie in derDocker CLI-Referenz.

Nächste Schritte

Weitere Informationen zur Textübersetzung