Documents-Divers/Docusaurus-tolgee-README.md

Chaînes de thème (navbar / footer / catégories) — flux Tolgee

Ce document décrit le vrai cycle push/pull de Tolgee tel qu'il est câblé dans le projet (.tolgeerc.json + tolgee/transform.mjs + @tolgee/cli). Il ne concerne pas le contenu des pages .mdx (ça, c'est translate.py — voir translate-README.md).

Deux systèmes de traduction, à ne pas confondre

Ce qu'on traduit	Outil	Où ça atterrit
Contenu des pages (.mdx)	translate.py / manuel	i18n/<lang>/docusaurus-plugin-content-docs/current/<page>
Chaînes de thème/UI (navbar, footer, labels de catégories comme « Editor », libellés de composants React comme le widget IA)	Tolgee	i18n/<lang>/docusaurus-theme-classic/*.json + .../current.json + code.json

« Editor » (label du menu de gauche) vient de docs/editor/_category_.json : c'est une chaîne de thème, donc elle passe par Tolgee, pas par translate.py.

Les pièces du dispositif

• .tolgeerc.json — config CLI : projet 4, format JSON_I18NEXT, push/pull vers tolgee-staging/{languageTag}/{namespace}.json.
• tolgee/transform.mjs — pont entre le format Docusaurus ({clé:{message}}) et le format Tolgee/i18next (plat/imbriqué). Deux commandes :
  • flatten : i18n/en/<ns> → tolgee-staging/en/<ns>.json (prépare la source anglaise à envoyer).
  • wrap : tolgee-staging/<locale>/<ns>.json → i18n/<locale>/<ns> (réinjecte les traductions reçues).
• @tolgee/cli (devDependency) — npx tolgee push / npx tolgee pull. Auth via la variable d'env TOLGEE_API_KEY (clé du projet Tolgee) ou l'option --api-key.
• Namespaces traduits (objet NS de transform.mjs) : navbar, footer, code (libellés des composants React — ex. widget IA askAI.*). (current, labels de catégories du menu, est prévu en Phase 2.)
• PUSH_FILTER (dans transform.mjs) — pour un namespace donné, ne pousse vers Tolgee que les clés retenues. Utilisé pour code (voir la section dédiée plus bas).

ℹ️ tolgee-staging/ est volontairement exclu de la sauvegarde (fichiers temporaires) : il est régénéré par flatten (côté en) et par pull (côté traductions). Rien à restaurer.

PUSH — envoyer les chaînes source (anglais) vers Tolgee

cd ~/docs-src
source .env.tolgee                    # charge TOLGEE_API_KEY

# 1. (Si tu as changé la navbar / footer / des labels de catégories / un libellé de
#     composant React — ex. le widget IA) régénère la source anglaise :
npm run write-translations -- --locale en

# 2. Convertis la source Docusaurus -> format Tolgee :
node tolgee/transform.mjs flatten     # écrit tolgee-staging/en/<ns>.json

# 3. Envoie la source vers Tolgee :
npx tolgee push

Puis traduis dans l'interface Tolgee (https://tolgee.karaokeclip.video, projet 4) — à la main ou via la traduction automatique de Tolgee — dans les 32 langues.

PULL — récupérer les traductions et les câbler dans Docusaurus

cd ~/docs-src
source .env.tolgee                    # charge TOLGEE_API_KEY

# 1. Rapatrie toutes les langues :
npx tolgee pull                       # remplit tolgee-staging/<lang>/<ns>.json

# 2. Réinjecte au format Docusaurus :
node tolgee/transform.mjs wrap        # écrit i18n/<lang>/docusaurus-theme-classic/*.json

# 3. Build + déploiement :
./deploy.sh

Labels de catégories du menu (namespace current)

Les labels de catégories (ex. « Editor », qui vient de docs/<dossier>/_category_.json) vivent dans le namespace current. Dès qu'ils apparaissent dans i18n/en/docusaurus-plugin-content-docs/current.json (régénéré par npm run write-translations -- --locale en), ils suivent exactement le même cycle PUSH / PULL que navbar / footer — rien de particulier à faire.

Libellés des composants React (namespace code)

Les chaînes d'interface écrites avec translate({id, message}) dans des composants React (ex. le widget « Ask AI » de la doc, clés askAI.*) sont extraites par npm run write-translations dans i18n/<locale>/code.json. Elles suivent alors le même cycle PUSH / PULL que navbar / footer — rien de particulier à faire.

⚠️ Filtre indispensable. code.json contient AUSSI des chaînes de thème Docusaurus (pagination, « Previous / Next »…). On ne pousse donc vers Tolgee que nos clés, grâce à PUSH_FILTER dans transform.mjs :

const PUSH_FILTER = { code: (k) => k.startsWith('askAI.') };

Sans ce filtre, wrap réécrirait les chaînes de thème en anglais dans toutes les langues et écraserait les traductions intégrées du thème. Pour un nouveau composant traduit, ajoute son préfixe dans PUSH_FILTER (ou nomme ses clés askAI.*).

ℹ️ Ne lance jamais write-translations pour une locale ≠ en : les autres langues sont remplies uniquement par wrap (depuis Tolgee). Sinon tu réinjecterais des chaînes de thème anglaises dans i18n/<locale>/code.json.

Ce qui est traduit aujourd'hui (référence)

i18n/en/docusaurus-theme-classic/navbar.json (source) contient : title, logo.alt, item.label.Documentation, item.label.App. footer.json : copyright, les liens Application / Site / KaraokeClip. Ce sont exactement les chaînes visibles dans Tolgee et sur le site.

i18n/en/code.json (namespace code, filtré) : les ~10 clés askAI.* du widget « Ask AI » (askAI.btn, askAI.title, askAI.placeholder, askAI.intro, askAI.thinking, askAI.sources, askAI.send, askAI.supportPrompt, askAI.support, askAI.error).

Instructions d'ajout dans Tolgee des chaînes liées à l'agent IA :

Voilà — rien à changer dans le widget (mon translate() est la bonne mécanique). La seule modification nécessaire était transform.mjs, que je viens de faire : ajout du namespace code avec un filtre askAI.*. Le widget rejoint donc exactement ton flux navbar/footer.

Ce que j'ai modifié

• tolgee/transform.mjs : namespace code → code.json + PUSH_FILTER (ne pousse que askAI.*, protège les traductions de thème). Syntaxe validée ✅.
• Rien d'autre. (Ton index.jsx widget est déjà correct.)

Procédure complète (sur le VPS, ~/docs-src)

PUSH — envoyer les 10 chaînes anglaises vers Tolgee

cd ~/docs-src
source .env.tolgee                      # charge TOLGEE_API_KEY

# 1. Extraire les chaînes du widget → crée/complète i18n/en/code.json
npm run write-translations -- --locale en

# 2. Convertir la source EN → format Tolgee (pour "code", ne pousse QUE askAI.*)
node tolgee/transform.mjs flatten       # écrit tolgee-staging/en/{navbar,footer,code}.json

# 3. Envoyer vers Tolgee
npx tolgee push

→ Traduire dans Tolgee (projet 4, namespace code, les ~10 clés askAI.*) — à la main ou via l'auto-traduction Tolgee, dans les 32 langues. (Le namespace code se crée tout seul au premier push.)

PULL — récupérer les traductions et builder

cd ~/docs-src
source .env.tolgee

# 1. Rapatrier toutes les langues
npx tolgee pull                         # remplit tolgee-staging/<lang>/code.json

# 2. Réinjecter au format Docusaurus (écrit i18n/<lang>/code.json : askAI.* uniquement)
node tolgee/transform.mjs wrap

# 3. Build + déploiement
./deploy.sh

Points de vigilance (importants)

• write-translations uniquement pour --locale en. Jamais pour les autres langues — c'est wrap (depuis Tolgee) qui les remplit. Sinon tu réinjecterais des chaînes de thème en anglais.
• Le filtre askAI.* fait que seules tes 10 chaînes partent dans Tolgee → les chaînes de thème Docusaurus gardent leurs traductions intégrées. C'est le point qui évite une régression.
• Zéro retraduction de page, zéro OpenRouter. Exactement le même cycle que navbar/footer.

---

Claude à mis à jour tolgee-README.md pour refléter le nouveau namespace code :

• Tableau « Deux systèmes » : ajout des libellés de composants React (widget IA) → code.json.
• Pièces du dispositif : code ajouté à la liste des namespaces + mention de PUSH_FILTER.
• PUSH – étape 1 : le commentaire inclut désormais « un libellé de composant React (ex. le widget IA) » comme déclencheur du write-translations.
• Nouvelle section « Libellés des composants React (namespace code) » : explique l'extraction dans code.json, le filtre askAI.* indispensable (avec le pourquoi : ne pas écraser les traductions de thème), et le rappel de ne jamais lancer write-translations pour une locale ≠ en.
• « Ce qui est traduit aujourd'hui » : liste des 10 clés askAI.*.

Le README décrit maintenant fidèlement le pipeline réel (navbar + footer + code), cohérent avec le transform.mjs modifié.