PTC
Registrarse Cambiar a Pro Su cuenta

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

Configure react-i18next, traduzca en.json a más de 40 idiomas con IA y luego 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: la configuración de react-i18next, el manejo de plurales y contenido dinámico, la traducción de su en.json a más de 40 idiomas con PTC y el cambio de idioma en tiempo de ejecución. Al final dispondrá de una configuración de localización de React funcional y lista para lanzar. Para una visión general de la herramienta autónoma de traducción de JSON, consulte traducir archivos JSON en línea con IA.

Cómo se ve una aplicación React localizada

Una aplicación React en la que:

  • Todas las cadenas visibles para el usuario residen en archivos de traducción JSON dentro de src/i18n/locales/ (o public/locales/).
  • Un selector de idioma alterna entre inglés, español, francés y alemán.
  • El contenido dinámico (nombres de usuario, recuentos, fechas) se interpola correctamente según la configuración regional.
  • Los plurales siguen las reglas de cada idioma de destino.
  • Los archivos .json traducidos los produce PTC, no se escriben a mano.

Paso 1: Crear 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 reemplazar las cadenas codificadas por t()

npm install i18next react-i18next

Cree la estructura de carpetas de su React i18n:

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 React típico con cadenas codificadas:

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:

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 configuración regional 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 detecta 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 se renderice su aplicación. 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 omite este paso, t() devolverá las claves de traducción en lugar del texto traducido.

Paso 4: Interpolar variables, plurales y enlaces con las convenciones de i18next

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. 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 maneja idiomas con más de dos formas plurales (polaco, árabe, ruso) sin configuración adicional.

Traducir enlaces y HTML con el componente Trans

Para traducciones que contienen 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 asignan a los elementos secundarios (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 dentro del componente y, al mismo tiempo, permite a los traductores reordenar el texto circundante de forma natural.

Formatear fechas, números y monedas con Intl

Utilice los formateadores de 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 en.json y necesita producir es.json, fr.json, de.json, etc. PTC está diseñado exactamente para esto.

  1. Inicie un proyecto de PTC y elija el inglés como idioma de origen. La prueba gratuita cubre 20.000 palabras a 2 idiomas, sin tarjeta de crédito.
  2. Suba 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 de su público. PTC utiliza este contexto para ajustar el tono y la terminología en todos los idiomas.
  4. Elija los idiomas de destino y confirme. PTC produce un archivo .json traducido por cada idioma de destino, estructuralmente idéntico al de origen. Las mismas claves, el mismo anidamiento, los mismos marcadores de posición. Valores traducidos.
  5. Coloque los archivos en src/i18n/locales/. Gracias a la carga automática de import.meta.glob que configuró en el Paso 3, los nuevos archivos funcionan de inmediato 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 PTC API para integrar la traducción en su flujo de CI/CD. Las nuevas cadenas en en.json desencadenan una traducción automática. PTC abre un PR con los archivos actualizados en el idioma de destino.

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

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() desencadena un nuevo renderizado de cada componente que utiliza useTranslation(), por lo que toda la interfaz se actualiza de inmediato. 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 a partir de la configuración del navegador, la URL o las preferencias guardadas del usuario:

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'],
    },
  });

Cargar traducciones de forma diferida con i18next-http-backend

De forma predeterminada, 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 únicamente 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

Cambiar a francés ahora obtiene /locales/fr/translation.json bajo demanda en lugar de empaquetarlo. El paquete inicial se mantiene reducido independientemente de cuántos idiomas admita.

Revisión visual de la traducción de su aplicación React en ejecución - lanzar sin QA manual por lanzamiento

Después de que PTC traduzca su en.json, aún necesita verificar la aplicación React en ejecución. Una etiqueta traducida puede desbordar un botón en alemán. "Save" puede traducirse como sustantivo en francés cuando la interfaz necesitaba un verbo. Una cadena en inglés codificada fuera de t() se renderizará sin traducir, sin importar cuántos idiomas lance.

La revisión visual con IA de PTC sustituye la pasada de QA manual. Para aplicaciones basadas en navegador como React, la variante adecuada es la extensión de navegador. Instálela una vez y grabe un recorrido breve de los flujos de usuario críticos de su aplicación React (inicio de sesión, función principal, ajustes). A partir de entonces, 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 se ajuste a un botón o regenera una forma plural.
  • Indicaciones de Cursor / Claude Code cuando el problema está en el código de su componente. Una cadena en inglés codificada fuera de t(), una oración construida mediante concatenación de cadenas en lugar de t('key', { var }), un componente Trans faltante para traducciones de texto enriquecido.

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

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

Sus notas de versión, páginas de marketing, páginas de aterrizaje y correos electrónicos a clientes residen fuera de en.json. La función «Paste to Translate» de PTC maneja ese texto en el mismo proyecto. Pegue el texto de origen en el panel de PTC, elija los idiomas de destino y obtenga traducciones que utilicen el mismo glosario y la misma voz de marca que las cadenas de la interfaz React.

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

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

Ahora traduzca su archivo en.json

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

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

En cualquier caso, instale la extensión de navegador y deje que la revisión visual con IA verifique su aplicación React en ejecución en cada idioma antes de lanzarla.