Saltar al contenido principal

Herramientas de Documentación

La documentación se construye usando 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
│   ├── hi/            # Hindi
│   ├── pt-BR/         # Brazilian Portuguese
│   └── zh-Hans/       # Simplified Chinese
├── src/               # React components and pages
│   ├── components/    # Custom React components
│   ├── css/           # Custom styles
│   ├── landing/       # Homepage HTML + CSS (English source; locale copies in landing/i18n/)
│   ├── pages/         # Additional pages (homepage shell, 404)
│   └── theme/         # Swizzled theme (navbar)
├── static/            # Static assets (images, files)
├── docusaurus.config.ts  # Docusaurus configuration
├── sidebars.ts        # Sidebar navigation configuration
└── package.json       # Dependencies and scripts

Internacionalización (i18n)​

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

  • Archivos fuente: docs/**/*.md (inglés)
  • Archivos traducidos: i18n/{locale}/docusaurus-plugin-content-docs/current/**/*.md
  • Traducciones de interfaz: 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 la interfaz de usuario (del tema de Docusaurus y de componentes personalizados) en archivos de traducción JSON. El script pnpm translate (desde documentation/, que delega en la raíz del repositorio) ejecuta ai-i18n-tools para traducir markdown, JSON, SVG y el HTML de la página de destino según ai-i18n-tools.config.json.

La página principal de la documentación es src/landing/landing.html envuelta por src/pages/index.tsx. Edite el archivo HTML para modificar el texto; las copias de cada configuración regional se encuentran en src/landing/i18n/ y se generan mediante pnpm i18n:translate:docs.

important

Solo edite los archivos en docs/, el archivo fuente de la página de destino src/landing/landing.html y los archivos JSON de origen en i18n/en-GB/. El markdown traducido en i18n/{other-locales}/ y las copias de la página de destino en src/landing/i18n/ son generados y no deben editarse manualmente.

Locales Compatibles​

LocaleIdiomaDirectorio
en-GBInglés (predeterminada)docs/ (fuente)
deAlemáni18n/de/docusaurus-plugin-content-docs/current/
esEspañoli18n/es/docusaurus-plugin-content-docs/current/
frFrancési18n/fr/docusaurus-plugin-content-docs/current/
hiHindii18n/hi/docusaurus-plugin-content-docs/current/
pt-BRPortugués Brasileñoi18n/pt-BR/docusaurus-plugin-content-docs/current/
zh-HansChino Simplificadoi18n/zh-Hans/docusaurus-plugin-content-docs/current/

Traducir la Documentación​

La documentación utiliza un sistema de traducción impulsado por IA para traducir tanto el contenido (archivos markdown) como las cadenas de interfaz (de Docusaurus y componentes personalizados). El contenido fuente está en inglés (docs/), y se generan traducciones para alemán, francés, español, portugués brasileño, hindi y chino simplificado.

Cómo Funciona la Traducción​

  1. Cadenas de interfaz de Docusaurus: pnpm write-translations extrae cadenas de tema/personalizadas en i18n/en/*.json.
  2. Traducción por IA (OpenRouter; configuración en ai-i18n-tools.config.json en la raíz del repositorio): desde documentation/, pnpm translate ejecuta el script raíz i18n:translate (cadenas de interfaz, SVGs, markdown/JSON de Docusaurus y plantillas de notificación predeterminadas) en documentation/i18n/, src/locales/ y src/locales/templates/ según se configure.
  3. Compilación: pnpm build genera HTML estático para todos los locales bajo documentation/build/.

Ejecutar Traducción​

cd documentation
pnpm translate          # Same as repo root: i18n:translate (ui + svg + docs + json)
pnpm translate:docs
pnpm translate:json
pnpm translate:svg
pnpm translate:ui
pnpm translate:status

Las banderas CLI se definen mediante ai-i18n-tools; ejecuta pnpm exec ai-i18n-tools --help desde la raíz del repositorio o consulta Translation Workflow.

Anulaciones de Traducción Manual​

Edita documentation/glossary-user.csv (y opcionalmente borra entradas obsoletas bajo .translation-cache/ en la raíz del repositorio), luego vuelve a ejecutar el comando pnpm translate:* correspondiente.

Comandos Comunes​

Todos los comandos deben ejecutarse desde el directorio documentation:

Desarrollo​

Inicia 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/duplistatus/ (o el siguiente puerto disponible). La ruta /duplistatus/ coincide con baseUrl de GitHub Pages y los enlaces del botón Ayuda en la aplicación.

Compilar​

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

cd documentation
pnpm build

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

Servir 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 - Borrar caché de Docusaurus
  • pnpm typecheck - Ejecutar verificación de tipos de TypeScript
  • pnpm write-heading-ids - Escribir anclajes de encabezado explícitos {/* #id */} en markdown usando la sintaxis de comentario MDX de Docusaurus (ejecutar desde documentation/ para enlaces estables entre traducciones). La CLI omite títulos h1, que Docusaurus utiliza como etiquetas de barra lateral.

