Translator 3.0: Języki

Artykuł
09/22/2023

Pobiera zestaw języków obsługiwanych obecnie przez inne operacje w usłudze Translator.

Adres URL żądania

Wyślij żądanie GET do:

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

ZobaczVirtual Network Obsługa wybranej sieci i prywatnej konfiguracji punktu końcowego w usłudze Translator oraz obsługi.

Parametry żądania

Parametry żądania przekazane w ciągu zapytania to:

Parametry zapytania	Opis
api-version	Wymagany parametr Wersja interfejsu API żądanego przez klienta. Wartość musi mieć wartość `3.0`.
scope	Opcjonalny parametr. Rozdzielona przecinkami lista nazw definiujących grupę języków do zwrócenia. Dozwolone nazwy grup to: `translation`, `transliteration`i `dictionary`. Jeśli nie podano zakresu, zwracane są wszystkie grupy, co jest równoważne z przekazywaniem `scope=translation,transliteration,dictionary`.

Zobacztreść odpowiedzi.

Nagłówki żądań to:

Nagłówki Opis

Accept-Language Opcjonalny nagłówek żądania.

Język ciągów interfejsu użytkownika. Niektóre pola w odpowiedzi to nazwy języków lub nazw regionów. Użyj tego parametru, aby zdefiniować język, w którym są zwracane te nazwy. Język jest określony przez podanie dobrze sformułowanego tagu języka BCP 47. Na przykład użyj wartości fr , aby zażądać nazw we języku francuskim lub użyć wartości zh-Hant do żądania nazw w języku chińskim tradycyjnym.
Nazwy są udostępniane w języku angielskim, gdy język docelowy nie jest określony lub gdy lokalizacja jest niedostępna.

X-ClientTraceId Opcjonalny nagłówek żądania.
Identyfikator GUID wygenerowany przez klienta w celu unikatowego zidentyfikowania żądania.

Nagłówki	Opis
Accept-Language	Opcjonalny nagłówek żądania. Język ciągów interfejsu użytkownika. Niektóre pola w odpowiedzi to nazwy języków lub nazw regionów. Użyj tego parametru, aby zdefiniować język, w którym są zwracane te nazwy. Język jest określony przez podanie dobrze sformułowanego tagu języka BCP 47. Na przykład użyj wartości `fr` , aby zażądać nazw we języku francuskim lub użyć wartości `zh-Hant` do żądania nazw w języku chińskim tradycyjnym. Nazwy są udostępniane w języku angielskim, gdy język docelowy nie jest określony lub gdy lokalizacja jest niedostępna.
X-ClientTraceId	Opcjonalny nagłówek żądania. Identyfikator GUID wygenerowany przez klienta w celu unikatowego zidentyfikowania żądania.

Uwierzytelnianie nie jest wymagane do pobrania zasobów językowych.

Treść odpowiedzi

Klient używa parametru scope zapytania do zdefiniowania grup języków, których interesuje.

scope=translation udostępnia języki obsługiwane do tłumaczenia tekstu z jednego języka na inny język;
scope=transliteration Zapewnia możliwości konwertowania tekstu w jednym języku z jednego skryptu na inny skrypt;
scope=dictionary Udostępnia pary językowe, dla których Dictionary operacje zwracają dane.

Klient może pobrać kilka grup jednocześnie, określając rozdzieloną przecinkami listę nazw. Na przykład scope=translation,transliteration,dictionary zwraca obsługiwane języki dla wszystkich grup.

Pomyślna odpowiedź to obiekt JSON z jedną właściwością dla każdej żądanej grupy:

{
    "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)
    }
}

Wartość każdej właściwości jest następująca.

translation Właściwość

Wartość translation właściwości to słownik par (klucz, wartość). Każdy klucz jest tagiem języka BCP 47. Klucz identyfikuje język, z którego można przetłumaczyć lub przetłumaczyć tekst. Wartość skojarzona z kluczem jest obiektem JSON z właściwościami opisujących język:
- name: nazwa wyświetlana języka w ustawieniach regionalnych żądanych za pośrednictwem Accept-Language nagłówka.
- nativeName: nazwa wyświetlana języka w ustawieniach regionalnych natywnych dla tego języka.
- dir: Kierunek, który jest rtl przeznaczony dla języków od prawej do lewej lub ltr dla języków od lewej do prawej.
Przykład:
```
{
  "translation": {
    ...
    "fr": {
      "name": "French",
      "nativeName": "Français",
      "dir": "ltr"
    },
    ...
  }
}
```
transliteration Właściwość

Wartość transliteration właściwości to słownik par (klucz, wartość). Każdy klucz jest tagiem języka BCP 47. Klucz identyfikuje język, dla którego tekst można przekonwertować z jednego skryptu na inny skrypt. Wartość skojarzona z kluczem jest obiektem JSON z właściwościami opisanymi językiem i obsługiwanymi skryptami:
- name: nazwa wyświetlana języka w ustawieniach regionalnych żądanych za pośrednictwem Accept-Language nagłówka.
- nativeName: nazwa wyświetlana języka w ustawieniach regionalnych natywnych dla tego języka.
- scripts: Lista skryptów do konwersji. Każdy element scripts listy ma właściwości:
  - code: kod identyfikujący skrypt.
  - name: nazwa wyświetlana skryptu w ustawieniach regionalnych żądanych za pośrednictwem Accept-Language nagłówka.
  - nativeName: nazwa wyświetlana języka w ustawieniach regionalnych natywnych dla języka.
  - dir: Kierunek, który jest rtl przeznaczony dla języków od prawej do lewej lub ltr dla języków od lewej do prawej.
  - toScripts: Lista skryptów dostępnych do konwersji tekstu na. Każdy element toScripts listy ma właściwości code, name, nativeNamei dir zgodnie z wcześniejszym opisem.
