@intlayer/docs 9.4.2 → 9.4.3

package/blog/it/date_time_number_formatting_locales.md

@@ -0,0 +1,216 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Formattare date e numeri per lingua con Intl"
+description: Probabilmente non hai bisogno di una libreria di formattazione esterna. Come Intl gestisce date, numeri, valute e liste per locale, il costo di caching e il bug di timezone in produzione.
+keywords:
+  - formattare date per locale
+  - Intl.DateTimeFormat
+  - Intl.NumberFormat
+  - toLocaleDateString
+  - formato valuta locale
+  - formato tempo relativo
+slugs:
+  - blog
+  - date-time-number-formatting-locales
+author: aymericzip
+---
+
+# Formattare date e numeri per lingua con Intl
+
+Tradurre stringhe è la metà visibile dell'internazionalizzazione. L'altra metà, quella che produce costantemente segnalazioni di bug, è la formattazione: un utente tedesco che visualizza `1,234.56` invece di `1.234,56`, un utente giapponese che vede `08/02/2026` interpretandolo come agosto, o una data che renderizza in modo disallineato tra server e client, mandando in crash l'idratazione in React.
+
+Niente di tutto questo richiede librerie di terze parti. L'API `Intl` è già integrata nativamente in tutti gli ambienti moderni.
+
+## Indice
+
+<TOC/>
+
+## Inizia rimuovendo le tue funzioni helper per le date
+
+Quasi ogni codebase include una funzione `formatDate` scritta prima ancora che qualcuno pensasse alla localizzazione. Impone un ordine rigido, un separatore fisso e generalmente nomi dei mesi in inglese.
+
+```ts
+// Il codice da eliminare:
+const formatDate = (d: Date) =>
+  `${d.getMonth() + 1}/${d.getDate()}/${d.getFullYear()}`;
+```
+
+`Intl.DateTimeFormat` la sostituisce completamente ed è corretta in ogni lingua:
+
+```ts
+new Intl.DateTimeFormat("de-DE", { dateStyle: "long" }).format(date);
+// "2. August 2026"
+new Intl.DateTimeFormat("ja-JP", { dateStyle: "long" }).format(date);
+// "2026年8月2日"
+```
+
+Lo stesso principio si applica ai numeri. `toFixed(2)` produce `1234.56` ovunque, il che è errato nella maggior parte dei paesi europei.
+
+## Cosa copre `Intl`
+
+| API                       | Quando usarla                                            |
+| :------------------------ | :------------------------------------------------------- |
+| `Intl.DateTimeFormat`     | Date e orari, con preset `dateStyle` / `timeStyle`       |
+| `Intl.NumberFormat`       | Decimali, valute, percentuali, unità, notazione compatta |
+| `Intl.RelativeTimeFormat` | "3 giorni fa", "tra 2 ore"                               |
+| `Intl.ListFormat`         | "a, b e c" rispetto a "a, b, and c"                      |
+| `Intl.PluralRules`        | Categorie di pluralizzazione per valori numerici         |
+| `Intl.Collator`           | Ordinamento alfabetico corretto in base alla lingua      |
+
+`Intl.Collator` è spesso trascurato. `array.sort()` sulle stringhe ordina in base ai code point Unicode, spostando le lettere accentate dopo la `z` e posizionando la `ö` svedese in modo errato. Se ordini elenchi visibili agli utenti, fallo con un collator.
+
+```ts
+["zebra", "édouard", "apple"].sort(new Intl.Collator("it").compare);
+// ["apple", "édouard", "zebra"]
+```
+
+## Preferisci i preset alle opzioni costruite a mano
+
+`dateStyle` e `timeStyle` consentono alla lingua di stabilire l'ordine e i separatori adeguati. Specificare manualmente `year`, `month` e `day` introduce un controllo che raramente conviene avere, poiché l'ordine corretto varia per area geografica e si finisce per sovrascrivere i dati CLDR con supposizioni arbitrarie.
+
+```ts
+// La lingua determina la struttura:
+new Intl.DateTimeFormat(locale, { dateStyle: "medium" }).format(d);
+
+// Struttura forzata a mano, errata altrove:
+new Intl.DateTimeFormat(locale, {
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+}).format(d);
+```
+
+Utilizza singoli componenti espliciti solo quando il design richiede obbligatoriamente una larghezza fissa, ad esempio in una colonna stretta di una tabella.
+
+## Creare formattatori è un'operazione onerosa
+
+Questo è il dettaglio di performance fondamentale. Istanziare un `Intl.NumberFormat` comporta il caricamento dei dati di locale ed è molto più pesante della chiamata `.format()` successiva. Farlo all'interno di un ciclo di rendering su mille righe introduce un rallentamento evidente.
+
+```ts
+// Ricostruisce il formattatore a ogni iterazione:
+rows.map((r) => new Intl.NumberFormat(locale).format(r.total));
+
+// Costruito una sola volta e riutilizzato:
+const nf = new Intl.NumberFormat(locale);
+rows.map((r) => nf.format(r.total));
+```
+
+`toLocaleDateString()` e `toLocaleString()` nascondono il medesimo problema: ogni invocazione crea una nuova istanza. Vanno bene per un singolo dato, ma non per una lista.
+
+Mantieni in cache le istanze combinando lingua e opzioni:
+
+```ts
+const cache = new Map<string, Intl.NumberFormat>();
+
+const getNumberFormat = (
+  locale: string,
+  options: Intl.NumberFormatOptions = {}
+) => {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let formatter = cache.get(key);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat(locale, options);
+    cache.set(key, formatter);
+  }
+  return formatter;
+};
+```
+
+## Il bug di timezone che si manifesta solo in produzione
+
+Questo errore ha fatto perdere interi pomeriggi a molti sviluppatori. Il server renderizza una data durante l'SSR, il browser la idrata nel client e React solleva un errore di hydration mismatch perché i due ambienti hanno generato testi differenti.
+
+La causa: `Intl.DateTimeFormat` ricorre al fuso orario del sistema operativo quando non ne viene indicato uno esplicitamente. Il server di produzione è impostato su UTC, mentre il computer locale su un altro fuso. Il problema risulta invisibile in sviluppo ed emerge solo in produzione.
+
+```ts
+// Server in UTC e browser in UTC+9 non coincidono. Hydration mismatch.
+new Intl.DateTimeFormat(locale, { dateStyle: "short" }).format(d);
+
+// Entrambi coincidono senza ambiguità:
+new Intl.DateTimeFormat(locale, { dateStyle: "short", timeZone: "UTC" }).format(
+  d
+);
+```
+
+Tre soluzioni percorribili:
+
+- **Fissare il fuso orario** sul server e passarlo esplicitamente. Deterministico, ma tutti vedono l'orario UTC.
+- **Renderizzare solo sul client**, usando un placeholder stabile durante l'SSR. Preciso per l'utente, comporta un lieve salto visivo.
+- **Memorizzare il fuso orario dell'utente** e passarlo a entrambi gli ambienti. Il risultato migliore con un po' di lavoro in più.
+
+In qualunque caso, definisci sempre `timeZone` esplicitamente su ogni data renderizzata sia sul server che sul client. Una data senza fuso orario dichiarato è una data con due valori distinti.
+
+## Una valuta ha bisogno di una valuta, non di una lingua
+
+Lingua e valuta sono concetti indipendenti. `fr-FR` non implica automaticamente l'euro: un utente francese può tranquillamente visualizzare una fattura in dollari statunitensi.
+
+```ts
+new Intl.NumberFormat("fr-FR", { style: "currency", currency: "USD" }).format(
+  1234.5
+);
+// "1 234,50 $US"
+```
+
+La lingua gestisce i separatori, il raggruppamento delle cifre e la posizione del simbolo. La valuta proviene dai dati applicativi. Dedurre l'una dall'altra genera discrepanze contabili.
+
+Presta attenzione anche a `currencyDisplay`. In contesti in cui convivono più valute col simbolo del dollaro, `"code"` rimuove ogni ambiguità tra dollari statunitensi, canadesi e australiani.
+
+## Il tempo relativo è più naturale del tempo assoluto
+
+Per gli eventi recenti, "2 ore fa" risulta molto più immediato di un timestamp rigido, e `Intl.RelativeTimeFormat` se ne occupa nativamente.
+
+```ts
+new Intl.RelativeTimeFormat("it", { numeric: "auto" }).format(-1, "day");
+// "ieri"
+```
+
+`numeric: "auto"` permette di ottenere "ieri" invece di "1 giorno fa". Senza questo parametro si ottiene la fredda forma numerica in tutte le lingue.
+
+## Cosa offre Intlayer in aggiunta
+
+Intlayer incapsula queste API in funzioni helper con cache automatica, sollevandoti dalla gestione della Map mostrata sopra, e applica la lingua attiva come default senza doverla specificare a ogni chiamata.
+
+```ts
+import {
+  number,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+  list,
+} from "intlayer";
+
+number(1234.5); // "1.234,5"
+currency(1234.5, { currency: "EUR" }); // "1.234,50 €"
+date(new Date(), "short");
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 ore fa"
+units(5, { unit: "kilometer", unitDisplay: "long" }); // "5 chilometri"
+compact(1200); // "1,2 mila"
+list(["mela", "banana", "arancia"]); // "mela, banana e arancia"
+```
+
+La funzione `date()` supporta anche preset (`"short"`, `"long"`, `"dateOnly"`, `"timeOnly"`, `"full"`), semplificando i casi più comuni. Gli equivalenti per React e Vue sono disponibili come hook e composable, risolvendo la lingua attiva direttamente dal contesto.
+
+Si tratta essenzialmente di uno strato di caching e gestione del locale predefinito costruito sopra l'API di piattaforma standard. Il comportamento di formattazione resta interamente quello di `Intl`. Consulta la lista completa nella [documentazione dei formattatori](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/formatters.md).
+
+## Errori comuni
+
+- **`toLocaleDateString()` senza specificare il locale.** Utilizza il locale del sistema host, che su un server dipende dall'immagine del container.
+- **Formattare all'interno di un ciclo senza cache.** La creazione dell'istanza assorbe la maggior parte del tempo CPU.
+- **Omettere `timeZone` sulle date isomorfe.** Causa errori di idratazione impossibili da riprodurre in locale.
+- **Dedurre la valuta dalla lingua.** `fr-FR` non garantisce euro.
+- **Eseguire `sort()` semplice su testo visualizzato.** Usa sempre `Intl.Collator`.
+- **Inserire a mano i nomi di mesi o giorni.** Sono già inclusi nel CLDR per ogni lingua.
+- **Lasciare `numeric: "always"` per il tempo relativo.** Produce "1 giorno fa" anziché "ieri".
+
+## Per approfondire
+
+- [Formattatori e utilità di locale: `number`, `currency`, `date`, `relativeTime`, `list`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/formatters.md)
+- [Riferimento configurazione](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md)
+- [Report di benchmark tra framework](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/benchmark/index.md)
+- [Adattatore di compatibilità react-intl](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/compat/react-intl.md)
+- [Formato messaggi ICU: plurali, select e scheletri numerici](https://github.com/aymericzip/intlayer/blob/main/docs/blog/it/icu_message_format.md)
+- [Come testare le traduzioni, inclusi formattatori e plurali](https://github.com/aymericzip/intlayer/blob/main/docs/blog/it/i18n_testing_strategies.md)
+- [Cosa comprende realmente l'internazionalizzazione](https://github.com/aymericzip/intlayer/blob/main/docs/blog/it/what_is_internationalization.md)

package/blog/it/detecting_missing_translations.md

@@ -0,0 +1,202 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Come individuare le traduzioni mancanti prima dei tuoi utenti"
+description: Le traduzioni mancanti falliscono in silenzio. Perché il fallback le nasconde, i quattro livelli di rilevamento realmente efficaci e come bloccare una build su una chiave non tradotta.
+keywords:
+  - trovare traduzioni mancanti
+  - chiavi traduzione mancanti
+  - audit i18n
+  - stringhe non tradotte
+  - copertura traduzioni
+  - lint i18n
+slugs:
+  - blog
+  - detecting-missing-translations
+author: aymericzip
+---
+
+# Come individuare le traduzioni mancanti prima dei tuoi utenti
+
+Una traduzione mancante non genera quasi mai un errore esplicito. A seconda della configurazione, mostra la stringa in inglese a un utente giapponese, oppure stampa `checkout.summary.total` direttamente sulla pagina in produzione. Entrambi i problemi passano la code review senza intoppi, finiscono online e vengono scoperti da un cliente anziché dal tuo team.
+
+## Indice
+
+<TOC/>
+
+## Questo vale qualunque sia la libreria utilizzata
+
+Nulla di quanto descritto qui è vincolato a uno stack specifico. I livelli di rilevamento funzionano allo stesso modo su i18next, react-i18next, next-intl, react-intl, vue-i18n, next-translate o Lingui, poiché tutti risolvono le chiavi con la medesima logica e falliscono nello stesso modo.
+
+Anche gli strumenti sono portabili. Se i tuoi messaggi risiedono oggi in cataloghi JSON, il [plugin Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/plugins/sync-json.md) punta Intlayer verso quei file, fornendoti i comandi di audit, fill e test senza spostare i contenuti né modificare un singolo import:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // o "icu" per next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+Se preferisci mantenere inalterata anche l'API a runtime, gli [adattatori di compatibilità](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/compat/index.md) creano alias a livello di bundler per `useTranslation`, `$t` e simili. In ogni caso, considera i comandi seguenti come una concreta attuazione dell'idea, non come un vincolo.
+
+## Perché i vuoti sono invisibili
+
+Ogni libreria i18n risolve una chiave attraverso la medesima catena: cerca la lingua attiva, ricorre alla lingua predefinita come fallback e, se anche questo fallisce, restituisce la chiave grezza. Quest'ultimo passaggio è il vero problema. Non c'è errore, nessun avviso in produzione e nessun test fallisce, perché nessun elemento della pipeline considera anomala una chiave mancante.
+
+Il fallback peggiora le cose anziché risolverle. Una pagina che renderizza silenziosamente in inglese sembra perfetta a uno sviluppatore anglofono e a tutti i controlli automatici. Il bug è visibile solo alla persona che non comprende il testo.
+
+La domanda non è "come gestisco le traduzioni mancanti a runtime". Bensì "come rendo impossibile il merge di una chiave non tradotta".
+
+## I quattro livelli in cui puoi intercettarle
+
+Ogni livello intercetta qualcosa che gli altri non vedono. È consigliabile adottarne più di uno.
+
+| Livello           | Rileva                                        | Ignora                                        |
+| :---------------- | :-------------------------------------------- | :-------------------------------------------- |
+| Tipi              | Chiavi che non esistono affatto               | Chiave esistente ma non tradotta in `ja`      |
+| Linter            | Testi hardcoded mai inviati in traduzione     | Chiavi mancanti da un catalogo                |
+| Audit             | Copertura lingue su ogni chiave dichiarata    | Testi che non sono mai stati resi traducibili |
+| Test di rendering | Chiavi risolte ma visualizzate in modo errato | Tutto ciò che non è coperto dai test          |
+
+La lacuna più comune riguarda la terza riga: i team sanno che le loro chiavi sono valide nel codice, ma nulla verifica che tutte le diciotto lingue contengano effettivamente un valore.
+
+## Livello 1: rendere la chiave un tipo, non una stringa
+
+`t("checkout.summry.total")` è un errore di battitura che compila perfettamente. Se le chiavi sono stringhe semplici, ogni rinomina è un rischio in produzione e ogni eliminazione lascia chiavi orfane.
+
+I tipi trasformano questo problema in un errore di compilazione. `react-i18next` lo supporta tramite declaration merging, `next-intl` lo deduce dalla struttura dei messaggi, Lingui ricava gli ID dal testo sorgente e Intlayer genera tipi restrittivi dai file di dichiarazione. Tutti funzionano; ciò che cambia è la quantità di codice di configurazione necessaria.
+
+Questo livello è indispensabile ma non sufficiente. I tipi descrivono la forma del catalogo predefinito. Non dicono nulla sul fatto che il coreano abbia un valore assegnato a quella chiave.
+
+## Livello 2: linter per le stringhe mai diventate chiavi
+
+La traduzione che non riesci a trovare è spesso quella che non è mai stata resa traducibile. Un'etichetta hardcoded in un componente è invisibile a qualsiasi audit basato su cataloghi, perché per gli strumenti quella stringa semplicemente non esiste.
+
+Il plugin ESLint di Intlayer copre questo caso con `no-raw-text`, insieme a `no-unused-content` per la situazione opposta: contenuti dichiarati che non vengono più letti da nessuna parte.
+
+```js fileName="eslint.config.mjs"
+import intlayer from "@intlayer/eslint-plugin";
+
+export default [
+  intlayer.configs.recommended,
+  {
+    rules: {
+      "@intlayer/no-raw-text": "error",
+      "@intlayer/no-unused-content": "warn",
+    },
+  },
+];
+```
+
+`no-unused-content` impedisce che i cataloghi si gonfino a dismisura. Le chiavi morte non rompono l'applicazione, ma fanno lievitare inutilmente le fatture dei servizi di traduzione. Consulta l'elenco completo delle regole nella [documentazione del plugin ESLint](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/eslint.md).
+
+## Livello 3: audit della copertura delle lingue
+
+Questo è il livello che risponde alla domanda fondamentale. Intlayer lo fornisce come comando CLI:
+
+```bash packageManager="npm"
+npx intlayer content test
+```
+
+Legge le lingue configurate e i dizionari dichiarati, quindi segnala quali chiavi mancano in quali lingue e in quale file.
+
+Un dettaglio cruciale prima di integrarlo nei tuoi flussi: **la CLI stampa un report ma restituisce codice di uscita zero.** Se la inserisci in una pipeline aspettandoti che blocchi la build, otterrai un esito positivo con una serie di avvisi che nessuno leggerà. Per creare un blocco effettivo, usa l'API programmatica illustrata di seguito.
+
+## Livello 4: asserzione nella suite di test
+
+`listMissingTranslations()` ti fornisce lo stesso audit strutturato come dati, perfetto per un gate di build.
+
+```ts fileName="i18n.test.ts"
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("translations", () => {
+  it("non presenta lingue richieste mancanti", async () => {
+    const result = await listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+Vengono restituiti tre campi principali:
+
+- `missingTranslations`: per chiave, quali lingue mancano e in quale file. È l'informazione da stampare se il test fallisce.
+- `missingLocales`: l'unione di tutte le lingue mancanti su tutte le chiavi.
+- `missingRequiredLocales`: limitato alle `requiredLocales` della tua configurazione, o a tutte le lingue se non è stato specificato.
+
+## `requiredLocales` rende il controllo sostenibile
+
+Offrire diciotto lingue non impone che tutte debbano essere complete per poter effettuare un deploy. La maggior parte dei team stabilisce un gruppo essenziale che blocca il rilascio e un gruppo che può essere completato con calma.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.JAPANESE,
+      Locales.POLISH,
+    ],
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Senza `requiredLocales`, ogni lingua configurata diventa obbligatoria e la build rimane rossa finché non arriva l'ultima traduzione. Questo finisce per spingere i team a disattivare completamente il controllo, peggiorando la situazione.
+
+## Trovare i vuoti già presenti in produzione
+
+I livelli precedenti impediscono nuovi problemi. Per un'applicazione già online, due strategie si rivelano preziose:
+
+**Pseudolocalizzazione.** Utilizza una finta lingua in cui ogni testo viene trasformato, ad esempio `[!!! Ĉĥéçķöũţ !!!]`. Tutto ciò che rimane in inglese puro è scritto direttamente nel codice. Rivela in dieci minuti ciò che un audit di catalogo non può strutturalmente vedere.
+
+**Scansione del proprio sito.** Se gestisci URL localizzati, scarica un campione di pagine per lingua e cerca nel codice HTML le stringhe della lingua di base. Una pagina in `/ja/` contenente "Add to cart" è una traduzione mancante o un fallback imprevisto.
+
+```bash
+curl -s https://example.com/ja/checkout | grep -c "Add to cart"
+```
+
+## Colmare le mancanze
+
+Una volta individuate le lacune, `intlayer fill` compila le voci vuote, e l'opzione `autoFill` può generare i file per lingua man mano che il contenuto viene dichiarato. Vedi [autoFill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/autoFill.md).
+
+È bene essere realisti: le traduzioni automatiche trasformano un vuoto _visibile_ in uno _invisibile_. La chiave ha ora un valore, l'audit diventa verde, ma nessuno ha letto il testo. Usalo per sbloccare i rilasci, ma sottoponi a revisione umana i testi critici prima che raggiungano gli utenti. È un punto di partenza, non la soluzione definitiva.
+
+## Errori comuni
+
+- **Considerare il fallback come una protezione.** È solo una strategia di rendering d'emergenza, non una rete di sicurezza. Una pagina che mostra l'inglese in silenzio è un bug invisibile.
+- **Affidarsi al report CLI per bloccare la CI.** `intlayer content test` esce con codice 0. Usa un'asserzione in un test.
+- **Rendere ogni lingua obbligatoria.** Il controllo viene rimosso non appena blocca una consegna urgente.
+- **Ispezionare i cataloghi ma mai la pagina renderizzata.** I testi hardcoded sono per definizione invisibili nei cataloghi.
+- **Testare solo la lingua predefinita.** L'unica lingua che non rischia mai di mancare.
+- **Fermarsi all'auto-fill automatico.** Audit verde su testi mai revisionati.
+
+## Per approfondire
+
+- [Testare i contenuti: audit CLI, API programmatica e asserzioni UI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/testing.md)
+- [Regole del plugin ESLint, tra cui `no-raw-text` e `no-unused-content`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/eslint.md)
+- [autoFill: generare file di dichiarazione per locale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/autoFill.md)
+- [Riferimento configurazione: `locales`, `requiredLocales`, `defaultLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md)
+- [Report di benchmark tra framework](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/benchmark/index.md)
+- [Adattatore di compatibilità i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/compat/i18next.md)
+- [Cosa comprende realmente l'internazionalizzazione](https://github.com/aymericzip/intlayer/blob/main/docs/blog/it/what_is_internationalization.md)
+- [i18n per componente vs centralizzata](https://github.com/aymericzip/intlayer/blob/main/docs/blog/it/per-component_vs_centralized_i18n.md)

package/blog/it/i18n_in_ci_cd_pipelines.md

@@ -0,0 +1,247 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Automatizzare le traduzioni in CI/CD senza rilasciare testi errati"
+description: Tre punti in cui automatizzare l'i18n, pre-push, pull request e runtime. Come bloccare una build sulla copertura, eseguire l'auto-fill in sicurezza ed evitare il loop infinito di commit.
+keywords:
+  - automatizzare traduzioni ci
+  - i18n ci cd
+  - github actions traduzioni
+  - husky pre-push
+  - localizzazione continua
+  - pipeline di traduzione
+slugs:
+  - blog
+  - i18n-in-ci-cd-pipelines
+author: aymericzip
+---
+
+# Automatizzare le traduzioni in CI/CD senza rilasciare testi errati
+
+La traduzione manuale non resiste ai ritmi di rilascio moderni. Qualcuno aggiunge una stringa il venerdì, l'esportazione avviene nello sprint successivo e nel frattempo altre tre lingue sono rimaste indietro. Automatizzarla è semplice. Automatizzarla senza pubblicare silenziosamente testi grezzi generati dalle macchine ai clienti è la vera sfida.
+
+## Indice
+
+<TOC/>
+
+## Non serve migrare per automatizzare
+
+I flussi di pipeline descritti di seguito sono indipendenti dalla libreria, così come gli strumenti. Se i tuoi messaggi sono cataloghi JSON per i18next, next-intl, react-intl, vue-i18n o next-translate, il [plugin Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/plugins/sync-json.md) legge e scrive direttamente quei file sul posto:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // o "icu" per next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+La tua applicazione continua a importare ciò che importa normalmente. I job di CI completano e proteggono i cataloghi esistenti, e il diff visualizzato dal revisore è una modifica a `locales/fr/checkout.json`, non una migrazione complessa. È disponibile anche un [plugin Sync PO](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/plugins/sync-po.md) per i flussi gettext, e [adattatori di compatibilità](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/compat/index.md) per mantenere inalterata l'API a runtime.
+
+## Separare il controllo di blocco (gate) dal riempimento (fill)
+
+Due operazioni distinte vengono continuamente confuse.
+
+Un **gate** è un controllo che fallisce. Stabilisce che la build non deve essere rilasciata perché mancano lingue richieste. Non scrive alcun file.
+
+Un **fill** è un'operazione di mutazione. Genera le traduzioni mancanti e ne esegue il commit. Non fa mai fallire una build.
+
+Eseguire solo un fill significa che nulla si blocca mai e che testi tradotti automaticamente arrivano in produzione senza revisione. Eseguire solo un gate significa che la build diventa rossa e un operatore umano deve intervenire ogni volta. La maggior parte dei team desidera entrambi con trigger separati: fill su pull request, gate al momento del merge sul branch di rilascio.
+
+## Dove collocare l'automazione
+
+| Fase           | Trigger    | Ideale per                                  | Costo                                           |
+| :------------- | :--------- | :------------------------------------------ | :---------------------------------------------- |
+| Hook pre-push  | Git locale | Feedback rapido, zero minuti CI             | Gira sulla macchina e con la chiave API del dev |
+| Pull request   | Job di CI  | Revisione prima del merge, segreti protetti | Minuti CI più chiamate al modello per PR        |
+| Branch release | Job di CI  | Blocco severo sulla copertura               | Economico, nessuna chiamata a modelli           |
+| Runtime        | CMS        | Modifiche ai testi senza ricompilazione     | Dipendenza ospitata                             |
+
+## Pre-push: il ciclo più veloce
+
+Husky esegue il fill prima che il codice lasci la macchina dello sviluppatore, così le traduzioni arrivano nello stesso push che ha introdotto le nuove stringhe.
+
+```bash fileName=".husky/pre-push"
+npx intlayer build
+npx intlayer fill --unpushed --mode complete
+```
+
+`--unpushed` limita l'elaborazione ai contenuti non ancora inviati, evitando ritardi a ogni push. `--mode complete` riempie solo ciò che manca senza sovrascrivere voci già tradotte, garantendo che una traduzione revisionata non venga mai rimpiazzata.
+
+In un monorepo, isola ogni applicazione:
+
+```bash fileName=".husky/pre-push"
+npx intlayer build --base-dir ./app1
+npx intlayer fill --base-dir ./app1 --unpushed --mode complete
+npx intlayer build --base-dir ./app2
+npx intlayer fill --base-dir ./app2 --unpushed --mode complete
+```
+
+Lo svantaggio è reale: ogni sviluppatore necessita di una chiave API e i costi ricadono su chi effettua il push. Per questo molti team spostano l'operazione nella CI con la crescita del team.
+
+## Pull request: generare dove avviene la revisione
+
+Lo stesso flusso in GitHub Actions, mirato sul diff:
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Auto-Fill
+on:
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: "autofill-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  autofill:
+    runs-on: ubuntu-latest
+    env:
+      AI_PROVIDER: openai
+      AI_MODEL: gpt-5-mini
+      AI_API_KEY: ${{ secrets.AI_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: true
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npx intlayer build
+      - run: npx intlayer fill --git-diff --mode complete --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+      - name: Commit
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            git config --local user.email "action@github.com"
+            git config --local user.name "GitHub Action"
+            git add .
+            git commit -m "chore: auto-fill missing translations [skip ci]"
+            git push origin HEAD:${{ github.head_ref }}
+          fi
+```
+
+Quattro dettagli sono fondamentali:
+
+- **`fetch-depth: 0`** è indispensabile affinché `--git-diff` funzioni. Un clone shallow non ha una base su cui calcolare il diff e l'operazione non elabora nulla silenziosamente.
+- **`[skip ci]` nel messaggio di commit** evita che il workflow si attivi all'infinito. Senza di esso il job fa commit, parte una nuova esecuzione, che fa un altro commit, esaurendo il budget CI in una notte.
+- **`concurrency` con `cancel-in-progress`** blocca due push concorrenti dall'eseguire scritture simultanee sugli stessi file.
+- **`--git-diff`** limita il riempimento alle modifiche della PR. Omettendolo, si ritraduce l'intero catalogo a ogni passaggio.
+
+Le traduzioni vengono caricate come commit sul branch della PR, così il revisore può vederle nel diff. Questo è il reale vantaggio rispetto a eseguirlo dopo il merge.
+
+## Branch di release: il gate
+
+Il gate non ha bisogno di accedere a modelli AI e deve essere veloce.
+
+```yaml fileName=".github/workflows/ci.yml"
+- run: npm run test:i18n
+```
+
+Supportato da un test che verifica la copertura con asserzioni invece di affidarsi solo all'output CLI:
+
+```ts fileName="i18n.test.ts"
+import { listMissingTranslations } from "intlayer/cli";
+
+test("non ha lingue richieste mancanti", async () => {
+  const result = await listMissingTranslations();
+  if (result.missingRequiredLocales.length > 0) {
+    console.log(result.missingTranslations);
+  }
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+`npx intlayer content test` genera un report ma restituisce codice di uscita zero, quindi informa senza bloccare. Usalo in locale; usa l'asserzione in CI. Approfondimenti in [individuare le traduzioni mancanti](https://github.com/aymericzip/intlayer/blob/main/docs/blog/it/detecting_missing_translations.md).
+
+## `requiredLocales` rende il gate sostenibile
+
+Un gate che richieda tutte le diciotto lingue complete blocca ogni rilascio finché l'ultima lingua non è pronta, e viene disabilitato entro un mese.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Dichiara le lingue supportate e richiedi come bloccanti solo quelle essenziali al rilascio. Il resto viene tradotto in modo asincrono senza frenare i deploy.
+
+## Gestire le traduzioni completamente fuori dal repository
+
+L'altro approccio consiste nel dichiarare una lingua di base nel codice e gestire il resto da remoto tramite il CMS con Live Sync. Le modifiche ai testi non richiedono alcuna ricompilazione, separando i tempi redazionali da quelli di sviluppo.
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    liveSync: true,
+  },
+};
+
+export default config;
+```
+
+Questo modello si adatta ai team in cui personale non tecnico gestisce i contenuti. È un compromesso: si ottiene autonomia editoriale ma si perde la caratteristica per cui un checkout git descrive completamente l'output dell'app. Maggiori dettagli nella [documentazione del CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_CMS.md).
+
+Nota che `clientSecret` è una credenziale lato server. Va inserita nei segreti della CI e nelle variabili d'ambiente del server, mai nel codice destinato al client.
+
+## Il limite reale
+
+Tutto ciò che è descritto sopra automatizza la _copertura_, non la _qualità_. Un riempimento automatico trasforma una mancanza evidente in una invisibile: l'audit diventa verde perché la chiave ha un valore, ma nessuno ne ha verificato la correttezza.
+
+Questo è accettabile per strumenti interni, changelog o lingue in fase beta. Non lo è per pagine di prezzi, note legali, messaggi di errore di pagamento o qualsiasi contenuto letto prima di una decisione d'acquisto. Inoltra questi testi a una revisione umana e usa `--mode complete` per evitare che stringhe già revisionate vengano sovrascritte.
+
+Fornisci contesto al modello per garantire coerenza:
+
+```ts
+ai: {
+  applicationContext: "App di fatturazione B2B. Registro formale. Non tradurre mai il nome del prodotto.",
+}
+```
+
+## Errori comuni
+
+- **Dimenticare `[skip ci]` nel commit automatico.** Il job entra in loop infinito rieseguendosi continuamente.
+- **Clone superficiale con `--git-diff`.** Nessuna base per il diff, nulla viene riempito senza alcun messaggio d'errore.
+- **Riempire l'intero catalogo a ogni esecuzione.** Limita l'ambito con `--git-diff` o `--unpushed` per contenere i costi.
+- **Usare il report CLI come gate.** Esce sempre con codice 0.
+- **Richiedere ogni lingua come obbligatoria.** Il controllo viene rimosso al primo blocco di un rilascio.
+- **Un job di fill privo di gate.** Nulla fallisce mai e testi non revisionati finiscono in produzione.
+- **Chiavi API dei modelli nel repository.** Devono risiedere nei segreti di CI, come `clientSecret`.
+
+## Per approfondire
+
+- [CI/CD: auto-generare traduzioni con Husky, GitHub Actions e il CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/CI_CD.md)
+- [Testare i contenuti e bloccare una build sulla copertura](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/testing.md)
+- [autoFill: generare file di dichiarazione per locale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/autoFill.md)
+- [Riferimento configurazione: `locales`, `requiredLocales`, `editor`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md)
+- [Report di benchmark tra framework](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/benchmark/index.md)
+- [Adattatore di compatibilità i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/compat/i18next.md)
+- [Come individuare le traduzioni mancanti](https://github.com/aymericzip/intlayer/blob/main/docs/blog/it/detecting_missing_translations.md)
+- [Come testare le traduzioni senza test fragili](https://github.com/aymericzip/intlayer/blob/main/docs/blog/it/i18n_testing_strategies.md)