Generando README.md​

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

Para generar o actualizar el archivo README.md:

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

Este script:

  • Extrae la package.json actual y añade un distintivo de versión
  • Copia contenido de documentation/docs/intro.md
  • Convierte admoniciones de Docusaurus (nota, consejo, advertencia, etc.) a alertas de estilo GitHub
  • Convierte todos los enlaces relativos de Docusaurus a URLs absolutas de documentos 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 emoji)
  • 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 raw de GitHub absolutas
  • Convierte enlaces de documentos relativos a URLs blob de GitHub absolutas
  • Convierte alertas de estilo GitHub ([!NOTE], [!WARNING], etc.) a formato basado en emoji para 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 de documentation/docs/release-notes/VERSION.md (donde VERSION se extrae de package.json)
  • Cambia el título de "# Versión xxxx" a "# Notas de Lanzamiento - Versión xxxxx"
  • Convierte enlaces markdown relativos a URLs absolutas de documentos 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 visualización correcta en descripciones de lanzamiento
  • Maneja 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 documentación​

pnpm take-screenshots

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

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

  • Después de verificaciones de entorno y salud, ejecuta pnpm exec playwright install para que los navegadores de Playwright estén presentes
  • Inicia un navegador sin interfaz gráfica (Chromium de Playwright)
  • Inicia sesión como administrador y usuario regular
  • Navega por varias páginas (panel de control, detalles del servidor, configuración, etc.)
  • Toma capturas de pantalla en diferentes tamaños de ventana gráfica
  • Guarda capturas de pantalla en documentation/static/assets/ (inglés) u 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 la cuenta de administrador
    • USER_PASSWORD: Contraseña para la cuenta de usuario regular

Opciones: --locale limita las capturas de pantalla a uno o más idiomas (separados por comas). Si se omite, se capturan todos los idiomas. Idiomas válidos: en-GB, de, fr, es, pt-BR, hi, zh-Hans. Usa -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-GB
# Multiple locales:
pnpm take-screenshots --locale en-GB,de,pt-BR

Desplegar la Documentación​

Para desplegar 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 ámbito repo.

Cuándo tengas el token, guárdalo en el almacén de credenciales de Git (por ejemplo, usando git config credential.helper store o el gestor de credenciales de tu sistema).

Luego, para desplegar la documentación en GitHub Pages, ejecuta 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 con IA, gestión de caché), consulta Translation Workflow.

Archivos de Origen​

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

Añadir Nuevos Componentes​

  1. Crea tu componente React en documentation/src/components/
  2. Expórtalo desde documentation/src/theme/MDXComponents.js para que esté disponible en MDX
  3. Si el componente incluye cadenas de interfaz traducibles, ejecuta pnpm write-translations para extraerlas
  4. Ejecuta pnpm translate para traducir las nuevas cadenas a todos los idiomas

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

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

Recursos Estáticos​

  • Imágenes: Coloca en documentation/static/img/ y referencia con /img/filename.png en markdown
  • Descargas/PDFs: Coloca en documentation/static/ y referencia con /filename.pdf
  • Recursos por idioma: Si un recurso necesita ser específico del idioma (por ejemplo, capturas de pantalla), colócalo 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 prueba tus cambios al menos en el idioma inglés predeterminado y en otro idioma para asegurar que las traducciones aparecen correctamente.