Cómo traducir una aplicación de React con react-i18next

Aprenda a traducir aplicaciones React con react-i18next utilizando archivos JSON, plurales y contenido dinámico. Configure la localización continua con PTC para automatizar las traducciones de React.

Esta guía le muestra cómo:

Configure react-i18next y cargue los archivos de traducción automáticamente
Gestione contenido dinámico (variables, plurales, texto con formato)
Traduzca sus archivos JSON e implemente su aplicación

Puede seguir un ejemplo completo de traducción de React en GitHub.

Ejemplo de internacionalización de React

Configure su aplicación de React

Este tutorial utiliza una nueva aplicación de React + TypeScript creada con Vite. Si está añadiendo traducciones a una aplicación existente, vaya al paso 2.

Para crear una nueva aplicación de React + TypeScript, ejecute:

npm create vite@latest react-localization-demo -- --template react-ts
cd react-localization-demo
npm install
npm run dev

npm create vite@latest react-localization-demo -- --template react-ts
cd react-localization-demo
npm install
npm run dev

Esto inicia un servidor de desarrollo y abre la página predeterminada de Vite + React en su navegador.

Default Vite + React page in the browser

Referencia de commit: Crear proyecto React con Vite y TypeScript

Instale y configure react-i18next

Instale las bibliotecas:

npm install i18next react-i18next
```

### Cree su archivo de traducción

Cree la siguiente estructura de carpetas:
```
src/
 i18n/
 locales/
 en.json

npm install i18next react-i18next
```

### Create Your Translation File

Create the following folder structure:
```
src/
  i18n/
    locales/
      en.json

Añada sus cadenas en inglés a src/i18n/locales/en.json:

{
 "welcome": "Welcome",
 "description": "This is a localization demo.",
 "clickMe": "Click me"
}

{
  "welcome": "Welcome",
  "description": "This is a localization demo.",
  "clickMe": "Click me"
}

Cada clave (welcome, description, clickMe) se asigna al texto que desea mostrar en la interfaz de usuario.

Actualice su componente

Ahora, convierta su componente de texto codificado a traducciones. Aquí tiene un componente típico de React con cadenas codificadas:

function App() {
  return (
    <div>
      <h1>Bienvenido</h1>
      <p>Esta es una demostración de localización.</p>
      <button onClick={() => alert('Click me')}>Haga clic aquí</button>
    </div>
  );
}

function App() {
  return (
    <div>
      <h1>Welcome</h1>
      <p>This is a localization demo.</p>
      <button onClick={() => alert('Click me')}>Click me</button>
    </div>
  );
}

Reemplace el texto codificado con el hook useTranslation en src/App.tsx:

import { useTranslation } from 'react-i18next';

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

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('description')}</p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

import { useTranslation } from 'react-i18next';

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

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('description')}</p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

El hook useTranslation() da a su componente acceso a:

t() – busca una cadena por clave
i18n – le permite cambiar de idioma mediante programación

Referencia de commit: Crear el archivo inicial en inglés para la traducción

Inicialice i18next

Cree src/i18n/index.ts para configurar i18next y cargar los archivos de traducción automáticamente.

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

type TranslationResources = string | { [k: string]: TranslationResources } | TranslationResources[];

const modules = import.meta.glob<{default: Record<string, TranslationResources>}>('./locales/*.json', { eager: true })

const resources: Record<string, { translation: Record<string, TranslationResources> }> = {};

for (const path in modules) {
 const lang = path.match(/.\/locales\/(.*)\.json$/)?.[1];
 if (lang) {
 resources[lang] = { translation: modules[path].default };
 }
}

i18n
 .use(initReactI18next)
 .init({
 resources,
 fallbackLng: 'en',
 interpolation: { escapeValue: false },
 });

export default i18n;

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

type TranslationResources = string | { [k: string]: TranslationResources } | TranslationResources[];

const modules = import.meta.glob<{default: Record<string, TranslationResources>}>('./locales/*.json', { eager: true })

const resources: Record<string, { translation: Record<string, TranslationResources> }> = {};

for (const path in modules) {
  const lang = path.match(/\.\/locales\/(.*)\.json$/)?.[1];
  if (lang) {
    resources[lang] = { translation: modules[path].default };
  }
}

i18n
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: 'en',
    interpolation: { escapeValue: false },
  });

export default i18n;

Esta configuración es útil porque:

Cada archivo *.json que añada a src/i18n/locales/ estará disponible automáticamente.
Cuando PTC crea nuevos archivos de idioma (por ejemplo, ar.json), esta configuración los cargará automáticamente, sin necesidad de importaciones ni cambios de código.

Importe i18n en su punto de entrada

