PTC
Registrarse Pasar a Pro Su cuenta

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

Configure react-i18next, traduzca su archivo en.json a más de 40 idiomas con IA y, a continuación, deje que la extensión de navegador de PTC (Private Translation Cloud) revise la aplicación React en ejecución en cada lanzamiento. Esta guía cubre la internacionalización de React de principio a fin: configuración de react-i18next, gestión de plurales y contenido dinámico, traducción de su en.json a más de 40 idiomas con PTC y cambio de idioma en tiempo de ejecución. Al finalizar, dispondrá de una configuración de localización de React lista para producción. Para obtener una visión general de la herramienta de traducción de JSON independiente, consulte traducir archivos JSON online con IA.

Cómo es una aplicación React localizada

Una aplicación React donde:

  • Todas las cadenas visibles para el usuario residen en archivos de recursos JSON bajo src/i18n/locales/ (o public/locales/).
  • Un selector de idiomas permite alternar entre inglés, español, francés y alemán.
  • El contenido dinámico (nombres de usuario, recuentos, fechas) se interpola correctamente según el locale.
  • Los plurales siguen las reglas de cada idioma de destino.
  • Los archivos .json traducidos son generados por PTC, no escritos a mano.

Paso 1: Crear la estructura de una aplicación React + TypeScript con Vite

Esta guía utiliza una aplicación React + TypeScript creada con Vite. Si está añadiendo react-i18next a una aplicación existente, salte al Paso 2.

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.

Paso 2: Instalar react-i18next y sustituir las cadenas fijas por t()

npm install i18next react-i18next

Cree la estructura de carpetas para la i18n de React:

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"
}

Un componente de React típico con cadenas de texto fijas (hardcoded):

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

Sustituya el texto fijo con el hook useTranslation:

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;

useTranslation() devuelve:

  • t(): busca una cadena por su clave.
  • i18n: le permite cambiar de idioma mediante programación.

Paso 3: Cargar automáticamente cada JSON de locale con import.meta.glob

Cree src/i18n/index.ts para configurar i18next y cargar automáticamente los archivos de traducción. El patrón import.meta.glob significa que cada archivo .json que añada a src/i18n/locales/ se detectará automáticamente. Sin importaciones manuales al añadir nuevos idiomas:

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;

Importe i18n antes de que su aplicación se renderice. Abra src/main.tsx y añada la importación:

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';
import './index.css';
import './i18n'; // <- add this

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

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

Interpolar variables con {{variableName}}

Utilice la sintaxis {{variableName}} en su JSON y pase el valor a t(). Actualice en.json:

{
  "welcome": "Welcome",
  "userGreeting": "Welcome back, {{firstName}}!",
  "description": "This is a localization demo.",
  "clickMe": "Click me"
}
const user = { firstName: 'Sarah' };
<p>{t('userGreeting', { firstName: user.firstName })}</p>

El segundo argumento de t() es un objeto con los valores que desea sustituir. Puede usar tantas variables como necesite.

Pluralizar con los sufijos de clave _one / _other

Utilice el patrón de sufijos _one / _other. La variable debe llamarse count:

{
  "newMessages_one": "You have {{count}} new message.",
  "newMessages_other": "You have {{count}} new messages."
}
<p>{t('newMessages', { count: messageCount })}</p>

i18next selecciona automáticamente la forma plural correcta. También gestiona idiomas con más de dos formas plurales (polaco, árabe, ruso) sin configuración adicional.

Para traducciones que contengan elementos HTML como enlaces o texto en negrita, utilice el componente Trans:

{
  "termsText": "I agree to the <1>Terms of Service</1> and <3>Privacy Policy</3>."
}

Las etiquetas <1> y <3> son marcadores de posición basados en índices que se mapean con los elementos hijos (contando desde 0):

import { Trans } from 'react-i18next';

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

Esto mantiene sus elementos JSX en el componente mientras permite a los traductores reordenar el texto circundante de forma natural.

Formatear fechas, números y monedas con Intl

Utilice los formateadores Intl en lugar de incrustar cadenas de formato en sus traducciones:

const formatDate = (date: Date, locale: string) =>
  new Intl.DateTimeFormat(locale, { dateStyle: 'long' }).format(date);

const formatCurrency = (amount: number, locale: string, currency: string) =>
  new Intl.NumberFormat(locale, { style: 'currency', currency }).format(amount);

const { i18n } = useTranslation();
<p>{formatDate(new Date(), i18n.language)}</p>
<p>{formatCurrency(199.99, i18n.language, 'EUR')}</p>

Paso 5: Traducir los archivos JSON con PTC en 5 pasos

Ahora tiene su en.json y necesita generar es.json, fr.json, de.json, etc. PTC está diseñado exactamente para esto.

  1. Inicie un proyecto en PTC y elija el inglés como origen. La prueba gratuita cubre 20.000 palabras a 2 idiomas, sin tarjeta de crédito.
  2. Suba su en.json. PTC analiza la estructura anidada, reconoce los marcadores de posición de i18next ({{name}}, {{count}}) y detecta los sufijos de plural (_one, _other).
  3. Añada una breve descripción de su aplicación React y su audiencia. PTC utiliza este contexto para adaptar el tono y la terminología en todos los idiomas.
  4. Elija los idiomas de destino y confirme. PTC genera un archivo .json traducido para cada idioma de destino, estructuralmente idéntico al de origen. Mismas claves, misma anidación, mismos marcadores de posición. Valores traducidos.
  5. Coloque los archivos en src/i18n/locales/. Gracias a la carga automática con import.meta.glob que configuró en el Paso 3, los nuevos archivos funcionarán inmediatamente sin cambios en el código.

