From b2b92e7ce11421f35d6eccca98bd838a84005edd Mon Sep 17 00:00:00 2001 From: Patrick Schurig Date: Tue, 13 Oct 2026 06:39:19 +0200 Subject: [PATCH] feat(i18n): mkdocs-static-i18n, trois langues construites en une passe MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- .gitea/workflows/docs.yml | 12 +++++- mkdocs.yml | 90 ++++++++++++++++++++++++++++++++++++++- requirements.txt | 1 + 3 files changed, 101 insertions(+), 2 deletions(-) diff --git a/.gitea/workflows/docs.yml b/.gitea/workflows/docs.yml index b4ea4f6..0b98d5c 100644 --- a/.gitea/workflows/docs.yml +++ b/.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 ─────────────────────────────────────────────────────────────── diff --git a/mkdocs.yml b/mkdocs.yml index 37cf9bc..b7139a7 100644 --- a/mkdocs.yml +++ b/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: diff --git a/requirements.txt b/requirements.txt index 0716a54..5609747 100644 --- a/requirements.txt +++ b/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