Freigeben über


Translator 3.0: Languages

Ruft die Sprachen ab, die derzeit von anderen Translator-Vorgängen unterstützt werden.

Anfrage-URL

Sendet eine GET-Anforderung an:

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

Verwenden Sie für virtuelle Netzwerke Ihren benutzerdefinierten Domänenendpunkt:

https://<your-custom-domain>.cognitiveservices.azure.com/languages?api-version=3.0

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

Anforderungsparameter

Die folgenden Anforderungsparameter werden in der Abfragezeichenfolge übergeben:

Abfrageparameter Beschreibung
api-version Erforderlicher Parameter

Die vom Client angeforderte Version der API. Der Wert muss 3.0 sein.
scope Optionaler Parameter.

Eine durch Trennzeichen getrennte Liste von Namen, die die Gruppe der zurückzugebenden Sprachen definieren. Zulässige Gruppennamen sind: translation, transliteration und dictionary. Wenn kein Bereich angegeben wird, werden alle Gruppen zurückgegeben. Dies entspricht dem Übergeben von scope=translation,transliteration,dictionary.

Siehe Antworttext.

Anforderungsheader:

Header BESCHREIBUNG
Accept-Language Optionaler Anforderungsheader.

Die Sprache, die für Zeichenfolgen der Benutzeroberfläche verwendet werden soll. Einige der Felder in der Antwort sind Namen von Sprachen oder Namen von Regionen. Verwenden Sie diesen Parameter, um die Sprache zu definieren, in der diese Namen zurückgegeben werden. Die Sprache wird durch Bereitstellen eines wohlgeformten BCP 47-Sprachtags angegeben. Verwenden Sie z.B. den Wert fr zum Anfordern von Namen in Französisch, oder verwenden Sie den Wert zh-Hant zum Anfordern von Namen in Chinesisch (traditionell).
Namen werden in englischer Sprache bereitgestellt, wenn keine Zielsprache angegeben wird oder keine Lokalisierung verfügbar ist.
X-ClientTraceId Optionaler Anforderungsheader.
Eine vom Client erstellte GUID zur eindeutigen Identifizierung der Anforderung.

Authentifizierung ist nicht erforderlich, um Sprachressourcen abzurufen.

Antworttext

Ein Client verwendet den scope Abfrageparameter, um zu definieren, welche Sprachengruppen aufgelistet werden sollen.

  • scope=translation bietet unterstützte Sprachen, um Text aus einer Sprache in eine andere Sprache zu übersetzen.

  • scope=transliteration bietet Funktionen zum Konvertieren von Text in einer Sprache aus einem Skript in ein anderes Skript.

  • scope=dictionary bietet Sprachpaare, für die Dictionary-Vorgänge Daten zurückgeben.

Ein Client kann mehrere Gruppen gleichzeitig abrufen, indem er eine durch Trennzeichen getrennte Liste von Namen angibt. Beispielsweise würde scope=translation,transliteration,dictionary unterstützte Sprachen für alle Gruppen zurückgeben.

Eine erfolgreiche Antwort ist ein JSON-Objekt mit einer Eigenschaft für jede angeforderte Gruppe:

{
    "translation": {
        //... set of languages supported to translate text (scope=translation)
    },
    "transliteration": {
        //... set of languages supported to convert between scripts (scope=transliteration)
    },
    "dictionary": {
        //... set of languages supported for alternative translations and examples (scope=dictionary)
    }
}

