PTC
Registrarse Actualizar a Pro Su cuenta

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

Configure react-i18next, traduzca en.json a más de 40 idiomas con IA y, a continuación, deje que la extensión de navegador del PTC (Private Translation Cloud) revise la aplicación de React en ejecución en cada lanzamiento. Esta guía cubre la internacionalización de React de principio a fin: configurar react-i18next, procesar plurales y contenido dinámico, traducir sus en.json a más de 40 idiomas con el PTC y cambiar de idioma en tiempo de ejecución. Al final, tendrá una configuración de localización de React funcional y lista para publicar. Para obtener una descripción general de la herramienta independiente de traducción de JSON, consulte traducir archivos JSON en línea con IA.

Cómo se ve una aplicación de React localizada

Una aplicación de React donde:

  • Todas las cadenas de la interfaz se encuentran en archivos de traducción JSON en 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 para cada locale.
  • Los plurales siguen las reglas de cada idioma de destino.
  • Los archivos .json traducidos son producidos por el PTC, no escritos a mano.

Paso 1: Genere una aplicación de React + TypeScript con Vite

Esta guía utiliza una aplicación de React + TypeScript compilada con Vite. Si está añadiendo react-i18next a una aplicación existente, pase 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: Instale react-i18next y reemplace las cadenas incrustadas en el código con t()

npm install i18next react-i18next

Cree la estructura de carpetas i18n de su aplicación 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 típico de React con cadenas incrustadas en el código:

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 incrustado en el código 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 de forma programática.

Paso 3: Cargue 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 omite este paso, t() devolverá las claves de traducción en lugar del texto traducido.

Interpole 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.

Pluralice con los sufijos de clave _one / _other

Utilice el patrón de sufijo _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 la forma plural correcta automáticamente. También procesa idiomas con más de dos formas plurales (polaco, árabe, ruso) sin configuración adicional.

Para las 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 en el componente y, al mismo tiempo, permite a los traductores reordenar el texto circundante de forma natural.

Formatee 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: Traduzca los archivos JSON con PTC en 5 pasos

Ahora tiene en.json y necesita generar 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 origen. La prueba de 30 días cubre 20.000 palabras en 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 plurales (_one, _other).
  3. Añada una breve descripción de su aplicación React y de su público. PTC utiliza este contexto para mantener el mismo tono y terminología en todos los idiomas.
  4. Elija los idiomas de destino y confirme. PTC genera un .json traducido por cada idioma de destino, estructuralmente idéntico al archivo 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 de import.meta.glob que configuró en el Paso 3, los nuevos archivos funcionan de inmediato sin necesidad de cambiar 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 merge request con los archivos actualizados en el idioma de destino.

Paso 6: Verifique 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() activa un nuevo renderizado de todos los componentes que utilizan useTranslation(), por lo que toda la interfaz de usuario se actualiza de inmediato. Sin recargar la página.

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

Cargue las traducciones bajo demanda con i18next-http-backend

Por defecto, todos los archivos de traducción se incluyen en el paquete durante 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 recursos estáticos:

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

Ahora, al cambiar al francés, se obtiene /locales/fr/translation.json bajo demanda en lugar de incluirlo en el paquete. El paquete inicial se mantiene ligero independientemente de cuántos idiomas admita.

Revisión visual de la traducción de su aplicación React en ejecución: publique sin control de calidad manual por 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 desbordar un botón en alemán. «Save» (guardar) podría traducirse como un sustantivo en francés cuando la interfaz necesitaba un verbo. Una cadena en inglés incrustada en el código fuera de t() se renderizará sin traducir, sin importar cuántos idiomas publique.

AI Visual QA de PTC sustituye la pasada de control de calidad manual. Para las aplicaciones basadas en el navegador como React, la variante adecuada es la extensión de navegador. Instálela una vez y grabe un breve recorrido de los flujos de usuario críticos de su aplicación React (inicio de sesión, función principal, configuración). A partir de entonces, PTC vuelve a ejecutar la grabación en cada idioma de destino después de cada actualización de la 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 encaje 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 incrustada en el código fuera de t(), una oración construida mediante concatenación de cadenas en lugar de t('key', { var }), o un componente Trans que falta para las traducciones de texto enriquecido.

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

Traduzca las notas de lanzamiento, las páginas de marketing y los correos electrónicos para clientes

Sus notas de lanzamiento, páginas de marketing, páginas de destino y correos electrónicos para clientes viven fuera de en.json. La función Paste to Translate de PTC procesa ese texto en el mismo proyecto. Pegue el texto de origen en el panel de control de PTC, elija los idiomas de destino y reciba traducciones que utilizan el mismo glosario y voz de marca que las cadenas de la interfaz de React.

Traduzca 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 procese su aplicación React necesitan traducirse a medida que llegan. La API REST de PTC traduce este contenido bajo demanda con autenticación Bearer, utilizando el mismo glosario y voz de marca que sus traducciones de en.json.

Ahora traduzca su archivo en.json

Comience su prueba 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.
  • Impulsado por CI: conecte su repositorio Git a través de la API de PTC y cualquier push que cambie sus cadenas de origen volverá traducido.

De cualquier manera, instale la extensión de navegador y deje que AI Visual QA verifique su aplicación React en ejecución en cada idioma antes de publicarla.