Recognize

Vous avez un texte sans aucune indication fiable sur la langue dans laquelle il est rédigé : un commentaire saisi par un utilisateur, une chaîne issue d’un fichier importé, le corps d’un ticket d’assistance entrant. Avant de pouvoir l’acheminer, le traduire ou même l’afficher correctement, il vous faut sa langue : quelle langue, quelle région, quelle écriture, et dans quel sens elle se lit. Recognize comble ce manque en un seul appel. Vous envoyez le texte ; vous récupérez en retour une identité de langue structurée, aussi précise que le texte le permet.

Cette page couvre l’endpoint de bout en bout : la requête, la réponse et chacun des champs qu’elle renvoie, les SDK disponibles, ainsi que le comportement de la réponse quand le texte ne permet pas d’établir une région ou une écriture. Il s’agit d’un appel synchrone : vous envoyez le texte via POST, la requête reste en attente pendant l’analyse, puis la réponse revient dans le même aller-retour. L’authentification passe par l’en-tête partagé X-API-Key — voir Authentication pour le fonctionnement des clés — et toute erreur suit le modèle d’erreur standard.

Requête#

POST /process/recognize

Seul text est requis. labelLocale contrôle la langue du label lisible dans la réponse : définissez-le sur de et le libellé d’un texte français sera renvoyé en allemand plutôt qu’en anglais. Cela ne change pas ce qui est détecté, seulement la façon dont le résultat vous est présenté.

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

Réponse#

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

Deux aspects de cette structure méritent une attention particulière, car ce sont eux qui rendent le résultat réellement exploitable, et pas seulement informatif.

D’abord, chaque code correspond à une norme publiée, et non à une invention de Lingo.dev. Le locale est du BCP-47 ; language est une sous-étiquette ISO 639 ; region correspond à ISO 3166 ; script correspond à ISO 15924. Autrement dit, tout ce que vous utilisez déjà pour analyser les langues — votre bibliothèque i18n, un appel Intl, une recherche CLDR — consomme directement cette sortie. Vous n’avez pas à vous adapter à un système de codes propriétaire ; vous obtenez les mêmes identifiants que le reste de votre stack utilise déjà.

Ensuite, region et script sont nullable par choix. Ils ne sont renseignés que lorsque le texte les démontre réellement — c’est l’objet des deux sections suivantes, et la propriété qui empêche l’endpoint de deviner.

La région et l’écriture ne sont renvoyées que lorsque le texte les révèle#

Le risque évident avec tout détecteur de langue, c’est qu’il en fasse trop : qu’il attribue une région ou un système d’écriture à un texte qui n’en a jamais apporté la preuve, puis que vous bâtissiez votre logique sur une supposition. Recognize fait l’inverse. Il ne renvoie une sous-étiquette que lorsque les éléments l’étayent, et renvoie null dans le cas contraire.

Lorsque des marqueurs régionaux sont présents dans le texte — du vocabulaire propre au portugais brésilien, par exemple — la réponse inclut la balise complète (pt-BR). Lorsque la variante régionale est indiscernable, seule la sous-étiquette de langue est renvoyée (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"
}

Même langue, deux réponses honnêtes. Le premier texte contenait suffisamment d’indices pour identifier la région ; le second non, donc region vaut null et le locale se réduit à pt. script suit la même règle dans l’autre sens : il vaut null lorsque le système d’écriture est celui par défaut pour la langue — le latin pour le français, par exemple — et n’est renseigné que lorsque l’écriture est l’élément distinctif.

C’est pourquoi locale est le champ sur lequel s’appuyer. Il contient toujours la balise la plus précise que le texte permet — pt-BR lorsque les éléments sont là, pt lorsqu’ils ne le sont pas — de sorte qu’en lisant locale, vous obtenez automatiquement le bon niveau de granularité, sans avoir à le reconstituer à partir des différentes parties ni à remettre en cause une région en apparence certaine qui n’était en réalité qu’une supposition.

direction est là pour vous permettre d’afficher avant de traduire#

La détection de langue est rarement une fin en soi — en général, vous détectez pour faire quelque chose avec le texte, et la première chose que vous faites souvent, c’est l’afficher. direction figure dans la réponse précisément pour cela : il vous indique si le texte se lit de gauche à droite ou de droite à gauche, afin que vous puissiez définir dir="rtl", choisir une mise en page ou sélectionner une police avant toute étape de traduction. Un texte arabe revient avec "rtl" ; l’exemple français ci-dessus revient avec "ltr". Vous n’avez pas à maintenir votre propre table de correspondance entre langues et directions — l’endpoint qui identifie la langue vous fournit aussi d’emblée l’information de rendu dont vous avez besoin en priorité.

Exemples#

Un seul POST avec le texte et une labelLocale facultative. La réponse est l’objet de langue structuré ci-dessus.

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

Étapes suivantes#

La raison la plus courante de détecter une langue, c’est d’agir en conséquence — le plus souvent, de la traduire. Recognize vous indique la langue source ; les endpoints de localisation prennent ensuite le relais.