2a8eea6cfc
Material affiche son icône `translate` : un idéogramme 文 collé à un A. Elle dit « traduire », pas « vous êtes en français », et à la taille du bandeau on n'y voit qu'un symbole asiatique — remarque de Patrick, et elle est juste. Le bouton affiche désormais le drapeau de la langue courante et son code, comme sur etm-powersync.fr. Dans la liste déroulante, la langue courante passe en gras et en couleur d'accent : les trois lignes étaient identiques, on ne savait pas d'où l'on partait. Fait entièrement en CSS, sur `html[lang]` que mkdocs-static-i18n pose déjà par locale (`fr` à la racine, `de` sous /de/, `en` sous /en/). Aucun gabarit du thème n'est surchargé : rien à reprendre à chaque mise à jour de Material, et l'icône d'origine est masquée, pas supprimée. Trois points qui ne sont pas des détails : - Les drapeaux sont des SVG en `data:`, pas des emojis — un emoji drapeau ne se rend pas sous Windows, où Chrome affiche « FR » dans un carré. - Chaque drapeau porte un liseré : sans lui la bande blanche du français se perd dans le bandeau clair, et le noir de l'allemand dans le bandeau sombre. - Le `aria-label` du bouton (« Sélectionner la langue ») est inchangé et porte seul le sens pour les lecteurs d'écran ; il l'emporte sur le contenu, donc le « FR » du `::after` ne sera pas annoncé en double. Vérifié avant le push, faute de mkdocs installé en local : les trois pages réellement servies ont été rechargées dans Chrome headless avec cette feuille de style en remplacement, bandeau capturé dans les trois langues, plus la liste déroulante forcée ouverte pour contrôler les drapeaux et la mise en évidence. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
108 lines
5.3 KiB
Markdown
108 lines
5.3 KiB
Markdown
# powersync-docs
|
|
|
|
Documentation ETM PowerSync — [docs.etm-powersync.fr](https://docs.etm-powersync.fr)
|
|
|
|
MkDocs Material, **docs-as-code**, trois langues : `fr` (défaut) · `de` · `en`.
|
|
Licence : CC-BY-4.0 pour la documentation, GPL-3.0 pour les exemples de code.
|
|
|
|
---
|
|
|
|
## La règle qui explique tout le reste
|
|
|
|
**95 % du volume est GÉNÉRÉ, pas rédigé.** Mesure du 2026-10-12 : 74 013 mots générés
|
|
contre 3 506 mots de prose, sur 107 pages. Tout ce qui est entre
|
|
|
|
```
|
|
<!-- BEGIN GENERATED: <clé> --> … <!-- END GENERATED -->
|
|
```
|
|
|
|
est produit par un script depuis une source de vérité, et **écrasé à chaque passage**.
|
|
Éditer à l'intérieur de ces marqueurs, c'est écrire quelque chose qui disparaîtra.
|
|
|
|
| Générateur | Source de vérité | Produit |
|
|
|---|---|---|
|
|
| `scripts/gen_device_reference.py` | `PORTING_STATUS.yaml` + les `integrationplugin*.json` et `meta.json` des 5 dépôts de plugins | fiches appareils, index de catégorie, matrice de compatibilité, `appareils/SUMMARY.md` |
|
|
| `scripts/gen_api_reference.py` | `introspect.json` (introspection nymea) | référence JSON-RPC (23 pages), `api/SUMMARY.md` |
|
|
|
|
## Multi-langue — où passe la frontière
|
|
|
|
Deux régimes, et ils ne se traitent pas pareil :
|
|
|
|
- **Le bloc de référence est en ANGLAIS, une seule fois, servi identique dans les trois
|
|
langues.** Décision du 2026-10-12. La raison est une mesure, pas un goût : nymea ne sert
|
|
**aucune** traduction sur notre parc — vérifié sur le banc `hems`, où
|
|
`Integrations.GetThingClasses` rend la **même charge utile au sha256 près** (243 340 octets)
|
|
pour `fr_FR`, `de_DE` et `en_US`. Les noms de modèles, de registres et d'unités sont donc
|
|
déjà en anglais ; traduire les seuls en-têtes de colonnes autour aurait fabriqué des pages
|
|
bilingues sans rien gagner. Le vocabulaire vit dans le dict `REF` de chaque générateur.
|
|
- **La prose et la navigation se TRADUISENT.** Fichiers suffixés (`page.md` = fr,
|
|
`page.de.md`, `page.en.md`), libellés de nav par `nav_translations` dans `mkdocs.yml`,
|
|
échafaudage des pages créées par le dict `SCAFFOLD` du générateur appareils.
|
|
|
|
> **Pourquoi `SCAFFOLD` existe.** Sans lui, chaque nouvel appareil ajouté créerait sa fiche
|
|
> dans la seule langue par défaut, et `fallback_to_default` la servirait **en français** sous
|
|
> `/de/` et `/en/`. Le générateur crée donc les trois variantes — et **ne réécrit jamais** une
|
|
> page existante, pour que la prose traduite à la main survive aux régénérations.
|
|
|
|
### Localisation ≠ traduction
|
|
|
|
`docs/tarifs.md` est l'exemple à connaître : la version FR parle de Tempo et du signal RTE,
|
|
la DE de `§14a EnWG` et de SMARD, l'EN des deux. Ce ne sont **pas** des traductions l'une de
|
|
l'autre, et c'est volontaire — les signaux tarifaires sont nationaux. Même traitement pour la
|
|
ligne correspondante de `docs/fonctionnalites/index.md`.
|
|
|
|
---
|
|
|
|
## Travailler dessus
|
|
|
|
```bash
|
|
python3 -m venv .venv && . .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
|
|
# Prévisualiser (les trois langues sont construites ensemble)
|
|
mkdocs serve
|
|
|
|
# Régénérer la référence appareils — exige les JSON des 5 dépôts de plugins
|
|
# dans .plugins-src/ (la CI les clone ; en local, copiez-les depuis le workspace)
|
|
python3 scripts/gen_device_reference.py --src .plugins-src --docs docs \
|
|
--lang fr --locales fr,de,en
|
|
|
|
# Régénérer la référence API
|
|
python3 scripts/gen_api_reference.py --src introspect.json --docs docs
|
|
|
|
# Ce que vérifie la CI : rien ne doit changer après régénération
|
|
mkdocs build --strict
|
|
python3 scripts/gen_device_reference.py --src .plugins-src --docs docs \
|
|
--lang fr --locales fr,de,en --check
|
|
```
|
|
|
|
### Le sélecteur de langue
|
|
|
|
Material affiche son icône `translate` — l'idéogramme 文 collé à un A. Elle dit
|
|
« traduire », pas « vous êtes en français », et à la taille du bandeau on y voit un
|
|
symbole asiatique plutôt qu'une langue. Depuis le 2026-10-15, `stylesheets/extra.css`
|
|
la masque et affiche à la place **le drapeau de la langue courante plus son code**,
|
|
comme sur etm-powersync.fr. La langue courante est aussi mise en évidence dans la
|
|
liste déroulante, où les trois lignes étaient jusque-là identiques.
|
|
|
|
Le drapeau se choisit sur `html[lang]`, que `mkdocs-static-i18n` pose déjà par locale.
|
|
**Aucun gabarit du thème n'est surchargé** — rien à reprendre à chaque mise à jour de
|
|
Material. Les drapeaux sont des SVG en `data:` (les emojis drapeaux ne se rendent pas
|
|
sous Windows) et le `aria-label` du bouton est inchangé : c'est lui qui porte le sens
|
|
pour les lecteurs d'écran, le code « FR » du `::after` restant décoratif.
|
|
|
|
⚠️ `mkdocs build --strict` **échoue sur un simple avertissement**. C'est pour cela que
|
|
`navigation.instant` est retiré de `theme.features` : il est incompatible avec le lien
|
|
contextuel du sélecteur de langue de `mkdocs-static-i18n`. Le commentaire est dans
|
|
`mkdocs.yml`, à l'endroit du retrait.
|
|
|
|
## Déploiement
|
|
|
|
CI Gitea (`.gitea/workflows/docs.yml`) sur push vers `main`, plus un passage nocturne à 3 h
|
|
(les `meta.json` des dépôts de plugins bougent sans que ce dépôt-ci bouge). Pipeline :
|
|
clone des 5 dépôts de plugins → génération appareils → génération API → `mkdocs build
|
|
--strict` → contrôle d'idempotence → `rsync` vers le serveur.
|
|
|
|
Le build produit `site/` (fr), `site/de/` et `site/en/` en une passe ; le `rsync --delete`
|
|
pousse l'ensemble.
|