Téléverser les fichiers vers "/"

2026-08-02 19:17:33 +02:00
parent 1c19a79e07
commit ed1f6ba8d1
1 changed files with 75 additions and 0 deletions
@@ -0,0 +1,75 @@
+# 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
+
+```bash
+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
+
+```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.
+
+## 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.