Antes de que React renderice su aplicación, i18next necesita la oportunidad de inicializarse. Abra src/main.tsx e importe la configuración de i18n:

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'
import './index.css'
import './i18n' // ← ¡Añada esta importación!

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
)

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'
import './index.css'
import './i18n'  // ← Add this import!

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
)

Si omite este paso, t() simplemente devolverá las claves de traducción en lugar del texto traducido.

Referencia de commit: configurar la configuración de i18n

Gestione contenido dinámico

Hasta ahora, solo ha utilizado cadenas estáticas como “Welcome” y “Click me”. Pero las aplicaciones reales necesitan contenido dinámico: saludar a los usuarios por su nombre, mostrar recuentos e incluir enlaces o formato dentro del texto traducido.

Interpolación (variables)

Para incluir variables en las traducciones, utilice la sintaxis {{variableName}} en su JSON y pase el valor al llamar a t().

Actualice src/i18n/locales/en.json:

{
 "welcome": "Welcome",
 "userGreeting": "Welcome back, {{firstName}}!",
 "description": "This is a localization demo.",
 "clickMe": "Click me"
}

{
  "welcome": "Welcome",
  "userGreeting": "Welcome back, {{firstName}}!",
  "description": "This is a localization demo.",
  "clickMe": "Click me"
}

Úselo en su componente:

import { useTranslation } from 'react-i18next';

function App() {
 const { t } = useTranslation();
 const user = { firstName: 'Sarah' };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('description')}</p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

import { useTranslation } from 'react-i18next';

function App() {
  const { t } = useTranslation();
  const user = { firstName: 'Sarah' };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('description')}</p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

El segundo argumento para t() es un objeto con los valores que desea sustituir. Puede tener tantas variables como necesite, solo asegúrese de que cada una aparezca en sus traducciones.

Plurales

Algunos cambios de texto basados en un número. Por ejemplo, “1 mensaje nuevo” vs “3 mensajes nuevos”. i18next maneja esto automáticamente cuando proporciona formas plurales.

Actualice src/i18n/locales/en.json:

{
 "welcome": "Welcome",
 "userGreeting": "Welcome back, {{firstName}}!",
 "description": "This is a localization demo.",
 "clickMe": "Click me",
 "newMessages_one": "Tiene {{count}} mensaje nuevo.",
 "newMessages_other": "Tiene {{count}} mensajes nuevos."
}

{
  "welcome": "Welcome",
  "userGreeting": "Welcome back, {{firstName}}!",
  "description": "This is a localization demo.",
  "clickMe": "Click me",
  "newMessages_one": "You have {{count}} new message.",
  "newMessages_other": "You have {{count}} new messages."
}

Para que la pluralización funcione, la variable interpolada debe llamarse count. i18next utiliza este valor para elegir la forma plural correcta para cada idioma.

Úselo en su componente:

import { useTranslation } from 'react-i18next';

function App() {
 const { t } = useTranslation();
 const user = { firstName: 'Sarah' };
 const [messageCount, setMessageCount] = useState<number>(1);

  const handleIncrement = () => {
 setMessageCount(messageCount + 1);
 };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('newMessages', { count: messageCount })}</p>
      <p>{t('description')}</p>
      <button onClick={handleIncrement}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

import { useTranslation } from 'react-i18next';

function App() {
  const { t } = useTranslation();
  const user = { firstName: 'Sarah' };
  const [messageCount, setMessageCount] = useState<number>(1);

  const handleIncrement = () => {
    setMessageCount(messageCount + 1);
  };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('newMessages', { count: messageCount })}</p>
      <p>{t('description')}</p>
      <button onClick={handleIncrement}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

i18next elegirá automáticamente newMessages (singular) cuando count sea 1, y newMessages_other (plural) para cualquier otro número.

Formato y enlaces con Trans

Para las traducciones que contienen elementos HTML (enlaces, texto en negrita, etc.), utilice el componente Trans.

Importe Trans:

import { useTranslation, Trans } from 'react-i18next';

import { useTranslation, Trans } from 'react-i18next';

Añada una nueva clave a src/i18n/locales/en.json:

{
 "welcome": "Welcome",
 "userGreeting": "Welcome back, {{firstName}}!",
 "newMessages_one": "You have {{count}} new message.",
 "newMessages_other": "You have {{count}} new messages.",
 "description": "This is a localization demo.",
 "termsText": "I agree to the <1>Terms of Service1> and <3>Privacy Policy3>.",
 "clickMe": "Click me"
}

{
  "welcome": "Welcome",
  "userGreeting": "Welcome back, {{firstName}}!",
  "newMessages_one": "You have {{count}} new message.",
  "newMessages_other": "You have {{count}} new messages.",
  "description": "This is a localization demo.",
  "termsText": "I agree to the <1>Terms of Service</1> and <3>Privacy Policy</3>.",
  "clickMe": "Click me"
}

