Translator 3.0: Jazyky

  • Článek

Získá sadu jazyků aktuálně podporovaných 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

VizVirtual Network Podpora pro konfiguraci a podporu vybrané sítě a privátního koncového bodu služby Translator.

Parametry požadavku

Parametry požadavku předávané řetězci dotazu jsou:

Parametry dotazů Description
verze-api Povinný parametr

Verze rozhraní API požadovaná klientem Hodnota musí být 3.0.
scope Volitelný parametr.

Seznam názvů oddělených čárkami definující skupinu jazyků, které se mají vrátit. Povolené názvy skupin jsou: translation, transliterationa dictionary. Pokud není zadaný žádný obor, vrátí se všechny skupiny, což odpovídá předání scope=translation,transliteration,dictionary.

Viztext odpovědi.

Hlavičky požadavků jsou:

Hlavičky Description
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í. Pomocí tohoto parametru můžete definovat jazyk, ve kterém jsou tyto názvy vráceny. Jazyk je určen poskytnutím značky jazyka BCP 47 ve správném formátu. Můžete například použít hodnotu fr k vyžádání názvů ve francouzštině nebo hodnotu použít zh-Hant k vyžádání názvů v tradiční čínštině.
Názvy se v angličtině zadají, když není zadaný cílový jazyk nebo když není k dispozici lokalizace.
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ů se nevyžaduje ověřování.

Text odpovědi

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

  • scope=translation poskytuje jazyky podporované pro překlad textu z jednoho jazyka do jiného;

  • scope=transliteration poskytuje možnosti pro převod textu v jednom jazyce z jednoho skriptu na jiný;

  • scope=dictionary poskytuje jazykové páry, pro které Dictionary operace vrací data.

Klient může načíst několik skupin současně zadáním seznamu názvů oddělených čárkami. Například scope=translation,transliteration,dictionary by vrátil 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 dvojic (klíč, hodnota). Každý klíč je značka jazyka BCP 47. Klíč označuje jazyk, do kterého lze text přeložit nebo ze kterého lze 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, což je rtl pro jazyky se zápisem zprava doleva nebo ltr pro jazyky zleva doprava.

    Příklad:

    {
  "translation": {
    ...
    "fr": {
      "name": "French",
      "nativeName": "Français",
      "dir": "ltr"
    },
    ...
  }
}

  • transliteration Vlastnost

    Hodnota transliteration vlastnosti je slovník dvojic (klíč, hodnota). Každý klíč je značka jazyka BCP 47. Klíč označuje jazyk, pro který lze text převést z jednoho skriptu na jiný. 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 tento jazyk.

      • dir: Směrovost, což je rtl pro jazyky se zápisem zprava doleva nebo ltr pro jazyky zleva doprava.

      • toScripts: Seznam skriptů dostupných pro převod textu. Každý prvek toScripts seznamu má vlastnosti code, name, nativeNamea dir , jak je popsáno výše.

    Příklad:

    {
  "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 dvojic (klíč, hodnota). Každý klíč je značka jazyka BCP 47. Klíč identifikuje jazyk, pro který jsou k dispozici alternativní a zpětné překlady. 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, což je rtl pro jazyky se zápisem zprava doleva nebo ltr pro jazyky zleva doprava.

    • translations: Seznam jazyků s alterativními překlady a příklady dotazu 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, což je rtl pro jazyky se zápisem zprava doleva nebo ltr pro jazyky zleva doprava.

      • code: Kód jazyka identifikující cílový jazyk.

    Příklad:

    "es": {
  "name": "Spanish",
  "nativeName": "Español",
  "dir": "ltr",
  "translations": [
    {
      "name": "English",
      "nativeName": "English",
      "dir": "ltr",
      "code": "en"
    }
  ]
},

Struktura objektu response se nezmění bez změny verze rozhraní API. Pro stejnou verzi 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). Klientská aplikace pak může pravidelně (například každých 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 hlavičky umožní službě optimalizovat odpověď. Pokud se prostředek nezměnil, vrátí služba stavový kód 304 a prázdný text odpovědi.

Hlavičky odpovědi

Hlavičky Description
Etag Aktuální hodnota značky entity pro požadované skupiny podporovaných jazyků Aby byly následné požadavky efektivnější, klient může odeslat ETag hodnotu v poli hlavičky If-None-Match .
X-RequestId Hodnota vygenerovaná službou k 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 vrací.

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

Pokud dojde k chybě, požadavek vrátí také chybovou odpověď JSON. Kód chyby je 6místné číslo kombinující 3místný stavový kód HTTP následovaný 3místným číslem pro další kategorizaci chyby. 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"