Localización de React con i18next

Crear una aplicación React para una audiencia global requiere una estrategia de internacionalización (i18n) sólida. react-i18next es la biblioteca de localización de React más popular, construida sobre el marco de trabajo i18next, probado en batalla. Esta guía le guía a través de todo lo que necesita para localizar su aplicación React, desde la configuración inicial hasta la automatización lista para producción con traducción por IA.

¿Por qué elegir react-i18next para la localización de React?

react-i18next es el estándar de facto para la internacionalización de React, en el que confían miles de aplicaciones de producción en todo el mundo. He aquí por qué los desarrolladores lo eligen:

• API basada en hooks - El hook useTranslation() proporciona una integración de React limpia e idiomática con renderizado automático al cambiar el idioma.
• Ecosistema rico - Plugins para detección de idioma, backends HTTP, almacenamiento en caché y más. Amplíe la funcionalidad sin reinventar la rueda.
• Formato de traducción JSON - Utiliza archivos JSON estándar que son fáciles de editar, controlar versiones e integrar con herramientas de traducción y servicios de IA.
• Soporte de espacios de nombres - Organice las traducciones en grupos lógicos (autenticación, panel, errores) para una mejor capacidad de mantenimiento y carga diferida.
• Listo para SSR y Next.js - Funciona a la perfección con el renderizado del lado del servidor, los componentes del servidor de React y el enrutador de aplicaciones de Next.js.
• Soporte de TypeScript - Seguridad de tipos completa para claves de traducción con autocompletado, detectando claves faltantes en tiempo de compilación.

Instalación

Instale react-i18next y la biblioteca i18next principal:

npm install react-i18next i18next

Plugins opcionales

Estos populares plugins mejoran su configuración de i18next con detección automática de idioma y traducciones de carga diferida:

# Language detector (auto-detects user language)
npm install i18next-browser-languagedetector

# HTTP backend (load translations from server)
npm install i18next-http-backend

Estructura de proyecto recomendada

Una estructura de proyecto bien organizada mantiene sus traducciones fáciles de mantener a medida que agrega más idiomas:

src/
├── i18n/
│   └── i18n.ts                  ← i18next configuration
├── locales/
│   ├── en/
│   │   └── translation.json     ← English (source)
│   ├── fr/
│   │   └── translation.json     ← French
│   ├── de/
│   │   └── translation.json     ← German
│   ├── ja/
│   │   └── translation.json     ← Japanese
│   └── es/
│       └── translation.json     ← Spanish
├── components/
├── App.tsx
└── index.tsx

Formato de archivo JSON de traducción

react-i18next utiliza archivos JSON anidados para las traducciones. Las claves admiten notación de puntos, interpolación con {{variables}} y pluralización integrada:

// locales/en/translation.json
{
  "welcome": {
    "title": "Welcome to our platform",
    "greeting": "Hello, {{name}}!",
    "description": "Explore features and get started."
  },
  "nav": {
    "home": "Home",
    "dashboard": "Dashboard",
    "settings": "Settings",
    "logout": "Log out"
  },
  "cart": {
    "empty": "Your cart is empty",
    "item_one": "{{count}} item in your cart",
    "item_other": "{{count}} items in your cart",
    "checkout": "Proceed to checkout"
  }
}

• Claves anidadas - Organice las traducciones jerárquicamente (p. ej., welcome.title, nav.home) para una estructura clara.
• Interpolación - Utilice la sintaxis {{variableName}} para valores dinámicos que se insertan en tiempo de ejecución.
• Pluralización - Agregue sufijos _one y _other (o _zero, _two, _few, _many para idiomas complejos) para el manejo automático de plurales.
• Contexto - Utilice sufijos _male, _female para traducciones específicas de género cuando sea necesario.

Configuración de i18next

i18next admite dos enfoques principales para cargar traducciones: backend HTTP (carga diferida) y recursos agrupados. Elija según las necesidades de su aplicación.

Backend HTTP (recomendado para aplicaciones grandes)

