Recognize

Tienes un fragmento de texto y ningún registro fiable del idioma en el que está: un comentario que ha escrito un usuario, una cadena de un archivo subido o 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 cubre ese vacío en una sola llamada. Envías el texto y recibes una identidad de idioma estructurada, tan específica como el propio texto permita.

Esta página cubre el endpoint al completo: la solicitud, la respuesta y cada campo que devuelve, los language bindings y qué hace la respuesta cuando el texto no permite determinar una región o una escritura. Es una llamada sincrónica: haces un POST con el texto, la solicitud queda bloqueada mientras se analiza y la respuesta vuelve en el mismo viaje de ida y vuelta. La autenticación se hace con la cabecera compartida X-API-Key; consulta Authentication para ver cómo funcionan las claves; y cualquier error sigue el modelo de errores estándar.

Solicitud#

POST /process/recognize

Solo es obligatorio text. labelLocale controla el idioma de la label legible que devuelve la respuesta: si lo estableces en de, la etiqueta de una entrada en francés se devolverá en alemán en lugar de en 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 esta estructura que merece la pena leer con atención, porque son los que hacen que el resultado sea útil y no solo informativo.

En primer lugar, cada código es un estándar publicado, no una invención de Lingo.dev. locale es BCP-47; language es una subetiqueta de ISO 639; region es ISO 3166; script es ISO 15924. Así que cualquier herramienta que ya uses para analizar idiomas —tu librería de i18n, una llamada a Intl o una consulta a CLDR— puede consumir esta salida directamente. No te estás adaptando a un sistema de códigos propietario; estás recibiendo los mismos identificadores que ya maneja el resto de tu stack.

En segundo lugar, region y script admiten null de forma intencionada. Solo se devuelven informados cuando el texto realmente los demuestra, que es precisamente el tema de las dos secciones siguientes y lo que evita que el endpoint haga suposiciones.

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

La preocupación más evidente con cualquier detector de idioma es que se exceda: que asigne una región o un sistema de escritura a un texto que nunca lo ha demostrado y que acabes construyendo lógica sobre una conjetura. Recognize hace justo lo contrario. Solo informa de una subetiqueta 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 se puede distinguir, 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 contenía 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 el idioma —latino para el francés, por ejemplo— y solo se indica cuando la escritura es el factor diferenciador.

Por eso locale es el campo sobre el que conviene construir. Siempre es la etiqueta más específica que el texto puede sostener: pt-BR cuando hay evidencia y pt cuando no la hay. Así, leer locale te da automáticamente el nivel de granularidad correcto, sin que tengas que recomponerlo a partir de las partes ni desconfiar de una región que parecía segura pero 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 a menudo lo primero que haces es mostrarlo. direction está en la respuesta exactamente para eso: te indica 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 se devuelve como "rtl"; el ejemplo en francés de arriba se devuelve como "ltr". No tienes que mantener tu propia tabla de idioma a dirección: el endpoint que identifica el idioma también te da el primer dato de renderizado que necesitas.

Ejemplos#

Un único 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 habitual para detectar un idioma es actuar en consecuencia; casi siempre, traducirlo. Recognize te indica el idioma de origen; los endpoints de localización se encargan del resto.