Docusaurus

El paquete translate-projects-docusaurus traduce las páginas de documentación, el blog, las páginas React (code.json) y los textos del tema de un sitio Docusaurus, y los escribe en la estructura i18n/ que Docusaurus ya entiende.

Requisitos

• Node.js 20 o superior.
• Un sitio Docusaurus 3 con el script write-translations en package.json (viene en la plantilla oficial).
• Un proyecto y un API token de Translate Projects. Mira Primeros pasos.

1. Instala el paquete

Terminal

npm i -D translate-projects-docusaurus

2. Activa los idiomas en Docusaurus

Añade los idiomas en docusaurus.config.js y el selector de idioma en la barra de navegación:

docusaurus.config.js

export default {
  i18n: {
    defaultLocale: 'es',
    locales: ['es', 'en', 'pt-BR', 'fr'],
    localeConfigs: {
      es: { label: 'Español' },
      en: { label: 'English' },
      'pt-BR': { label: 'Português (Brasil)' },
      fr: { label: 'Français' },
    },
  },
  themeConfig: {
    navbar: {
      items: [{ type: 'localeDropdown', position: 'right' }],
    },
  },
};

3. Escribe tus textos en la carpeta translate/

Mueve tus carpetas docs/ y blog/ a translate/. A partir de ahora editas solo translate/: el paquete genera docs/, blog/ e i18n/ en cada ejecución.

Terminal

mkdir translate
mv docs blog translate/

Estructura

translate/
├── docs/
│   └── intro.md
└── blog/
    └── 2025-01-01-bienvenida.md

Encierra entre llaves dobles cada texto que quieras traducir. Lo que no esté marcado (código, enlaces, nombres) se copia tal cual:

translate/docs/intro.md

---
title: {{Primeros pasos}}
---

# {{Bienvenido a mi proyecto}}

{{Este párrafo se traduce.}} [{{Ver ejemplo}}](https://example.com)

• Escribe el texto pegado a las llaves, sin espacios al principio ni al final.
• Para escribir llaves literales (por ejemplo, las variables de i18next en un bloque de código), pon una barra invertida delante. No se envían a traducir y la barra desaparece en el resultado: \{{lng}} → {{lng}}.
• Fuera de los bloques de código, MDX no admite llaves sueltas: no dejes llaves dobles sin cerrar.

4. Configura la traducción

Crea translate.config.mjs en la raíz del sitio. El API token se lee de la variable de entorno TRANSLATE_PROJECTS_API_KEY:

translate.config.mjs

export default {
  sourceLang: 'es', // Idioma base: el idioma por defecto del proyecto
  targetLangs: ['en', 'pt-BR', 'fr'], // Idiomas a generar
  apiKey: process.env.TRANSLATE_PROJECTS_API_KEY,
};

Y el script en package.json:

package.json

{
  "scripts": {
    "translate": "translate-projects-docusaurus"
  }
}

Opciones

Opción	Por defecto	Descripción
sourceLang	—	Idioma base (obligatorio).
targetLangs	—	Idiomas a generar (obligatorio).
apiKey	—	API token del proyecto.
force	false	Ignora la caché y vuelve a traducir todo (igual que --force).
docs	{ enable: true, baseDir: './translate/docs', outputDir: './docs' }	Documentación.
blog	{ enable: true, baseDir: './translate/blog', outputDir: './blog' }	Blog. Desactívalo si tu sitio no tiene blog.
react	{ enable: true }	Textos de tus páginas React (i18n/<lang>/code.json).
theme	{ enable: true, ignoreKeys: [] }	Textos del tema (barra de navegación y pie). En ignoreKeys van las claves que no se traducen.
config	{ outputDir: './i18n' }	Carpeta i18n de Docusaurus.

5. Traduce

Terminal

export TRANSLATE_PROJECTS_API_KEY=tu_token
npm run translate

Después compila el sitio con todos los idiomas:

Terminal

npm run build
npm run serve

Archivos que genera

Origen	Idioma base	Otros idiomas
translate/docs/**	docs/**	i18n/<lang>/docusaurus-plugin-content-docs/current/**
translate/blog/**	blog/**	i18n/<lang>/docusaurus-plugin-content-blog/**
i18n/<base>/code.json	—	i18n/<lang>/code.json
i18n/<base>/docusaurus-theme-classic/*.json	—	i18n/<lang>/docusaurus-theme-classic/*.json

Las imágenes y demás archivos que no son texto se copian a cada idioma. Si despliegas desde el repositorio, incluye docs/, blog/ e i18n/ en el despliegue o ejecuta la traducción antes del build.

Vista previa mientras escribes

El modo --dev vigila translate/ y actualiza el idioma base al instante, sin llamar a la API:

Terminal 1

npx docusaurus start --locale es

Terminal 2

npx translate-projects-docusaurus --dev

Caché y --force

Solo se traducen los archivos que cambiaron; una segunda ejecución sin cambios no traduce nada. Para traducir todo de nuevo:

Terminal

npx translate-projects-docusaurus --force

Más detalles en Caché y errores.

Errores comunes

• Token inválido (401): revisa TRANSLATE_PROJECTS_API_KEY. No se escribe ni se borra ningún archivo.
• 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 quedan en el idioma base, el comando termina con código 1 y se piden otra vez en la siguiente ejecución.
• El build falla con Invalid translation file: hay un JSON vacío o roto en i18n/. Bórralo y ejecuta npm run write-translations -- --locale <lang>.
• Aparecen llaves dobles en la página traducida: el texto tenía espacios dentro de las llaves o eran llaves literales sin \.

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.

• Sitio web: neiderruiz.com
• GitHub: @neiderruiz
• Twitter: @neiderruiz
• YouTube: Neider Ruiz

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í! ☕