Translator 3.0: Języki

Artykuł
09/02/2024

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

Adres URL żądania

Wyślij żądanie GET do:

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

W przypadku sieci wirtualnych użyj niestandardowego punktu końcowego domeny:

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

Aby uzyskać więcej informacji, zobacz Virtual Network Support for Translator service selected network and private endpoint configuration and support (Obsługa sieci wirtualnej dla wybranej sieci translator i konfiguracji prywatnego punktu końcowego).

Parametry żądania

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

Parametry zapytań	opis
api-version	Wymagany parametr Wersja interfejsu API żądana przez klienta. Wartość musi mieć wartość `3.0`.
zakres	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 z przekazywaniem `scope=translation,transliteration,dictionary`elementu .

Zobacz treść 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 BCP tagu języka 47. Na przykład użyj wartości fr , aby zażądać nazw w 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 `BCP` tagu języka 47. Na przykład użyj wartości `fr` , aby zażądać nazw w 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 do wyświetlenia.

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łasność

Wartość translation właściwości to słownik par (klucz, wartość). Każdy klucz jest tagiem BCP języka 47. Klucz określa język, dla którego tekst można przetłumaczyć lub przetłumaczyć. 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łasność

Wartość transliteration właściwości to słownik par (klucz, wartość). Każdy klucz jest tagiem BCP języka 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łasność

Wartość dictionary właściwości to słownik par (klucz, wartość). Każdy klucz jest tagiem BCP języka 47. Klucz określa język, dla którego są dostępne alternatywne tłumaczenia i tłumaczenia wsteczne. Wartość jest obiektem 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 z przetłumaczeniami alteratywnymi 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. Przekazanie 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	Sukces.
304	Zasób nie jest modyfikowany i jest zgodny z wersją określoną 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-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"

Udostępnij za pośrednictwem