Una vez que haya traducido su primer archivo con PTC, puede pasar a un proceso automatizado. Conecte su repositorio de GitHub, GitLab o Bitbucket mediante la integración con Git, o utilice la API de PTC para integrar la traducción en su pipeline de CI/CD. Las nuevas cadenas en en.json activan la traducción automática. PTC abre un pull request con los archivos de los idiomas de destino actualizados.

Paso 6: Verificar la configuración con un selector de idiomas

Añada botones de idioma para verificar que su configuración de react-i18next funciona:

import { useTranslation } from 'react-i18next';

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

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

i18n.changeLanguage() activa un nuevo renderizado de cada componente que use useTranslation(), por lo que toda la interfaz de usuario se actualiza inmediatamente. Sin recargar la página.

Detectar automáticamente el idioma del usuario con i18next-browser-languagedetector

Instale i18next-browser-languagedetector para cargar automáticamente el idioma correcto basándose en la configuración del navegador del usuario, la URL o las preferencias guardadas:

npm install i18next-browser-languagedetector
import LanguageDetector from 'i18next-browser-languagedetector';

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: 'en',
    supportedLngs: ['en', 'fr', 'de', 'ar'],
    interpolation: { escapeValue: false },
    detection: {
      order: ['querystring', 'localStorage', 'cookie', 'navigator'],
      caches: ['localStorage', 'cookie'],
    },
  });

Carga diferida (lazy-load) de traducciones con i18next-http-backend

Por defecto, todos los archivos de traducción se empaquetan en el momento de la compilación. Para aplicaciones con muchos idiomas, utilice i18next-http-backend para obtener solo el idioma que el usuario realmente necesita:

npm install i18next-http-backend
import Backend from 'i18next-http-backend';

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

Mueva sus archivos de traducción a public/locales/ para que se sirvan como activos estáticos:

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

Al cambiar al francés, ahora se obtendrá /locales/fr/translation.json bajo demanda en lugar de incluirlo en el paquete inicial. El bundle inicial se mantiene ligero independientemente de cuántos idiomas soporte.

Revisión visual de la traducción de su aplicación React en ejecución: publique sin control de calidad manual en cada lanzamiento

Después de que PTC traduzca su en.json, todavía necesita verificar la aplicación React en ejecución. Una etiqueta traducida puede causar un desbordamiento en un botón en alemán. “Save” puede traducirse como un sustantivo en francés cuando la interfaz requería un verbo. Una cadena en inglés fija fuera de t() se renderizará sin traducir, sin importar cuántos idiomas ofrezca.

AI Visual QA de PTC sustituye la fase de control de calidad manual. Para aplicaciones basadas en navegador como React, la opción adecuada es la extensión de navegador. Instálela una vez y grabe un breve recorrido por los flujos de usuario críticos de su aplicación React (inicio de sesión, función principal, ajustes). A partir de ahí, PTC reproduce la grabación en cada idioma de destino tras cada actualización de traducción, captura cada pantalla e inspecciona el resultado renderizado:

  • Correcciones en los archivos de traducción cuando PTC los controla. PTC vuelve a traducir una categoría gramatical incorrecta, elige un sinónimo más corto que quepa en un botón o regenera una forma plural.
  • Prompts para Cursor / Claude Code cuando el problema está en el código de su componente. Una cadena en inglés fija fuera de t(), una frase construida mediante concatenación de cadenas en lugar de t('key', { var }) o la falta de un componente Trans para traducciones con texto enriquecido.

El resultado: la revisión como un paso más de la CI. Cada lanzamiento se publica con verificación visual en todos los idiomas de destino, sin cuellos de botella humanos.

Traducir notas de lanzamiento, páginas de marketing y correos electrónicos a clientes

Sus notas de lanzamiento, páginas de marketing, landing pages y correos electrónicos a clientes residen fuera de en.json. La función Pegar para traducir de PTC gestiona esos textos en el mismo proyecto. Pegue el texto de origen en el panel de control de PTC, elija los idiomas de destino y obtenga traducciones que utilicen el mismo glosario y voz de marca que las cadenas de la interfaz de su aplicación React.

Traducir comentarios de usuarios, publicaciones y resultados de búsqueda con la API de PTC

Los comentarios de los usuarios, las publicaciones, los resultados de búsqueda y cualquier otro contenido generado por el usuario que gestione su aplicación React necesitan traducción a medida que llegan. La API REST de PTC traduce este contenido bajo demanda con autenticación mediante token Bearer, utilizando el mismo glosario y voz de marca que sus traducciones de en.json.

Ahora traduzca su archivo en.json

Comience su prueba gratuita de 30 días: 20.000 palabras en 2 idiomas, sin tarjeta de crédito. Dos caminos:

  • Manual: suba src/i18n/locales/en.json en la página de traducción de JSON.
  • Basado en CI: conecte su repositorio Git a través de la API de PTC y las traducciones se realizarán automáticamente en cada push.

En cualquier caso, instale la extensión de navegador y deje que AI Visual QA verifique su aplicación React en ejecución en todos los idiomas antes de publicar.