Ir al contenido principal

Herramientas de Documentación

La documentación se construye utilizando Docusaurus y se encuentra en la carpeta documentation. La documentación se aloja en GitHub Pages y ya no se incluye en la imagen del contenedor Docker.

Estructura de Carpetas​

documentation/
├── docs/              # Documentation markdown files (English source)
│   ├── api-reference/
│   ├── development/
│   ├── installation/
│   ├── migration/
│   ├── release-notes/
│   └── user-guide/
├── i18n/              # Translations (auto-generated by translation workflow)
│   ├── de/            # German
│   ├── es/            # Spanish
│   ├── fr/            # French
│   └── pt-BR/         # Brazilian Portuguese
├── src/               # React components and pages
│   ├── components/    # Custom React components
│   ├── css/           # Custom styles
│   └── pages/         # Additional pages (e.g., 404)
├── static/            # Static assets (images, files)
├── docusaurus.config.ts  # Docusaurus configuration
├── sidebars.ts        # Sidebar navigation configuration
├── package.json       # Dependencies and scripts
└── .intlayer/         # Intlayer generated UI translation files (auto-generated)

Internacionalización (i18n)​

La documentación utiliza el sistema de internacionalización integrado de Docusaurus con inglés como configuración regional predeterminada. El contenido traducido se encuentra en i18n/{locale}/docusaurus-plugin-content-docs/current/, reflejando la estructura de la carpeta docs/.

  • Archivos de origen: docs/**/*.md (Inglés)
  • Archivos traducidos: i18n/{locale}/docusaurus-plugin-content-docs/current/**/*.md
  • Traducciones de la interfaz de usuario: i18n/{locale}/docusaurus-theme-classic/*.json y otros archivos JSON
  • Capturas de pantalla localizadas: i18n/{locale}/docusaurus-plugin-content-docs/current/**/assets, generadas por pnpm take-screenhots en el directorio base.

El comando pnpm write-translations extrae cadenas de texto de la interfaz de usuario (del tema de Docusaurus y componentes personalizados) a archivos JSON de traducción. El script pnpm translate utiliza IA para traducir tanto la documentación markdown como los archivos JSON de la interfaz de usuario.

important

Solo edite archivos en docs/ y los archivos JSON de origen en i18n/en/. Los archivos markdown traducidos en i18n/{other-locales}/ se generan automáticamente y no deben editarse manualmente.

Configuraciones Regionales Compatibles​

Configuración regionalIdiomaDirectorio
enInglés (predeterminado)docs/ (origen)
deAlemáni18n/de/docusaurus-plugin-content-docs/current/
esEspañoli18n/es/docusaurus-plugin-content-docs/current/
frFrancési18n/fr/docusaurus-plugin-content-docs/current/
pt-BRPortugués brasileñoi18n/pt-BR/docusaurus-plugin-content-docs/current/

Traducir la Documentación​

La documentación utiliza un sistema de traducción con tecnología de IA para traducir tanto el contenido (archivos markdown) como las cadenas de la interfaz de usuario (de Docusaurus y componentes personalizados). El contenido de origen está en inglés (docs/), y se generan traducciones para alemán, francés, español y portugués brasileño.

Cómo Funciona la Traducción​

  1. Extracción de cadenas de la interfaz de usuario: pnpm write-translations extrae cadenas traducibles del tema de Docusaurus y componentes personalizados en archivos JSON en i18n/en/

  2. Traducción de contenido: pnpm translate utiliza OpenRouter IA para traducir:

    • Archivos markdown de docs/ → i18n/{locale}/docusaurus-plugin-content-docs/current/
    • Cadenas JSON de la interfaz de usuario de i18n/en/ → i18n/{locale}/
    • Archivos SVG de static/img/duplistatus*.svg (traduce texto dentro de SVG y exporta a PNG a través de Inkscape)

  3. Compilación: pnpm build genera HTML estático para todos los idiomas en build/ (un subdirectorio por configuración regional)

Ejecutando Traducción​

cd documentation
pnpm translate                       # Translate everything to all locales
pnpm translate --force               # force the translation of all files
pnpm translate --locale fr           # Translate only to French
pnpm translate --no-svg              # Skip SVG translation
pnpm translate --path docs/intro.md  # Translate specific file
pnpm translate:status                # Show the status of translation of all files

Para opciones detalladas, gestión de caché, resolución de problemas y el sistema de glosario, consulte Flujo de Trabajo de Traducción.

Anulaciones de Traducción Manual​

Si necesita ajustar manualmente una traducción:

  1. añada los términos a glossary-user.csv
  2. elimine las entradas de caché para estos términos usando la herramienta de edición de caché basada en web
  3. vuelva a ejecutar la traducción con pnpm translate --force

