Распознавание

У вас есть фрагмент текста, но нет надёжной информации о том, на каком он языке: комментарий от пользователя, строка из загруженного файла, текст входящего обращения в поддержку. Прежде чем направить его дальше, перевести или хотя бы корректно отобразить, нужно определить его локаль: язык, регион, письменность и направление письма. Recognize закрывает этот пробел одним вызовом. Вы отправляете текст и получаете структурированное описание локали — настолько конкретное, насколько это позволяет сам текст.

На этой странице разобран endpoint целиком: запрос, ответ и каждое поле, языковые SDK и то, как ответ ведёт себя, когда текст не позволяет однозначно определить регион или письменность. Это синхронный вызов: вы отправляете текст через POST, запрос ждёт, пока сервис проанализирует текст, и ответ приходит в рамках того же round-trip. Аутентификация выполняется через общий заголовок X-API-Key — как работают ключи, см. в разделе Authentication — а любые ошибки следуют стандартной модели ошибок.

Запрос#

POST /process/recognize

Обязателен только text. Параметр labelLocale управляет языком человекочитаемого label в ответе: установите его в de, и метка для французского текста вернётся на немецком, а не на английском. На само распознавание это не влияет — меняется только то, как результат будет назван в ответе.

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

Ответ#

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

В этой структуре есть два момента, на которые стоит обратить особое внимание: именно они делают результат не просто информативным, а по-настоящему пригодным в работе.

Во-первых, каждый код здесь — это опубликованный стандарт, а не внутреннее изобретение Lingo.dev. locale — это BCP-47; language — подтег ISO 639; region — ISO 3166; script — ISO 15924. Поэтому всё, что вы уже используете для разбора локалей — библиотека i18n, вызов Intl, lookup в CLDR — принимает этот результат напрямую. Вам не нужно подстраиваться под проприетарную систему кодов: вы получаете те же идентификаторы, на которых уже работает остальная часть вашего стека.

Во-вторых, поля region и script допускают null намеренно. Они заполняются только тогда, когда текст действительно даёт для этого основания — об этом следующие два раздела. Именно благодаря этому endpoint не строит догадок.

Регион и письменность возвращаются только тогда, когда это видно из текста#

Главная опасность любого детектора языка в том, что он может зайти слишком далеко: приписать тексту регион или систему письма, которых тот никак не подтверждает, а вы потом построите логику на догадке. Recognize работает наоборот. Он возвращает подтег только тогда, когда это подтверждается самим текстом, и возвращает null, когда оснований недостаточно.

Если в тексте есть региональные маркеры — например, лексика бразильского португальского, — ответ включает полный тег (pt-BR). Если региональный вариант неразличим, возвращается только языковой подтег (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"
}

Один и тот же язык, два честных ответа. В первом тексте было достаточно информации, чтобы указать регион; во втором — нет, поэтому region равно null, а locale сводится к pt. С полем script действует то же правило, только с другой стороны: оно равно null, когда система письма является стандартной для языка — например, латиница для французского, — и указывается только тогда, когда именно письменность служит отличительным признаком.

Именно поэтому опираться стоит на поле locale. В нём всегда содержится самый конкретный тег, который можно обоснованно вывести из текста: pt-BR, когда данные это позволяют, и pt, когда не позволяют. Поэтому, если вы используете locale, вы автоматически получаете правильный уровень детализации — без необходимости собирать его заново из частей или гадать, не был ли уверенно выглядящий регион всего лишь предположением.

direction нужен, чтобы вы могли отрисовать текст ещё до перевода#

Определение языка редко бывает конечной целью — обычно язык определяют для того, чтобы что-то сделать с текстом, и часто первое, что нужно сделать, — показать его. Поле direction в ответе нужно именно для этого: оно сообщает, читается ли текст слева направо или справа налево, чтобы вы могли установить dir="rtl", выбрать раскладку интерфейса или подобрать шрифт ещё до этапа перевода. Для арабского текста вернётся "rtl"; для французского примера выше — "ltr". Вам не нужно поддерживать собственную таблицу соответствия языков и направления письма — endpoint, который определяет язык, сразу сообщает и тот факт о рендеринге, который нужен вам в первую очередь.

Примеры#

Один POST-запрос с текстом и необязательным labelLocale. В ответе — структурированный объект локали, описанный выше.

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", ... }

Что дальше#

Чаще всего язык определяют, чтобы затем что-то с ним сделать — обычно перевести. Recognize сообщает исходную локаль, а endpoint'ы локализации берут остальное на себя.