Übersetzer 3.0: Übersetzen

Übersetzt Text.

Anfrage-URL

Senden Sie eine POST Anforderung an:

https://api.cognitive.microsofttranslator.com/translate?api-version=3.0

Weitere Informationen finden Sie unter"Virtual Network Support for Translator service selected network and private endpoint configuration and support".

Anforderungsparameter

Anforderungsparameter, die an die Abfragezeichenfolge übergeben werden, sind:

Erforderliche Parameter

Optionale Parameter

Anforderungsheader umfassen:

Anfragekörper

Der Textkörper der Anforderung ist ein JSON-Array. Jedes Arrayelement ist ein JSON-Objekt mit einer Zeichenfolgeneigenschaft namens Text, die die zu übersetzende Zeichenfolge darstellt.

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

Informationen zu Zeichen- und Arraygrenzwerten finden Sie unterAnforderungsgrenzwerte.

Antworttext

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

• detectedLanguage: Ein Objekt, das die erkannte Sprache durch die folgenden Eigenschaften beschreibt:

  • language: Eine Zeichenfolge, die den Code der erkannten Sprache darstellt.

  • score: Ein Float-Wert, der die Konfidenz des Ergebnisses angibt. Die Bewertung liegt zwischen Null und 1 und einem niedrigen Wert, was eine niedrige Konfidenz angibt.

  Die detectedLanguage Eigenschaft ist nur im Ergebnisobjekt vorhanden, wenn die automatische Spracherkennung angefordert wird.

• translations: Ein Array von Übersetzungsergebnissen. Die Größe des Arrays entspricht der Anzahl der im Abfrageparameter angegebenen to Zielsprachen. Jedes Element im Array umfasst Folgendes:

  • to: Eine Zeichenfolge, die den Sprachcode der Zielsprache darstellt.

  • text: Eine Zeichenfolge, die den übersetzten Text angibt.

  • transliteration: Ein Objekt, das den übersetzten Text in dem vom toScript Parameter angegebenen Skript angibt.

    • script: Eine Zeichenfolge, die das Zielskript angibt.

    • text: Eine Zeichenfolge, die den übersetzten Text im Zielskript angibt.

    Das transliteration Objekt ist nicht enthalten, wenn die Transliteration nicht stattfindet.

    • alignment: Ein Objekt mit einer einzelnen Zeichenfolgeneigenschaft mit dem Namen proj, die Eingabetext übersetztem Text zuordnet. Die Ausrichtungsinformationen werden nur bereitgestellt, wenn der Anforderungsparameter includeAlignment ist true. Die Ausrichtung wird als Zeichenfolgenwert des folgenden Formats zurückgegeben: [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]. Der Doppelpunkt trennt den Anfangs- und Endindex, der Gedankenstrich trennt die Sprachen, und Leerzeichen trennen die Wörter. Ein Wort kann mit Null, einem oder mehreren Wörtern in der anderen Sprache ausgerichtet werden, und die ausgerichteten Wörter können nicht zusammenhängend sein. Wenn keine Ausrichtungsinformationen verfügbar sind, ist das Ausrichtungselement leer. Siehe Abrufen von Ausrichtungsinformationen für ein Beispiel und Einschränkungen.

  • sentLen: Ein Objekt, das Satzbegrenzungen in den Eingabe- und Ausgabetexten zurückgibt.

    • srcSentLen: Ein ganzzahliges Array, das die Längen der Sätze im Eingabetext darstellt. Die Länge des Arrays ist die Anzahl der Sätze, und die Werte sind die Länge jedes Satzes.

    • transSentLen: Ein ganzzahliges Array, das die Längen der Sätze im übersetzten Text darstellt. Die Länge des Arrays ist die Anzahl der Sätze, und die Werte sind die Länge jedes Satzes.

    Satzgrenzen werden nur einbezogen, wenn der Anforderungsparameter includeSentenceLength ist true.

• sourceText: Ein Objekt mit einer einzelnen Zeichenfolgeneigenschaft namens text, die den Eingabetext im Standardskript der Quellsprache angibt. sourceText eigenschaft 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 beispielsweise arabisch in lateinischer Schrift geschrieben wurde, wäre derselbe sourceText.text arabische Text, der in arabische Schrift konvertiert wird.

Beispiele für JSON-Antworten finden Sie im Abschnitt "Beispiele ".

Antwortkopfzeilen

Statuscodes für Antworten

Nachfolgend sind die möglichen HTTP-Statuscodes aufgeführt, die von einer Anforderung zurückgegeben werden.

Wenn ein Fehler auftritt, gibt die Anforderung eine JSON-Fehlerantwort zurück. Der Fehlercode ist eine 6-stellige Zahl, die den 3-stelligen HTTP-Statuscode kombiniert, gefolgt von einer 3-stelligen Zahl, um den Fehler weiter zu kategorisieren. Allgemeine Fehlercodes finden Sie auf der v3 Translator-Referenzseite.

Examples

Übersetzen einer einzelnen Eingabe