Der Wert für jede Eigenschaft lautet wie folgt.

  • translation-Eigenschaft

    Der Wert der translation-Eigenschaft ist ein Wörterbuch aus Schlüssel-Wert-Paaren. Jeder Schlüssel ist ein BCP 47-Sprachtag. Ein Schlüssel identifiziert eine Sprache, in die oder aus der Text übersetzt werden kann. Der Wert, der dem Schlüssel zugeordnet ist, ist ein JSON-Objekt mit Eigenschaften, die die Sprache beschreiben:

    • name: Der Anzeigename der Sprache im Gebietsschema, der über den Accept-Language-Header angefordert wurde.

    • nativeName: Der Anzeigename der Sprache in dem Gebietsschema, das nativ für diese Sprache ist.

    • dir: Die Direktionalität, also rtl für Sprachen, die von rechts nach links gelesen werden, bzw. ltr für Sprachen, die von links nach rechts gelesen werden.

    Im folgenden Code wird ein Beispiel veranschaulicht:

    {
      "translation": {
        ...
        "fr": {
          "name": "French",
          "nativeName": "Français",
          "dir": "ltr"
        },
        ...
      }
    }
    
  • transliteration-Eigenschaft

    Der Wert der transliteration-Eigenschaft ist ein Wörterbuch aus Schlüssel-Wert-Paaren. Jeder Schlüssel ist ein BCP 47-Sprachtag. Ein Schlüssel identifiziert eine Sprache, für die Text aus einem Skript in ein anderes Skript konvertiert werden kann. Der Wert, der dem Schlüssel zugeordnet ist, ist ein JSON-Objekt mit Eigenschaften, die die Sprache und deren unterstützte Skripts beschreiben:

    • name: Der Anzeigename der Sprache im Gebietsschema, der über den Accept-Language-Header angefordert wurde.

    • nativeName: Der Anzeigename der Sprache in dem Gebietsschema, das nativ für diese Sprache ist.

    • scripts: Die Liste der Skripts, aus denen die Konvertierung erfolgen soll. Jedes Element der scripts-Liste verfügt über Eigenschaften:

      • code: Code, der das Skript identifiziert.

      • name: Der Anzeigename des Skripts im Gebietsschema, der über den Accept-Language-Header angefordert wurde.

      • nativeName: Der Anzeigename der Sprache in dem Gebietsschema, das nativ für die Sprache ist.

      • dir: Die Direktionalität, also rtl für Sprachen, die von rechts nach links gelesen werden, bzw. ltr für Sprachen, die von links nach rechts gelesen werden.

      • toScripts: Die Liste der Skripts, in die Text konvertiert werden kann. Jedes Element der toScripts-Liste verfügt über die Eigenschaften code, name, nativeName und dir (wie zuvor beschrieben).

    Im folgenden Code wird ein Beispiel veranschaulicht:

    {
      "transliteration": {
        ...
        "ja": {
          "name": "Japanese",
          "nativeName": "日本語",
          "scripts": [
            {
              "code": "Jpan",
              "name": "Japanese",
              "nativeName": "日本語",
              "dir": "ltr",
              "toScripts": [
                {
                  "code": "Latn",
                  "name": "Latin",
                  "nativeName": "ラテン語",
                  "dir": "ltr"
                }
              ]
            },
            {
              "code": "Latn",
              "name": "Latin",
              "nativeName": "ラテン語",
              "dir": "ltr",
              "toScripts": [
                {
                  "code": "Jpan",
                  "name": "Japanese",
                  "nativeName": "日本語",
                  "dir": "ltr"
                }
              ]
            }
          ]
        },
        ...
      }
    }
    
  • dictionary-Eigenschaft

    Der Wert der dictionary-Eigenschaft ist ein Wörterbuch aus Schlüssel-Wert-Paaren. Jeder Schlüssel ist ein BCP 47-Sprachtag. Der Schlüssel identifiziert eine Sprache, für die alternative Übersetzungen und Rückübersetzungen verfügbar sind. Der Wert ist ein JSON-Objekt, das die Quellsprache und die Zielsprachen mit verfügbaren Übersetzungen beschreibt:

    • name: Der Anzeigename der Quellsprache im Gebietsschema, der über den Accept-Language-Header angefordert wurde.

    • nativeName: Der Anzeigename der Sprache in dem Gebietsschema, das nativ für diese Sprache ist.

    • dir: Die Direktionalität, also rtl für Sprachen, die von rechts nach links gelesen werden, bzw. ltr für Sprachen, die von links nach rechts gelesen werden.

    • translations: Die Liste der Sprachen mit alternativen Übersetzungen sowie Beispiele für die in der Quellsprache ausgedrückte Abfrage. Jedes Element der translations-Liste verfügt über Eigenschaften:

      • name: Der Anzeigename der Zielsprache im Gebietsschema, der über den Accept-Language-Header angefordert wurde.

      • nativeName: Der Anzeigename der Zielsprache in dem Gebietsschema, das nativ für die Zielsprache ist.

      • dir: Die Direktionalität, also rtl für Sprachen, die von rechts nach links gelesen werden, bzw. ltr für Sprachen, die von links nach rechts gelesen werden.

      • code: Sprachcode, der die Zielsprache identifiziert.

    Im folgenden Code wird ein Beispiel veranschaulicht:

    "es": {
      "name": "Spanish",
      "nativeName": "Español",
      "dir": "ltr",
      "translations": [
        {
          "name": "English",
          "nativeName": "English",
          "dir": "ltr",
          "code": "en"
        }
      ]
    },
    

