Aller au contenu principal

Outils de Documentation

La documentation est construite à l'aide de Docusaurus et se trouve dans le dossier documentation. La documentation est hébergée sur GitHub Pages et n'est plus incluse dans l'image du conteneur Docker.

Structure des dossiers​

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

Internationalisation (i18n)​

La documentation utilise le système d'internationalisation intégré de Docusaurus avec l'anglais comme langue par défaut. Le contenu traduit se trouve dans i18n/{locale}/docusaurus-plugin-content-docs/current/, en miroir de la structure du dossier docs/.

  • Fichiers source : docs/**/*.md (anglais)
  • Fichiers traduits : i18n/{locale}/docusaurus-plugin-content-docs/current/**/*.md
  • Traductions de l'interface : i18n/{locale}/docusaurus-theme-classic/*.json et autres fichiers JSON
  • Captures d'écran localisées : i18n/{locale}/docusaurus-plugin-content-docs/current/**/assets, générées par pnpm take-screenhots dans le répertoire de base.

La commande pnpm write-translations extrait les chaînes d'interface utilisateur (du thème Docusaurus et des composants personnalisés) dans des fichiers de traduction JSON. Le script pnpm translate (depuis documentation/, délègue au répertoire racine du dépôt) exécute ai-i18n-tools pour traduire les fichiers markdown, JSON et SVGs selon ai-i18n-tools.config.json.

important

Modifiez uniquement les fichiers dans docs/ et les fichiers JSON source dans i18n/en/. Les fichiers markdown traduits dans i18n/{autres-locales}/ sont générés automatiquement et ne doivent pas être modifiés manuellement.

Paramètres régionaux pris en charge​

Paramètres régionauxLangueRépertoire
en-GBAnglais (par défaut)docs/ (source)
deAllemandi18n/de/docusaurus-plugin-content-docs/current/
esEspagnoli18n/es/docusaurus-plugin-content-docs/current/
frFrançaisi18n/fr/docusaurus-plugin-content-docs/current/
hi-LatnHindi (roman)i18n/hi-Latn/docusaurus-plugin-content-docs/current/
pt-BRPortugais brésilieni18n/pt-BR/docusaurus-plugin-content-docs/current/
zh-HansChinois simplifiéi18n/zh-Hans/docusaurus-plugin-content-docs/current/

Traduire la Documentation​

La documentation utilise un système de traduction basé sur l'IA pour traduire à la fois le contenu (fichiers markdown) et les chaînes de l'interface utilisateur (issues de Docusaurus et de composants personnalisés). Le contenu source est en anglais (docs/), et des traductions sont générées pour l'allemand, le français, l'espagnol, le portugais brésilien, l'hindi (roman) et le chinois simplifié.