In diesem Beispiel wird gezeigt, wie ein einzelner Satz aus Englisch in vereinfachtes Chinesisch übersetzt wird.

curl -X POST "https://api.cognitive.microsofttranslator.com/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 Textabschnitts in der Eingabe bereitstellt.

Übersetzen einer einzelnen Eingabe mit automatischer Spracherkennung

In diesem Beispiel wird gezeigt, wie ein einzelner Satz aus Englisch in vereinfachtes Chinesisch übersetzt wird. Die Anforderung gibt die Eingabesprache nicht an. Stattdessen wird die automatische Erkennung der Quellsprache verwendet.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&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:

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

Die Antwort ähnelt der Antwort aus dem vorherigen Beispiel. Da die automatische Spracherkennung angefordert wurde, enthält die Antwort auch Informationen über die sprache, die für den Eingabetext erkannt wurde. Die automatische Spracherkennung funktioniert besser mit längerem Eingabetext.

Übersetzen mit Transliteration

Lassen Sie uns das vorherige Beispiel erweitern, indem wir Transliteration hinzufügen. Die folgende Anforderung fordert eine chinesische Übersetzung, die in lateinischer Schrift geschrieben wurde.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=zh-Hans&toScript=Latn" -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:

[
    {
        "detectedLanguage":{"language":"en","score":1.0},
        "translations":[
            {
                "text":"你好, 你叫什么名字？",
                "transliteration":{"script":"Latn", "text":"nǐ hǎo , nǐ jiào shén me míng zì ？"},
                "to":"zh-Hans"
            }
        ]
    }
]

Das Übersetzungsergebnis enthält nun eine transliteration Eigenschaft, die den übersetzten Text mit lateinischen Zeichen angibt.

Übersetzen mehrerer Textabschnitte

Das Gleichzeitige Übersetzen mehrerer Zeichenfolgen ist einfach eine Frage der Angabe eines Arrays von Zeichenfolgen im Anforderungstext.

curl -X POST "https://api.cognitive.microsofttranslator.com/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 Textabschnitte in der genauen Reihenfolge wie in der Anforderung. Der Antworttext lautet:

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

In mehrere Sprachen übersetzen

In diesem Beispiel wird gezeigt, wie Sie dieselbe Eingabe in mehrere Sprachen in einer Anforderung übersetzen.

curl -X POST "https://api.cognitive.microsofttranslator.com/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"}
        ]
    }
]

Behandeln von Profanität

Normalerweise behält der Übersetzerdienst Profanität bei, die in der Quelle in der Übersetzung vorhanden ist. Der Grad der Profanität und der Kontext, der Wörter profan zwischen kulturen unterscheidet, und folglich kann der Grad der Profanität in der Zielsprache verstärkt oder reduziert werden.

Wenn Sie vermeiden möchten, in der Übersetzung Profanität zu erhalten, unabhängig vom Vorhandensein von Profanität im Quelltext, können Sie die Option zum Filtern von Profanität verwenden. Mit der Option können Sie auswählen, ob Sie Obszönität gelöscht, mit den entsprechenden Tags gekennzeichnet werden sollen (sodass Sie ihre eigene Nachbearbeitung hinzufügen können) oder keine Aktion ausgeführt werden soll. Die akzeptierten ProfanityAction Werte sind Deleted, Markedund NoAction (Standard).

In den obigen Beispielen <ist insert-profane-word> ein Platzhalter für profane Wörter.

Beispiel:

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'This is an <expletive> good idea.'}]"

Diese Anforderung gibt Folgendes zurück:

[
    {
        "translations":[
            {"text":"Das ist eine *** gute Idee.","to":"de"}
        ]
    }
]

Vergleichen mit:

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked&profanityMarker=Tag" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'This is an <expletive> good idea.'}]"

Diese letzte Anforderung gibt Folgendes zurück:

[
    {
        "translations":[
            {"text":"Das ist eine <profanity>verdammt</profanity> gute Idee.","to":"de"}
        ]
    }
]

Übersetzen von Inhalten, die Markup enthalten

Es ist üblich, Inhalte zu übersetzen, die Markup wie z. B. Inhalte von einer HTML-Seite oder Inhalte aus einem XML-Dokument enthalten. Einschließen des Abfrageparameters textType=html beim Übersetzen von Inhalten mit Tags. Darüber hinaus ist es manchmal nützlich, bestimmte Inhalte aus der Übersetzung auszuschließen. Sie können das Attribut class=notranslate verwenden, um Inhalte anzugeben, die in der ursprünglichen Sprache verbleiben sollen. Im folgenden Beispiel wird der Inhalt innerhalb des ersten div Elements 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>

Hier ist eine Beispielanforderung zur Veranschaulichung.

curl -X POST "https://api.cognitive.microsofttranslator.com/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"}
        ]
    }
]

Abrufen von Ausrichtungsinformationen

Die Ausrichtung wird als Zeichenfolgenwert des folgenden Formats für jedes Wort der Quelle zurückgegeben. Die Informationen für jedes Wort werden durch ein Leerzeichen getrennt, einschließlich für nicht leerzeichentrennte Sprachen (Skripts) wie Chinesisch:

