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
│   └── pt-BR/         # Brazilian Portuguese
├── 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
└── .intlayer/         # Intlayer generated UI translation files (auto-generated)

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 de l'interface (à partir du thème Docusaurus et des composants personnalisés) dans des fichiers de traduction JSON. Le script pnpm translate utilise l'IA pour traduire à la fois la documentation markdown et les fichiers JSON de l'interface.

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

Locale	Langue	Répertoire
en	Anglais (par défaut)	docs/ (source)
de	Allemand	i18n/de/docusaurus-plugin-content-docs/current/
es	Espagnol	i18n/es/docusaurus-plugin-content-docs/current/
fr	Français	i18n/fr/docusaurus-plugin-content-docs/current/
pt-BR	Portugais brésilien	i18n/pt-BR/docusaurus-plugin-content-docs/current/

Traduire la Documentation

La documentation utilise un système de traduction alimenté par l'IA pour traduire à la fois le contenu (fichiers markdown) et les chaînes de l'interface (à partir de Docusaurus et des 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 et le portugais brésilien.

Fonctionnement de la traduction

1. Extraction des chaînes de l'interface : pnpm write-translations extrait les chaînes traduisibles de l'interface Docusaurus et des composants personnalisés dans des fichiers JSON dans i18n/en/

2. Traduction du contenu : pnpm translate utilise OpenRouter AI pour traduire :

   • Fichiers markdown de docs/ → i18n/{locale}/docusaurus-plugin-content-docs/current/
   • Chaînes de l'interface JSON de i18n/en/ → i18n/{locale}/
   • Fichiers SVG de static/img/duplistatus*.svg (traduit le texte à l'intérieur des SVG et les exporte en PNG via Inkscape)

3. Compilation : pnpm build génère du HTML statique pour toutes les locales dans build/ (un sous-répertoire par locale)

Exécution de la traduction

cd documentation
pnpm translate                       # Translate everything to all locales
pnpm translate --force               # force the translation of all files
pnpm translate --locale fr           # Translate only to French
pnpm translate --no-svg              # Skip SVG translation
pnpm translate --path docs/intro.md  # Translate specific file
pnpm translate:status                # Show the status of translation of all files

Pour des options détaillées, la gestion du cache, le dépannage et le système de glossaire, consultez Workflow de Traduction.

Remplacements manuels de traduction

Si vous devez ajuster manuellement une traduction :

1. ajoutez les termes à glossary-user.csv
2. supprimez les entrées du cache pour ces termes en utilisant l'outil d'édition de cache web
3. relancez la traduction avec pnpm translate --force

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 de Docusaurus
• pnpm typecheck - Exécuter la vérification des types TypeScript
• pnpm write-heading-ids - Générer des identifiants de titre au format interne de Docusaurus (ne modifie pas les fichiers markdown)
• pnpm heading-ids - Ajouter des identifiants d'ancrage explicites {#id} à tous les titres markdown (modifie les fichiers ; garantit des identifiants cohérents 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 de package.json et ajoute un badge de version
• Copie le contenu de documentation/docs/intro.md
• Convertit les admonitions Docusaurus (note, tip, warning, etc.) en alertes de style GitHub
• Convertit tous les liens Docusaurus relatifs en URLs GitHub docs absolues (https://wsj-br.github.io/duplistatus/...)
• Convertit les chemins d'images de /img/ à documentation/static/img/ pour la compatibilité GitHub
• Supprime le bloc IMPORTANT de migration et ajoute une section Informations de 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 URLs absolues, convertit les alertes GitHub en format basé sur des emojis)
• Génère les notes de version GitHub (RELEASE_NOTES_github_VERSION.md) à partir de documentation/docs/release-notes/VERSION.md (convertit les liens et les images en URLs 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 avec Docker Hub. Il :

• Copie README.md vers README_dockerhub.md
• Convertit les chemins d'images relatifs en URLs GitHub brutes absolues
• Convertit les liens de documents relatifs en URLs GitHub blob absolues
• Convertit les alertes de style GitHub ([!NOTE], [!WARNING], etc.) en format basé sur les emojis pour une meilleure compatibilité avec Docker Hub
• Garantit 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 version GitHub lors de son exécution. Il :

• Lit les notes de version depuis documentation/docs/release-notes/VERSION.md (où VERSION est extrait de package.json)
• Change le titre de « # Version xxxx » à « # Release Notes - Version xxxxx »
• Convertit les liens markdown relatifs en URLs absolues de documentation GitHub (https://wsj-br.github.io/duplistatus/...)
• Convertit les chemins d'images en URLs brutes GitHub (https://raw.githubusercontent.com/wsj-br/duplistatus/main/documentation/static/img/...) pour un affichage correct dans les descriptions de version
• Gère les chemins relatifs avec le préfixe ../
• Préserve les URLs absolues (http:// et https://) inchangées
• 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 en mode headless (Puppeteer)
• Se connecte en tant qu'admin et utilisateur standard
• Navigue à travers différentes pages (tableau de bord, détails du serveur, paramètres, etc.)
• Prend des captures d'écran à différentes tailles de viewport
• 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
• 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 standard

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, de, fr, es, pt-BR. Utilisez -h ou --help pour afficher l'utilisation.

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
# Multiple locales:
pnpm take-screenshots --locale en,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 : Fichiers JSON en anglais dans documentation/i18n/en/ (générés automatiquement par pnpm write-translations)
• Navigation de la barre 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 heading-ids pour générer les identifiants de titre (ancres)
5. Exécutez pnpm translate pour traduire la nouvelle page dans tous les paramètres régionaux
6. Construire et tester : 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/

Construire 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.