Translator 3.0: Języki

Artykuł
12/05/2022
Czas czytania: 5 min

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

Adres URL żądania

Wyślij żądanie GET do:

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

Parametry żądania

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

Parametr 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 żadnego zakresu, zwracane są wszystkie grupy, co jest równoważne przekazywaniu wartości "scope=translation,transliteration,dictionary". Aby zdecydować, który zestaw obsługiwanych języków jest odpowiedni dla danego scenariusza, zobacz opis obiektu [response](#response-body).

Parametr 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 żadnego zakresu, zwracane są wszystkie grupy, co jest równoważne przekazywaniu wartości "scope=translation,transliteration,dictionary". Aby zdecydować, który zestaw obsługiwanych języków jest odpowiedni dla danego scenariusza, zobacz opis obiektu [response](#response-body).

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 w języku francuskim lub użyć wartości "zh-Hant", aby zażądać nazw w języku chińskim tradycyjnym. Nazwy są podawane 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 generowany 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 w języku francuskim lub użyć wartości "zh-Hant", aby zażądać nazw w języku chińskim tradycyjnym.
Nazwy są podawane 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 generowany 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, które grupy języków są zainteresowane.

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 funkcja zwróci 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 jest słownikiem par (klucz, wartość). Każdy klucz jest tagiem języka BCP 47. Klucz identyfikuje język, z którego tekst można przetłumaczyć lub przetłumaczyć. Wartość skojarzona z kluczem jest obiektem JSON z właściwościami, które opisują 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 jest słownikiem 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, które opisują język i obsługiwane skrypty:
- 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 z. 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 jest słownikiem par (klucz, wartość). Każdy klucz jest tagiem języka BCP 47. Klucz identyfikuje język, dla którego dostępne są alternatywne tłumaczenia i tłumaczenia wsteczne. Wartość to obiekt JSON, który opisuje 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 ze zmieniającymi się tłumaczeniami 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 zmieni 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ż Microsoft Translator stale rozszerza listę języków obsługiwanych przez jej usługi.

Lista obsługiwanych języków nie będzie często zmieniana. 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. Przekazanie bieżącej ETag wartości w polu nagłówka If-None-Match umożliwi usłudze optymalizację odpowiedzi. Jeśli zasób nie został zmodyfikowany, usługa zwróci 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 zwiększyć wydajność kolejnych żądań, klient może wysłać wartość "ETag" 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 ponowieniu próby.
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 "X-RequestId" i identyfikatorem klienta z nagłówka żądania "X-ClientTraceId".
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 "X-RequestId" i identyfikatorem klienta z nagłówka żądania "X-ClientTraceId".

Jeśli wystąpi błąd, żądanie zwróci też odpowiedź JSON dotyczącą błędu. Kod błędu to 6-cyfrowy numer łączący 3-cyfrowy kod stanu HTTP, po którym następuje 3-cyfrowy numer 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"