Passa al contenuto principale

ADR 008: Invariante Strutturale Bilingue — Il Symmetry Guardrail

Stato: Attivo Decisore: Architecture Lead Data: 2026-04-20 (sprint v0.8.x, D045 — Migrazione Diátaxis)

Contesto​

Zenzic.dev è un sito di documentazione bilingue. L'inglese (docs/) è la fonte autorevole; l'italiano (i18n/it/docusaurus-plugin-content-docs/current/) è lo specchio di traduzione. Il language switcher di Docusaurus risolve le pagine italiane specchiando il percorso del filesystem inglese: un utente su /docs/reference/finding-codes passa a /it/docs/reference/finding-codes — e Docusaurus serve il file al percorso corrispondente nell'albero i18n/it/.

Durante la migrazione Diátaxis v0.8.x (D045), 29 file inglesi sono stati rinominati e spostati per allinearsi alla struttura a quattro quadranti. Diversi file italiani non sono stati spostati atomicamente nello stesso commit. Il risultato: il language switcher produceva errori 404 sulle pagine dove il file inglese era stato spostato ma lo specchio italiano no.

Questa classe di bug è particolarmente insidiosa perché:

  1. Non viene prodotto alcun errore in fase di build. onBrokenLinks: 'throw'

    rileva solo i riferimenti [testo](link) interni — non valida i percorsi del language switcher.

  2. Il bug è invisibile in modalità sviluppo. npm run start serve un solo

    locale. Il switcher è inattivo. Il 404 appare solo nell'output di just build quando entrambi i locale vengono compilati simultaneamente.

  3. La finestra di rilevamento è lunga. Un file IT mancante scoperto tre commit

    dopo il rename EN richiede un git blame forense per risalire — l'accoppiamento tra i due spostamenti non è più visibile nella storia.

Decisione​

Ogni modifica strutturale a docs/ deve essere applicata atomicamente in i18n/it/docusaurus-plugin-content-docs/current/ nello stesso commit.

Questa non è una raccomandazione — è un invariante rigido. Tre regole specifiche ne derivano:

Regola 1 — Spostamenti Atomici​

Qualsiasi spostamento o rinomina applicata a un file in docs/ deve essere accompagnata da un corrispondente spostamento o rinomina nello specchio italiano nello stesso commit.

Regola 2 — Parità degli Slug​

Se un valore slug: viene modificato in un file inglese, deve essere modificato identicamente nel file italiano corrispondente. Uno slug: divergente causa un 404 nel language switcher.

Regola 3 — Validazione della Simmetria​

Prima di fare commit di qualsiasi modifica che tocchi la struttura del filesystem, deve essere verificata la simmetria strutturale.

Per la procedura passo dopo passo con i comandi CLI e i dettagli sul controllo di simmetria, vedi la checklist per la Parità Bilingue nel Protocollo di Rilascio.

Motivazione​

1. L'Italiano è un Cittadino di Prima Classe​

La documentazione italiana non è un asset secondario o un "nice to have". È parte del contratto del Exclusion Zone. Un link che funziona in inglese ma dà 404 in italiano è un fallimento strutturale del sistema documentale — equivalente a un link interno rotto nell'albero inglese.

2. Il Language Switcher Non Ha Reti di Sicurezza​

Il onBrokenLinks: 'throw' di Docusaurus non copre i percorsi del language switcher. Questo significa che l'unica salvaguardia è la disciplina del contributore imposta da questo ADR. Non c'è nessun backstop in fase di build.

3. Coerenza della Storia Git​

Un commit atomico che sposta sia i file EN che IT crea un'unità di storia coerente: la rinomina è un singolo passaggio reversibile. I commit separati creano rumore nella storia e rendono bisect inaffidabile quando si indagano regressioni.

Invarianti (Non Negoziabili)​

  • Il comando diff di simmetria deve uscire con 0 prima di qualsiasi commit che

    modifica la struttura del filesystem di docs/ o i18n/it/.

  • I nuovi file aggiunti a docs/ devono avere un corrispondente stub aggiunto a

    i18n/it/ nello stesso commit — anche se il contenuto italiano è una copia dell'inglese fino a quando non viene fornita una traduzione.

  • L'hook pre-commit (pre-commit-config.yaml) impone la simmetria al gate.

    Aggirarlo con --no-verify su un commit strutturale è una violazione di Classe 1 (Technical Debt).

Conseguenze​

  • Ogni contributore che rinomina o sposta un file di documentazione deve essere

    consapevole dello specchio italiano — questa è una parte non opzionale del workflow di contribuzione documentato in CONTRIBUTING.md.

  • La recipe just lint-all (uvx pre-commit run --all-files) applica questo

    controllo in CI. Una PR che rompe la simmetria strutturale fallirà al gate.

  • L'invariante di simmetria si applica solo alla struttura delle directory. Il

    contenuto italiano può essere in ritardo rispetto all'inglese durante i cicli di sviluppo attivi, purché il file sia presente (anche come stub). Un 404 è peggio di una traduzione obsoleta.