Solucionar problemas con los mensajes de React

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

Sigue el recorrido del mensaje que realmente aparece en pantalla. Su texto de origen y su contexto determinan la clave; el proveedor más cercano aporta el catálogo; y la plantilla seleccionada se formatea con los valores de la llamada. Revisar estos datos suele bastar para localizar el fallo 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 en 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 con la implementación actual del proveedor. Que el paquete admita un rango más amplio de versiones en sus dependencias entre pares no hace que la sintaxis abreviada de contexto de React 19 que utiliza sea compatible con React 18.

Aparece el texto de origen en lugar de la 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 dar lugar a una identidad nueva.
  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 sin que sea posible extraerla.
  4. Si el catálogo de origen contiene 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 contiene la clave, pero el proveedor no, revisa las rutas del cargador y la selección de rutas. Carga de catálogos muestra cómo asociar los datos mediante la clave de origen cuando el JSONC traducido ha perdido los metadatos.

Tanto los valores ausentes como las cadenas vacías hacen que se use el texto de origen como alternativa. Las advertencias de desarrollo distinguen ambos casos y se muestran sin duplicados por clave e idioma. En producción se suprimen estos diagnósticos, así que una consola vacía no demuestra que el catálogo esté completo.

El cargador de Next devuelve {} si 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, devuelve {} y almacena ese resultado en caché. En ambos casos, usar el texto de origen como alternativa puede mantener la página legible y, al mismo tiempo, ocultar un problema de carga.

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

Comprueba 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 sin duplicados. Por tanto, puede mostrarse 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 el caso.

Las declaraciones generadas permiten comprobar los argumentos detectados en el texto de origen, pero no validan la sintaxis de destino ni identifican todos los marcadores de posición anidados dentro de 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. El nombre de la etiqueta traducida debe coincidir exactamente, y su destino debe mantenerse 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 se conservan como texto literal.

Usa nombres distintos para los elementos anidados. Anidar repetidamente elementos con el mismo nombre queda fuera de la estructura que admite el analizador. Los mensajes enriquecidos admiten marcadores de posición simples, no la gramática ICU completa; para ello, usa las funciones auxiliares de gramática de texto. Texto enriquecido muestra las formas admitidas.

La URL cambia, pero el idioma no #

Sustituye el idioma y el catálogo a la vez. Actualizar solo el idioma puede hacer que un texto en francés se formatee con las reglas del español. Comprueba también los proveedores anidados: un proveedor hijo con un idioma distinto es independiente y no hereda el catálogo del padre.

Sigue el mecanismo de cambio de idioma del adaptador elegido. Next Pages usa la navegación del enrutador y una cookie de idioma. TanStack usa enlaces normales 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 de tiempo relativo. Configura lang y dir del documento en la estructura base del entorno de trabajo; el proveedor base no los modifica. Después, prueba el HTML inicial y la página hidratada con la lista de comprobación del renderizado en el servidor.