Cargue traducciones bajo demanda desde archivos JSON en su servidor. Esto mantiene su paquete inicial pequeño y es ideal para aplicaciones con muchos idiomas o archivos de traducción grandes:

// src/i18n/i18n.ts
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import HttpBackend from "i18next-http-backend";

i18n
  .use(HttpBackend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de", "ja", "es"],
    defaultNS: "translation",
    interpolation: {
      escapeValue: false, // React already escapes by default
    },
    backend: {
      loadPath: "/locales/{{lng}}/{{ns}}.json",
    },
    detection: {
      order: ["localStorage", "navigator", "htmlTag"],
      caches: ["localStorage"],
    },
  });

export default i18n;

Recursos agrupados (enfoque simple)

Importe traducciones directamente al paquete. Es mejor para aplicaciones más pequeñas o cuando necesita que las traducciones estén disponibles inmediatamente sin solicitudes de red:

// src/i18n/i18n.ts — Bundled approach (no HTTP backend)
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

import en from "../locales/en/translation.json";
import fr from "../locales/fr/translation.json";
import de from "../locales/de/translation.json";

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de"],
    defaultNS: "translation",
    interpolation: {
      escapeValue: false,
    },
    resources: {
      en: { translation: en },
      fr: { translation: fr },
      de: { translation: de },
    },
  });

export default i18n;

Inicialización en su aplicación

Importe el archivo de configuración de i18n en el punto de entrada de su aplicación antes de renderizar cualquier componente. Esto garantiza que las traducciones se carguen antes de que se renderice su IU:

// src/index.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./i18n/i18n"; // Initialize i18next before rendering

const root = ReactDOM.createRoot(
  document.getElementById("root") as HTMLElement
);

root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Traducción de componentes de React

react-i18next proporciona dos API principales para traducir componentes: el hook useTranslation para acceso programático y el componente Trans para texto enriquecido con JSX.

Hook useTranslation

El hook useTranslation es la forma más común de acceder a las traducciones en componentes funcionales. Proporciona la función t() y se vuelve a renderizar automáticamente cuando cambia el idioma:

import { useTranslation } from "react-i18next";

function WelcomeBanner() {
  const { t } = useTranslation();

  return (
    <div>
      <h1>{t("welcome.title")}</h1>
      <p>{t("welcome.greeting", { name: "Alice" })}</p>
      <p>{t("welcome.description")}</p>
    </div>
  );
}

Componente Trans para texto enriquecido

Cuando las traducciones contienen elementos HTML o JSX (negrita, enlaces, etc.), utilice el componente Trans. Conserva su árbol de componentes de React dentro de las traducciones:

import { Trans } from "react-i18next";

function RichTextExample() {
  return (
    <p>
      <Trans i18nKey="richText.welcome">
        Welcome to <strong>our platform</strong>.
        Visit your <a href="/dashboard">dashboard</a> to get started.
      </Trans>
    </p>
  );
}

// In the translation file:
// "richText.welcome": "Welcome to <1>our platform</1>. Visit your <3>dashboard</3> to get started."

Manejo de la pluralización

i18next maneja las formas plurales automáticamente según las reglas de plural de ICU para cada idioma. Pase un parámetro de recuento e i18next selecciona la forma plural correcta:

// In translation JSON:
// "cart.item_one": "{{count}} item in your cart"
// "cart.item_other": "{{count}} items in your cart"

import { useTranslation } from "react-i18next";

function CartSummary({ itemCount }: { itemCount: number }) {
  const { t } = useTranslation();

  return (
    <p>{t("cart.item", { count: itemCount })}</p>
  );
}

// itemCount=0 → "0 items in your cart"
// itemCount=1 → "1 item in your cart"
// itemCount=5 → "5 items in your cart"

• Agregue sufijos _one y _other a sus claves de traducción para inglés
• Para idiomas con reglas de plural complejas (árabe, polaco, ruso), agregue sufijos _zero, _two, _few, _many según sea necesario
• i18next selecciona automáticamente la forma correcta según las reglas de plural CLDR del idioma de destino

Organización con espacios de nombres

