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 40+ idiomas con IA y, a continuación, deje que la extensión de navegador de 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: la configuración de react-i18next, el tratamiento de plurales y contenido dinámico, la traducción de su en.json a 40+ idiomas con PTC y el cambio de idiomas 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 de traducción de JSON independiente, consulte cómo traducir archivos JSON en línea con IA.

Qué aspecto tiene una aplicación de React localizada

Una aplicación de React donde:

  • Todas las cadenas de la interfaz residen 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 los produce PTC, no se escriben a mano.

Paso 1: Generar el esqueleto de una aplicación de React + TypeScript con Vite

Esta guía utiliza una aplicación de React + TypeScript compilada con Vite. Si va a añadir 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 hardcoded con t()

npm install i18next react-i18next

Cree la estructura de carpetas de 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 típico de React con cadenas hardcoded:

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 hardcoded 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 omite 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. 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 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, al tiempo que 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 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 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 de plural (_one, _other).
  3. Añada una breve descripción de su aplicación de React y su público objetivo. PTC utiliza este contexto para mantener la coherencia del tono y la terminología en cada idioma.
  4. Elija los idiomas de destino y confirme. PTC produce un .json traducido por cada idioma de destino, estructuralmente idéntico al origen. Mismas claves, mismo anidamiento, 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 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 a través de la integración con Git, o utilice la API de PTC para conectar la traducción a 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 los idiomas 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 está funcionando:

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 utiliza useTranslation(), por lo que toda la interfaz 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 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'],
    },
  });

Cargar traducciones de forma diferida con i18next-http-backend

Por defecto, todos los archivos de traducción se empaquetan en el momento de la compilación. Para las 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

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

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

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

AI Visual QA de PTC reemplaza la pasada de control de calidad manual. Para las aplicaciones basadas en 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 de 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, toma capturas de pantalla de cada una 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 de Cursor / Claude Code cuando el problema está en el código de su componente. Una cadena en inglés hardcoded fuera de t(), una oración construida por concatenación de cadenas en lugar de t('key', { var }) o un componente Trans faltante para traducciones de texto enriquecido.

El resultado: revisión como paso de 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 de clientes

Sus notas de lanzamiento, páginas de marketing, páginas de destino y correos electrónicos de clientes residen fuera de en.json. 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 utilicen el mismo glosario y voz de marca que las cadenas de la interfaz de 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 los usuarios que procese su aplicación de React necesitan traducción 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 las traducciones se realizarán automáticamente en cada push.

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