Translator 3.0: Languages

Artikel
09/01/2024

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.

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-Match`angegebenen 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"

Freigeben über