Los espacios de nombres le permiten dividir las traducciones en archivos separados por característica o dominio. Esto mejora la capacidad de mantenimiento y permite la carga diferida de paquetes de traducción:

// src/i18n/i18n.ts
i18n.init({
  defaultNS: "common",
  ns: ["common", "dashboard", "auth", "errors"],
  backend: {
    loadPath: "/locales/{{lng}}/{{ns}}.json",
  },
});

// Usage in components:
import { useTranslation } from "react-i18next";

function DashboardPage() {
  // Load specific namespace
  const { t } = useTranslation("dashboard");

  return <h1>{t("title")}</h1>;
}

function LoginForm() {
  // Load multiple namespaces
  const { t } = useTranslation(["auth", "common"]);

  return (
    <form>
      <h2>{t("auth:login.title")}</h2>
      <button>{t("common:submit")}</button>
    </form>
  );
}

Cambio de idioma dinámico

react-i18next hace que el cambio de idioma sea fluido. Llame a i18n.changeLanguage() y todos los componentes que utilicen useTranslation se volverán a renderizar automáticamente con el nuevo idioma:

import { useTranslation } from "react-i18next";

const LANGUAGES = [
  { code: "en", label: "English" },
  { code: "fr", label: "Français" },
  { code: "de", label: "Deutsch" },
  { code: "ja", label: "日本語" },
  { code: "es", label: "Español" },
];

function LanguageSwitcher() {
  const { i18n } = useTranslation();

  const changeLanguage = (lng: string) => {
    i18n.changeLanguage(lng);
  };

  return (
    <select
      value={i18n.language}
      onChange={(e) => changeLanguage(e.target.value)}
    >
      {LANGUAGES.map(({ code, label }) => (
        <option key={code} value={code}>
          {label}
        </option>
      ))}
    </select>
  );
}

React Suspense y carga diferida

react-i18next se integra con React Suspense para manejar la carga de traducciones asíncronas con elegancia. Al utilizar el backend HTTP, Suspense proporciona un estado de carga limpio mientras se obtienen las traducciones:

import { Suspense } from "react";
import { useTranslation } from "react-i18next";

// i18next supports React Suspense for async translation loading
function App() {
  return (
    <Suspense fallback={<div>Loading translations...</div>}>
      <MainContent />
    </Suspense>
  );
}

function MainContent() {
  const { t, ready } = useTranslation();

  // With Suspense, 'ready' is always true here
  return <h1>{t("welcome.title")}</h1>;
}

Claves de traducción con seguridad de tipos de TypeScript

i18next admite una integración completa con TypeScript. Al aumentar el módulo i18next, obtiene autocompletado y comprobación en tiempo de compilación para todas las claves de traducción, evitando errores tipográficos y traducciones faltantes:

// src/i18n/types.ts
import "i18next";
import translation from "../locales/en/translation.json";

declare module "i18next" {
  interface CustomTypeOptions {
    defaultNS: "translation";
    resources: {
      translation: typeof translation;
    };
  }
}

// Now t() calls are fully type-safe:
// t("welcome.title")       ✅ Autocomplete works
// t("welcome.greeting")    ✅ Valid key
// t("invalid.key")         ❌ TypeScript error

Renderizado del lado del servidor con Next.js

Para aplicaciones Next.js que utilizan el enrutador de aplicaciones, puede utilizar i18next tanto en componentes de servidor como de cliente. Cree una instancia de i18next separada para las traducciones del lado del servidor para evitar compartir el estado entre solicitudes:

// next-i18next.config.js (Next.js App Router)
// For Next.js 13+ with App Router, use next-intl or i18next directly

// src/i18n/server.ts
import { createInstance } from "i18next";
import { initReactI18next } from "react-i18next/initReactI18next";

export async function getServerTranslation(lng: string) {
  const i18nInstance = createInstance();
  await i18nInstance.use(initReactI18next).init({
    lng,
    fallbackLng: "en",
    resources: {
      [lng]: {
        translation: (await import(`../locales/${lng}/translation.json`)).default,
      },
    },
  });
  return i18nInstance;
}

