Migra los mensajes existentes de React

Migra un pequeño conjunto de mensajes de prueba de React a mensajes con texto de origen y contexto explícitos, sin perder los marcadores de posición, el comportamiento de los plurales ni las traducciones aceptadas.

Un catálogo existente de React ya reúne decisiones valiosas: identificadores de búsqueda, reglas de interpolación, comportamiento de los plurales y traducciones que alguien ya revisó. Migrar a mensajes con texto de origen y contexto debe preservar ese trabajo. Primero convierte un componente completo, vincula sus traducciones aceptadas con los nuevos identificadores y compara lo que renderiza antes de ampliar la migración.

Registra el comportamiento anterior antes de cambiar la identidad #

Elige un componente con una etiqueta, una variable, un enlace, un conteo y un mensaje condicional. Guarda sus claves anteriores, los textos de origen y destino, la sintaxis de interpolación, el espacio de nombres y el idioma del proveedor. Renderízalo en el idioma de origen y en uno de destino con valores fijos. Así tendrás un resultado concreto que preservar durante la migración.

Por ejemplo, una llamada existente al estilo de i18next podría ser:

tsx
t("account.greeting", { name });

Su catálogo de origen podría contener Welcome, {{name}}. No copies esa sintaxis de interpolación tal cual a un nuevo contrato de mensajes. El mensaje explícito de React usa la variable con nombre {name}:

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

El cambio de delimitadores que se muestra aquí corresponde a esa configuración específica de la biblioteca de origen. Revisa la biblioteca instalada antes de convertir otros mensajes: los delimitadores de interpolación personalizados y las convenciones de plurales pueden requerir otros cambios.

Establece correspondencias entre comportamientos, no solo entre nombres de métodos #

Usa text para mensajes simples con valores, rich para espacios de componentes con nombre, plural para formas que dependen del conteo y select para alternativas de valor exacto con other como opción de respaldo. Mensajes interactivos enriquecidos ofrece un ejemplo completo de los cuatro.

Un componente antiguo de mensajes enriquecidos puede codificar los enlaces mediante índices. Reemplázalos por espacios con nombres significativos y conserva el destino del enlace en el código. Mantén los nombres, los tipos y las funciones semánticas de las variables. Un catálogo antiguo de plurales puede almacenar claves con sufijos; el nuevo entorno de ejecución construye el mensaje plural a partir de sus formas. Verifica el comportamiento en el idioma de destino en lugar de limitarte a renombrar las claves con sufijos.

Elige un contexto que explique cómo se usa el mensaje. La nueva identidad se obtiene del texto de origen y del contexto, en lugar de account.greeting. Mantén una tabla de migración con la clave anterior, el idioma, la nueva clave extraída y cualquier conversión de sintaxis. Para el saludo, esa fila registra la conversión de {{name}} a {name}. Esta correspondencia permite que quien revise rastree el texto aceptado hasta el nuevo catálogo y vea qué mensajes aún no tienen correspondencia.

Extrae e importa un catálogo pequeño de forma controlada #

Instala @lingo.dev/react y configura LingoProvider siguiendo la guía de inicio rápido de React. Usa React 19 para la implementación actual del proveedor; el rango declarado de compatibilidad con React 18 como dependencia de pares no sustituye las pruebas en una aplicación más antigua. Después de convertir el componente, ejecuta la CLI instalada:

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

Si no configuraste rutas alternativas, inspecciona locales/en.jsonc y lingo.d.ts. Busca cada mensaje de origen y su contexto, y copia la clave que se extrajo realmente en la tabla de migración. Conservar la clave anterior o inventar un hash desconectaría la traducción de destino de la búsqueda en tiempo de ejecución.

Coloca cada traducción de destino aceptada bajo la nueva clave que le corresponde. Convierte con cuidado la sintaxis de los marcadores de posición, los espacios de contenido enriquecido y los plurales, sin alterar el significado. Carga un mapa de hashes a cadenas mediante el flujo de trabajo de carga de catálogos, usando las claves activas del origen correspondiente cuando no haya metadatos de destino. Mantén visibles las entradas sin correspondencia como trabajo pendiente, en lugar de clasificarlas como obsoletas.

Proporciona juntos a LingoProvider el idioma solicitado y sus mensajes de destino. Durante la migración incremental, mantén el proveedor anterior y el nuevo envolviendo el código que llama a cada uno. El contrato del proveedor explica la combinación dentro de un mismo idioma y el aislamiento entre idiomas distintos; verifica estos comportamientos al migrar una pantalla anidada.

Verifica los casos con mensajes faltantes o mal formados #

Renderiza el conjunto de prueba con los mismos valores que usaste antes de la migración. Compara el significado visible, la ubicación de las variables, el comportamiento de los enlaces, el resultado de los plurales y la selección de la opción de respaldo. Incluye conteos de cero, uno y valores mayores; valores largos para las variables; y un valor de selección desconocido.

Elimina una entrada de destino en un conjunto de prueba local y comprueba que se use el texto de origen como respaldo. Los mensajes faltantes o vacíos pueden mostrar el texto de origen, así que una pantalla funcional no demuestra que la cobertura del idioma de destino esté completa. Ejecuta las comprobaciones de consistencia de la extracción y de TypeScript con las declaraciones generadas incluidas; después, ejecuta las pruebas de renderizado existentes de la aplicación. Los tipos establecen la compatibilidad de las llamadas, no la calidad de la traducción.

Ante una etiqueta de contenido enriquecido o un mensaje ICU mal formado, inspecciona el resultado y los diagnósticos. El nuevo entorno de ejecución puede dejar visible el marcado literal o una plantilla sin formatear, así que contrasta este comportamiento con los requisitos de la aplicación antes de eliminar el entorno de ejecución anterior. La guía de solución de problemas de React documenta esos límites.

Revisa el trabajo realizado con ayuda de agentes #

Pídele al agente que inspeccione la biblioteca existente, mantenga una correspondencia entre claves, identifique patrones no compatibles y separe los cambios en el código fuente de la importación del catálogo. Revisa los cambios que proponga para el código fuente y el catálogo antes de aplicarlos.

Amplía la migración por componente o espacio de nombres una vez que el conjunto de prueba pase las comprobaciones de renderizado y nativas. Conserva ambos catálogos hasta que todo el código que los llama y cada traducción de destino aceptada tengan un destino verificado. Elimina el proveedor anterior y su dependencia solo cuando ya no quede código que los use. Los clientes de API y los adaptadores del enrutador tienen responsabilidades distintas; cambiar el entorno de ejecución de mensajes no los reemplaza.