Localización de React: guía completa de i18n

Empieza con una única fuente de verdad para las configuraciones regionales compatibles. Almacena juntos el código de configuración regional, el nombre visible, la dirección del texto y la relación de respaldo. El análisis de rutas, el selector de idioma, los formateadores Intl y la carga de catálogos deben consumir esa misma configuración. Así se evita que un componente acepte fr-CA mientras otro recurre silenciosamente a fr o al inglés siguiendo reglas distintas.

Los mensajes deben representar ideas completas. Asígnales claves semánticas estables, como checkout.payment.failed, en lugar de claves copiadas de la frase inglesa actual. Pasa las variables como valores con nombre, usa los marcadores de posición de marcado de forma intencionada y deja que la sintaxis del mensaje seleccione plurales o alternativas gramaticales. Esto conserva el contexto para los traductores y permite que otro idioma cambie el orden de las palabras sin modificar el código React.

• ✓ Configuración regional: la preferencia lingüística o regional validada y activa durante un renderizado.
• ✓ Catálogo de mensajes: identificadores de mensajes estables asociados a valores traducidos.
• ✓ Interpolación: valores de tiempo de ejecución insertados en un mensaje traducido completo.
• ✓ Reglas de plural y selección: variantes gramaticales elegidas a partir de datos sensibles a la configuración regional.
• ✓ Respaldo: el comportamiento deliberado cuando una configuración regional o un mensaje no están disponibles.

Esta configuración utiliza react-i18next porque su modelo JSON basado en claves resulta familiar para muchos equipos de React. La misma secuencia se aplica a otras bibliotecas: define catálogos, inicializa una instancia sensible a la configuración regional, proporciónala en el límite de la aplicación, traduce mensajes completos en los componentes y haz que el cambio de configuración regional actualice tanto la interfaz visible como la URL o la preferencia guardada de la aplicación.

1. Paso 1

   Estructurar los catálogos

   Crea un catálogo de origen y los archivos de configuración regional correspondientes. Agrupa las claves por dominios de producto estables, como navegación, pago y validación. Mantén sincronizado el conjunto de claves de cada configuración regional e incluye contexto para los traductores en los mensajes ambiguos.

2. Paso 2

   Inicializar la instancia de i18n

   Crea la instancia de i18next en un módulo específico, registra solo los complementos que necesite la aplicación, define las configuraciones regionales compatibles y de respaldo y mantén los diagnósticos de desarrollo separados del comportamiento en producción.

3. Paso 3

   Proporcionar la localización en la raíz

   Haz que la instancia inicializada esté disponible en la raíz de la aplicación. En frameworks con renderizado en servidor, sigue la integración del framework para que la configuración regional activa y los recursos sean coherentes entre la salida del servidor y la hidratación.

4. Paso 4

   Traducir mensajes completos en los componentes

   Llama a useTranslation para el espacio de nombres correspondiente y pasa los valores de interpolación como datos con nombre. Usa Trans solo cuando un mensaje cohesionado contenga elementos React, no para ensamblar fragmentos arbitrarios.

5. Paso 5

   Crear un selector de idioma accesible

   Cambia la configuración regional activa de la biblioteca y navega a la URL correspondiente cuando las rutas estén localizadas. Conserva una preferencia solo como ayuda; no la conviertas en la única fuente de verdad para las páginas públicas.

{
  "navigation": {
    "home": "Home"
  },
  "cart": {
    "items_one": "{{count}} item",
    "items_other": "{{count}} items"
  }
}

import {useTranslation} from 'react-i18next';

export function CartSummary({count}: {count: number}) {
  const {t, i18n} = useTranslation('common');

  return (
    <section>
      <h2>{t('cart.title')}</h2>
      <p>{t('cart.items', {count})}</p>
      <button onClick={() => i18n.changeLanguage('fr')}>
        {t('language.french')}
      </button>
    </section>
  );
}

