Génération de la documentation localement

Le site de documentation que vous consultez est publié à partir de docs/book/. Vous pouvez générer le même site sur votre propre machine, ce qui est utile pour une lecture hors ligne, pour prévisualiser vos modifications avant d’ouvrir une PR, ou pour développer des traductions.

Catalogues de traduction (git submodule)

Les catalogues .po traduits se trouvent dans le sous-module zeroclaw-labs/zeroclaw-docs-translations monté à docs/book/po. La boucle de développement Rust (cargo build, cargo test, cargo clippy) n’en a pas besoin, mais construire ou synchroniser la documentation en a besoin. Initialisez-le une fois :

git clone --recurse-submodules https://github.com/zeroclaw-labs/zeroclaw   # nouveau clone
git submodule update --init docs/book/po                                   # clone existant

Sans le sous-module extrait, l’anglais se construit toujours (les sources anglaises se trouvent dans docs/book/src/), mais les locales traduites s’affichent vides.

Démarrage rapide en une commande

cargo mdbook serve                       # servir toutes les langues à http://localhost:3000/en/
cargo mdbook serve --locale ja           # rechargement automatique contre des sources en japonais
cargo mdbook build                       # build statique de chaque locale dans docs/book/book/
cargo mdbook refs                        # régénérer les pages de référence générées automatiquement
cargo mdbook sync                        # passe translation-cache : ré-extraction + fusion des fichiers .po
cargo mdbook sync --locale ja            # synchroniser uniquement une locale
cargo mdbook sync --force                # forcer la retraduction de tout (passage de qualité)
cargo mdbook sync --locale ja --force    # forcer la retraduction d'une locale
cargo mdbook stats                       # afficher les chaînes traduites/floues/non traduites par locale
cargo mdbook check                       # valider le format .po (à exécuter avant une PR de traduction)

Utilisez toujours le wrapper cargo mdbook …. Exécuter mdbook build directement depuis docs/book/ ignore l’étape xtask qui génère theme/lang-switcher.js à partir de locales.toml, ce qui fait échouer la compilation avec failed to open theme/lang-switcher.js for hashing.

Outils requis

cargo mdbook échouera rapidement et vous indiquera ce qui manque, mais à titre de référence :

La version de mdbook-mermaid est verrouillée, mais son fichier de verrouillage publié sélectionne encore le préprocesseur mdBook 0.5.0. Omettez --locked pour cet outil afin que Cargo résolve le préprocesseur 0.5.x compatible utilisé par mdBook 0.5.4.

Ce qui est construit où

Les deux fichiers reference/*.md sont générés à partir des dérives clap réelles et du schéma JSON présents dans le code, ne les modifiez jamais à la main. Modifiez plutôt les commentaires de documentation /// sur les types Rust concernés.

cargo mdbook est un alias pour cargo run -p xtask --bin mdbook -- (défini dans la configuration cargo).

Pour l’architecture derrière les références générées, les sorties destinées uniquement à la compilation, l’extraction gettext, le repli de locale et le déploiement, consultez Generated documentation pipeline et Localization catalog lifecycle.

Traductions

L’anglais est la langue source des chapitres rédigés et des références générées. Les traductions se trouvent dans les fichiers docs/book/po/<locale>.po, qui font office de cache, et cargo mdbook sync les maintient à jour. Les PR de documentation anglaise courantes n’ont pas besoin d’inclure les modifications générées des fichiers .po : laissez-les pour une PR dédiée au cache de traduction. Pour le pipeline de traduction complet (chaînes de l’application, docs, zerocode, ajout d’une locale, passes de publication), consultez Docs & Translations.

Conseils

• Itération rapide sur le texte : cargo mdbook serve reconstruit automatiquement à chaque sauvegarde. Évitez cargo mdbook refs sauf si vous avez modifié les indicateurs CLI ou le schéma de configuration.
• Itération rapide sur les traductions : modifiez po/<locale>.po et rechargez le navigateur, mdbook serve détecte les modifications des fichiers .po et reconstruit automatiquement.
• Nettoyage : rm -rf docs/book/book target/doc supprime tout ce qui a été généré.
• Réexécutions à coût nul : cargo mdbook sync sur une source anglaise inchangée se termine en quelques secondes, sans appels d’IA, sans coût.