feat: doc translation

.claude/skills/traduire/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: traduire
+description: Traduit ou met à jour les pages anglaises de la documentation DraftBot à partir des sources françaises. Prend en argument une liste de chemins de fichiers français, séparés par des espaces.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(git:*), Bash(gh pr create:*), Bash(node scripts/check-translations.mjs:*), Bash(node scripts/check-links.mjs:*), Bash(node scripts/content-hash.mjs:*)
+---
+
+Tu mets à jour la documentation anglaise de DraftBot à partir de la version
+française, qui fait autorité.
+
+## Ce que tu reçois
+
+Une liste de chemins relatifs à `docs/fr/`. Pour chacun, la page anglaise
+correspondante est au même chemin sous `docs/en/` : les noms de fichiers et
+de dossiers sont identiques entre les deux locales, seul le segment de
+locale change.
+
+Si la page anglaise existe déjà, mets-la à jour plutôt que de la réécrire :
+compare la version française actuelle à celle qu'elle traduisait
+(`git show <sourceCommit>:docs/fr/<chemin>`, d'après le frontmatter) et ne
+touche qu'aux passages correspondant aux changements. Une page anglaise
+relue par un humain ne doit pas être régénérée pour une virgule ajoutée
+côté français.
+
+## Terminologie
+
+`glossaire.json` à la racine fait autorité sur tout terme d'interface :
+noms de commandes, options du panel, libellés de boutons. Il est extrait des
+traductions officielles du bot et du panel — n'invente jamais la traduction
+d'un terme qui s'y trouve. Si un terme d'interface est absent du glossaire,
+traduis-le au mieux et signale-le dans la description de la pull request,
+pour qu'un relecteur confirme la forme retenue.
+
+Le fichier est court (un peu moins de 500 termes, environ 490 lignes) et peut
+être lu en entier. `Grep` reste le moyen le plus direct de cibler un terme
+précis :
+
+```
+Grep pattern="\"Rôles automatiques\"" path=glossaire.json
+Grep pattern="(?i)\"arrivées & départs\"" path=glossaire.json   # toutes les casses
+```
+
+Cherche chaque terme au moment où tu en as besoin. Une absence de résultat est
+une information : le terme n'est pas au glossaire, traduis-le et signale-le.
+
+Une entrée du glossaire vaut soit une chaîne, soit un tableau :
+
+```json
+"Rôles automatiques": "Automatic roles",
+"Tickets : modérateurs": ["Tickets: moderators", "Tickets: staff"]
+```
+
+Un tableau signale que plusieurs traductions officielles coexistent dans le
+produit. N'essaie pas de deviner laquelle vient du bot et laquelle du panel :
+l'ordre du tableau ne l'indique pas de façon fiable. Retiens une forme,
+tiens-t'y dans toute la page et dans les pages voisines, et signale ce choix
+dans la description de la pull request pour qu'un relecteur tranche.
+
+Une entrée dont les deux formes sont identiques n'est pas un doublon : elle
+signale un nom de commande ou d'option que le bot ne traduit pas.
+
+```json
+"config": "config",
+"couple": "couple"
+```
+
+Reprends-la telle quelle. Le nom du fichier source du bot n'est pas le nom
+de la commande : `/couple` vit dans `love.json`, `/chifumi` dans `rps.json`.
+Écrire `/love` documenterait une commande qui n'existe pas.
+
+Le glossaire distingue les termes par leur casse, et des variantes voisines
+peuvent porter des traductions différentes :
+
+```json
+"Arrivées & départs": "Welcome & goodbye",
+"Arrivées & Départs": "Joins & Leaves"
+```
+
+Avant de retenir une traduction, regarde les entrées qui l'entourent dans le
+fichier trié — `Grep` avec `-C 3` les rend sans ouvrir le fichier. Une entrée
+isolée peut cacher une contradiction située une ligne plus haut.
+
+## Règles de rédaction
+
+`docs/fr/9.appendices/1.contribute.md` définit le style attendu. Le français
+vouvoie ; l'anglais n'a pas cette distinction, mais garde le même registre :
+informatif, neutre, sans « simply », « just » ni « obviously », qui
+minimisent la difficulté pour le lecteur.
+
+## Ce qui ne se traduit pas
+
+- Les blocs MDC (`::hint`, `::tabs`, `::card`, `::collapse`) : la syntaxe et
+  les noms de propriétés restent identiques. Leurs **valeurs** se traduisent :
+  `label="Depuis le panel"` devient `label="From the panel"`.
+- Les noms de commandes Discord (`/config`, `/premium activer`) : utilise la
+  forme anglaise réelle du bot, vérifiée dans le glossaire.
+- Les émojis personnalisés (`<:icon_premium:1096140508625125417>`).
+- Les chemins d'assets : reprends ceux du fichier français, sauf si une
+  capture anglaise existe au même chemin sous le dossier `assets/` de la
+  catégorie anglaise.
+
+## Frontmatter
+
+- `slug` : le chemin d'URL anglais. Il doit commencer par le `slug` du
+  `_dir.yml` du dossier parent, privé de son suffixe `/_dir`.
+- `sourceHash` : le SHA-256 du fichier français traduit. L'obtenir par
+  `node scripts/content-hash.mjs docs/fr/<chemin>`.
+- `sourceCommit` : le SHA du commit courant (`git rev-parse HEAD`).
+- Reprends `navigation.icon`, `noindex`, `redactors` et `contributors` tels
+  quels depuis la version française.
+- Ne reprends **pas** `translate`. Cette clé, posée sur une page française,
+  l'exclut de la traduction — le changelog la porte. Une page qui te parvient
+  malgré elle est une anomalie : ne la traduis pas, signale-le.
+
+## Liens internes
+
+Un lien `/docs/engagement/niveaux` pointe vers un slug français. Dans la page
+anglaise, remplace-le par le `slug` déclaré dans le frontmatter de la page
+anglaise correspondante. Si cette page n'est pas encore traduite, garde le
+lien français : il reste valide grâce au repli par page.
+
+## Pour finir
+
+**Crée une branche avant tout commit.** Ne commite jamais sur `main` : un push
+sur `main` déclenche le déploiement en production sans relecture, et c'est
+cette relecture que la pull request existe pour obtenir.
+
+```bash
+git switch -c traduction/<pages-du-lot>   # ex. traduction/joins-and-leaves
+```
+
+Le nom dérive des pages traduites — le dernier segment du chemin d'une page,
+ou un thème commun quand le lot en compte plusieurs. Vérifie que tu n'es plus
+sur `main` (`git branch --show-current`) avant de committer, puis pousse cette
+branche et ouvre la pull request depuis elle.
+
+Lance `node scripts/check-translations.mjs` puis `node scripts/check-links.mjs`
+et vérifie que les deux passent, puis ouvre une pull request vers `main`.
+
+Dans la description de la pull request, liste pour chaque page ce qui a
+changé côté français et ce que tu as répercuté. Signale explicitement tout
+passage où tu as hésité sur la terminologie — un relecteur doit pouvoir
+vérifier tes choix sans relire l'intégralité du diff.

.github/workflows/checks.yml

@@ -0,0 +1,18 @@
+name: Vérifications
+
+on:
+  pull_request:
+    paths: ['docs/**', 'scripts/**', '.github/workflows/**']
+  workflow_dispatch:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - run: node --test 'scripts/lib/*.test.mjs'
+      - run: node scripts/check-translations.mjs
+      - run: node scripts/check-links.mjs

.github/workflows/translations.yml

@@ -0,0 +1,47 @@
+name: Synchronisation des traductions
+
+on:
+  push:
+    branches: [main]
+    paths: ['docs/fr/**']
+  workflow_dispatch:
+
+concurrency:
+  group: translations
+  # Annuler une traduction en cours laisserait une branche orpheline a mi-chemin.
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      # Requis meme sans github_token : l'action s'authentifie comme la Claude GitHub App.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # Sans cela, checkout laisse le jeton automatique dans .git/config et
+          # le push partirait sous l'identite github-actions[bot] : GitHub ne
+          # declenche aucun workflow sur ces commits, donc checks.yml ne
+          # tournerait pas sur la pull request produite ici.
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+
+      - id: stale
+        run: node scripts/check-translations.mjs --github-output
+
+      - if: steps.stale.outputs.pages != ''
+        # Ne pas ajouter github_token : GitHub ne declenche aucun workflow sur les
+        # commits signes par GITHUB_TOKEN, donc checks.yml ne tournerait pas sur la
+        # pull request produite ici.
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: "/traduire ${{ steps.stale.outputs.pages }}"
+          claude_args: |
+            --model claude-opus-5
+            --max-turns 40

.gitignore

@@ -0,0 +1,7 @@
+# Espace de travail des sessions d'implémentation assistée
+.superpowers/
+plans/
+specs/
+
+# Preferences locales de Claude Code, propres a chaque poste
+.claude/settings.local.json

README.md

@@ -1,10 +1,19 @@
 # Documentation communautaire de DraftBot
 
-Ce dépôt contient la documentation de DraftBot accesible depuis le site [draftbot.fr/docs](https://www.draftbot.fr/docs).
+Ce dépôt contient la documentation de DraftBot, accessible depuis
+[draftbot.fr/docs](https://www.draftbot.fr/docs) en français et
+[draftbot.gg/docs](https://www.draftbot.gg/docs) en anglais.
+
+Le français fait autorité : les pages sont écrites sous `docs/fr/`, et leurs
+traductions anglaises sous `docs/en/` sont produites puis relues en pull
+request.
 
 ## Contribuer à la documentation
 
-Toute aide est la bienvenue, si vous souhaitez nous aider à améliorer la documentation, n'hésitez pas à nous contacter sur le [support Discord](https://discord.gg/draftbot).
+Toute aide est la bienvenue. La page de référence pour la rédaction se trouve
+dans [`docs/fr/9.appendices/1.contribute.md`](docs/fr/9.appendices/1.contribute.md).
+Si vous souhaitez nous aider, n'hésitez pas à nous contacter sur le
+[support Discord](https://discord.gg/draftbot).
 
 ### Licence
 

docs/en/0.home.md

@@ -0,0 +1,18 @@
+---
+slug: /home
+title: Home
+description: Welcome to the DraftBot documentation. Here you will find tips, tutorials and answers to your questions.
+navigation.icon: 'twemoji:round-pushpin'
+sourceHash: 02d1db648953b017c8ae9115dd93bc0492f91dfb4d2a8136c08bb5e0bdc82ffc
+sourceCommit: 26d5c1c130aed68c757ff49ef9ac7c175ae7e59f
+---
+
+So that your discovery of **DraftBot** through our documentation goes as smoothly as possible, here are a few details about how it is written:
+
+The documentation groups **commands** and features by **module**, so you can get to know the bot clearly and intuitively.
+
+If you want to go straight to a specific feature, you can use the **search bar**.
+
+::hint{ type="info" }
+  If you would like to contact **Support**, find us on Discord by [**`clicking here`**](https://discord.gg/draftbot).
+::

docs/en/1.installation.md

@@ -0,0 +1,75 @@
+---
+slug: /installation
+title: Installation and settings
+description: Here is the process for inviting and installing DraftBot.
+navigation.icon: 'twemoji:gear'
+contributors: ['ls62', 'sagipierre', 'imroxxor', 'rababio4579']
+updatedAt: '2025-07-31'
+sourceHash: 41c9766341a9a03820fd056da4a936d7680e5d75c7aac234815422d7cec87437
+sourceCommit: 51972c2686adbcf5e90fce49c0fb3a6d854c3b34
+---
+
+## Inviting DraftBot
+
+Let's start by inviting **DraftBot** to the server by [`clicking here`](/invite).
+
+![Log in if needed, then choose your server. Finally, click "Authorize".](./assets/installation/add.jpg)
+
+::hint{ type="success" }
+  Congratulations, 𝗗𝗿𝗮𝗳𝘁𝗕𝗼𝘁 is now added to your server!
+::
+
+## Installing DraftBot
+
+Once **DraftBot** has been added to your server, you need to give it the permissions it requires. To do so, open your server settings and go to the Roles section.
+
+::hint{ type="warning" }
+  The **Administrator** permission is **strongly recommended** for **DraftBot**.
+
+  Without it, you must make sure to grant it the [permissions](#draftbot-permission-guidelines) it needs in its other roles and in every channel where it has to act.
+::
+
+If you want **DraftBot** to be able to assign roles, make sure those roles sit lower in the server hierarchy. You can change the order by dragging roles up and down:
+
+![DraftBot is positioned above the Administrator role in the role hierarchy.](./assets/installation/role.png)
+
+::hint{ type="info" }
+  In our example, **DraftBot** will be able to assign the second, third, fourth and fifth roles, but will not be able to grant the first one.
+::
+
+### DraftBot permission guidelines
+
+| Essential | Strongly recommended |
+|-----------|----------------------|
+| View Channels | **Administrator** |
+| Manage Webhooks | Manage Channels |
+| Send Messages | Manage Roles |
+| Send Messages in Threads | Manage Expressions |
+| Embed Links | View Audit Log |
+| Attach Files | Manage Nicknames |
+| Add Reactions | Kick Members |
+| Use External Emoji | Timeout Members |
+| Manage Messages | Mute Members |
+| Read Message History | Deafen Members |
+| | Move Members |
+
+::hint{ type="success" }
+  With this installation done, and if you chose to trust **DraftBot** by leaving it as Administrator, you should not run into any problem. The initial setup is now complete.
+::
+
+
+## Configuring commands
+DraftBot uses Discord slash commands. This lets users run commands easily by typing `/`. You can configure them and restrict them to certain **roles**, **channels** and **members**.
+
+To configure DraftBot's commands, go to **your server** settings on Discord, then to the **Integrations** section. You will find every bot on your server there, including DraftBot. Click **DraftBot** to display all of its commands and configure their permissions.
+
+![Overview of the Integrations page](./assets/installation/preview_integrations.png)
+
+::hint{ type="info" }
+  Command permissions can currently only be configured from Discord on desktop or Discord in a browser.
+::
+
+::hint{ type="danger" }
+  Pay close attention to how you configure your slash commands: wrong permissions given to the wrong people could compromise your server's security.
+::
+