Recognize

Tem um excerto de texto e nenhum registo fiável do idioma em que está — um comentário escrito por um utilizador, uma string de um ficheiro carregado, o corpo de um pedido de suporte recebido. Antes de o poder encaminhar, traduzir ou sequer apresentar corretamente, precisa do respetivo idioma: que língua, que região, que escrita e em que direção se lê. O Recognize fecha essa lacuna numa única chamada. Envia o texto; recebe de volta uma identidade de idioma estruturada, tão específica quanto o próprio texto permitir.

Esta página cobre o endpoint completo — o pedido, a resposta e todos os campos que devolve, os language bindings e o comportamento da resposta quando o texto não permite determinar uma região ou uma escrita. É uma chamada síncrona: faz POST do texto, o pedido fica bloqueado enquanto o texto é analisado, e a resposta regressa na mesma ida e volta. A autenticação é feita através do cabeçalho partilhado X-API-Key — veja Authentication para perceber como funcionam as chaves — e qualquer erro segue o standard error model.

Pedido#

POST /process/recognize

Só text é obrigatório. labelLocale controla o idioma da label legível na resposta — se o definir como de, a designação de um texto em francês é devolvida em alemão em vez de inglês. Não altera o que é detetado, apenas a forma como o resultado lhe é apresentado.

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

Resposta#

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

Há dois aspetos nesta estrutura que merecem uma leitura atenta, porque são eles que tornam o resultado útil — e não apenas informativo.

Primeiro, todos os códigos seguem normas publicadas, não são uma invenção da Lingo.dev. O locale é BCP-47; language é uma subtag ISO 639; region é ISO 3166; script é ISO 15924. Por isso, tudo o que já utiliza para processar idiomas — a sua biblioteca de i18n, uma chamada Intl, uma pesquisa CLDR — consome esta saída diretamente. Não está a adaptar-se a um sistema de códigos proprietário; está a receber os mesmos identificadores que o resto da sua stack já fala.

Segundo, region e script são anuláveis de propósito. Só vêm preenchidos quando o texto os demonstra efetivamente — e é isso que as duas secções seguintes explicam, além de ser a propriedade que impede o endpoint de adivinhar.

A região e a escrita só são devolvidas quando o texto as revela#

A preocupação mais óbvia com qualquer detetor de idioma é que vá longe de mais: que atribua uma região ou um sistema de escrita a um texto que nunca o comprovou, e que depois construa lógica com base num palpite. O Recognize faz o contrário. Só devolve uma subtag quando a evidência a sustenta e devolve null quando isso não acontece.

Quando há marcadores regionais no texto — vocabulário do português do Brasil, por exemplo — a resposta inclui a etiqueta completa (pt-BR). Quando a variante regional é indistinguível, devolve apenas a subtag de língua (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"
}

A mesma língua, duas respostas honestas. O primeiro texto trazia informação suficiente para identificar a região; o segundo não, por isso region é null e o locale reduz-se a pt. script segue a mesma regra no sentido inverso: é null quando o sistema de escrita é o predefinido para a língua — latim no caso do francês, por exemplo — e só é indicado quando a escrita é o fator distintivo.

É por isso que locale é o campo em que deve basear-se. É sempre a etiqueta mais específica que o texto suporta — pt-BR quando existe evidência, pt quando não existe — por isso, ler locale dá-lhe automaticamente o nível certo de granularidade, sem ter de o reconstruir a partir das partes nem de desconfiar de uma região aparentemente segura que, na verdade, não passava de um palpite.

direction está lá para poder apresentar antes de traduzir#

A deteção de idioma raramente é o objetivo final — normalmente, deteta-se para fazer alguma coisa com o texto, e a primeira coisa que muitas vezes se faz é mostrá-lo. direction está na resposta exatamente por isso: diz-lhe se o texto se lê da esquerda para a direita ou da direita para a esquerda, para que possa definir dir="rtl", escolher um layout ou selecionar um tipo de letra antes de qualquer passo de tradução. Um texto em árabe é devolvido como "rtl"; o exemplo em francês acima é devolvido como "ltr". Não precisa de manter a sua própria tabela de língua para direção — o endpoint que identifica o idioma também lhe dá o primeiro dado de apresentação de que precisa.

Exemplos#

Um único POST com o texto e um labelLocale opcional. A resposta é o objeto de idioma estruturado 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#

A razão mais comum para detetar um idioma é agir sobre ele — na maioria dos casos, traduzi-lo. O Recognize diz-lhe o idioma de origem; os endpoints de localização tratam do resto a partir daí.