Localiza mensajes interactivos enriquecidos

Traduce una oración completa sin que el código de React pierda el control de sus enlaces, componentes y valores.

“Lee la política antes de continuar” es una sola oración, incluso si “política” es un enlace. Traducirla como una unidad permite que otro idioma ubique el enlace donde corresponde, sin sacar del código de la aplicación el control de su destino.

El método rich del paquete de React representa ese enlace como un espacio con nombre. El catálogo aporta la oración y un renderizador de React aporta el componente para ese espacio.

Renderiza una oración completa con un enlace #

Instala @lingo.dev/react en una aplicación existente de React 19. Este ejemplo local usa un catálogo de muestra en español y no requiere una solicitud de traducción:

sh
npm install @lingo.dev/react
tsx
import { computeKey, LingoProvider, useLingo } from "@lingo.dev/react";

const messages = {
  [computeKey(
    "Read the <policy>policy</policy> before continuing.",
    "Notice before account creation",
  )]: "Antes de continuar, lee la <policy>política</policy>.",
};

function ConsentNotice() {
  const l = useLingo();
  return (
    <p>
      {l.rich("Read the <policy>policy</policy> before continuing.", {
        context: "Notice before account creation",
        tags: {
          policy: (children) => <a href="/policy">{children}</a>,
        },
      })}
    </p>
  );
}

export function App() {
  return (
    <LingoProvider locale="es" messages={messages}>
      <ConsentNotice />
    </LingoProvider>
  );
}

El párrafo debería decir “Antes de continuar, lee la política.” La oración traducida cambia de lugar la referencia a la política, pero el enlace sigue apuntando a /policy. El texto de origen literal y el contexto de la llamada también permiten reconocer el mensaje durante la extracción. computeKey construye la identidad real de los datos de prueba en lugar de usar un hash inventado.

Actualmente, el proveedor usa la sintaxis de contexto de React 19, aunque el paquete declara React 18/19 como dependencias de pares. Verifica React 18 por separado. La guía de inicio rápido de React explica cómo configurar el proveedor y el primer catálogo.

Mantén los valores y el comportamiento en el código #

El nombre policy identifica un espacio, no un elemento HTML proporcionado por quien traduce. Su renderizador controla el destino y el comportamiento. Resuelve el destino de cada idioma a partir de un mapeo de rutas conocido en el código; deja los controladores de eventos y los atributos HTML arbitrarios fuera del catálogo.

Para los valores que cambian, usa marcadores de posición con nombre:

tsx
const greeting = l.text("Welcome, {name}", {
  context: "Greeting on the signed-in account page",
  values: { name },
});

const countLabel = l.plural(
  count,
  { one: "# item", other: "# items" },
  { context: "Number of items in the cart" },
);

const roleLabel = l.select(
  role,
  { admin: "Administrator", other: "Member" },
  { context: "Account role label" },
);

Estas llamadas deben estar dentro de un componente con const l = useLingo() y valores de la aplicación para name, count y role. text devuelve texto sin formato, plural resuelve la gramática según la cantidad y select busca una coincidencia exacta con un selector, con other como alternativa. La ruta de texto enriquecido admite etiquetas con nombre e interpolación simple de valores; no ejecuta el formateador ICU complejo de la ruta de texto. Usa plurales, fechas y números para esas decisiones en tiempo de ejecución.

Mantén estático el texto de origen. Incluir el nombre de una persona en la cadena de origen generaría un texto distinto para cada persona e impediría una extracción confiable. El contexto debe explicar el uso, por ejemplo, “Etiqueta del rol de la cuenta”, porque el texto de origen y el contexto determinan juntos la identidad. Una vez que existan traducciones, cambia el contexto de forma deliberada.

Reemplaza los datos de prueba locales por catálogos extraídos #

Con la versión actual de la CLI instalada, ejecuta:

sh
lingo extract --src src --source-locale en

Si no especificas rutas alternativas, esto escribe locales/en.jsonc y lingo.d.ts. Revisa el texto de origen, el contexto y la clave extraídos. Incluye la declaración en la configuración de TypeScript de la aplicación. La extracción admite llamadas de mensajes reconocibles; no detecta cadenas de origen arbitrarias generadas dinámicamente.

Sigue la guía de inicio rápido de la CLI para autenticarte y vincular un motor de localización. Luego, selecciona este archivo de origen real locales/en.jsonc y los idiomas de destino necesarios en .lingo/config.json. Traduce y recupera el catálogo mediante ese flujo de trabajo con archivos. Usa el procedimiento de carga de catálogos para analizar JSONC, seleccionar las claves activas de la revisión de origen correspondiente y proporcionar las cadenas de destino al proveedor. El traductor general de archivos no conserva los comentarios del catálogo de origen en el resultado de destino.

Carga el mismo aviso con el catálogo en español recuperado. Las entradas faltantes o vacías recurren al texto de origen, así que compara tanto las claves de destino requeridas como el resultado visible.

Prueba la interacción y los casos con formato incorrecto #

Abre el enlace a la política con el teclado y comprueba su nombre accesible. Revisa la puntuación que lo rodea después de que cambie de lugar. Una traducción completa debe conservar tanto el significado de la oración como la acción disponible para quien la lee.

En un catálogo local de prueba, elimina el controlador de una etiqueta, introduce una etiqueta desconocida y deja una etiqueta sin cerrar. El renderizador actual deja como texto el marcado desconocido o sin pareja; el emparejamiento de etiquetas anidadas con el mismo nombre es limitado. No es un renderizador de HTML arbitrario ni un validador que rechace todos los mensajes con formato incorrecto.

Para el texto sin formato, comprueba los valores faltantes y los mensajes ICU complejos con formato incorrecto: los marcadores de posición sin resolver o la plantilla sin formatear pueden seguir visibles, junto con mensajes de diagnóstico durante el desarrollo. Para los mensajes de cantidad y rol, prueba las categorías de plural del idioma de destino y un rol desconocido. Consulta la referencia de texto enriquecido y la guía de pruebas de React para conocer el comportamiento exacto detrás de estas comprobaciones.