Comandos Comunes​

Todos los comandos deben ejecutarse desde el directorio documentation:

Desarrollo​

Iniciar el servidor de desarrollo con recarga en caliente para una configuración regional específica:

cd documentation
pnpm start:en    # English (default)
pnpm start:fr    # French
pnpm start:de    # German
pnpm start:es    # Spanish
pnpm start:pt-br # Brazilian Portuguese

El sitio estará disponible en http://localhost:3000 (o el siguiente puerto disponible).

Compilar​

Construir el sitio de documentación para producción:

cd documentation
pnpm build

Esto genera archivos HTML estáticos en el directorio documentation/build.

Servir la compilación de producción​

Vista previa de la compilación de producción localmente:

cd documentation
pnpm serve

Esto sirve el sitio compilado desde el directorio documentation/build.

Otros Comandos Útiles​

  • pnpm clear - Limpiar caché de Docusaurus
  • pnpm typecheck - Ejecutar verificación de tipos de TypeScript
  • pnpm write-heading-ids - Generar IDs de encabezados en formato interno de Docusaurus (no modifica archivos markdown)
  • pnpm heading-ids - Añadir IDs de anclaje explícitos {#id} a todos los encabezados markdown (modifica archivos; asegura IDs consistentes entre traducciones)

Generando README.md​

El archivo README.md del proyecto se genera automáticamente a partir de documentation/docs/intro.md para mantener sincronizado el README del repositorio de GitHub con la documentación de Docusaurus.

Para generar o actualizar el archivo README.md:

./scripts/generate-readme-from-intro.sh

Este script:

  • Extrae la versión actual de package.json y añade una insignia de versión
  • Copia contenido de documentation/docs/intro.md
  • Convierte admoniciones de Docusaurus (note, tip, warning, etc.) a alertas de estilo GitHub
  • Convierte todos los enlaces relativos de Docusaurus a URLs absolutas de documentación de GitHub (https://wsj-br.github.io/duplistatus/...)
  • Convierte rutas de imágenes de /img/ a documentation/static/img/ para compatibilidad con GitHub
  • Elimina el bloque IMPORTANT de migración y añade una sección de Información de Migración con un enlace a la documentación de Docusaurus
  • Genera una tabla de contenidos usando doctoc
  • Genera README_dockerhub.md con formato compatible con Docker Hub (convierte imágenes y enlaces a URLs absolutas, convierte alertas de GitHub a formato basado en emojis)
  • Genera notas de lanzamiento de GitHub (RELEASE_NOTES_github_VERSION.md) desde documentation/docs/release-notes/VERSION.md (convierte enlaces e imágenes a URLs absolutas)

Actualizar README para Docker Hub​

El script generate-readme-from-intro.sh genera automáticamente README_dockerhub.md con formato compatible con Docker Hub. Realiza lo siguiente:

  • Copia README.md a README_dockerhub.md
  • Convierte rutas de imágenes relativas a URLs absolutas de GitHub raw
  • Convierte enlaces de documentos relativos a URLs absolutas de GitHub blob
  • Convierte alertas de estilo GitHub ([!NOTE], [!WARNING], etc.) a formato basado en emojis para una mejor compatibilidad con Docker Hub
  • Garantiza que todas las imágenes y enlaces funcionen correctamente en Docker Hub

Generar Notas de Lanzamiento de GitHub​

El script generate-readme-from-intro.sh genera automáticamente notas de lanzamiento de GitHub cuando se ejecuta. Realiza lo siguiente:

  • Lee las notas de lanzamiento desde documentation/docs/release-notes/VERSION.md (donde VERSION se extrae de package.json)
  • Cambia el título de "# Version xxxx" a "# Release Notes - Versión xxxxx"
  • Convierte enlaces markdown relativos a URLs absolutas de documentación de GitHub (https://wsj-br.github.io/duplistatus/...)
  • Convierte rutas de imágenes a URLs raw de GitHub (https://raw.githubusercontent.com/wsj-br/duplistatus/main/documentation/static/img/...) para una visualización correcta en descripciones de lanzamiento
  • Gestiona rutas relativas con prefijo ../
  • Preserva URLs absolutas (http:// y https://) sin cambios
  • Crea RELEASE_NOTES_github_VERSION.md en la raíz del proyecto

Ejemplo:

# This will generate both README.md and RELEASE_NOTES_github_VERSION.md
./scripts/generate-readme-from-intro.sh

El archivo de notas de lanzamiento generado se puede copiar y pegar directamente en la descripción de lanzamiento de GitHub. Todos los enlaces e imágenes funcionarán correctamente en el contexto de lanzamiento de GitHub.

Tomar capturas de pantalla para la documentación​

pnpm take-screenshots

O ejecutar directamente: pnpm take-screenshots (use --env-file=.env si es necesario para variables de entorno).

Este script toma automáticamente capturas de pantalla de la aplicación para documentación. Hace lo siguiente:

  • Inicia un navegador sin interfaz (Puppeteer)
  • Inicia sesión como admin y usuario regular
  • Navega por diferentes páginas (panel de control, detalles del servidor, configuración, etc.)
  • Toma capturas de pantalla en diferentes tamaños de ventana gráfica
  • Guarda las capturas de pantalla en documentation/static/assets/ (inglés) o documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets (otros idiomas)

Requisitos:

  • El servidor de desarrollo debe estar ejecutándose en http://localhost:8666
  • Las variables de entorno deben estar configuradas, añádalas a su archivo .env o expórtelas:
    • ADMIN_PASSWORD: Contraseña para cuenta de administrador
    • USER_PASSWORD: Contraseña para cuenta de usuario regular

Opciones: --locale limita las capturas de pantalla a una o más configuraciones regionales (separadas por comas). Si se omite, se capturan todas las configuraciones regionales. Configuraciones regionales válidas: en, de, fr, es, pt-BR. Use -h o --help para imprimir el uso.

Ejemplo:

export ADMIN_PASSWORD="your-admin-password"
export USER_PASSWORD="your-user-password"
pnpm take-screenshots
# All locales (default):
pnpm take-screenshots
# Single locale:
pnpm take-screenshots --locale en
# Multiple locales:
pnpm take-screenshots --locale en,de,pt-BR

Implementación de la Documentación​

Para implementar la documentación en GitHub Pages, necesitarás generar un Token de Acceso Personal de GitHub. Ve a GitHub Personal Access Tokens y crea un nuevo token con el alcance repo.

Cuando tenga el token, guárdelo en el almacén de credenciales de Git (por ejemplo, usando git config credential.helper store o el administrador de credenciales de su sistema).

Luego, para implementar la documentación en GitHub Pages, ejecute el siguiente comando desde el directorio documentation:

pnpm run deploy

Esto compilará la documentación y la enviará a la rama gh-pages del repositorio, y la documentación estará disponible en https://wsj-br.github.io/duplistatus/.

Trabajar con Documentación​

Para el flujo de trabajo de traducción completo (gestión de glosario, traducción de IA, gestión de caché), consulte Flujo de Trabajo de Traducción.

Archivos de Origen​

  • Contenido de la documentación: Archivos markdown en inglés en documentation/docs/
  • Traducciones de la interfaz de usuario: Archivos JSON en inglés en documentation/i18n/en/ (generados automáticamente por pnpm write-translations)
  • Navegación de la barra lateral: documentation/sidebars.ts
  • Configuración de Docusaurus: documentation/docusaurus.config.ts
  • Componentes personalizados de React: documentation/src/components/
  • Recursos estáticos: documentation/static/
  • Página de inicio principal: documentation/docs/intro.md (fuente para generar README.md)

Añadiendo Nuevos Componentes​

  1. Cree su componente de React en documentation/src/components/
  2. Expórtelo desde documentation/src/theme/MDXComponents.js para que esté disponible en MDX
  3. Si el componente incluye cadenas de texto traducibles de la interfaz de usuario, ejecute pnpm write-translations para extraerlas
  4. Ejecute pnpm translate para traducir las nuevas cadenas a todos los idiomas

Añadiendo Nuevas Páginas de Documentación​

  1. Crear un nuevo archivo .md en documentation/docs/ (o un subdirectorio)
  2. Añadirlo a la barra lateral en documentation/sidebars.ts
  3. Ejecutar pnpm write-translations para actualizar la estructura de archivos de traducción
  4. Ejecutar pnpm heading-ids para generar IDs de encabezados (anclajes)
  5. Ejecutar pnpm translate para traducir la nueva página a todos los idiomas
  6. Compilar y probar: pnpm build

Recursos Estáticos​

  • Imágenes: Colóquelas en documentation/static/img/ y refiéralas con /img/filename.png en markdown
  • Descargas/PDFs: Colóquelos en documentation/static/ y refiéralos con /filename.pdf
  • Recursos por idioma: Si un recurso necesita ser específico de un idioma (por ejemplo, capturas de pantalla), colóquelo en documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets/

Compilar y Probar​

cd documentation
pnpm build            # Builds all locales
pnpm serve            # Preview the built site locally
pnpm start:en         # Development server for English
pnpm start:pt-br      # Development server for Portuguese

Siempre pruebe sus cambios al menos en el idioma inglés predeterminado y en otro idioma para asegurarse de que las traducciones aparezcan correctamente.