325409dd3f
82 pages .de.md et 82 .en.md. La volumétrie explique la forme : 95 % du volume est GÉNÉRÉ (74 013 mots contre 3 506 rédigés, mesuré sur 107 pages). On ne traduisait donc pas 77 500 mots — on traduit la prose, et le vocabulaire des générateurs fait le reste. Prose traduite à la main : accueil, installation (4), fonctionnalités (4), tarifs, référence, dépannage, FAQ, intégrations (2), api/index, et les 6 fiches appareils qui portent une vraie prose + compatibilite.md. Les blocs générés ne sont JAMAIS recopiés dans une traduction : le script de pose les reprend verbatim du fichier français via des placeholders, pour qu'une traduction ne puisse pas désynchroniser un bloc généré. Les 49 fiches légères n'ont rien à traduire : leur tagline vient d'amont et est DÉJÀ en anglais (« Connects nymea to powerfox. »). Constat, pas renoncement. Localisation ≠ traduction, et tarifs.md en 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. Aucune des deux n'est annoncée comme livrée : les deux sont Roadmap, et les pages le disent. Référence régénérée : en-têtes et libellés en anglais (Field/Type/Notes, Supported models, Settings, Read-only, Brand / Model…). Conséquence assumée et signalée : les pages FR en ligne changent aussi. README.md (il était VIDE) : la règle du 95 % généré en tête, la frontière de décision du multi-langue avec sa mesure, pourquoi SCAFFOLD existe, et le piège --strict/navigation.instant. TODO : multi-langue clos, et trois points ouverts qui en restent — les tagline vivent dans les meta.json de 5 autres dépôts (forme à ajouter : tagline_de / tagline_en), les stubs traduits restent des stubs (la dette éditoriale a triplé en surface, pas en fond), api/types.md n'a pas besoin de variante. Le P1 openmeteo est corrigé sur constat : il EST dans PORTING_STATUS depuis, et une ligne commentée contradictoire y traîne encore. Vérifié : mkdocs build --strict vert sur les trois langues, 322 pages HTML, contenu traduit relu dans le HTML produit, et les deux générateurs rendent « Doc à jour » en --check. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
93 lines
4.4 KiB
Markdown
93 lines
4.4 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
|
|
```
|
|
|
|
⚠️ `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.
|