From 662108684cd364a7141b3219525a864e6b50d438 Mon Sep 17 00:00:00 2001 From: Jo Bo <3+jobo@noreply.localhost> Date: Sun, 2 Aug 2026 19:36:32 +0200 Subject: [PATCH] =?UTF-8?q?T=C3=A9l=C3=A9verser=20les=20fichiers=20vers=20?= =?UTF-8?q?"/"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Docusaurus-tolgee-README.md | 104 ++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 Docusaurus-tolgee-README.md diff --git a/Docusaurus-tolgee-README.md b/Docusaurus-tolgee-README.md new file mode 100644 index 0000000..a9389e7 --- /dev/null +++ b/Docusaurus-tolgee-README.md @@ -0,0 +1,104 @@ +# 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//docusaurus-plugin-content-docs/current/` | +| **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//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/` → `tolgee-staging/en/.json` (prépare la **source** anglaise à envoyer). + - `wrap` : `tolgee-staging//.json` → `i18n//` (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 + +```bash +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/.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 + +```bash +cd ~/docs-src +source .env.tolgee # charge TOLGEE_API_KEY + +# 1. Rapatrie toutes les langues : +npx tolgee pull # remplit tolgee-staging//.json + +# 2. Réinjecte au format Docusaurus : +node tolgee/transform.mjs wrap # écrit i18n//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//_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//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` : +> +> ```js +> 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//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`).