Recognize

Tienes un texto y no cuentas con un registro confiable del idioma en el que está: un comentario escrito por un usuario, una cadena extraída de un archivo cargado, el cuerpo de un ticket de soporte entrante. Antes de poder enrutarlo, traducirlo o incluso mostrarlo correctamente, necesitas su idioma: qué idioma es, qué región, qué escritura y en qué dirección se lee. Recognize cierra esa brecha en una sola llamada. Envías el texto y recibes una identidad de idioma estructurada, tan específica como el propio texto lo permita.

Esta página cubre el endpoint completo: la solicitud, la respuesta y cada campo que devuelve, los enlaces para cada lenguaje y cómo responde cuando el texto no permite precisar una región o una escritura. Es una llamada sincrónica: haces un POST con el texto, la solicitud se bloquea mientras lo analiza y la respuesta vuelve en el mismo viaje de ida y vuelta. La autenticación se hace con el encabezado compartido X-API-Key; consulta Authentication para ver cómo funcionan las claves; y cualquier error sigue el modelo de error estándar.

Solicitud#

POST /process/recognize

Solo text es obligatorio. labelLocale controla el idioma de la label legible en la respuesta: si lo configuras como de, la etiqueta para una entrada en francés volverá en alemán en lugar de inglés. No cambia lo que se detecta, solo cómo se te presenta el resultado.

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

Respuesta#

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

Hay dos aspectos de esa estructura que conviene leer con atención, porque son los que hacen que el resultado sea realmente útil y no solo informativo.

Primero, cada código corresponde a un estándar publicado, no a una invención de Lingo.dev. locale es BCP-47; language es una subetiqueta ISO 639; region es ISO 3166; script es ISO 15924. Eso significa que cualquier herramienta que ya uses para interpretar idiomas —tu biblioteca de i18n, una llamada a Intl, una consulta a CLDR— puede consumir esta salida directamente. No tienes que adaptarte a un sistema de códigos propietario; recibes los mismos identificadores que ya usa el resto de tu stack.

Segundo, region y script son anulables a propósito. Solo vienen completos cuando el texto realmente los demuestra; justo de eso tratan las dos secciones siguientes, y esa es la propiedad que evita que el endpoint adivine.

La región y la escritura solo se devuelven cuando el texto las demuestra#

La preocupación obvia con cualquier detector de idioma es que se exceda: que le asigne una región o un sistema de escritura a un texto que nunca los demostró, y que termines construyendo lógica sobre una suposición. Recognize hace lo contrario. Reporta una subetiqueta solo cuando la evidencia la respalda y devuelve null cuando no es así.

Cuando el texto contiene marcadores regionales —por ejemplo, vocabulario del portugués de Brasil—, la respuesta incluye la etiqueta completa (pt-BR). Cuando la variante regional no puede distinguirse, solo se devuelve la subetiqueta de idioma (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"
}

Mismo idioma, dos respuestas honestas. El primer texto aportaba suficiente información para identificar la región; el segundo no, así que region es null y locale se reduce a pt. script sigue la misma regla desde el otro lado: es null cuando el sistema de escritura es el predeterminado para ese idioma —latín para el francés, por ejemplo—, y solo se especifica cuando la escritura es el rasgo distintivo.

Por eso conviene construir sobre locale. Siempre es la etiqueta más específica que el texto puede respaldar: pt-BR cuando la evidencia está presente, pt cuando no lo está. Así, al leer locale obtienes automáticamente el nivel correcto de granularidad, sin tener que recomponerlo a partir de las partes ni desconfiar de una región aparentemente precisa que en realidad era una suposición.

direction está ahí para que puedas renderizar antes de traducir#

La detección de idioma rara vez es el objetivo final: normalmente detectas para hacer algo con el texto, y muchas veces lo primero es mostrarlo. direction está en la respuesta exactamente para eso: te dice si el texto se lee de izquierda a derecha o de derecha a izquierda, para que puedas establecer dir="rtl", elegir un diseño o seleccionar una fuente antes de cualquier paso de traducción. El texto en árabe vuelve como "rtl"; el ejemplo en francés de arriba vuelve como "ltr". No tienes que mantener tu propia tabla de idioma a dirección: el endpoint que identifica el idioma también te entrega el primer dato de renderizado que necesitas.

Ejemplos#

Un solo POST con el texto y un labelLocale opcional. La respuesta es el objeto de idioma estructurado de arriba.

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

Siguientes pasos#

La razón más común para detectar un idioma es actuar en función de él; la mayoría de las veces, traducirlo. Recognize te dice el idioma de origen; los endpoints de localización se encargan del resto.