Rozpoznání

Máte kus textu a žádný spolehlivý záznam o tom, v jakém je jazyce – komentář od uživatele, řetězec z nahraného souboru, tělo příchozího ticketu podpory. Než ho můžete směrovat, přeložit nebo vůbec správně vykreslit, potřebujete znát jeho jazyk: jaký jazyk, jaký region, jaké písmo a jakým směrem se čte. Rozpoznání tuto mezeru vyplní jedním voláním. Pošlete text a dostanete zpět strukturovanou identitu jazyka tak konkrétní, jak to text dovolí.

Tato stránka pokrývá celý endpoint – požadavek, odpověď a každé pole, které vrací, jazykové bindingy i to, co se v odpovědi stane, když text neurčuje region nebo písmo. Jde o synchronní volání: pošlete text přes POST, požadavek během analýzy blokuje a odpověď se vrátí ve stejném round-tripu. Autentizace používá sdílenou hlavičku X-API-Key – jak fungují klíče najdete v části Authentication – a každá chyba se řídí standardním modelem chyb.

Požadavek#

POST /process/recognize

Povinné je pouze text. labelLocale určuje jazyk čitelného label v odpovědi – nastavte ho na de a štítek pro francouzský vstup se vrátí v němčině místo v angličtině. Nemění to, co se rozpozná, jen to, jak je výsledek pojmenovaný.

{
  "text": "Bonjour le monde",
  "labelLocale": "en"
}

Odpověď#

{
  "locale": "fr",
  "language": "fr",
  "region": null,
  "script": null,
  "label": "French",
  "direction": "ltr"
}

Za pozorné přečtení tu stojí dvě věci, protože právě díky nim je výsledek opravdu použitelný, ne jen informativní.

Za prvé, každý kód je publikovaný standard, ne vynález Lingo.dev. locale je BCP-47; language je subtag ISO 639; region je ISO 3166; script je ISO 15924. Takže cokoli už používáte k parsování jazyků – svou i18n knihovnu, volání Intl, lookup v CLDR – tento výstup zpracuje přímo. Nepřizpůsobujete se proprietárnímu systému kódů; dostáváte stejné identifikátory, kterými už mluví zbytek vašeho stacku.

Za druhé, region a script jsou nullable záměrně. Vrátí se vyplněné jen tehdy, když je text skutečně prokazuje – což je tématem následujících dvou sekcí a zároveň vlastností, díky které endpoint nehádá.

Region a písmo se vracejí jen tehdy, když je text prokáže#

U každého detektoru jazyka se nabízí obava, že zajde příliš daleko: že textu přiřadí region nebo systém písma, aniž by je text kdy skutečně prokázal, a vy pak stavíte logiku na odhadu. Rozpoznání dělá pravý opak. Subtag vrátí jen tehdy, když pro něj má oporu v datech, a jinak vrátí null.

Když jsou v textu přítomné regionální znaky – například slovní zásoba brazilské portugalštiny – odpověď obsahuje plný tag (pt-BR). Když regionální varianta nejde rozlišit, vrátí se jen jazykový subtag (pt):

{
  "locale": "pt-BR",
  "language": "pt",
  "region": "BR",
  "script": null,
  "label": "Portuguese (Brazil)",
  "direction": "ltr"
}

{
  "locale": "pt",
  "language": "pt",
  "region": null,
  "script": null,
  "label": "Portuguese",
  "direction": "ltr"
}

Stejný jazyk, dvě poctivé odpovědi. První text nesl dost informací na určení regionu; druhý ne, takže region je null a locale se zredukuje na pt. script se řídí stejným pravidlem z opačné strany: je null, když je písmo pro daný jazyk výchozí – například latinka pro francouzštinu – a uvede se jen tehdy, když je právě písmo tím rozlišujícím znakem.

Proto je locale pole, na kterém se vyplatí stavět. Vždy jde o nejkonkrétnější tag, který text podporuje – pt-BR, když pro něj existují důkazy, pt, když ne – takže přečtením locale automaticky získáte správnou úroveň podrobnosti, aniž byste ji museli znovu skládat z jednotlivých částí nebo domýšlet region, který jen vypadal sebejistě, ale ve skutečnosti byl odhadnutý.

direction je tu proto, abyste mohli vykreslovat ještě před překladem#

Rozpoznání jazyka je málokdy konečný cíl – obvykle jazyk rozpoznáváte proto, abyste s textem něco udělali, a první věc, kterou často potřebujete, je ho zobrazit. direction je v odpovědi právě proto: řekne vám, jestli se text čte zleva doprava, nebo zprava doleva, takže můžete nastavit dir="rtl", zvolit layout nebo vybrat písmo ještě před jakýmkoli krokem překladu. Arabský text se vrátí jako "rtl"; výše uvedený francouzský příklad jako "ltr". Nemusíte udržovat vlastní tabulku jazyk–směr – endpoint, který identifikuje jazyk, vám rovnou předá i první údaj potřebný pro vykreslení.

Příklady#

Jeden POST s textem a nepovinným labelLocale. Odpovědí je výše uvedený strukturovaný objekt jazyka.

const response = await fetch(
  "https://api.lingo.dev/process/recognize",
  {
    method: "POST",
    headers: {
      "X-API-Key": "your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Bonjour le monde",
      labelLocale: "en",
    }),
  }
);

const result = await response.json();
// { locale: "fr", language: "fr", label: "French", direction: "ltr", ... }

Další kroky#

Nejčastějším důvodem, proč rozpoznávat jazyk, je něco na jeho základě udělat – nejčastěji ho přeložit. Rozpoznání vám řekne zdrojový jazyk; lokalizační endpointy se postarají o zbytek.