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
│   ├── hi-Latn/       # Hindi (Roman)
│   ├── pt-BR/         # Brazilian Portuguese
│   └── zh-Hans/       # Simplified Chinese
├── 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

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 interfaz de usuario (del tema de Docusaurus y componentes personalizados) en archivos de traducción JSON. El script pnpm translate (de documentation/, delega en la raíz del repositorio) ejecuta ai-i18n-tools para traducir markdown, JSON y SVGs según ai-i18n-tools.config.json.

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​

LocaleIdiomaDirectorio
en-GBEnglish (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/
hi-LatnHindi (Romano)i18n/hi-Latn/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​

El sistema de documentación utiliza un sistema de traducción con IA para traducir tanto el contenido (archivos Markdown) como las cadenas de la interfaz de usuario (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 (romano) y chino simplificado.

Cómo Funciona la Traducción​

  1. Cadenas de interfaz de usuario de Docusaurus: pnpm write-translations extrae las cadenas del tema y personalizadas en i18n/en/*.json.
  2. Traducción con 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 y archivos markdown/JSON de Docusaurus) hacia documentation/i18n/ y src/locales/ según la configuración.
  3. Compilación: pnpm build genera HTML estático para todas las ubicaciones en documentation/build/.

Ejecutando Traducción​

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

Las banderas CLI están definidas por ai-i18n-tools; ejecute pnpm exec ai-i18n-tools --help desde la raíz del repositorio o consulte Flujo de traducción.

Anulaciones de Traducción Manual​

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

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 - Borrar caché de Docusaurus
  • pnpm typecheck - Ejecutar verificación de tipos de TypeScript
  • pnpm write-heading-ids - Escribir anclas de encabezado explícitas {#id} en el markdown usando las reglas de Docusaurus (ejecutar desde documentation/ para enlaces estables 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 agrega una etiqueta de versión
  • Copia el contenido de documentation/docs/intro.md
  • Convierte las admoniciones de Docusaurus (nota, consejo, advertencia, etc.) a alertas con estilo de GitHub
  • Convierte todos los enlaces relativos de Docusaurus a URLs absolutas de la documentación de GitHub (https://wsj-br.github.io/duplistatus/...)
  • Convierte las rutas de las imágenes de /img/ a documentation/static/img/ para compatibilidad con GitHub
  • Elimina el bloque IMPORTANT de migración y agrega 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 las notas de lanzamiento de GitHub (RELEASE_NOTES_github_VERSION.md) a partir de 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. Hace 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 blob de GitHub
  • Convierte alertas con estilo de GitHub ([!NOTE], [!WARNING], etc.) a formato basado en emojis para mejor compatibilidad con Docker Hub
  • Asegura 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 las notas de lanzamiento de GitHub al ejecutarse. Hace 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 la documentación de GitHub (https://wsj-br.github.io/duplistatus/...)
  • Convierte las rutas de las imágenes a URLs raw de GitHub (https://raw.githubusercontent.com/wsj-br/duplistatus/main/documentation/static/img/...) para una correcta visualización en las descripciones de lanzamiento
  • Maneja rutas relativas con el prefijo ../
  • Mantiene sin cambios las URLs absolutas (http:// y https://)
  • 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 fines de documentación. Realiza las siguientes acciones:

  • Inicia un navegador sin interfaz gráfica (Playwright Chromium)
  • Inicia sesión como administrador y usuario normal
  • Navega por varias páginas (panel de control, detalles del servidor, configuración, etc.)
  • Toma capturas de pantalla en diferentes tamaños de ventana
  • Guarda las capturas 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 en ejecución en http://localhost:8666
  • El navegador Playwright Chromium debe estar instalado (ejecute pnpm take-screenshots:install una vez, lo que ejecuta playwright install chromium)
  • Las variables de entorno deben estar configuradas, añádalas a su archivo .env o expórtelas:
    • ADMIN_PASSWORD: Contraseña de la cuenta de Administrador
    • USER_PASSWORD: Contraseña de la cuenta de Usuario normal

Opciones: --locale limita las capturas de pantalla a una o varias localidades (separadas por comas). Si se omite, se capturan todas las localidades. Localidades válidas: en-GB, de, fr, es, pt-BR, hi-Latn, zh-Hans. Utilice -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

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: Archivos JSON en inglés en documentation/i18n/en/ (generados automáticamente por pnpm write-translations)
  • Navegación lateral: documentation/sidebars.ts
  • Configuración de Docusaurus: documentation/docusaurus.config.ts
  • Componentes React personalizados: documentation/src/components/
  • Activos estáticos: documentation/static/
  • Página 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. Cree un nuevo archivo .md en documentation/docs/ (o en un subdirectorio)
  2. Agréguelo a la barra lateral en documentation/sidebars.ts
  3. Ejecute pnpm write-translations para actualizar la estructura de los archivos de traducción
  4. Ejecute pnpm write-heading-ids para generar los ID de encabezado (anclas)
  5. Ejecute pnpm translate para traducir la nueva página a todos los idiomas
  6. Compile y pruebe: 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.