Docusaurus

Creación proyecto

• Creación proyecto basico guia de instalación oficial.

  npx create-docusaurus@latest my-website-example classic

• Creación proyecto con TypeScript

  npx create-docusaurus@latest my-website-example classic --typescript

Configurar Translate Projects

Debemos de instalar el paquete de translate-projects-docusaurus en nuestro proyecto.

npm i translate-projects-docusaurus -D

Añadir configuración i18n en docusaurus.config.js

El archivo debe de tener la siguiente estructura con los idiomas que quieras traducir.

Puedes ver la configuración oficial configuración i18n docusaurus

docusaurus.config.js

  i18n: {
    defaultLocale: 'es',
    locales: ['es','fr','en','hi','de'],
    localeConfigs: {
      es: { label: 'Español' },
      fr: { label: 'Français' },
      en: { label: 'English' },
      hi: { label: 'हिंदी' },
      de: { label: 'Deutsch' },
    },
  },

Añadir lista de idiomas en el menu de la barra lateral

Puedes ver mas información de posiicionamiento en su documentación Navbar posicionamiento

docusaurus.config.js

export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'localeDropdown',
          position: 'right',
        },
      ],
    },
  },
};

Visualizaras algo como esto en tu sitio web 🤯

Crea carpeta base para traducciones

Crea una carpeta llamada translate en la raiz de tu proyecto, en ella vas a estar creando tu estructura de directorios, para la documentación de tu proyecto.

Creación carpeta

mkdir translate

Despues de crear la carpeta translate vamos a copiar nuestras carpetas de interes a traducir dentro

Hacer copia de nuestro proyecto

cp -r docs translate/
cp -r blog translate/

Esta seria nuestra estructura de directorios

Estructura proyecto

docs/
blog/
translate/
  - docs/
  - blog/

Nuestra sintaxis es sencilla

Todo lo que coloques dentro de corchetes sera traducido, te dejo el siguiente ejemplo...

Muy importante utilizar las llaves dobles para que funcione y no olvidar cerrarlas.

Vamos a editar nuestro archivo translate/docs/intro.md, actualizaremos nuestro titulo y descripción.

Crear un archivo de configuración para las traducciones

Crea un archivo llamado translate.js dentro de la carpeta utils y añade el siguiente código:

Comando crear archivo

mkdir -p utils && touch utils/translate.js

• Configuración translate.js

utils/translate.js

const { translateProject }  = require('translate-projects-docusaurus');

translateProject({
    defaultLocale: 'es', //Idioma por defecto
    locales: ['en'], // Lista de idiomas
    apikey: '#' // Api Key
})

---

Crear cuenta

🚀 Automatiza y optimiza tus traducciones

Para aprovechar al máximo Translate Projects, necesitas una API Key. Regístrate sin compromiso.

• No pedimos tarjeta de crédito para probar Translate Projects

Beneficios al obtener tu API Key

• Administración Inteligente: Sincroniza y gestiona automáticamente las traducciones de tus proyectos.
• Panel Administrativo Exclusivo: Personaliza y supervisa todas tus traducciones desde una interfaz centralizada.
• Soporte Prioritario: Recibe asistencia técnica rápida y especializada cuando la necesites.
• Traducciones Precisas: Nuestra tecnología entiende el contexto de tu código para ofrecer traducciones exactas.
• 30.000 Eniacs de Bienvenida: Prueba todas las funciones sin compromiso con tokens internos que potencian tus traducciones.

¡Regístrate ahora y obtén tu API Key para desbloquear todo el potencial de Translate Projects!

Crear cuenta ahora→

---

Configurar comando para npm

Añadir el siguiente comando en tu archivo package.json:

package.json

"scripts": {
  "translate": "node ./utils/translate.js"
}

Habilitar vista previa en modo de desarrollo

Solo debes de habilitar el modo debug

utils/translate.js

const { translateProject }  = require('translate-projects-docusaurus');

translateProject({
    defaultLocale: 'es',
    locales: ['en'],
    apikey: '#',
    debug: true 
})

Antes debemos de activar idioma por defecto con el siguiente comando, en mi caso añadire es pero puedes usar el que tengas por defecto Documentación oficial write-translations

npm run write-translations -- --locale es

Ejecutar el comando npm run translate y vas a ver algo como esto:

Ejecutar el modo de debug

• Puedes ejecutar en una ventana de tu terminal

  docusaurus start --locale es

• En otra ventana de tu terminal ejecutas

  npm run translate

Estara escuchando los cambios que realices dentro de la carpeta ./translate, asi puedes ver en tu proyecto lo que estas modificando en tiempo real.

Cada ves que modifiques un archivo este se refrescara en tu sitio web automaticamente

Generar traducciones (producción)

• Debes de cambiar el modo debug=false

• luego ejecutas el comando

  npm run translate

  El tiempo de espera depende de la cantidad de traducciones que tengas

  

• Estructura de carpetas en el directorio i18n

  

Despues de tener tus traducciones, puedes compilar tu proyecto

npm run build

Cuando finalice ejecutas el comando npm run serve para ver tu resultado

npm run serve

Opciones de configuración

El objeto ConfigOptions le permite personalizar el comportamiento de Translate Projects. A continuación se muestra un desglose detallado de todas las opciones disponibles.

Configuración general (config)

Parametro	Tipo	Descripción
outputDir	string	El directorio donde se guardarán los archivos traducidos.

Idiomas

Parametro	Tipo	Descripción
locales	TypeListLang[]	Un array de idiomas admitidos por ejemplo ['es','en','ko']
defaultLocale	TypeListLang	El idioma predeterminado que se utilizará. es

API Key

Parametro	Tipo	Descripción
apiKey	string	Su clave API para el servicio de traducción.

Debug Mode

Parametro	Tipo	Descripción
debug	boolean	Habilita el modo de depuración para tener vista previa de tus cambios antes de enviar a traducir.

Blog Configuración (blog)

Parametro	Tipo	Descripción
baseDir	string	El directorio donde se encuentran los archivos de tu blog.
outputDir	string	El directorio donde se guardarán los archivos del blog traducidos.
enable	boolean	Habilita o deshabilita la traducción del blog.

Docs Configuración (docs)

Parametro	Tipo	Descripción
baseDir	string	El directorio donde se encuentran sus archivos de documentación.
outputDir	string	El directorio donde se guardarán los archivos de la documentación traducida.
enable	boolean	Habilita o deshabilita la traducción de la documentación.

React Configuración (react)

Parametro	Tipo	Descripción
enable	boolean	Habilita o deshabilita las funciones de traducción específicas de React.

Theme Configuración (theme)

Parametro	Tipo	Descripción
enable	boolean	Habilita o deshabilita la traducción del tema.
ignoreKeys	string[]	Un array de claves que se deben ignorar durante la traducción del tema.
recreateFiles	string	(Opcional) Especifica si se deben recrear los archivos de tema durante la traducción.

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