Localiza mensajes interactivos con texto enriquecido
Traduce una frase 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 frase, aunque «política» sea un enlace. Traducirla como una unidad permite colocar el enlace donde corresponda en otro idioma sin que el código de la aplicación deje de controlar su destino.
El método rich del paquete de React representa ese enlace como un espacio reservado con nombre. El catálogo aporta la frase; un renderizador de React aporta el componente para ese espacio.
Renderiza una frase completa con un enlace #
Instala @lingo.dev/react en una aplicación existente de React 19. Este ejemplo local utiliza un catálogo de muestra en español y no requiere ninguna solicitud de traducción:
npm install @lingo.dev/reactimport { 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 mostrar «Antes de continuar, lee la política.». La frase traducida cambia de posición 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 genera la identidad real de los datos de prueba en lugar de recurrir a un hash inventado.
Actualmente, el proveedor utiliza la sintaxis de contexto de React 19, aunque el paquete declara dependencias entre pares para React 18/19. Comprueba la compatibilidad con 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 reservado, no un elemento HTML proporcionado por quien traduce. Su renderizador controla el destino y el comportamiento. Resuelve el destino específico de cada idioma mediante una correspondencia de rutas conocida en el código; deja los controladores de eventos y los atributos HTML arbitrarios fuera del catálogo.
Para los valores que cambian, utiliza marcadores de posición con nombre:
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 en función de la cantidad y select busca una coincidencia exacta con un selector y recurre a other si no la encuentra. La vía de texto enriquecido admite etiquetas con nombre e interpolación simple de valores; no ejecuta el formateador de ICU complejo de la vía de texto. Utiliza 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 fiable. El contexto debe explicar el uso, por ejemplo, «Etiqueta del rol de la cuenta», ya que el texto de origen y el contexto determinan juntos la identidad. Una vez que haya traducciones, cambia el contexto solo de forma deliberada.
Sustituye los datos de prueba locales por catálogos extraídos #
Con la versión actual de la CLI instalada, ejecuta:
lingo extract --src src --source-locale enSi 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 a mensajes que pueda reconocer; 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. Después, selecciona este archivo de origen locales/en.jsonc concreto y los idiomas de destino necesarios en .lingo/config.json. Traduce y recupera el catálogo mediante ese flujo de trabajo con archivos. Utiliza 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. Si una entrada falta o está vacía, se utiliza el texto de origen, así que compara tanto las claves de destino necesarias 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. Lee la puntuación que lo rodea después de que el enlace cambie de posición. Una traducción completa debe conservar tanto el significado de la frase como la acción disponible para quien la lee.
En un catálogo local de prueba, elimina el controlador de la etiqueta, introduce una etiqueta desconocida y deja una etiqueta sin cerrar. El renderizador actual conserva como texto el marcado desconocido o sin pareja; su capacidad para emparejar etiquetas anidadas con el mismo nombre es limitada. 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 casos con valores ausentes y mensajes de ICU complejos con formato incorrecto: los marcadores de posición sin resolver o la plantilla sin formatear pueden seguir visibles, acompañados de diagnósticos 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 las indicaciones para realizar pruebas en React para conocer el comportamiento exacto que se comprueba en estas pruebas.