¿Cómo traducir archivos JSON de i18next en React y Next.js (2026)?

Acabas de terminar una aplicación de React que necesita ser lanzada en 12 idiomas para el próximo viernes. Tus archivos de localización están en public/locales/en/common.json, tienes 340 claves por localización, y los tokens dentro de tus cadenas se ven como {{userName}} y {{count}} dispersos en objetos anidados. Pegas el JSON en ChatGPT, y te devuelve {{ nombreUsuario }}, espacios extra y la mitad de las claves de pluralización renombradas. Tu aplicación falla al compilar.

Si has intentado automatizar la traducción de JSON de i18next, conoces este problema. El formato JSON es flexible, por lo que la mayoría de las herramientas de traducción lo estropean. El problema real no es la calidad del modelo de lenguaje, sino que las herramientas de IA de consumo no entienden las reglas estructurales de i18next.

Esta guía explica qué hace que el JSON de i18next sea diferente de otros formatos de localización, por qué los enfoques de traducción ingenuos rompen las aplicaciones de React y Next.js, y cómo automatizar la traducción de forma segura en decenas de localizaciones sin revisar manualmente cada clave.

Qué es el JSON de i18next y por qué su traducción es complicada

i18next es la librería i18n más utilizada en el ecosistema JavaScript. Impulsa aplicaciones React (react-i18next), Next.js (next-i18next, App Router next-intl), Vue y servicios backend de Node. Almacena cadenas traducibles en archivos JSON planos o anidados, uno por cada localización.

Un archivo típico se ve así:

{
  "welcome": "Welcome, {{userName}}!",
  "cart": {
    "empty": "Your cart is empty",
    "items_one": "{{count}} item in your cart",
    "items_other": "{{count}} items in your cart"
  },
  "errors": {
    "network": "Network error. <strong>Please retry</strong>."
  }
}

Esto parece simple, pero tres cosas hacen que sea peligroso traducirlo con IA de propósito general.

Los tokens de interpolación son estructurales, no texto

La secuencia {{userName}} no es una palabra, es un marcador de posición que el tiempo de ejecución reemplaza con datos. Si añades un espacio ({{ userName }}), lo renombras o traduces el identificador interno, el tiempo de ejecución falla silenciosamente o lanza un error. Algunos traductores convierten útilmente {{count}} a {{conteo}} en español. Tu aplicación ahora intenta interpolar una variable que no existe y muestra el marcador de posición original a tu usuario.

Las claves de pluralización son sufijos mágicos

i18next detecta los plurales por sufijos: _zero, _one, _two, _few, _many, _other. Estas no son cadenas arbitrarias; deben coincidir con las categorías de plural CLDR para la localización de destino. El inglés solo usa _one y _other. El ruso, árabe y polaco utilizan hasta seis categorías. Si tu traductor elimina _other o lo renombra, la cadena de reserva se rompe.

Las claves anidadas deben permanecer intactas

A diferencia de los archivos .po de Gettext, que son pares clave-valor planos, los archivos de i18next pueden anidarse arbitrariamente. Un traductor perezoso podría aplanar la estructura, cambiar los nombres de las claves para que coincidan con el texto traducido o reordenar objetos. Tu llamada t('cart.items_other') en el código ya no se resuelve.

Malas soluciones que los desarrolladores prueban primero

Cada equipo pasa por el mismo ciclo de fracaso de tres etapas antes de invertir en una solución real.

Etapa uno: Pegar en ChatGPT

Copias 200 claves en ChatGPT, preguntas "traduce este JSON al español" y pegas el resultado. Funciona para 180 claves. Veinte tienen espacios añadidos dentro de {{...}}, tres tienen los sufijos plurales reescritos y una etiqueta <strong> se tradujo a <fuerte>. Tu compilación falla o envía cadenas silenciosamente rotas a producción.

Etapa dos: API de Google Translate

Conectas la API REST de Google Translate, iteras sobre tu JSON y envías cada valor. La velocidad es excelente. La calidad no. La API de Google trata cada cadena de forma aislada, sin contexto sobre tu aplicación, sin entender que {{count}} es un marcador de posición, sin saber que la clave cart.empty es diferente de cart.items_one. Todavía necesitas revisión humana para cada clave.

Etapa tres: Plataformas TMS comerciales

Te registras en un sistema de gestión de traducciones. Cobran por palabra, requieren integraciones con GitHub y te encierran en suscripciones mensuales. Para un proyecto secundario o una aplicación independiente, la economía se desmorona rápidamente, y aun así te encuentras con los mismos problemas de corrupción de marcadores de posición si su motor no analiza el formato i18next específicamente.

Los mismos modos de fallo también aparecen en los flujos de trabajo de Gettext. Nuestra guía sobre cómo traducir archivos .po sin romper variables de código cubre el problema paralelo para WordPress y otras pilas basadas en Gettext.

El enfoque seguro: Traducción consciente de la sintaxis

La única forma fiable de traducir JSON de i18next a gran escala es con una herramienta que primero analice el formato, bloquee la sintaxis y solo envíe texto traducible a la IA.

Esto es lo que hace el procesamiento consciente de la sintaxis bajo el capó:

1. Analiza el JSON en un árbol abstracto, conservando las rutas de las claves y el anidamiento.
2. Identifica los tokens de interpolación ({{name}}, {{count, number}}, {{date, datetime}}) y los reemplaza con ID de marcador de posición.
3. Identifica las etiquetas HTML dentro de los componentes Trans (<0>, <strong>, <br/>) y las bloquea.
4. Detecta las claves plurales por sufijo y las asigna a las reglas CLDR para la localización de destino.
5. Envía solo el texto limpio al LLM con contexto sobre la ruta de la clave.
6. Reinserta los tokens y etiquetas originales en sus posiciones exactas.
7. Valida la salida: si falta algún marcador de posición o está mal formado, revierte al origen.

