Translator 3.0: Jazyky

Článek
07/03/2024

Získá sadu jazyků, které jsou aktuálně podporovány jinými operacemi služby Translator.

Adresa URL požadavku

Odešlete požadavek GET do:

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

Viz Podpora virtuální sítě pro vybranou službu Translator a konfiguraci a podporu privátního koncového bodu.

Parametry požadavku

Parametry požadavku předané v řetězci dotazu jsou:

Parametry dotazů	Popis
verze-api	Povinný parametr Verze rozhraní API, kterou klient požaduje. Hodnota musí být `3.0`.
rozsah	Volitelný parametr. Čárkami oddělený seznam názvů definujících skupinu jazyků, které se mají vrátit. Povolené názvy skupin: `translation`, `transliteration`a `dictionary`. Pokud není zadaný žádný obor, vrátí se všechny skupiny, což odpovídá předání `scope=translation,transliteration,dictionary`.

Viz text odpovědi.

Hlavičky požadavku jsou:

Hlavičky Popis

Accept-Language Volitelná hlavička požadavku.

Jazyk, který se má použít pro řetězce uživatelského rozhraní. Některá pole v odpovědi jsou názvy jazyků nebo názvů oblastí. Tento parametr použijte k definování jazyka, ve kterém jsou tyto názvy vráceny. Jazyk je určen poskytnutím dobře vytvořené značky jazyka BCP 47. Například hodnotu fr použijte k vyžádání názvů ve francouzštině nebo použijte hodnotu zh-Hant k vyžádání názvů v čínštině Tradiční.
Názvy jsou k dispozici v anglickém jazyce, pokud není zadaný cílový jazyk nebo pokud lokalizace není k dispozici.

X-ClientTraceId Volitelná hlavička požadavku.
Identifikátor GUID vygenerovaný klientem pro jedinečnou identifikaci požadavku.

Hlavičky	Popis
Accept-Language	Volitelná hlavička požadavku. Jazyk, který se má použít pro řetězce uživatelského rozhraní. Některá pole v odpovědi jsou názvy jazyků nebo názvů oblastí. Tento parametr použijte k definování jazyka, ve kterém jsou tyto názvy vráceny. Jazyk je určen poskytnutím dobře vytvořené značky jazyka BCP 47. Například hodnotu `fr` použijte k vyžádání názvů ve francouzštině nebo použijte hodnotu `zh-Hant` k vyžádání názvů v čínštině Tradiční. Názvy jsou k dispozici v anglickém jazyce, pokud není zadaný cílový jazyk nebo pokud lokalizace není k dispozici.
X-ClientTraceId	Volitelná hlavička požadavku. Identifikátor GUID vygenerovaný klientem pro jedinečnou identifikaci požadavku.

K získání jazykových prostředků není vyžadováno ověřování.

Text odpovědi

Klient pomocí parametru scope dotazu definuje, které skupiny jazyků vás zajímají.

scope=translation poskytuje jazyky podporované pro překlad textu z jednoho jazyka do jiného jazyka;
scope=transliteration poskytuje možnosti pro převod textu v jednom jazyce z jednoho skriptu do jiného skriptu;
scope=dictionary poskytuje páry jazyka, pro které Dictionary operace vracejí data.

Klient může současně načíst několik skupin zadáním seznamu názvů oddělených čárkami. Například scope=translation,transliteration,dictionary by se vrátily podporované jazyky pro všechny skupiny.

Úspěšná odpověď je objekt JSON s jednou vlastností pro každou požadovanou skupinu:

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

Hodnota každé vlastnosti je následující.

translation vlastnost

Hodnota translation vlastnosti je slovník párů (klíč, hodnota). Každý klíč je značka jazyka BCP 47. Klíč identifikuje jazyk, ze kterého lze text přeložit nebo z něho přeložit. Hodnota přidružená ke klíči je objekt JSON s vlastnostmi, které popisují jazyk:
- name: Zobrazovaný název jazyka v národním prostředí požadovaném prostřednictvím Accept-Language hlavičky.
- nativeName: Zobrazovaný název jazyka v nativním národním prostředí pro tento jazyk.
- dir: Směrovost, která je rtl určená pro jazyky se zápisem zprava doleva nebo ltr pro jazyky se zápisem zleva doprava.
Příkladem je:
```
{
  "translation": {
    ...
    "fr": {
      "name": "French",
      "nativeName": "Français",
      "dir": "ltr"
    },
    ...
  }
}
```
transliteration vlastnost

