# Guide — Traduction, langues et traducteur (Xcloud-Lion-v1) Ce document résume le comportement **actuel** de l’interface et des fichiers, pour éviter les zones floues (Sync manifest, scanner, fichiers JSON, etc.). --- ## 1. Où vivent les traductions ? - **Dossier :** `data/lang/` - **Fichiers :** un fichier par langue, nom officiel **`XX.json`** (ex. `fr.json`, `en.json`, `zh.json`). - **Principe :** chaque entrée est une paire **`« texte source »` → `traduction`** (la clé est en général la phrase dans la **langue de référence** du site). ### `fr.json` vs `fr_base.json` (ou autres `*_base`) - **`fr.json`** : fichier **utilisé par l’application** pour le français (`load_translation&lang=fr`). - **`fr_base.json`** (ou tout nom du genre) : **non utilisé** par le code tant qu’il n’est pas nommé exactement `fr.json`. Souvent une **sauvegarde manuelle**. À ranger hors de `data/lang/` ou renommer (`fr_backup_YYYY-MM-DD.json`) pour éviter la confusion. --- ## 2. Langue de référence vs langue affichée | Concept | Source | Rôle | |--------|--------|------| | **Langue de référence (site)** | Config Xcloud (`site_lang`) → constante JS `TRAD_REF_LANG` | Définit **quel fichier** sert de référence pour les clés et le libellé « … (réf. site) » dans le traducteur. | | **Langue affichée (visiteur / admin)** | Menu globe + `localStorage` `xcloud_lang` | Détermine **quel texte est rendu dans le HTML** après chargement des JSON. | Ce ne sont **pas** les mêmes réglages : tu peux avoir la référence en **français** et afficher le site en **中文**. --- ## 3. Changement de langue (menu globe) - Après un choix dans le menu langue, la **page entière est rechargée** (`location.reload()`), y compris en **mode admin**. - **Effet :** tout repart sur une base cohérente (`initTranslation()`), comme un premier chargement. - **Attention :** formulaires non sauvegardés sont perdus au rechargement — sauvegarder avant de changer de langue si besoin. --- ## 4. Traducteur — « Scanner le site » - Le scanner lit le **DOM** : **texte visible à l’écran au moment du scan**, pas une étiquette abstraite. - Si le menu langue est sur **中文**, tu collectes des chaînes **en chinois**, même si la colonne dit « FRANÇAIS (réf. site) » — ce libellé indique la **langue de référence configurée**, pas la langue réellement affichée. ### Avant le scan (comportement actuel) - Si la **langue affichée** ≠ **langue de référence**, une **confirmation** propose de **basculer** `xcloud_lang` vers la référence et de **recharger** — pour éviter de scanner la mauvaise langue par erreur. - Un **bandeau d’avertissement** peut aussi expliquer l’écart (langue menu ≠ réf. site). ### Bon réflexe Pour des clés **alignées sur la référence** : menu langue = **langue de référence** (ex. FR), puis ouvrir le traducteur et scanner. --- ## 5. Boutons du traducteur (récap) ### Sauvegarder - Enregistre sur le serveur le fichier JSON de la **langue cible** sélectionnée dans **Target**. - Fusionne le contenu déjà sur disque avec les modifications faites **dans la grille** du traducteur. - **À utiliser** après avoir traduit ou corrigé des lignes — c’est l’action principale du flux quotidien. ### Sync manifest - **Ne traduit pas** et **ne remplace pas** Sauvegarder. - Côté serveur (`ensure_lang_keys`) : pour la langue **Target**, ajoute les **clés** qui existent dans le fichier de **référence** (`site_lang`.json, avec repli fr/en) mais **pas encore** dans le fichier cible. - Nouvelles entrées : valeurs **vides** par défaut (tu traduis après, ou avec **IA — manquants**). ### + REF (Sync avec préremplissage) - Même alignement de **clés**, mais les nouvelles entrées sont **préremplies** avec le texte de la langue de référence (brouillon ; à retraduire si besoin). - Inutile si la cible est déjà la langue de référence (message d’erreur dans ce cas). ### IA — manquants - Remplit les **traductions vides** de la colonne cible via l’API configurée (OpenAI, etc.) — **ce** bouton fait du remplissage automatique, pas Sync. ### Filtre / tri (barre sous les boutons) - Champ **Filtrer**, **A → Z**, **Z → A**, **NON TRADUIT** : aident à naviguer dans la liste ; **pas** liés à Sync. --- ## 6. Quand utiliser Sync manifest ? | Situation | Sync utile ? | |-----------|----------------| | Tu **scannes**, tu **traduis**, tu **sauvegardes** | **Non** en général — Sauvegarder suffit. | | La **référence** (`fr.json`, etc.) a **plus de clés** que la langue cible (nouveaux textes ajoutés côté site/ref sans passer par le scan) | **Oui** — pour créer les **lignes manquantes** (vides ou via + REF). | Si tu n’utilises jamais ce cas : tu peux **ignorer Sync** sans problème pour un usage « scan → traduire → sauvegarder ». --- ## 7. Langues disponibles dans le menu - **Au chargement du JS**, une liste fixe **`Z_LANGS`** propose notamment : ar, bn, de, en, es, fr, hi, id, pt, ru, ur, zh (12 langues). - **En plus** : tout code qui apparaît dans `data/lang/*.json` sur le serveur peut être pris en charge via `list_translation_langs` / `initTranslation` (ex. `vi.json` créé à la main). - **Ajouter une langue** (gestionnaire, crayon sur le globe) : taper un code ou un nom → soit **cliquer une ligne** dans les suggestions, soit laisser le champ rempli et appuyer sur **SAUVEGARDER** (validation du champ en attente). Le serveur crée `XX.json` ; sans clé IA, le fichier est une **copie de la langue de référence** à retraduire ensuite. - Le **vietnamien** (`vi`) existe dans le **catalogue mondial** ; il n’apparaît dans le menu qu’après ajout comme ci-dessus. --- ## 8. SEO / tags (rappel court) - Les **meta** servies aux robots au premier chargement PHP suivent surtout la **config / langue du site** ; le widget ne remplace pas tout le SEO multilingue côté serveur automatiquement. - Champs **tags / mots-clés** : pensés pour des séparateurs (virgule, `;`, retours ligne au collage) ; suggestions limitées si la requête est très longue. --- ## 9. Checklist « tout actualiser » après une mise à jour du code À vérifier ensemble lors des prochaines évolutions : - [ ] **Menu langue** → rechargement complet documenté (section 3). - [ ] **Traducteur** : scanner = DOM visible ; confirmation si langue ≠ réf. (section 4). - [ ] **Sauvegarder** vs **Sync** vs **IA** : rôles distincts (sections 5–6). - [ ] **Fichiers** : seul `XX.json` officiel ; pas de double `*_base` dans `data/lang/` sans le savoir (section 1). - [ ] **Liste des langues** : défaut `Z_LANGS` + fichiers sur disque (section 7). --- *Dernière mise à jour du guide : alignée sur le comportement décrit dans les échanges produit / technique pour Xcloud-Lion-v1 (`index.php`, `server.php`).*