Este es el mismo principio que hace segura la traducción de PO basada en la nube. Si tienes curiosidad sobre la arquitectura subyacente, nuestra comparación de calidad de traducción de IA desglosa cómo los diferentes LLM manejan estas restricciones.

Paso a paso: Traducir JSON de i18next con SimplePoTranslate

SimplePoTranslate es compatible con JSON de i18next de forma nativa en los planes Pro y Lifetime. El nivel gratuito actualmente cubre .po y .pot; actualiza o usa una prueba para acceder a JSON.

1. Prepara tu archivo de origen

Usa tu archivo en inglés (o de la localización de origen) como maestro. Asegúrate de que sea un JSON válido y contenga todas las claves que utiliza tu aplicación. Un error común es dejar claves obsoletas o sin usar, lo que consume tu cuota de traducción para cadenas que nunca renderizarás.

# From your project root
cp public/locales/en/common.json ~/Desktop/common.json

2. Sube a SimplePoTranslate

Inicia sesión en tu panel de control, haz clic en Nueva traducción y sube common.json. La plataforma detecta automáticamente el formato i18next. Elige tu idioma de destino entre las 41 localizaciones admitidas, selecciona un tono (profesional, informal, marketing) y envía.

3. Deja que el motor trabaje

Bajo el capó, el archivo se analiza, se divide en lotes seguros y se traduce en paralelo. Los tokens de interpolación se bloquean. Los sufijos plurales se conservan y se asignan a las reglas CLDR de la localización de destino. El HTML dentro de los componentes Trans permanece intacto.

4. Descarga el ZIP

Obtendrás un ZIP que contiene el JSON traducido más formatos alternativos (.php para aplicaciones PHP, .po para compatibilidad entre herramientas). Coloca el JSON en public/locales/es/common.json y vuelve a implementar.

unzip common_es.zip
mv common.json public/locales/es/common.json
npm run build

5. Repetir o procesar por lotes

Para las 12 localizaciones de destino, envía 12 trabajos. Las cuotas del plan Pro cubren docenas de aplicaciones SaaS típicas. Para monorepos con varios archivos de espacio de nombres, sube cada uno por separado o procésalos por lotes secuencialmente.

Integrando las traducciones de nuevo en tu aplicación

Una vez que tienes los archivos JSON traducidos, la integración es la parte fácil. Algunas consideraciones:

• Verifica las categorías plurales. Realiza una prueba rápida por cada localización: renderiza un componente con count={0}, count={1}, count={5} y confirma que los tres producen la cadena correcta.
• Comprueba las localizaciones RTL. Si has traducido al árabe, hebreo o persa, tu UI necesita CSS compatible con RTL. Nuestra guía de traducción RTL para WordPress cubre los patrones CSS que también se aplican a las aplicaciones React.
• Configura una cadena de reserva. Configura i18next para que recurra al inglés si falta una clave, de modo que los estados a mitad de despliegue no bloqueen a los usuarios.
• Bloquea tu archivo de origen en CI. Añade una verificación que rechace las solicitudes de extracción (PRs) donde en/common.json cambie sin regenerar otras localizaciones. La deriva de la traducción es la causa más importante de los errores de i18n en producción.

Para los equipos que trabajan con React, Next.js y el lado del servidor, producir todos los formatos desde una única fuente es una gran ventaja. Nuestra publicación sobre un archivo de entrada, cinco formatos de salida explica por qué la salida multiformato es importante para el mantenimiento a largo plazo.

Cuando JSON no es suficiente: Manejo de casos complejos

Algunos casos límite requieren atención adicional.

MessageFormat de ICU

Si tu proyecto utiliza la sintaxis ICU ({count, plural, one {1 item} other {# items}}), i18next lo trata como interpolación, pero la estructura es más compleja. Asegúrate de que tu herramienta de traducción reconoce los parámetros ICU y no traduce los nombres de categorías como one, other, o los identificadores de formato como plural, number, date.

Componente Trans con Nodos React

<Trans> renderiza componentes React dentro de cadenas traducidas, indexados por clave (<0>, <1>). El traductor debe preservar el orden exacto de las etiquetas. El bloqueo de sintaxis de SimplePoTranslate maneja esto, pero si usas una herramienta diferente, verifica antes de lanzar.

Archivos de espacio de nombres

Las aplicaciones grandes dividen las localizaciones en espacios de nombres: common.json, dashboard.json, checkout.json. Traduce cada archivo de forma independiente; no los fusiones. La calidad del contexto es mayor cuando las rutas de clave de cada espacio de nombres permanecen acotadas.

Poniéndolo todo junto

Traducir JSON de i18next para una aplicación React o Next.js no se trata de elegir el mejor modelo de IA. Se trata de respetar las reglas estructurales del formato: las interpolaciones, los sufijos plurales, las claves anidadas y las etiquetas HTML deben sobrevivir al viaje de ida y vuelta. Las herramientas de IA de consumo tratan el JSON como texto no estructurado. Las herramientas conscientes de la sintaxis lo analizan como datos estructurados y solo tocan las superficies traducibles.

Si estás lanzando una aplicación multilingüe y has estado copiando y pegando JSON en interfaces de chat, ya conoces el costo: horas de revisión manual por localización, errores de producción aleatorios y una pila creciente de formas plurales rotas. Un pipeline consciente del formato elimina cada uno de esos modos de fallo.

¿Listo para traducir tus archivos JSON de i18next de forma segura? Prueba SimplePoTranslate gratis - no se requiere tarjeta de crédito. Sube una vez, lanza en 41 idiomas.