Container: Text übersetzen

Ü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

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

Optionale Parameter

Anforderungsheader

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

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

Ü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 Translator-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?'}]"

Übersetzen von Text mithilfe der Swagger-API

Englisch ↔ Deutsch

1. Navigieren Sie zur Seite "Swagger": http://localhost:5000/swagger/index.html
2. Wählen Sie POST /translate aus.
3. Klicken Sie auf Try it out (Ausprobieren).
4. Geben Sie für den From-Parameter den Wert en ein.
5. Geben Sie für den To-Parameter den Wert de ein.
6. Geben Sie für den api-version-Parameter den Wert 3.0 ein.
7. 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 50.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.

Verwenden von Docker Compose: Translator 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.

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:

Erstellen Ihrer Anwendung

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

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

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

4. Der Name der obersten Ebene (azure-ai-translator, azure-ai-language, azure-ai-read) ist der Parameter, den Sie angeben.

5. 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}
   

6. Öffnen Sie ein Terminal, navigieren Sie zum Ordner container-environment, und starten Sie die Container mit dem folgenden docker-compose-Befehl:

   docker compose up
   

7. 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 der Docker CLI-Referenz.

Nächste Schritte