Inicializa i18next antes del primer renderizado visible para el usuario. En una aplicación exclusivamente cliente, muestra un estado de carga intencionado mientras llega el catálogo activo, en lugar de claves sin procesar. En SSR, crea u obtén una instancia acotada de forma segura a la solicitud, carga la configuración regional resuelta, renderiza con ella y serializa únicamente los recursos que el cliente necesita para hidratar el mismo árbol.

Un selector de idioma debe mostrar nombres de idiomas legibles, identificar la opción actual y conservar la ruta equivalente del usuario. Para las páginas públicas localizadas, es preferible usar enlaces porque cada configuración regional tiene una URL real. Un selector desplegable o un menú puede mejorar la interacción, pero deben mantenerse intactos el acceso mediante teclado, el comportamiento del foco y una vía de navegación sin JavaScript.

Un catálogo para cada idioma puede convertirse en uno de los recursos más grandes de la aplicación si se importa por adelantado. Divide primero los catálogos por configuración regional y, cuando el producto sea lo bastante grande como para beneficiarse, por ruta o espacio de nombres. Carga el catálogo activo antes de renderizar la interfaz crítica, guarda en caché los recursos inmutables con versión y evita iniciar una segunda solicitud para obtener mensajes que el servidor ya utilizó al generar la página.

Para contenido público, da prioridad a un framework de React capaz de emitir HTML localizado mediante generación estática o renderizado en servidor. La hidratación debe conservar la misma configuración regional y los mismos mensajes que generaron la salida del servidor. Si el cliente vuelve a detectar el idioma de forma independiente, puede provocar parpadeos del contenido y discrepancias de hidratación. Pasa la configuración regional resuelta a través del límite de renderizado en lugar de deducirla dos veces.

El SEO multilingüe depende de que las alternativas se puedan descubrir. Publica una URL estable por idioma, localiza el título y la descripción, emite una URL canónica que apunte a sí misma y conecta las páginas equivalentes con valores hreflang recíprocos. Es posible que los rastreadores no envíen una cabecera Accept-Language útil, por lo que la detección del navegador nunca debe ser la única forma de llegar a las traducciones. Un selector de idioma visible y basado en enlaces ayuda tanto a las personas como a los rastreadores.

• ✓ Carga únicamente la configuración regional activa y los espacios de nombres necesarios para la ruta.
• ✓ Renderiza la configuración regional seleccionada en el servidor o durante la compilación de las páginas públicas.
• ✓ Precarga los mensajes críticos para evitar que se muestren fugazmente las claves o el idioma de respaldo.
• ✓ Asigna a cada página localizada una URL distinta, una URL canónica y enlaces hreflang recíprocos.
• ✓ Mantén el selector de idioma como enlaces ordinarios y conserva la ruta equivalente.

La biblioteca de React se ocupa de lo que ocurre en tiempo de ejecución: seleccionar mensajes, interpolar valores y actualizar componentes. Una plataforma de localización gestiona el flujo que rodea esos mensajes: mantener la paridad de claves, invitar a revisores, traducir a escala, registrar cambios e incorporar a la aplicación los catálogos aprobados. Mantener separadas estas responsabilidades protege la capa de componentes frente a la dependencia de un proveedor.

Translatable trabaja con catálogos JSON y flujos para desarrolladores. Importa archivos de configuración regional existentes, gestiona los valores en una interfaz específica, usa la ayuda de la IA para borradores o traducciones masivas, sincroniza los cambios mediante proveedores de Git y, opcionalmente, distribuye las actualizaciones de los catálogos a través de una CDN. React permanece conectado mediante la biblioteca de i18n que el equipo ya haya elegido.

Adopta gradualmente la automatización del flujo de trabajo. Un equipo pequeño puede empezar con exportaciones bajo control de versiones y revisar cada cambio en una pull request. A medida que aumente la cadencia de lanzamientos, añade sincronización automática o distribución mediante CDN, pero conserva la validación y un respaldo integrado. El resultado es una iteración de textos más rápida sin hacer que el renderizado de la aplicación dependa de un tercero que podría no estar disponible.