[Docs] Documentation bilingue — anglais langue principale, français conservé #18

New Issue

xmortelette · 2026-06-12T19:06:54+02:00

xmortelette commented

2026-06-12 19:06:54 +02:00

Contexte

Retour de sebt3 sur la PR documentation (sebt3/vynil#232) : « la doc publique doit être anglophone, ou mieux encore : bilingue ». Décision retenue avec Xavier : bilingue, anglais en langue principale. La PR #232 finalise le contenu en français ; la bascule linguistique se fait dans une PR dédiée pour ne pas noyer la review.

Cible

docs/ devient anglophone (langue principale, source de vérité) ;
le français est conservé intégralement sous docs/fr/ ;
le site mkdocs propose un sélecteur de langue (plugin mkdocs-static-i18n, structure par dossier) ;
llms.txt indexe la version anglaise (avec mention de l'existence du miroir français) ;
le README.md est déjà anglophone — inchangé.

Plan

Plomberie : ajouter mkdocs-static-i18n à mkdocs.yml (structure docs/en|fr ou suffixe, à trancher selon le rendu « forge » : les liens relatifs doivent rester navigables sans build) ; vérifier que la nav, la recherche et les mermaid fonctionnent dans les deux langues.
Migration : déplacer le contenu français actuel vers docs/fr/ en conservant l'arborescence (packages/, jukebox/, tooling/, operations/) et l'historique git (git mv).
Traduction (~21 pages, par lots pour des PR relisibles) :
- lot 1 — entrée : index, concepts, installation, distribution ;
- lot 2 — moteur : architecture, reconciliation, crds ;
- lot 3 — paquets : packages/format, packages/lifecycle, packages/portability, gen-package, build-signing ;
- lot 4 — jukebox & outillage : jukebox/sources, jukebox/gitlab-registry, jukebox/registry-maintenance, cli, tooling/lint, tooling/test ;
- lot 5 — exploitation : operations/security, operations/troubleshooting, operations/reference.
Index : réécrire llms.txt sur la version anglaise ; mettre à jour la section Documentation du README (liens + mention du miroir docs/fr/).
Garde-fou CI : un check (script ou lint) qui signale les pages présentes dans une langue et absentes de l'autre, pour que le miroir ne dérive pas silencieusement.

Règle de maintenance proposée

Toute nouvelle page ou modification de fond se fait d'abord en anglais, le miroir français suit dans la même PR (le check CI du point 5 l'impose structurellement).

Critères d'acceptance

mkdocs serve affiche les deux langues avec sélecteur ; aucun lien cassé dans les deux arborescences ;
navigation « forge » (Markdown brut) fonctionnelle dans les deux langues ;
llms.txt pointe sur les pages anglaises et toutes existent ;
le check de parité FR/EN passe en CI.

Hors périmètre (suivi séparé)

La généralisation des diagrammes mermaid à tous les workflows (également demandée dans le retour de la PR #232) sera traitée à part — idéalement avant la traduction pour ne traduire qu'une fois.

Issue rédigée par Claude (assistant IA), publiée via le compte de Xavier.

## Contexte Retour de sebt3 sur la PR documentation ([sebt3/vynil#232](https://github.com/sebt3/vynil/pull/232)) : « la doc publique doit être anglophone, ou mieux encore : bilingue ». Décision retenue avec Xavier : **bilingue, anglais en langue principale**. La PR #232 finalise le contenu en français ; la bascule linguistique se fait dans une PR dédiée pour ne pas noyer la review. ## Cible - `docs/` devient **anglophone** (langue principale, source de vérité) ; - le français est conservé intégralement sous `docs/fr/` ; - le site mkdocs propose un **sélecteur de langue** (plugin `mkdocs-static-i18n`, structure par dossier) ; - `llms.txt` indexe la version anglaise (avec mention de l'existence du miroir français) ; - le `README.md` est déjà anglophone — inchangé. ## Plan 1. **Plomberie** : ajouter `mkdocs-static-i18n` à `mkdocs.yml` (structure `docs/en|fr` ou suffixe, à trancher selon le rendu « forge » : les liens relatifs doivent rester navigables sans build) ; vérifier que la nav, la recherche et les mermaid fonctionnent dans les deux langues. 2. **Migration** : déplacer le contenu français actuel vers `docs/fr/` en conservant l'arborescence (`packages/`, `jukebox/`, `tooling/`, `operations/`) et l'historique git (`git mv`). 3. **Traduction** (~21 pages, par lots pour des PR relisibles) : - lot 1 — entrée : `index`, `concepts`, `installation`, `distribution` ; - lot 2 — moteur : `architecture`, `reconciliation`, `crds` ; - lot 3 — paquets : `packages/format`, `packages/lifecycle`, `packages/portability`, `gen-package`, `build-signing` ; - lot 4 — jukebox & outillage : `jukebox/sources`, `jukebox/gitlab-registry`, `jukebox/registry-maintenance`, `cli`, `tooling/lint`, `tooling/test` ; - lot 5 — exploitation : `operations/security`, `operations/troubleshooting`, `operations/reference`. 4. **Index** : réécrire `llms.txt` sur la version anglaise ; mettre à jour la section Documentation du README (liens + mention du miroir `docs/fr/`). 5. **Garde-fou CI** : un check (script ou lint) qui signale les pages présentes dans une langue et absentes de l'autre, pour que le miroir ne dérive pas silencieusement. ## Règle de maintenance proposée Toute nouvelle page ou modification de fond se fait **d'abord en anglais**, le miroir français suit dans la même PR (le check CI du point 5 l'impose structurellement). ## Critères d'acceptance - `mkdocs serve` affiche les deux langues avec sélecteur ; aucun lien cassé dans les deux arborescences ; - navigation « forge » (Markdown brut) fonctionnelle dans les deux langues ; - `llms.txt` pointe sur les pages anglaises et toutes existent ; - le check de parité FR/EN passe en CI. ## Hors périmètre (suivi séparé) La généralisation des diagrammes mermaid à tous les workflows (également demandée dans le retour de la PR #232) sera traitée à part — idéalement *avant* la traduction pour ne traduire qu'une fois. --- *Issue rédigée par Claude (assistant IA), publiée via le compte de Xavier.*

xmortelette added the Kind/Documentation

Priority

Medium

3

labels 2026-06-12 19:06:54 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: shuss/vynil#18