[[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]] *

Beispielausrichtungszeichenfolge: "0:0-7:10 1:2-11:20 3:4-0:3 3:4-4:6 5:5-21:21".

Mit anderen Worten, der Doppelpunkt trennt den Anfangs- und Endindex, der Gedankenstrich trennt die Sprachen, und Leerzeichen trennen die Wörter. Ein Wort kann mit Null, einem oder mehreren Wörtern in der anderen Sprache ausgerichtet werden, und die ausgerichteten Wörter können nicht zusammenhängend sein. Wenn keine Ausrichtungsinformationen verfügbar sind, ist das Alignment-Element leer. Die Methode gibt in diesem Fall keinen Fehler zurück.

Geben Sie includeAlignment=true zum Empfangen von Ausrichtungsinformationen die Abfragezeichenfolge an.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeAlignment=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The answer lies in machine translation.'}]"

Die Antwort lautet:

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique.",
                "to":"fr",
                "alignment":{"proj":"0:2-0:1 4:9-3:9 11:14-11:19 16:17-21:24 19:25-40:50 27:37-29:38 38:38-51:51"}
            }
        ]
    }
]

Die Ausrichtungsinformationen beginnen mit 0:2-0:1, was bedeutet, dass die ersten drei Zeichen im Quelltext (The) den ersten beiden Zeichen im übersetzten Text (La) zugeordnet sind.

Einschränkungen

Das Abrufen von Ausrichtungsinformationen ist ein experimentelles Feature, das wir für die Prototypforschung und Erfahrungen mit potenziellen Begriffszuordnungen ermöglicht haben. Hier sind einige der wichtigen Einschränkungen, bei denen Ausrichtungen nicht unterstützt werden:

• Die Ausrichtung ist für Text im HTML-Format nicht verfügbar, d. h. textType=html
• Die Ausrichtung wird nur für eine Teilmenge der Sprachpaare zurückgegeben:
  • Englisch in/aus einer anderen Sprache außer Chinesisch (traditionell), Kantonesisch (traditionell) oder Serbisch (Kyrillisch)
  • von Japanisch nach Koreanisch oder von Koreanisch nach Japanisch
  • von Japanisch bis Chinesisch vereinfacht und Chinesisch vereinfacht auf Japanisch
  • von Chinesisch vereinfacht in Chinesisch (traditionell) und chinesisch (traditionell) bis chinesisch (vereinfacht)
• Sie haben keine Ausrichtung, wenn es sich bei dem Satz um eine canned Translation handelt. Beispiel für eine vertonte Übersetzung ist This is a test, I love youund andere hochfrequente Sätze
• Die Ausrichtung ist nicht verfügbar, wenn Sie einen der Ansätze anwenden, um die Übersetzung wie hier beschrieben zu verhindern.

Abrufen von Satzgrenzen

Wenn Sie Informationen zur Satzlänge im Quelltext und übersetzten Text erhalten möchten, geben Sie includeSentenceLength=true die Abfragezeichenfolge an.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeSentenceLength=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The answer lies in machine translation. The best machine translation technology cannot always provide translations tailored to a site or users like a human. Simply copy and paste a code snippet anywhere.'}]"

Die Antwort lautet:

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique. La meilleure technologie de traduction automatique ne peut pas toujours fournir des traductions adaptées à un site ou des utilisateurs comme un être humain. Il suffit de copier et coller un extrait de code n'importe où.",
                "to":"fr",
                "sentLen":{"srcSentLen":[40,117,46],"transSentLen":[53,157,62]}
            }
        ]
    }
]

Übersetzen mit dynamischem Wörterbuch

Wenn Sie bereits die Übersetzung kennen, die Sie auf ein Wort oder einen Ausdruck anwenden möchten, können Sie sie als Markup innerhalb der Anforderung angeben. Das dynamische Wörterbuch ist nur für richtige Substantive wie Persönliche Namen und Produktnamen sicher. Hinweis: Bei der Funktion "Dynamisches Wörterbuch" wird die Groß-/Kleinschreibung beachtet.

Das zu liefernde Markup verwendet die folgende Syntax.

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

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

curl -X POST "https://api.cognitive.microsofttranslator.com/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\">wordomatic</mstrans:dictionary> is a dictionary entry.'}]"

Das Ergebnis lautet:

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

Dieses Feature für dynamisches Wörterbuch funktioniert auf die gleiche Weise mit textType=text oder mit textType=html. Das Feature sollte sparsam verwendet werden. Die geeignete und weitaus bessere Methode zum Anpassen der Übersetzung ist die Verwendung von Benutzerdefiniertem Übersetzer. Custom Translator verwendet kontextbezogene und statistische Wahrscheinlichkeiten vollständig. Wenn Sie Schulungsdaten erstellen können, die Ihre Arbeit oder Ihren Ausdruck im Kontext anzeigen, erhalten Sie bessere Ergebnisse. Weitere Informationen zum benutzerdefinierten Übersetzer.

Nächste Schritte