// In a Server Component:
export default async function Page({ params }: { params: { lng: string } }) {
  const i18n = await getServerTranslation(params.lng);
  const t = i18n.t.bind(i18n);

  return <h1>{t("welcome.title")}</h1>;
}

• Cree una nueva instancia de i18next por solicitud en el servidor para evitar fugas de estado entre usuarios
• Utilice los mismos archivos JSON de traducción tanto para el renderizado del lado del servidor como del cliente
• Considere i18next-resources-to-backend o next-intl como alternativas para configuraciones complejas de Next.js

Acelere la traducción con IA

Configurar react-i18next es solo la mitad de la batalla; todavía necesita traducciones de alta calidad para cada idioma de destino. Traducir manualmente docenas de archivos JSON es lento, costoso y propenso a errores. La traducción con IA cambia las reglas del juego.

¿Por qué utilizar l10n.dev para React i18next?

l10n.dev está diseñado específicamente para flujos de trabajo de localización de desarrolladores. Entiende sus archivos de traducción JSON de forma nativa y produce traducciones que se sienten naturales, no generadas por máquina:

• Soporte JSON nativo: cargue su translation.json y obtenga archivos JSON perfectamente formateados y listos para usar
• IA consciente del contexto: entiende el dominio de su aplicación, preservando los términos técnicos y la voz de la marca en todos los idiomas
• Seguro para la interpolación: preserva {{variables}}, sufijos plurales (_one, _other) y estructuras de claves anidadas
• Traducción por lotes: traduzca a más de 10 idiomas simultáneamente en segundos, no en días
• Integración CI/CD: automatice las traducciones como parte de su canalización de compilación con el paquete npm ai-l10n

Flujo de trabajo de traducción con IA

1. Escriba su translation.json de origen en inglés (o su idioma base)
2. Cárguelo en l10n.dev o ejecute la CLI de ai-l10n para traducir
3. La IA genera traducciones contextualmente precisas para todos los idiomas de destino
4. Coloque los archivos JSON traducidos en su directorio locales/ y despliegue

Automatice traducciones con la CLI de ai-l10n

El paquete npm ai-l10n integra la traducción con IA directamente en su flujo de trabajo de desarrollo. Traduzca sus archivos JSON desde la línea de comandos:

# Install the l10n.dev CLI
npm install ai-l10n

# Translate your JSON files to multiple languages at once
npx ai-l10n translate src/locales/en/translation.json \
  --languages fr,de,ja,es,ko,zh-CN

Integración de compilación

Agregue la automatización de la traducción a su canalización de compilación para que las traducciones estén siempre actualizadas:

Scripts de package.json

{
  "scripts": {
    "translate": "ai-l10n translate src/locales/en/translation.json --languages fr,de,ja,es,ko --update",
    "pretranslate": "npm run translate",
    "dev": "vite",
    "build": "npm run translate && vite build"
  }
}

Makefile

LANGUAGES = fr,de,ja,es,ko,zh-CN

translate:
	npx ai-l10n translate src/locales/en/translation.json --languages $(LANGUAGES) --update

dev: translate
	npx vite

build: translate
	npx vite build

Para obtener más detalles sobre la integración y automatización de CI/CD, consulte nuestra Guía de automatización de localización

Extensión de VS Code para traducción JSON

Traduzca sus archivos JSON de React i18next directamente desde VS Code. La extensión l10n.dev le permite traducir archivos sin salir de su editor:

Cómo funciona

1. Instale la extensión l10n.dev desde el Marketplace de VS Code
2. Abra su archivo translation.json de origen
3. Haga clic derecho y seleccione 'Translate with l10n.dev'
4. Elija sus idiomas de destino y obtenga archivos traducidos al instante

Empiece a localizar su aplicación React hoy mismo

Ahora tiene todo lo que necesita para crear una aplicación React totalmente localizada con react-i18next. Combine el poder del ecosistema maduro de i18next con la traducción por IA para enviar su aplicación en cualquier idioma, rápidamente.