Observe las etiquetas <1> y <3>. Estos son marcadores de posición que se asignan a componentes secundarios por índice (comenzando desde 0).

Utilice el componente Trans en su JSX:

import { useTranslation, Trans } from 'react-i18next';

function App() {
 const { t } = useTranslation();
 const user = { firstName: "Sarah" };
 const [messageCount, setMessageCount] = useState<number>(1);

  const handleIncrement = () => {
 setMessageCount(messageCount + 1);
 };

  return (
    <div>
      <h1>{t("welcome")}</h1>
      <p>{t("userGreeting", { firstName: user.firstName })}</p>
      <p>{t("newMessages", { count: messageCount })}</p>
      <p>{t("description")}</p>

      <p>
        <Trans i18nKey="termsText">
  Acepto los  <a href="/terms">Términos de Servicio</a> y la  
          <a href="/privacy">Política de Privacidad</a>.
        </Trans>
      </p>

      <button onClick={handleIncrement}>{t("clickMe")}</button>
    </div>
 );
}

export default App;

import { useTranslation, Trans } from 'react-i18next';

function App() {
  const { t } = useTranslation();
  const user = { firstName: "Sarah" };
  const [messageCount, setMessageCount] = useState<number>(1);

  const handleIncrement = () => {
    setMessageCount(messageCount + 1);
  };

  return (
    <div>
      <h1>{t("welcome")}</h1>
      <p>{t("userGreeting", { firstName: user.firstName })}</p>
      <p>{t("newMessages", { count: messageCount })}</p>
      <p>{t("description")}</p>

      <p>
        <Trans i18nKey="termsText">
          I agree to the <a href="/terms">Terms of Service</a> and 
          <a href="/privacy">Privacy Policy</a>.
        </Trans>
      </p>

      <button onClick={handleIncrement}>{t("clickMe")}</button>
    </div>
  );
}

export default App;

Traduzca los archivos JSON en su aplicación de React

En este punto, su aplicación está completamente lista para la internacionalización. Ahora es el momento de traducir su archivo en.json.

Puede traducir manualmente, pero a medida que añade archivos de traducción, esto puede ser difícil de gestionar. Por eso estamos utilizando nuestro Private Translation Cloud (PTC): crea traducciones de IA con reconocimiento del contexto y puede integrarse con su repositorio de GitHub para una localización continua.

PTC comienza siempre con una prueba gratuita de 30 días que le permite traducir 20.000 palabras a un máximo de 2 idiomas. Después, podrá utilizar el pago por uso sin suscripción: solo pagará por lo que traduzca.

Por ejemplo, con el pago por uso, traducir sus próximas 10.000 palabras a 1 idioma cuesta 22 €. Cuanto más traduzca, menos pagará por palabra.

Regístrese en PTC

Para empezar a traducir:

Siga los pasos de la Guía de inicio para crear un nuevo proyecto.
En el asistente de configuración, seleccione su archivo de origen (en nuestro caso, src/i18n/locales/en.json)
Elija su ruta de salida: src/i18n/locales/{{lang}}.json

Este patrón crea un archivo por idioma (por ejemplo, fr.json, de.json) utilizando la misma estructura de carpetas que su aplicación ya espera.

Cuando sus traducciones estén listas, PTC abre una solicitud de extracción con los nuevos archivos de idioma. Debido a la configuración de carga automática que configuró en el Paso 3, estos archivos funcionan de inmediato, sin necesidad de cambios en el código.

Referencia de commit: PTC ReactLocalizationDemo : traducciones automáticas

Pruebe su aplicación React traducida con un selector de idiomas

Ahora que tiene un archivo de traducción, añada un simple selector de idiomas para verificar que todo funciona.

Actualice src/App.tsx para añadir botones de selector de idiomas:

import { useTranslation } from 'react-i18next';

function App() {
 const { t, i18n } = useTranslation();

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('newMessages', { count: messageCount })}</p>
      <p>{t('description')}</p>
      
      <p>
        <Trans i18nKey="termsText">
  Acepto los  <a href="/terms">Términos de Servicio</a> y la  <a href="/privacy">Política de Privacidad</a>.
        </Trans>
      </p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>

      <button onClick={() => i18n.changeLanguage('en')}>EN</button>
      <button onClick={() => i18n.changeLanguage('fr')}>FR</button>
    </div>
 );
}

import { useTranslation } from 'react-i18next';

function App() {
  const { t, i18n } = useTranslation();

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('newMessages', { count: messageCount })}</p>
      <p>{t('description')}</p>
      
      <p>
        <Trans i18nKey="termsText">
          I agree to the <a href="/terms">Terms of Service</a> and <a href="/privacy">Privacy Policy</a>.
        </Trans>
      </p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>

      <button onClick={() => i18n.changeLanguage('en')}>EN</button>
      <button onClick={() => i18n.changeLanguage('fr')}>FR</button>
    </div>
  );
}

