feat(i18n): mkdocs-static-i18n, trois langues construites en une passe

mkdocs.yml : plugin i18n en mode `suffix` (page.md = fr, page.de.md,
page.en.md), fr par défaut, fallback_to_default, un index de recherche par
langue, et nav_translations — 29 éléments traduits par langue, vérifié au
build. i18n est placé AVANT literate-nav et search : il réécrit l'arbre des
fichiers par langue, les autres doivent voir l'arbre déjà localisé.

navigation.instant est RETIRÉ de theme.features. Ce n'est pas un arbitrage de
confort : il est incompatible avec le lien contextuel du sélecteur de langue de
mkdocs-static-i18n, et l'avertissement fait ÉCHOUER `mkdocs build --strict`.
Le sélecteur l'emporte — atterrir sur la même page dans l'autre langue vaut
plus qu'un chargement instantané qui renvoie à l'accueil. Le commentaire est à
l'endroit du retrait, pas ailleurs.

Vérifié que literate-nav et static-i18n cohabitent, plutôt que supposé : build
construit, nav de /de/ relue dans le HTML produit (« Geräte », « Kompatibilität »,
liste des appareils bien dépliée).

CI : --locales fr,de,en sur la génération ET sur le contrôle d'idempotence. Et
une étape qui manquait — gen_api_reference.py n'était pas dans le pipeline, sa
sortie ne se propageait donc qu'au prochain passage manuel.

requirements.txt : mkdocs-static-i18n >= 1.3.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.gitea/workflows/docs.yml

@@ -63,9 +63,18 @@ jobs:
           python3 scripts/gen_device_reference.py \
             --src .plugins-src \
             --docs docs \
-            --lang fr
+            --lang fr \
+            --locales fr,de,en
+
+      - name: Generate JSON-RPC API reference
+        run: |
+          cd /root/_work/powersync-docs
+          python3 scripts/gen_api_reference.py \
+            --src introspect.json \
+            --docs docs
 
       # ── Build MkDocs ──────────────────────────────────────────────────────
+      # i18n construit les trois langues en une passe : site/ (fr), site/de/, site/en/.
       - name: MkDocs build --strict
         run: |
           cd /root/_work/powersync-docs
@@ -79,6 +88,7 @@ jobs:
             --src .plugins-src \
             --docs docs \
             --lang fr \
+            --locales fr,de,en \
             --check
 
       # ── SSH ───────────────────────────────────────────────────────────────

mkdocs.yml

@@ -24,7 +24,10 @@ theme:
   features:
     - navigation.indexes
     - navigation.top
-    - navigation.instant
+    # - navigation.instant        # RETIRÉ (multi-langue, 2026-10-12) :
+    #   incompatible avec le lien contextuel du sélecteur de langue de
+    #   mkdocs-static-i18n, et l'avertissement fait échouer `mkdocs build --strict`.
+    #   Le sélecteur l'emporte : il ramène sur la même page dans l'autre langue.
     - navigation.footer
     - search.suggest
     - search.highlight
@@ -55,6 +58,91 @@ markdown_extensions:
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
 
 plugins:
+  # i18n AVANT literate-nav et search : il réécrit l'arbre des fichiers par langue,
+  # les autres doivent voir l'arbre déjà localisé.
+  - i18n:
+      docs_structure: suffix          # index.md (fr) · index.de.md · index.en.md
+      fallback_to_default: true       # pas de page absente : on retombe sur le FR
+      reconfigure_material: true      # bascule de langue dans le header Material
+      reconfigure_search: true        # un index de recherche par langue
+      languages:
+        - locale: fr
+          name: Français
+          default: true
+          build: true
+          site_name: ETM PowerSync — Documentation
+          theme:
+            language: fr
+        - locale: de
+          name: Deutsch
+          build: true
+          site_name: ETM PowerSync — Dokumentation
+          theme:
+            language: de
+          nav_translations:
+            Accueil: Startseite
+            Installation: Installation
+            Appareils: Geräte
+            Fonctionnalités: Funktionen
+            Référence: Referenz
+            Aide: Hilfe
+            Compatibilité: Kompatibilität
+            Dépôt APT: APT-Repository
+            Configuration: Konfiguration
+            L'application: Die App
+            Surplus solaire: Solarüberschuss
+            Délestage: Lastabwurf
+            Gestion batterie: Speicherverwaltung
+            Tarifs dynamiques: Dynamische Tarife
+            API JsonRPC: JSON-RPC-API
+            Référence API: API-Referenz
+            Dépannage: Fehlersuche
+            FAQ: FAQ
+            Compteurs: Zähler
+            Bornes de recharge: Wallboxen
+            SmartDevices: SmartDevices
+            HVAC: HVAC
+            Onduleurs / PV: Wechselrichter / PV
+            Batteries / ESS: Speicher / ESS
+            Tarifs & prévisions: Tarife & Prognosen
+            Types génériques: Generische Typen
+            API — Métier: API — Fachlich
+            API — Système: API — System
+        - locale: en
+          name: English
+          build: true
+          site_name: ETM PowerSync — Documentation
+          theme:
+            language: en
+          nav_translations:
+            Accueil: Home
+            Installation: Installation
+            Appareils: Devices
+            Fonctionnalités: Features
+            Référence: Reference
+            Aide: Help
+            Compatibilité: Compatibility
+            Dépôt APT: APT repository
+            Configuration: Configuration
+            L'application: The app
+            Surplus solaire: Solar surplus
+            Délestage: Load shedding
+            Gestion batterie: Battery management
+            Tarifs dynamiques: Dynamic tariffs
+            API JsonRPC: JSON-RPC API
+            Référence API: API reference
+            Dépannage: Troubleshooting
+            FAQ: FAQ
+            Compteurs: Meters
+            Bornes de recharge: EV chargers
+            SmartDevices: SmartDevices
+            HVAC: HVAC
+            Onduleurs / PV: Inverters / PV
+            Batteries / ESS: Batteries / ESS
+            Tarifs & prévisions: Tariffs & forecasts
+            Types génériques: Generic types
+            API — Métier: API — Domain
+            API — Système: API — System
   - search:
       lang: fr
   - literate-nav:

requirements.txt

@@ -1,3 +1,4 @@
 mkdocs-material>=9.5
 mkdocs-literate-nav>=0.6
+mkdocs-static-i18n>=1.3        # multi-langue FR/DE/EN (2026-10-12)
 PyYAML>=6.0