Die Struktur des Antwortobjekts ändert sich nur, wenn sich die API-Version ändert. Für die gleiche Version der API kann sich die Liste der verfügbaren Sprachen im Laufe der Zeit ändern, da Microsoft Translator die Liste der von seinen Diensten unterstützten Sprachen ständig erweitert.

Die Liste der unterstützten Sprachen ändert sich nicht häufig. Um Netzwerkbandbreite zu sparen und die Reaktionsfähigkeit zu verbessern, sollte eine Clientanwendung die Zwischenspeicherung von Sprachressourcen und des entsprechenden Entitätstags (ETag) in Betracht ziehen. Dann kann die Clientanwendung regelmäßig (z.B. ein Mal alle 24 Stunden) den Dienst abfragen, um die neuesten unterstützten Sprachen abzurufen. Das Übergeben des aktuellen ETag-Werts in einem If-None-Match-Headerfeld ermöglicht es dem Dienst, die Antwort zu optimieren. Wenn die Ressource nicht geändert wird, gibt der Dienst den Statuscode 304 und einen leeren Antworttext zurück.

Antwortheader

Header BESCHREIBUNG
ETag Der aktuelle Wert des Entitätstags für die angeforderten Gruppen unterstützter Sprachen. Um nachfolgende Anforderungen effizienter zu gestalten, kann der Client den ETag-Wert in einem If-None-Match-Headerfeld senden.
X-RequestId Der Wert, der vom Dienst für die Identifizierung der Anforderung generiert wird. Er wird zu Problembehandlungszwecken verwendet.

Antwortstatuscodes

Im Folgenden finden Sie die möglichen HTTP-Statuscodes, die eine Anforderung zurückgeben kann.

Statuscode BESCHREIBUNG
200 Erfolg.
304 Die Ressource wird nicht geändert und an der durch Anforderungsheader If-None-Matchangegebenen Version ausgerichtet.
400 Einer der Abfrageparameter fehlt oder ist ungültig. Korrigieren Sie die Anforderungsparameter, bevor Sie es erneut versuchen.
429 Der Server hat die Anforderung abgelehnt, da der Client die Anforderungsgrenzwerte überschritten hat.
500 Ein unerwarteter Fehler ist aufgetreten. Wenn der Fehler weiterhin besteht, melden Sie ihn, und gebe Sie Folgendes an: Datum und Zeitpunkt des Fehlers, Anforderungsbezeichner aus dem Anforderungsheader X-RequestId und Clientbezeichner aus dem Anforderungsheader X-ClientTraceId.
503 Der Server ist vorübergehend nicht verfügbar. Wiederholen Sie die Anforderung. Wenn der Fehler weiterhin besteht, melden Sie ihn, und gebe Sie Folgendes an: Datum und Zeitpunkt des Fehlers, Anforderungsbezeichner aus dem Anforderungsheader X-RequestId und Clientbezeichner aus dem Anforderungsheader X-ClientTraceId.

Sollte ein Fehler auftreten, gibt die Anforderung auch 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.

Beispiele

Im folgenden Beispiel wird dargestellt, wie Sprachen abgerufen werden, die für die Textübersetzung unterstützt werden.

curl "https://api.cognitive.microsofttranslator.com/languages?api-version=3.0&scope=translation"