165 lines
8.8 KiB
Markdown
165 lines
8.8 KiB
Markdown
# 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
|
||
|
||
```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/<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
|
||
|
||
```bash
|
||
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` :
|
||
>
|
||
> ```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/<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**
|
||
```bash
|
||
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**
|
||
```bash
|
||
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é.
|