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 »)	Tolgee	i18n/<lang>/docusaurus-theme-classic/*.json + .../current.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, current (labels de catégories du menu, ex. « Editor »).

ℹ️ 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) 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.

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.