Compilar la documentación localmente

El sitio de documentación que estás leyendo se publica desde docs/book/. Puedes compilar el mismo sitio en tu propia máquina, lo cual es útil para lectura sin conexión, previsualizar ediciones antes de abrir un PR o desarrollar traducciones.

Catálogos de traducción (submódulo de git)

Los catálogos .po traducidos viven en el submódulo zeroclaw-labs/zeroclaw-docs-translations montado en docs/book/po. El ciclo de desarrollo en Rust (cargo build, cargo test, cargo clippy) no lo necesita, pero construir o sincronizar la documentación sí. Inicialízalo una vez:

git clone --recurse-submodules https://github.com/zeroclaw-labs/zeroclaw   # clonación nueva
git submodule update --init docs/book/po                                   # clon existente

Sin el submódulo extraído, inglés sigue compilando (el código fuente en inglés vive en docs/book/src/), pero las versiones localizadas se renderizan vacías.

Inicio rápido con un solo comando

cargo mdbook serve                       # servir todas las localizaciones en http://localhost:3000/en/
cargo mdbook serve --locale ja           # recarga en vivo contra fuentes en japonés
cargo mdbook build                       # compilación estática de cada localización en docs/book/book/
cargo mdbook refs                        # regenerar las páginas de referencia generadas automáticamente
cargo mdbook sync                        # pase de translation-cache: volver a extraer + fusionar archivos .po
cargo mdbook sync --locale ja            # sincronizar solo una configuración regional
cargo mdbook sync --force                # Forzar la retraducción de todo (paso de calidad)
cargo mdbook sync --locale ja --force    # forzar la retraducción de una configuración regional
cargo mdbook stats                       # mostrar traducidos/ambiguos/no traducidos por localización
cargo mdbook check                       # validar el formato .po (ejecutar antes de un PR de traducción)

Utiliza siempre el contenedor cargo mdbook …. Ejecutar mdbook build directamente desde docs/book/ omite el paso de xtask que renderiza theme/lang-switcher.js a partir de locales.toml, lo que provoca un fallo en la compilación con el error failed to open theme/lang-switcher.js for hashing.

Herramientas requeridas

cargo mdbook fallará rápidamente y te indicará qué falta, pero como referencia:

La versión de mdbook-mermaid está fijada, pero su archivo de bloqueo publicado sigue seleccionando el preprocesador de mdBook 0.5.0. No incluyas --locked para esa herramienta, de modo que Cargo resuelva el preprocesador 0.5.x compatible que usa mdBook 0.5.4.

Qué se construye en cada lugar

Los dos archivos reference/*.md se generan a partir de las derivaciones clap reales y del esquema JSON en el código; nunca los edites a mano. En su lugar, edita los comentarios de documentación /// en los tipos de Rust relevantes.

cargo mdbook es un alias de cargo run -p xtask --bin mdbook -- (definido en la configuración de cargo).

Para consultar la arquitectura que subyace a las referencias generadas, los resultados exclusivos de la compilación, la extracción de gettext, el respaldo de la configuración regional y el despliegue, consulta Canalización de documentación generada y Ciclo de vida del catálogo de localización.

Traducciones

El inglés es el idioma fuente para los capítulos redactados y las referencias generadas. Las traducciones residen en archivos docs/book/po/<locale>.po que actúan como caché, y cargo mdbook sync las mantiene actualizadas. Los PRs de documentación en inglés de rutina no necesitan incluir el ruido generado en los archivos .po: déjalo para un PR dedicado a la caché de traducciones. Para conocer el pipeline completo de traducción (cadenas de la aplicación, documentación, zerocode, agregar un idioma, pasadas de lanzamiento), consulta Docs & Translations.

Consejos

• Iteración rápida en el texto: cargo mdbook serve reconstruye automáticamente al guardar. Omite cargo mdbook refs a menos que hayas modificado las banderas de la CLI o el esquema de configuración.
• Iteración rápida en traducciones: edita po/<locale>.po y recarga el navegador, mdbook serve detecta los cambios en .po y reconstruye automáticamente.
• Limpieza: rm -rf docs/book/book target/doc elimina todo lo generado.
• Re-ejecuciones sin costo: cargo mdbook sync sobre código fuente en inglés sin cambios se completa en segundos, sin llamadas a IA, sin costo.