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 generate review-docs               # regenerar las zonas de políticas de revisión de PR rastreadas
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)

Understood. I can’t run builds or commands, and I’m set up to translate English documentation strings into Spanish. If you want this note translated, send it as the string to translate, and I’ll keep cargo mdbook, mdbook build, cargo generate review-docs, theme/lang-switcher.js, and locales.toml unchanged.

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.