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 recoge decisiones valiosas: identidades de búsqueda, reglas de interpolación, comportamiento de los plurales y traducciones que alguien ha revisado. La migración a mensajes basados en texto de origen y contexto debe conservar ese trabajo. Convierte primero un componente completo, asigna sus traducciones aceptadas a las nuevas identidades y compara lo que muestra 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 recuento 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 un idioma de destino con valores fijos. Así tendrás un resultado concreto que conservar durante la migración.
Por ejemplo, una llamada existente al estilo de i18next podría ser:
t("account.greeting", { name });Su catálogo de origen podría contener Welcome, {{name}}. No copies esa sintaxis de interpolación tal cual en un nuevo contrato de mensajes. El mensaje explícito de React utiliza una variable con nombre, {name}:
l.text("Welcome, {name}", {
context: "Greeting on the signed-in account page",
values: { name },
});El cambio de delimitadores que se muestra aquí es específico de esa configuración de la biblioteca de origen. Comprueba la biblioteca instalada antes de convertir otros mensajes: los delimitadores de interpolación personalizados y las convenciones de plural pueden exigir cambios distintos.
Establece correspondencias entre comportamientos, no solo entre nombres de métodos #
Utiliza text para mensajes sencillos con valores, rich para espacios reservados con nombre para componentes, plural para formas que dependen del recuento y select para alternativas basadas en valores exactos con other como opción de reserva. Mensajes interactivos enriquecidos ofrece un ejemplo completo de los cuatro.
Un componente antiguo de mensajes enriquecidos puede codificar los enlaces mediante índices. Sustituye esos índices por espacios reservados con nombres significativos y mantén el destino del enlace en el código. Conserva 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. Comprueba el comportamiento del idioma de destino en lugar de renombrar las claves con sufijos de forma mecánica.
Elige un contexto que explique cómo se usa el mensaje. La nueva identidad se deriva 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 recoge la conversión de {{name}} a {name}. Esta correspondencia permite a quien revise los mensajes seguir el recorrido de los textos aceptados hasta el nuevo catálogo y ver qué mensajes siguen sin asignar.
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. Utiliza React 19 para la implementación actual del proveedor; el rango declarado de compatibilidad con React 18 como dependencia par no sustituye las pruebas en una aplicación más antigua. Tras convertir el componente, ejecuta la CLI instalada:
lingo extract --src src --source-locale enSi no has personalizado las rutas, inspecciona locales/en.jsonc y lingo.d.ts. Localiza cada mensaje de origen y su contexto y copia la clave extraída real en la tabla de migración. Conservar la clave anterior o inventar un hash desvincularí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 corresponda. Convierte de forma controlada la sintaxis de los marcadores de posición, los espacios reservados de contenido enriquecido y los plurales, sin alterar el significado. Carga un mapa de hashes a cadenas de destino mediante el flujo de trabajo de carga de catálogos, utilizando las claves activas del origen correspondiente cuando no haya metadatos de destino. Mantén visibles las entradas sin asignar como trabajo pendiente, en lugar de clasificarlas como obsoletas.
Proporciona a LingoProvider el idioma solicitado junto con sus mensajes de destino. Durante la migración incremental, mantén los proveedores antiguo y nuevo envolviendo el código que invoca a cada uno. El contrato del proveedor explica la combinación para un mismo idioma y el aislamiento entre idiomas distintos; comprueba estos aspectos al migrar una pantalla anidada.
Comprueba los casos de mensajes ausentes o mal formados #
Renderiza el conjunto de prueba con los mismos valores que utilizaste antes de la migración. Compara el significado visible, la posición de las variables, el comportamiento de los enlaces, el resultado de los plurales y la selección de la opción de reserva. Incluye recuentos de cero, uno y valores mayores; valores de variables largos; y un valor de selección desconocido.
Elimina una entrada de destino en un conjunto de prueba local y comprueba que se usa el texto de origen como alternativa. Los mensajes ausentes o vacíos pueden mostrar el texto de origen, por lo que una pantalla utilizable no demuestra que la traducción de destino esté completa. Ejecuta las comprobaciones de coherencia de la extracción y las de TypeScript con las declaraciones generadas incluidas. Después, ejecuta las pruebas de renderizado existentes de la aplicación. Los tipos determinan la compatibilidad de las llamadas, no la calidad de la traducción.
Si una etiqueta de contenido enriquecido o un mensaje ICU están mal formados, inspecciona el resultado y los diagnósticos. El nuevo entorno de ejecución puede dejar visibles 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 antiguo. La guía de resolución de problemas de React documenta esos límites.
Trata la ayuda del agente como trabajo sujeto a revisión #
Pide al agente que inspeccione la biblioteca existente, conserve una correspondencia entre claves, identifique patrones no compatibles y separe las modificaciones del código de origen de la importación del catálogo. Revisa los cambios que proponga en el código de origen y en el catálogo antes de aplicarlos.
Amplía la migración por componente o espacio de nombres cuando el conjunto de prueba supere las comprobaciones de renderizado y las comprobaciones nativas. Conserva ambos catálogos hasta que todo el código que realiza llamadas y cada traducción de destino aceptada tengan un destino verificado. Elimina el proveedor antiguo y la dependencia solo cuando ya no quede código que los utilice. Los clientes de API y los adaptadores de enrutamiento tienen responsabilidades distintas; cambiar el entorno de ejecución de los mensajes no los sustituye.