Saltar al contenido principal

React

El paquete translate-projects-react traduce los archivos JSON de react-i18next de tu app a varios idiomas y conserva la estructura de claves. Opcionalmente extrae los textos de tu código con un escáner.

Requisitos​

  • Node.js 20 o superior.
  • Una app React (por ejemplo, creada con Vite) con i18next y react-i18next.
  • Un proyecto y un API token de Translate Projects. Mira Primeros pasos.

1. Instala los paquetes​

Terminal
npm i i18next react-i18next i18next-http-backend
npm i translate-projects-react

2. Configura i18next​

Crea src/i18n.js. Los archivos de cada idioma se cargan desde public/locales/<lang>/translation.json:

src/i18n.js
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import HttpBackend from 'i18next-http-backend';

i18n
  .use(HttpBackend)
  .use(initReactI18next)
  .init({
    lng: 'es',
    fallbackLng: 'es',
    ns: ['translation'],
    defaultNS: 'translation',
    interpolation: { escapeValue: false },
    backend: { loadPath: '/locales/{{lng}}/{{ns}}.json' },
  });

export default i18n;

Impórtalo una vez en src/main.jsx:

src/main.jsx
import './i18n';

3. Escribe tus textos​

Pon los textos del idioma base en public/locales/<idioma base>/translation.json (se admiten claves anidadas):

public/locales/es/translation.json
{
  "home": {
    "title": "Bienvenido",
    "subtitle": "Traduce tu app en minutos"
  }
}

Y úsalos en tus componentes:

src/App.jsx
import { useTranslation, Trans } from 'react-i18next';

export default function App() {
  const { t } = useTranslation();
  return (
    <>
      <h1>{t('home.title')}</h1>
      <Trans>Hola, este texto también se traduce</Trans>
    </>
  );
}

Con el escáner activado (scanner: true), los textos de t('...') y <Trans> de tu código se añaden solos a translation.json. Se ignoran los textos muy cortos, las rutas, las URL y las plantillas con variables.

4. Configura la traducción​

Crea translate.mjs en la raíz del proyecto. Si no pasas apiKey, se usa la variable de entorno TRANSLATE_PROJECTS_API_KEY. Si prefieres CommonJS, llámalo translate.cjs y usa require.

translate.mjs
import { translateProject } from 'translate-projects-react';

await translateProject({
  sourceLang: 'es', // Idioma base: el idioma por defecto del proyecto
  targetLangs: ['en', 'pt-BR', 'fr'], // Idiomas a generar
  outputDir: './public/locales', // Valor por defecto
  scanner: true, // Opcional: extrae los textos de ./src
});
OpciónPor defectoDescripción
sourceLang—Idioma base (obligatorio).
targetLangs—Idiomas a generar.
apiKeyprocess.env.TRANSLATE_PROJECTS_API_KEYAPI token del proyecto.
outputDir./public/localesCarpeta con una subcarpeta por idioma.
scannerfalsetrue escanea ./src; { sourceDir: './app' } escanea otra carpeta.

Guarda el token en un archivo .env (fuera de git) y añade el script en package.json. --env-file necesita Node 20.6 o superior; en CI define la variable como secreto:

.env
TRANSLATE_PROJECTS_API_KEY=tu_token
package.json
{
  "scripts": {
    "translate": "node --env-file=.env translate.mjs"
  }
}

5. Traduce​

Terminal
npm run translate

Traducción en la terminal

Archivos que genera​

public/locales/
├── es/translation.json   ← tu idioma base (o el que genera el escáner)
├── en/translation.json   ← generado
├── pt-BR/translation.json
└── fr/translation.json

Cada archivo conserva la estructura anidada del original. Los idiomas se traducen en paralelo, hasta 3 a la vez.

Autocompletado de claves (opcional)​

src/Title.tsx
import { useTypedTranslation } from 'translate-projects-react/hooks';
import es from '../public/locales/es/translation.json';

export function Title() {
  const { t } = useTypedTranslation<typeof es>();
  return <h1>{t('home.title')}</h1>; // Las claves se autocompletan y se validan
}

Autocompletado de claves

Caché y forzar​

Solo se envían los archivos y las claves que cambiaron; una segunda ejecución sin cambios no traduce nada. Este paquete no tiene --force: para traducir todo de nuevo, borra ~/.config/translate-projects-core/cache.json y vuelve a ejecutar. Más detalles en Caché y errores.

Errores comunes​

translateProject devuelve true si todo salió bien. Si algo falla muestra el error real, devuelve false y deja el código de salida en 1, sin cerrar tu proceso.

  • Token inválido (401): revisa TRANSLATE_PROJECTS_API_KEY. Los archivos existentes no se tocan.
  • Falta la key de IA (MISSING_API_KEY): configura el proveedor, el modelo y la key en el proyecto. Mientras tanto los textos quedan en el idioma base.
  • Traducción parcial: los textos que faltan se piden otra vez en la siguiente ejecución.
  • JSON inválido: si un archivo del idioma base no es JSON válido, no se escribe nada para él.
Gratis

🚀 Automatiza tus traducciones gratis​

Translate Projects es gratuito. Creas tu proyecto, conectas la key de tu proveedor de IA y solo le pagas a él lo que gastes.

  • Sin planes ni tarjeta de crédito: Todas las funciones están disponibles desde el primer día.
  • Usa tu propia IA: Claude, OpenAI, DeepSeek o Gemini. Tu key se guarda cifrada.
  • Red de traducciones compartida: Si un texto ya fue traducido, lo recibes al instante sin gastar tu key.
  • Panel de administración: Revisa y edita todas tus traducciones desde un solo lugar.

Crear cuenta gratis →

Soporte

Estamos aquí para ayudarte​

Si tienes alguna pregunta, necesitas ayuda o quieres contribuir, no dudes en contactarme. Estoy a tu disposición para apoyarte en lo que necesites.

Apoya el Proyecto​

Si este proyecto te ha sido útil, te invito a invitarme un café. Tu apoyo me ayuda a seguir mejorando y creando contenido de valor. ¡Gracias por estar aquí! ☕

Buy me a coffee