HL ConsultingKNOWLEDGE HUB

← Journal

Perso · Méthode

Knowledge Hub bilingue : version anglaise + auto-traduction

Claude · HL ·
meta seo-gtm agent en-prod Perso

Contexte

Je maîtrise le FR et l'EN, et je voulais ouvrir le site à un public anglophone. J'ai d'abord demandé une étude d'impact et de charge avant de lancer quoi que ce soit.

Première surprise en explorant le repo : la branche de travail de départ était périmée — elle ne contenait qu'une poignée de pages, alors que le vrai site sur main fait ~76 pages (≈44 entrées de journal, ~20 guides, les pages projets, veille IA, lexique…). J'ai donc resynchronisé sur main avant tout, sinon je traduisais un site fantôme.

Contraintes à respecter : site statique (HTML/CSS, zéro dépendance, GitHub Pages), socle SEO/GEO existant (JSON-LD, llms.txt) à préserver, et un ton direct/chaleureux à garder à l'identique en anglais.

Ce qui a été fait

Architecture : anglais en miroir sous /en/, FR conservé à la racine (hreflang x-default = FR), zéro JS pour la bascule. Mêmes slugs FR/EN pour fiabiliser le mapping.

Socle (scripts réutilisables dans scripts/) :

  • i18n_scaffold.py : génère le miroir /en/, injecte hreflang fr/en/x-default + canonical/og:locale par langue, et un sélecteur de langue FR/EN dans la nav de chaque page.
  • search.js / lexique.js rendus bilingues (détection de /en/ → index, glossaire et libellés EN).
  • build_sitemap.py : sitemap.xml bilingue avec alternances xhtml:link (146 URLs).
  • i18n_us_spelling.py : normalisation en anglais US (organize, color, analyze…), en protégeant les slugs d'URL et les tags.
  • i18n_normalize_nav.py : uniformisation nav/footer (Glossary, AI Watch, Connect…).
  • en/llms.txt + en/llms-full.txt, et pointeur EN dans le llms.txt FR.

Traduction (~59 000 mots) : j'ai traduit les pages piliers à la main (accueil, méthode, à propos) pour fixer le ton de référence, puis lancé 7 sous-agents en parallèle pour les 20 guides, les 43 entrées de journal et les pages structurelles, le tout cadré par un TRANSLATION_GUIDE.md (ton, règles, zones à ne pas toucher, glossaire imposé).

Automatisation : .github/workflows/i18n-translate.yml + scripts/auto_translate.py (appel API Claude en urllib, zéro dépendance). À chaque page FR poussée sur main, il (re)traduit sa jumelle EN et ouvre une PR à relire. Secret requis : ANTHROPIC_API_KEY (configuré côté GitHub, jamais dans le repo).

Bug corrigé en cours de route : le script ré-échafaudait une source FR déjà balisée i18n → il régressait nav/footer et cassait les hreflang. Passage en mode « splice » : on garde le chrome EN existant et on ne re-traduit que <main> + les méta (title/description/og), avec échappement des guillemets (" → &quot;).

Commandes types :

python3 scripts/i18n_scaffold.py        # génère/rafraîchit le miroir /en/
python3 scripts/build_sitemap.py        # sitemap bilingue
python3 scripts/auto_translate.py guides/<page>.html   # traduit la jumelle EN

Résultat & suite

En prod : le site est désormais bilingue, FR par défaut à la racine et EN en miroir sous /en/, avec sélecteur de langue, hreflang, sitemap bilingue (146 URLs) et recherche/lexique adaptés à la langue. Le socle SEO/GEO (JSON-LD, llms.txt) est préservé dans les deux langues.

Surtout, la suite est automatique : chaque nouvelle page FR poussée déclenche la traduction de sa jumelle EN via GitHub Actions, livrée en PR à relire. La leçon clé : ne jamais ré-échafauder une page déjà balisée — isoler la traduction au seul contenu (<main> + méta) évite de casser le maillage et les balises de langue.