Fonctionnement de la traduction​

  1. Chaînes d'interface Docusaurus : pnpm write-translations extrait les chaînes du thème et personnalisées dans i18n/en/*.json.
  2. Traduction par IA (OpenRouter ; configuration dans ai-i18n-tools.config.json à la racine du dépôt) : à partir de documentation/, pnpm translate exécute le script racine i18n:translate (chaînes d'interface, SVG et documents Docusaurus en markdown/JSON) vers documentation/i18n/ et src/locales/ selon la configuration.
  3. Construction : pnpm build génère les fichiers HTML statiques pour toutes les locales dans documentation/build/.

Exécution de la traduction​

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

Les indicateurs CLI sont définis par ai-i18n-tools ; exécutez pnpm exec ai-i18n-tools --help depuis la racine du dépôt ou consultez Translation Workflow.

Remplacements manuels de traduction​

Modifiez documentation/glossary-user.csv (et éventuellement effacez les entrées obsolètes situées sous .translation-cache/ à la racine du dépôt), puis relancez la commande pnpm translate:* correspondante.

Commandes courantes​

Toutes les commandes doivent être exécutées à partir du répertoire documentation :

Développement​

Démarrer le serveur de développement avec rechargement à chaud pour une locale spécifique :

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

Le site sera disponible à http://localhost:3000 (ou au prochain port disponible).

Construire​

Construire le site de documentation pour la production :

cd documentation
pnpm build

Cela génère des fichiers HTML statiques dans le répertoire documentation/build.

Servir la version de production​

Prévisualisez la version de production localement :

cd documentation
pnpm serve

Cela sert le site construit à partir du répertoire documentation/build.

Autres Commandes Utiles​

  • pnpm clear - Effacer le cache Docusaurus
  • pnpm typecheck - Exécuter la vérification des types TypeScript
  • pnpm write-heading-ids - Écrire des ancres de titre explicites {#id} dans le markdown en utilisant les règles de Docusaurus (à exécuter depuis documentation/ pour des liens stables entre les traductions)

Génération de README.md​

Le fichier README.md du projet est généré automatiquement à partir de documentation/docs/intro.md pour maintenir la synchronisation du fichier README du référentiel GitHub avec la documentation Docusaurus.

Pour générer ou mettre à jour le fichier README.md :

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

Ce script :

  • Extrait la version actuelle depuis package.json et ajoute un badge de version
  • Copie le contenu depuis documentation/docs/intro.md
  • Convertit les admonitions Docusaurus (note, astuce, avertissement, etc.) en alertes au format GitHub
  • Convertit tous les liens relatifs Docusaurus en URL absolues vers la documentation GitHub (https://wsj-br.github.io/duplistatus/...)
  • Convertit les chemins d'images de /img/ vers documentation/static/img/ pour une compatibilité avec GitHub
  • Supprime le bloc IMPORTANT relatif à la migration et ajoute une section Informations sur la migration avec un lien vers la documentation Docusaurus
  • Génère une table des matières à l'aide de doctoc
  • Génère README_dockerhub.md avec un formatage compatible Docker Hub (convertit les images et les liens en URL absolues, convertit les alertes GitHub en format basé sur des émojis)
  • Génère les notes de publication GitHub (RELEASE_NOTES_github_VERSION.md) à partir de documentation/docs/release-notes/VERSION.md (convertit les liens et les images en URL absolues)

Mettre à jour le README pour Docker Hub​

Le script generate-readme-from-intro.sh génère automatiquement README_dockerhub.md avec un formatage compatible Docker Hub. Il :

  • Copie README.md vers README_dockerhub.md
  • Convertit les chemins d'images relatifs en URL absolues brutes GitHub
  • Convertit les liens de documents relatifs en URL absolues blob GitHub
  • Convertit les alertes au format GitHub ([!NOTE], [!WARNING], etc.) en format basé sur des émojis pour une meilleure compatibilité avec Docker Hub
  • S'assure que toutes les images et tous les liens fonctionnent correctement sur Docker Hub

Générer les notes de version GitHub​

Le script generate-readme-from-intro.sh génère automatiquement les notes de publication GitHub lorsqu'il est exécuté. Il :

  • Lit les notes de publication depuis documentation/docs/release-notes/VERSION.md (où VERSION est extraite depuis package.json)
  • Remplace le titre "# Version xxxx" par "# Notes de publication - Version xxxxx"
  • Convertit les liens markdown relatifs en URL absolues vers la documentation GitHub (https://wsj-br.github.io/duplistatus/...)
  • Convertit les chemins d'images en URL brutes GitHub (https://raw.githubusercontent.com/wsj-br/duplistatus/main/documentation/static/img/...) pour un affichage correct dans les descriptions de publication
  • Gère les chemins relatifs avec le préfixe ../
  • Conserve inchangés les URL absolues (http:// et https://)
  • Crée RELEASE_NOTES_github_VERSION.md à la racine du projet

Exemple :

# This will generate both README.md and RELEASE_NOTES_github_VERSION.md
./scripts/generate-readme-from-intro.sh

Le fichier de notes de version généré peut être copié et collé directement dans la description de la version GitHub. Tous les liens et images fonctionneront correctement dans le contexte de la version GitHub.

Prendre des captures d'écran pour la documentation​

pnpm take-screenshots

Ou exécuter directement : pnpm take-screenshots (utilisez --env-file=.env si nécessaire pour les variables d'environnement).

Ce script prend automatiquement des captures d'écran de l'application à des fins de documentation. Il :

  • Lance un navigateur sans tête (Playwright Chromium)
  • Se connecte en tant qu'admin et utilisateur régulier
  • Navigue à travers différentes pages (tableau de bord, détails du serveur, paramètres, etc.)
  • Prend des captures d'écran à différentes tailles de fenêtre d'affichage
  • Enregistre les captures d'écran dans documentation/static/assets/ (anglais) ou documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets (autres langues)

Prérequis :

  • Le serveur de développement doit être en cours d'exécution sur http://localhost:8666
  • Le navigateur Playwright Chromium doit être installé (exécutez pnpm take-screenshots:install une fois, ce qui exécute playwright install chromium)
  • Les variables d'environnement doivent être définies, ajoutez-les à votre fichier .env ou exportez-les :
    • ADMIN_PASSWORD : Mot de passe du compte admin
    • USER_PASSWORD : Mot de passe du compte utilisateur régulier

Options : --locale limite les captures d'écran à une ou plusieurs locales (séparées par des virgules). Si omis, toutes les locales sont capturées. Locales valides : en-GB, de, fr, es, pt-BR, hi-Latn, zh-Hans. Utilisez -h ou --help pour afficher l'aide.

Exemple :

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

Déploiement de la documentation​

Pour déployer la documentation sur GitHub Pages, vous devrez générer un jeton d'accès personnel GitHub. Allez à GitHub Personal Access Tokens et créez un nouveau jeton avec la portée repo.

Une fois le jeton obtenu, stockez-le dans le magasin d'informations d'identification Git (par exemple en utilisant git config credential.helper store ou le gestionnaire d'informations d'identification de votre système).

Ensuite, pour déployer la documentation sur GitHub Pages, exécutez la commande suivante depuis le répertoire documentation :

pnpm run deploy

Cela construira la documentation et la poussera vers la branche gh-pages du référentiel, et la documentation sera disponible à l'adresse https://wsj-br.github.io/duplistatus/.

Travailler avec la documentation​

Pour le workflow de traduction complet (gestion du glossaire, traduction par IA, gestion du cache), consultez Workflow de Traduction.

Fichiers source​

  • Contenu de la documentation : fichiers markdown en anglais dans documentation/docs/
  • Traductions de l'interface utilisateur : fichiers JSON en anglais dans documentation/i18n/en/ (générés automatiquement par pnpm write-translations)
  • Navigation latérale : documentation/sidebars.ts
  • Configuration de Docusaurus : documentation/docusaurus.config.ts
  • Composants React personnalisés : documentation/src/components/
  • Ressources statiques : documentation/static/
  • Page d'accueil principale : documentation/docs/intro.md (source pour générer README.md)

Ajout de nouveaux composants​

  1. Créez votre composant React dans documentation/src/components/
  2. Exportez-le depuis documentation/src/theme/MDXComponents.js pour le rendre disponible dans MDX
  3. Si le composant contient des chaînes de l'interface traduisibles, exécutez pnpm write-translations pour les extraire
  4. Exécutez pnpm translate pour traduire les nouvelles chaînes dans tous les locales

Ajout de nouvelles pages de documentation​

  1. Créez un nouveau fichier .md dans documentation/docs/ (ou un sous-répertoire)
  2. Ajoutez-le à la barre latérale dans documentation/sidebars.ts
  3. Exécutez pnpm write-translations pour mettre à jour la structure des fichiers de traduction
  4. Exécutez pnpm write-heading-ids pour générer les identifiants de titres (ancres)
  5. Exécutez pnpm translate pour traduire la nouvelle page dans toutes les langues
  6. Générez et testez : pnpm build

Ressources statiques​

  • Images : Placez-les dans documentation/static/img/ et référencez-les avec /img/filename.png dans le markdown
  • Téléchargements/PDFs : Placez-les dans documentation/static/ et référencez-les avec /filename.pdf
  • Ressources par locale : Si une ressource doit être spécifique à un locale (par exemple, des captures d'écran), placez-la dans documentation/i18n/{locale}/docusaurus-plugin-content-docs/current/assets/

Créer et tester​

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

Testez toujours vos modifications dans au moins le locale anglais par défaut et un autre locale pour vous assurer que les traductions apparaissent correctement.