Przykład:
```
{
  "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 Właściwość

Wartość dictionary właściwości to słownik par (klucz, wartość). Każdy klucz jest tagiem języka BCP 47. Klucz identyfikuje język, dla którego są dostępne alternatywne tłumaczenia i tłumaczenia wsteczne. Wartość to obiekt JSON opisujący język źródłowy i języki docelowe z dostępnymi tłumaczeniami:
- name: nazwa wyświetlana języka źródłowego w ustawieniach regionalnych żądanych za pośrednictwem Accept-Language nagłówka.
- nativeName: nazwa wyświetlana języka w ustawieniach regionalnych natywnych dla tego języka.
- dir: Kierunek, który jest rtl przeznaczony dla języków od prawej do lewej lub ltr dla języków od lewej do prawej.
- translations: Lista języków z translacjami zmianowymi i przykładami dla zapytania wyrażonego w języku źródłowym. Każdy element translations listy ma właściwości:
  - name: nazwa wyświetlana języka docelowego w ustawieniach regionalnych żądanych za pośrednictwem Accept-Language nagłówka.
  - nativeName: nazwa wyświetlana języka docelowego w ustawieniach regionalnych natywnych dla języka docelowego.
  - dir: Kierunek, który jest rtl przeznaczony dla języków od prawej do lewej lub ltr dla języków od lewej do prawej.
  - code: kod języka identyfikujący język docelowy.
Przykład:
```
"es": {
  "name": "Spanish",
  "nativeName": "Español",
  "dir": "ltr",
  "translations": [
    {
      "name": "English",
      "nativeName": "English",
      "dir": "ltr",
      "code": "en"
    }
  ]
},
```

Struktura obiektu odpowiedzi nie zmienia się bez zmiany wersji interfejsu API. W przypadku tej samej wersji interfejsu API lista dostępnych języków może ulec zmianie w czasie, ponieważ usługa Microsoft Translator stale rozszerza listę języków obsługiwanych przez jej usługi.

Lista obsługiwanych języków nie zmienia się często. Aby zaoszczędzić przepustowość sieci i poprawić czas odpowiedzi, aplikacja kliencka powinna rozważyć buforowanie zasobów języka i odpowiedniego tagu jednostki (ETag). Następnie aplikacja kliencka może okresowo (na przykład raz co 24 godziny) wysyłać zapytanie do usługi, aby pobrać najnowszy zestaw obsługiwanych języków. Przekazywanie bieżącej ETag wartości w polu nagłówka If-None-Match umożliwia usłudze optymalizację odpowiedzi. Jeśli zasób nie został zmodyfikowany, usługa zwraca kod stanu 304 i pustą treść odpowiedzi.

Nagłówki odpowiedzi

Nagłówki	Opis
Etag	Bieżąca wartość tagu jednostki dla żądanych grup obsługiwanych języków. Aby kolejne żądania bardziej wydajne, klient może wysłać `ETag` wartość w polu nagłówka `If-None-Match` .
X-RequestId	Wartość wygenerowana przez usługę w celu zidentyfikowania żądania. Służy do rozwiązywania problemów.

Kody stanu odpowiedzi

Poniżej przedstawiono możliwe kody stanu HTTP zwracane przez żądanie.

Kod stanu	Opis
200	Powodzenie.
304	Zasób nie został zmodyfikowany od wersji określonej przez nagłówki żądań `If-None-Match`.
400	Brakuje jednego z parametrów zapytania lub jest on nieprawidłowy. Popraw parametry żądania przed ponowną próbą.
429	Serwer odrzucił żądanie, ponieważ klient przekroczył limity żądań.
500	Wystąpił nieoczekiwany błąd. Jeśli błąd będzie się powtarzać, zgłoś go z: datą i godziną niepowodzenia, identyfikatorem żądania z nagłówka odpowiedzi i identyfikatorem klienta z nagłówka `X-RequestIdX-ClientTraceId`żądania .
503	Serwer jest tymczasowo niedostępny. Ponów próbę żądania. Jeśli błąd będzie się powtarzać, zgłoś go z: datą i godziną niepowodzenia, identyfikatorem żądania z nagłówka odpowiedzi i identyfikatorem klienta z nagłówka `X-RequestIdX-ClientTraceId`żądania .

Jeśli wystąpi błąd, żądanie zwróci również odpowiedź o błędzie JSON. Kod błędu to 6-cyfrowy numer łączący 3-cyfrowy kod stanu HTTP, po którym następuje 3-cyfrowa liczba w celu dalszego kategoryzowania błędu. Typowe kody błędów można znaleźć na stronie dokumentacji usługi Translator w wersji 3.

Przykłady

W poniższym przykładzie pokazano, jak pobrać języki obsługiwane na potrzeby tłumaczenia tekstu.

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