Hodnota transliteration vlastnosti je slovník párů (klíč, hodnota). Každý klíč je značka jazyka BCP 47. Klíč identifikuje jazyk, pro který lze text převést z jednoho skriptu do jiného skriptu. Hodnota přidružená ke klíči je objekt JSON s vlastnostmi, které popisují jazyk a jeho podporované skripty:
- name: Zobrazovaný název jazyka v národním prostředí požadovaném prostřednictvím Accept-Language hlavičky.
- nativeName: Zobrazovaný název jazyka v nativním národním prostředí pro tento jazyk.
- scripts: Seznam skriptů, ze které se mají převést. Každý prvek scripts seznamu má vlastnosti:
  - code: Kód identifikující skript.
  - name: Zobrazovaný název skriptu v národním prostředí požadovaném prostřednictvím Accept-Language hlavičky.
  - nativeName: Zobrazovaný název jazyka v nativním národním prostředí pro jazyk.
  - dir: Směrovost, která je rtl určená pro jazyky se zápisem zprava doleva nebo ltr pro jazyky se zápisem zleva doprava.
  - toScripts: Seznam skriptů, na které lze převést text. Každý prvek toScripts seznamu má vlastnosti code, name, nativeNamea dir jak je popsáno výše.
Příkladem je:
```
{
  "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 vlastnost

Hodnota dictionary vlastnosti je slovník párů (klíč, hodnota). Každý klíč je značka jazyka BCP 47. Klíč identifikuje jazyk, pro který jsou k dispozici alternativní překlady a back-translationy. Hodnota je objekt JSON, který popisuje zdrojový jazyk a cílové jazyky s dostupnými překlady:
- name: Zobrazovaný název zdrojového jazyka v národním prostředí požadovaném prostřednictvím Accept-Language hlavičky.
- nativeName: Zobrazovaný název jazyka v nativním národním prostředí pro tento jazyk.
- dir: Směrovost, která je rtl určená pro jazyky se zápisem zprava doleva nebo ltr pro jazyky se zápisem zleva doprava.
- translations: Seznam jazyků s alterativními překlady a příklady pro dotaz vyjádřený ve zdrojovém jazyce. Každý prvek translations seznamu má vlastnosti:
  - name: Zobrazovaný název cílového jazyka v národním prostředí požadovaném prostřednictvím Accept-Language hlavičky.
  - nativeName: Zobrazovaný název cílového jazyka v nativním národním prostředí pro cílový jazyk.
  - dir: Směrovost, která je rtl určená pro jazyky se zápisem zprava doleva nebo ltr pro jazyky se zápisem zleva doprava.
  - code: Kód jazyka identifikující cílový jazyk.
Příkladem je:
```
"es": {
  "name": "Spanish",
  "nativeName": "Español",
  "dir": "ltr",
  "translations": [
    {
      "name": "English",
      "nativeName": "English",
      "dir": "ltr",
      "code": "en"
    }
  ]
},
```

Struktura objektu odpovědi se nezmění bez změny ve verzi rozhraní API. U stejné verze rozhraní API se seznam dostupných jazyků může v průběhu času měnit, protože Microsoft Translator neustále rozšiřuje seznam jazyků podporovaných jeho službami.

Seznam podporovaných jazyků se často nemění. Aby se ušetřila šířka pásma sítě a zlepšila rychlost odezvy, měla by klientská aplikace zvážit ukládání prostředků jazyka do mezipaměti a odpovídající značku entity (ETag). Potom může klientská aplikace pravidelně (například jednou za 24 hodin) dotazovat službu, aby načítá nejnovější sadu podporovaných jazyků. Předání aktuální ETag hodnoty v If-None-Match poli záhlaví umožňuje službě optimalizovat odpověď. Pokud prostředek nebyl změněn, vrátí služba stavový kód 304 a prázdný text odpovědi.

Hlavičky odpovědi

Hlavičky	Popis
ETag	Aktuální hodnota značky entity pro požadované skupiny podporovaných jazyků Aby následné požadavky byly efektivnější, klient může odeslat `ETag` hodnotu v poli hlavičky `If-None-Match` .
X-RequestId	Hodnota vygenerovaná službou pro identifikaci požadavku Používá se pro účely řešení potíží.

Stavové kódy odpovědí

Níže jsou uvedené možné stavové kódy HTTP, které požadavek vrátí.

Kód stavu	Popis
200	Úspěch
304	Prostředek se od verze určené hlavičkami `If-None-Match`požadavku nezměnil.
400	Jeden z parametrů dotazu chybí nebo je neplatný. Před opakováním opravte parametry požadavku.
429	Server odmítl požadavek, protože klient překročil limity požadavků.
500	Došlo k neočekávané chybě. Pokud chyba přetrvává, nahlašte ji s: datem a časem selhání, identifikátorem požadavku z hlavičky `X-RequestId`odpovědi a identifikátorem klienta z hlavičky `X-ClientTraceId`požadavku .
503	Server je dočasně nedostupný. Zkuste požadavek zopakovat. Pokud chyba přetrvává, nahlašte ji s: datem a časem selhání, identifikátorem požadavku z hlavičky `X-RequestId`odpovědi a identifikátorem klienta z hlavičky `X-ClientTraceId`požadavku .

Pokud dojde k chybě, požadavek vrátí také chybovou odpověď JSON. Kód chyby je 6místné číslo, které kombinuje 3místný stavový kód HTTP následovaný 3místným číslem, aby se chyba dále kategorizovala. Běžné kódy chyb najdete na referenční stránce služby Translator v3.

Příklady

Následující příklad ukazuje, jak načíst jazyky podporované pro překlad textu.

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

Sdílet prostřednictvím