Recognize

Você tem um trecho de texto, mas não tem um registro confiável de qual é o idioma dele – um comentário digitado por um usuário, uma string de um arquivo enviado, o corpo de um ticket de suporte recebido. Antes de encaminhar, traduzir ou até exibir esse texto corretamente, você precisa do idioma dele: qual idioma, qual região, qual escrita e em que direção ele é lido. O Recognize fecha essa lacuna em uma única chamada. Você envia o texto e recebe de volta uma identidade estruturada de idioma, tão específica quanto o próprio texto permitir.

Esta página cobre o endpoint completo – a requisição, a resposta e cada campo retornado, os bindings de linguagem e o que acontece quando o texto não permite determinar região ou escrita. É uma chamada síncrona: você faz um POST com o texto, a requisição fica em espera enquanto o texto é analisado, e a resposta volta na mesma ida e volta. A autenticação é feita pelo cabeçalho compartilhado X-API-Key – veja Authentication para entender como as chaves funcionam – e qualquer erro segue o modelo de erro padrão.

Requisição#

POST /process/recognize

Apenas text é obrigatório. labelLocale controla o idioma do label legível na resposta – defina como de e o rótulo de um texto em francês volta em alemão, em vez de inglês. Isso não muda o que é detectado, apenas a forma como o resultado é apresentado para você.

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

Resposta#

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

Há dois pontos nesse formato que merecem atenção, porque são eles que tornam o resultado útil na prática, e não apenas informativo.

Primeiro, cada código segue um padrão publicado, não uma invenção da Lingo.dev. O locale é BCP-47; language é uma subtag ISO 639; region é ISO 3166; script é ISO 15924. Então qualquer coisa que você já use para interpretar idiomas – sua biblioteca de i18n, uma chamada de Intl, uma consulta ao CLDR – consome essa saída diretamente. Você não está se adaptando a um sistema de códigos proprietário; está recebendo os mesmos identificadores que o restante da sua stack já entende.

Segundo, region e script aceitam null de propósito. Eles só vêm preenchidos quando o texto realmente traz evidência disso – e é justamente essa característica, explicada nas próximas duas seções, que impede o endpoint de adivinhar.

Região e escrita só são retornadas quando o texto mostra isso#

A preocupação mais óbvia com qualquer detector de idioma é que ele vá longe demais: atribua uma região ou um sistema de escrita a um texto que nunca comprovou nenhum dos dois, e faça você construir lógica em cima de um palpite. O Recognize faz o oposto. Ele informa uma subtag apenas quando há evidência suficiente para sustentá-la e retorna null quando não há.

Quando há marcadores regionais no texto – vocabulário do português brasileiro, por exemplo – a resposta inclui a tag completa (pt-BR). Quando a variante regional é indistinguível, só a subtag de idioma é retornada (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"
}

Mesmo idioma, duas respostas honestas. O primeiro texto trazia informação suficiente para identificar a região; o segundo não, então region é null e o locale se reduz a pt. script segue a mesma lógica pelo outro lado: ele vem como null quando o sistema de escrita é o padrão do idioma – latim para o francês, por exemplo – e só é informado quando a escrita é o elemento que realmente distingue o texto.

É por isso que locale é o campo em que você deve se basear. Ele sempre traz a tag mais específica que o texto sustenta – pt-BR quando há evidência, pt quando não há – então basta ler locale para obter automaticamente a granularidade correta, sem precisar remontá-la a partir das partes ou desconfiar de uma região aparentemente precisa que, no fim, era só um palpite.

direction está ali para você renderizar antes de traduzir#

Detectar o idioma raramente é o objetivo final – normalmente, você detecta para fazer algo com o texto, e muitas vezes a primeira coisa é exibi-lo. direction está na resposta exatamente por isso: ele informa se o texto é lido da esquerda para a direita ou da direita para a esquerda, para que você possa definir dir="rtl", escolher um layout ou selecionar uma fonte antes de qualquer etapa de tradução. Um texto em árabe volta como "rtl"; o exemplo em francês acima volta como "ltr". Você não precisa manter sua própria tabela de idioma para direção – o endpoint que identifica o idioma também entrega a primeira informação de renderização de que você precisa.

Exemplos#

Uma única requisição POST com o texto e um labelLocale opcional. A resposta é o objeto estruturado de idioma acima.

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

Próximos passos#

O motivo mais comum para detectar um idioma é agir com base nele – na maioria das vezes, traduzi-lo. O Recognize informa o idioma de origem; os endpoints de localização cuidam do restante.