Solución de problemas con mensajes de React

Encuentra en qué punto un mensaje pierde su traducción, valores, etiquetas o idioma entre la extracción y el renderizado.

Sigue el mensaje que realmente aparece en pantalla. Su texto de origen y su contexto determinan una clave; el proveedor más cercano proporciona el catálogo; la plantilla seleccionada se formatea con los valores de la llamada. Revisar estos datos suele ayudar a localizar el problema sin modificar a mano las claves generadas.

useLingo lanza una excepción fuera de un proveedor #

Coloca LingoProvider por encima del componente que llama al hook, también en las pruebas y las vistas previas aisladas. Un proveedor devuelto por ese mismo componente queda por debajo del hook. Mueve el hook a un componente hijo o usa createLingo(locale, messages) en una función que no se renderice a través del contexto de React.

Usa React 19 para la implementación actual del proveedor. Aunque el paquete declare un rango más amplio de versiones para sus dependencias pares, eso no hace que la sintaxis abreviada de contexto de React 19 sea compatible con React 18.

Aparece el texto de origen en lugar de una traducción #

  1. Revisa los valores reales de locale y messages del proveedor más cercano. Los mensajes deben ser un mapa de hashes a cadenas, no la URL de un archivo, una promesa ni LocaleFile.
  2. Calcula computeKey(source, context) a partir de la llamada exacta. Busca esa clave en el mapa proporcionado. Los cambios en la puntuación, los espacios en blanco o el contexto pueden generar una nueva identidad.
  3. Si la extracción no incluye la clave, usa un texto de origen y un contexto literales con un receptor compatible, como l.text(...), y vuelve a ejecutar la extracción. Una llamada calculada puede renderizarse en tiempo de ejecución aunque no se pueda extraer.
  4. Si el catálogo de origen tiene la clave, pero el de destino no, recupera la traducción terminada y vuelve a cargar el mapa. El envío por sí solo no incorpora el archivo a la aplicación.
  5. Si el archivo tiene la clave, pero el proveedor no, revisa las rutas del cargador y la selección de rutas. Carga de catálogos muestra la unión por claves de origen necesaria cuando el JSONC traducido ha perdido sus metadatos.

Tanto los valores ausentes como las cadenas vacías recurren al texto de origen. Las advertencias de desarrollo distinguen ambos casos y se deduplican por clave e idioma. En producción se suprimen estos diagnósticos, así que una consola vacía no sirve para comprobar que el catálogo esté completo.

El cargador de Next devuelve {} cuando falta un archivo, pero puede lanzar una excepción si el JSONC está mal formado. El catálogo integrado de TanStack captura los fallos por archivos ausentes, carga y análisis como {} y guarda ese resultado en caché. En ambos casos, recurrir al texto de origen puede mantener la página legible y, a la vez, ocultar un problema de carga.

Un marcador de posición o una expresión ICU sigue visible #

Revisa el objeto values que llega a la llamada. Si faltan valores simples, {name} permanece visible. Si no hay un objeto de valores, el entorno de ejecución devuelve la plantilla seleccionada sin formatearla.

Para un mensaje ICU complejo, revisa la sintaxis, los nombres de los argumentos y los tipos de valores de la traducción de destino seleccionada. Un error de análisis o de formato devuelve esa misma plantilla y emite un error de desarrollo deduplicado. Por eso, puede aparecer una traducción mal formada en lugar del texto de origen en inglés. Corrige la plantilla o proporciona el argumento que falta y vuelve a renderizar ese caso.

Las declaraciones generadas comprueban los argumentos detectados en el texto de origen, pero no validan la sintaxis de destino ni identifican todos los marcadores de posición anidados en una rama ICU. Prueba la rama afectada con valores reales.

Los mensajes enriquecidos usan funciones de devolución de llamada con nombre, como tags.link. Asegúrate de que el nombre coincida exactamente con el de la etiqueta traducida y conserva el destino del enlace en la función de devolución de llamada. Las etiquetas emparejadas desconocidas, las etiquetas de cierre automático y las etiquetas de apertura sin cerrar permanecen como texto literal.

Usa nombres distintos para los elementos anidados. El analizador no admite el anidamiento repetido con el mismo nombre. Los mensajes enriquecidos admiten marcadores de posición simples, no la gramática ICU completa; para eso, usa las funciones auxiliares de gramática de texto. Texto enriquecido muestra las formas admitidas.

La URL cambia, pero el idioma no #

Reemplaza el idioma y el catálogo al mismo tiempo. Actualizar solo el idioma puede hacer que el texto en francés se formatee con las reglas del español. Revisa también los proveedores anidados: un proveedor hijo con un idioma diferente es independiente y no hereda el catálogo del padre.

Sigue el mecanismo de cambio del adaptador seleccionado. Next Pages usa la navegación del enrutador y una cookie de idioma. TanStack usa enlaces simples para que una nueva solicitud pueda cargar el nuevo catálogo.

El texto, la dirección o las fechas cambian durante la hidratación #

Compara los datos de entrada del servidor y del cliente: revisión del catálogo, idioma, valores, marca de tiempo, zona horaria y referencia para el tiempo relativo. Configura lang y dir del documento en la estructura base del framework; el proveedor base no los modifica. Luego prueba el HTML inicial y la página hidratada con la lista de verificación del renderizado en el servidor.