Ejecute su aplicación (npm run dev) y haga clic en los botones EN / FR. Al ejecutar la aplicación en francés, el diseño debería ser exactamente igual al de la versión en inglés; solo cambia el idioma del texto.

React app in English

React app in French

Referencia de commit: Añadir un selector de idiomas para probar la traducción

Próximos pasos: Optimización de su aplicación de React traducida

Su aplicación de React ahora tiene soporte multiidioma completo. Si está implementando en producción o admitiendo muchos idiomas, estas optimizaciones pueden mejorar el rendimiento y la experiencia del usuario.

Detección automática del idioma del usuario

De forma predeterminada, su aplicación se inicia en inglés y requiere que los usuarios cambien de idioma manualmente. Con la detección automática de idiomas, i18next comprueba el navegador, la URL o las preferencias guardadas y carga el idioma correcto al instante.

Instale el detector de idioma:

npm install i18next-browser-languagedetector

npm install i18next-browser-languagedetector

Actualice src/i18n/index.ts:

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

type TranslationResources = string | { [k: string]: TranslationResources } | TranslationResources[];

const modules = import.meta.glob<{default: Record<string, TranslationResources>}>('./locales/*.json', { eager: true })

const resources: Record<string, { translation: Record<string, TranslationResources> }> = {};

for (const path in modules) {
 const lang = path.match(/.\/locales\/(.*)\.json$/)?.[1];
 if (lang) {
 resources[lang] = { translation: modules[path].default };
 }
}

i18n
 .use(LanguageDetector) // detect browser/localStorage/etc.
 .use(initReactI18next)
 .init({
 resources,
 fallbackLng: "en",
 supportedLngs: ["en", "fr", "de", "ar"], // adjust to your languages
 interpolation: { escapeValue: false },
 detection: {
 order: ["querystring", "localStorage", "cookie", "navigator"],
 caches: ["localStorage", "cookie"],
 }
 });

export default i18n;

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

type TranslationResources = string | { [k: string]: TranslationResources } | TranslationResources[];

const modules = import.meta.glob<{default: Record<string, TranslationResources>}>('./locales/*.json', { eager: true })

const resources: Record<string, { translation: Record<string, TranslationResources> }> = {};

for (const path in modules) {
  const lang = path.match(/\.\/locales\/(.*)\.json$/)?.[1];
  if (lang) {
    resources[lang] = { translation: modules[path].default };
  }
}

i18n
  .use(LanguageDetector) // detect browser/localStorage/etc.
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de", "ar"], // adjust to your languages
    interpolation: { escapeValue: false },
    detection: {
      order: ["querystring", "localStorage", "cookie", "navigator"],
      caches: ["localStorage", "cookie"],
    }
  });

export default i18n;

Los usuarios ahora verán automáticamente la aplicación en su idioma preferido cuando esté disponible.

Carga diferida de traducciones

En este momento, i18next carga todos los archivos de traducción al inicio. Para las aplicaciones con muchos idiomas, la carga diferida reduce el tamaño inicial del paquete al descargar solo los archivos de idioma que necesita el usuario.

Instale el backend HTTP:

npm install i18next-http-backend

npm install i18next-http-backend

Actualice src/i18n/index.ts:

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import Backend from "i18next-http-backend";
import LanguageDetector from "i18next-browser-languagedetector";

i18n
 .use(Backend) // load JSON over HTTP
 .use(LanguageDetector)
 .use(initReactI18next)
 .init({
 fallbackLng: "en",
 supportedLngs: ["en", "fr"],
 interpolation: { escapeValue: false },
 backend: {
 loadPath: "/locales/{{lng}}/{{ns}}.json"
 }
 });

export default i18n;

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import Backend from "i18next-http-backend";
import LanguageDetector from "i18next-browser-languagedetector";

i18n
  .use(Backend) // load JSON over HTTP
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",
    supportedLngs: ["en", "fr"],
    interpolation: { escapeValue: false },
    backend: {
      loadPath: "/locales/{{lng}}/{{ns}}.json"
    }
  });

export default i18n;

Mueva sus archivos de traducción al directorio público:

public/
 locales/
 en/
 translation.json
 fr/
 translation.json

public/
  locales/
    en/
      translation.json
    fr/
      translation.json

Con esta estructura, i18next obtendrá los archivos de traducción a través de HTTP en lugar de agruparlos. Cuando un usuario cambia a francés, i18next obtiene /locales/fr/translation.json a petición.

Traduzca su aplicación React con PTC

Su aplicación ya está lista para la localización por IA. Utilice PTC para traducir sus archivos JSON automáticamente. Sus primeras 20.000 palabras son gratuitas.

Pruebe PTC ahora