@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/docs/it/releases/v9.md

@@ -0,0 +1,376 @@
+---
+createdAt: 2026-06-14
+updatedAt: 2026-06-30
+title: Nuovo Intlayer v9 - Cosa c'è di nuovo?
+description: Scopri le novità di Intlayer v9. Introduzione di package di compatibilità drop-in per le più diffuse librerie i18n e supporto per Collections e Variants.
+keywords:
+  - Intlayer
+  - Compatibilità
+  - Migrazione
+  - Collections
+  - Variants
+  - CMS SDK
+  - Self-Hosting
+  - Docker
+  - i18next
+  - next-intl
+  - vue-i18n
+slugs:
+  - doc
+  - releases
+  - v9
+author: aymericzip
+---
+
+# Nuovo Intlayer v9 - Cosa c'è di nuovo?
+
+Benvenuti a Intlayer v9! Questa major release segna un'enorme pietra miliare nella semplificazione del percorso di migrazione a Intlayer con i **Compat Adapter Packages** per le principali librerie i18n (`react-i18next`, `next-intl`, `vue-i18n`, ecc.) e aggiunge il supporto per strutture di contenuto ricche: **Collections** e **Variants**.
+
+## Indice
+
+<TOC levels={[2]} maxDepth={1} />
+
+---
+
+## Compat Adapter Packages
+
+La migrazione a Intlayer dalle popolari librerie i18n è ora più facile che mai. Abbiamo creato cinque compat package che espongono le **stesse identiche API pubbliche** delle librerie i18n standard, ma delegano tutto il lavoro di traduzione a Intlayer a runtime.
+
+### Esporre la stessa API pubblica con tipizzazione stretta
+
+Sostituendo gli import, ottieni tutti i vantaggi di Intlayer (inclusa la type safety in fase di compilazione rispetto ai tuoi dizionari effettivi) con modifiche minime al codice:
+
+- `@intlayer/i18next`
+- `@intlayer/react-i18next`
+- `@intlayer/next-intl`
+- `@intlayer/react-intl`
+- `@intlayer/next-i18next`
+- `@intlayer/vue-i18n`
+- `@intlayer/lingui`
+
+Ad esempio, è sufficiente cambiare:
+
+```ts
+import { useTranslation } from "react-i18next";
+```
+
+in:
+
+```ts
+import { useTranslation } from "@intlayer/react-i18next";
+```
+
+Le tue chiavi saranno ora **strettamente tipizzate** rispetto ai tuoi dizionari Intlayer, offrendo il completamento automatico completo del dot-path nel tuo IDE!
+
+### Bundler Alias Plugins (Vite, Next.js, Turbopack)
+
+Per consentire la migrazione senza riscrivere manualmente tutte le tue istruzioni di import, ogni compat adapter package include un **plugin bundler personalizzato** (Vite o Next.js) sotto il sottopercorso `/plugin`.
+
+Questi plugin riscrivono automaticamente gli import esistenti (ad esempio `react-i18next` o `next-intl`) nei loro equivalenti `@intlayer/*` in fase di build.
+
+#### Esempio Next.js (Webpack / Turbopack)
+
+Invece di `withIntlayer`, avvolgi la tua configurazione Next.js con il compat plugin:
+
+```ts fileName="next.config.ts"
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+import type { NextConfig } from "next";
+
+const withIntlayer = createNextI18nPlugin();
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+#### Esempio Vite (React, Vue, Solid, Svelte)
+
+```ts fileName="vite.config.ts"
+import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";
+
+export default defineConfig({
+  plugins: [vueI18nVitePlugin()],
+});
+```
+
+---
+
+## Risolutore Runtime Mutualizzato
+
+Tutti i compat adapter ora instradano la risoluzione delle traduzioni attraverso un singolo parser runtime altamente ottimizzato: `@intlayer/core/messageFormat`.
+
+- **Interpolate Message**: Risolve `{{var}}` standard (spazi bianchi e dot-paths), argomenti formattati ICU (`{v, number, percent}` ecc.) e template `{var}` semplici.
+- **Message Node Resolver**: Risolve nodi annidati: `insert()`, `plural()` (regole plurali CLDR), `enu()` (enumerazione), `gender()`, tag HTML, array e nodi di funzione richiamabili.
+- **Tokenized Tag Parser**: Supporta tag XML/HTML inline e tag numerati (ad esempio, `<1>children</1>`) per abilitare il rendering di testo ricco out of the box.
+
+---
+
+## Specifica delle Funzionalità: Collections & Variants
+
+Intlayer v9 si espande oltre gli oggetti chiave-valore statici, consentendo ai dizionari di dichiarare strutture di layout dinamiche che sono completamente tipizzate end-to-end.
+
+### 1. Collections
+
+Definisci un elenco di elementi ordinati gestito da CMS (ad esempio FAQ, prodotti o elenchi di blog):
+
+```ts fileName="faq.1.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "faq",
+  item: 1,
+  content: {
+    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),
+    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),
+  },
+} satisfies Dictionary;
+```
+
+```ts fileName="faq.2.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "faq",
+  item: 2,
+  content: {
+    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),
+    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),
+  },
+} satisfies Dictionary;
+```
+
+#### Utilizzo:
+
+```ts
+// Fetch all items as an array
+const allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]
+
+// Fetch a single item by index
+const faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }
+```
+
+### 2. Variants
+
+Fornisci A/B test, header stagionali, feature flag o landing page personalizzate:
+
+#### Varianti stringa (es. test A/B)
+
+```ts fileName="hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero-banner",
+  variant: "default",
+  content: {
+    control: t({ it: "Benvenuto", en: "Welcome", fr: "Bienvenue" }),
+    black_friday: t({
+      it: "Acquista ora",
+      en: "Shop now",
+      fr: "Acheter maintenant",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+#### Utilizzo:
+
+```ts
+const banner = useIntlayer("hero-banner", { variant: "black_friday" });
+```
+
+#### Varianti oggetto (es. Dynamic Records)
+
+```ts fileName="product.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "product-copy",
+  variant: {
+    id: "prod_123",
+    category: "books",
+  },
+  content: {
+    title: t({ it: "Clean Code", en: "Clean Code", fr: "Code Propre" }),
+  },
+} satisfies Dictionary;
+```
+
+#### Utilizzo:
+
+```ts
+// Recupera solo l'elemento richiesto dinamicamente (richiede Suspense)
+const product = useIntlayer("product-copy", {
+  variant: { id: "prod_123", category: "books" },
+});
+```
+
+---
+
+## Caricamento Dinamico e Ottimizzazioni delle Dimensioni del Bundle
+
+Per mantenere i bundle estremamente piccoli, Intlayer v9 supporta il caricamento dinamico lazy loading.
+
+Nella tua configurazione, imposta `importMode` su `'dynamic'` o `'fetch'`:
+
+```ts fileName="intlayer.config.ts"
+export default {
+  dictionary: {
+    importMode: "dynamic", // "static" | "dynamic" | "fetch"
+  },
+};
+```
+
+In fase di build, `@intlayer/swc` e `@intlayer/babel` scansionano i tuoi file e sostituiscono le chiamate `useIntlayer` / `getIntlayer` con wrapper tree-shakeable (`useDictionary` / `useDictionaryDynamic`). Viene caricato solo il contenuto richiesto per l'elemento della collection, la variante o la locale selezionati, impedendo al tuo bundle di produzione di contenere traduzioni inutilizzate.
+
+---
+
+## Vite Plugin: Compiler e Proxy in Bundle
+
+Il plugin Vite `intlayer()` ora raggruppa il **compiler** e il **proxy di locale-routing** direttamente, quindi la maggior parte dei progetti ha bisogno solo di un singolo plugin in `vite.config.ts`:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+- **Compiler**: Si attiva automaticamente quando `compiler.enabled` è impostato su `true` e un percorso `compiler.output` è configurato. Non è più necessario registrare `intlayerCompiler()` separatamente.
+- **Proxy**: Si attiva automaticamente in base alla nuova opzione `routing.enableProxy` (`true` per impostazione predefinita). Collega il middleware di rilevamento locale / reindirizzamento / riscrittura in sviluppo, anteprima e SSR in produzione. Non è più necessario registrare `intlayerProxy()` separatamente.
+
+### Opzione `routing.enableProxy`
+
+Una nuova opzione `routing.enableProxy` controlla se il proxy di routing per le locale è attivo. Il valore predefinito è `true`. Disabilitalo quando desideri gestire il routing delle locale autonomamente:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  routing: {
+    enableProxy: false, // Default: true
+  },
+};
+
+export default config;
+```
+
+I plugin standalone `intlayerCompiler()` e `intlayerProxy()` rimangono esportati per configurazioni avanzate. Registrarli insieme a `intlayer()` è sicuro — ogni plugin si deduplica e viene eseguito una sola volta.
+
+---
+
+## Compilatore disabilitato per impostazione predefinita
+
+A partire da Intlayer v9, il **compilatore è disabilitato per impostazione predefinita** (`compiler.enabled` ora ha come valore predefinito `false`). Per abilitare l'estrazione dei tuoi file `.content.ts` in fase di build, imposta `compiler.enabled: true` nella tua configurazione:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  compiler: {
+    enabled: true, // Predefinito: false — richiesto per abilitare il compilatore dalla v9
+    output: ({ fileName }) => `./${fileName}.content.ts`,
+  },
+};
+
+export default config;
+```
+
+Quando il compilatore è disabilitato, Intlayer salta il passaggio di estrazione in fase di build e si basa sui dizionari che hai già dichiarato. Abilitalo solo quando vuoi che il plugin del bundler (`@intlayer/swc`, `@intlayer/babel` o il plugin Vite `intlayer()`) estragga il contenuto automaticamente.
+
+---
+
+## React Native: importazioni da un unico pacchetto
+
+In un'app React Native o Expo, non è più necessario destreggiarsi tra `react-intlayer` e `react-native-intlayer`. Il pacchetto `react-native-intlayer` ora **riesporta l'intera API `react-intlayer`** (hook, utility e i sottopercorsi `/format`, `/html` e `/markdown`), e il suo `IntlayerProvider` applica automaticamente i polyfill di React Native.
+
+Importa tutto dal pacchetto singolo `react-native-intlayer`:
+
+```tsx
+import {
+  IntlayerProvider,
+  useIntlayer,
+  useLocale,
+} from "react-native-intlayer";
+```
+
+```bash
+npm install intlayer react-native-intlayer
+```
+
+> L'importazione da `react-intlayer` continua a funzionare, ma `react-native-intlayer` è ora il punto di ingresso singolo consigliato per React Native: il suo provider include i polyfill che il provider orientato al web `react-intlayer` non ha.
+
+---
+
+## SDK CMS: usa Intlayer come database di contenuti headless
+
+Intlayer v9 include un SDK pulito e con autenticazione automatica in `@intlayer/api` per interagire con il CMS in modo programmatico — recuperare progetti, recuperare dizionari e inviarli o aggiornarli dal tuo server, script o CI. L'autenticazione (OAuth2 `client_credentials`) è gestita e rinnovata automaticamente.
+
+L'SDK è suddiviso in **due import separati**, così il tuo bundle include solo i domini che usi davvero:
+
+1. `createIntlayerCMS` — un **autenticatore** leggero che custodisce le credenziali e il token gestito (nessun client di dominio incluso).
+2. `dictionaryEndpoint`, `projectEndpoint`, … — **binder di endpoint** per dominio, ciascuno importato dal proprio sottopercorso.
+
+```ts fileName="cms.ts"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+// La configurazione è opzionale: le credenziali ricadono su INTLAYER_CLIENT_ID /
+// INTLAYER_CLIENT_SECRET risolti da `@intlayer/config/built`.
+const cms = createIntlayerCMS();
+
+// Lettura
+const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();
+
+// Scrittura — usa il CMS come un database
+await dictionaryEndpoint(cms).pushDictionaries([myDictionary]);
+```
+
+> Sicurezza: le credenziali del CMS concedono l'accesso in scrittura ai tuoi contenuti. Crea l'autenticatore sempre **lato server** — non inviare mai `clientId` / `clientSecret` al browser.
+
+---
+
+## Self-Hosting
+
+Intlayer v9 offre supporto di prima classe per eseguire la propria istanza di Intlayer con un singolo comando — nessun account Intlayer Cloud richiesto.
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+Il programma di installazione scarica un `docker-compose.yml` e un `.env`, genera automaticamente i secret necessari ed esegue `docker compose up -d`. Tutto — il dashboard, l'API, il database, l'archiviazione di oggetti e le email transazionali — viene eseguito localmente nei container.
+
+### Servizi inclusi
+
+| Servizio                                | Scopo                                                                         |
+| --------------------------------------- | ----------------------------------------------------------------------------- |
+| **app** (TanStack Start)                | Interfaccia del dashboard sulla porta `3000`                                  |
+| **backend** (Fastify/Bun)               | API REST sulla porta `3100`                                                   |
+| **MongoDB 7** (single-node replica set) | Database principale                                                           |
+| **Redis 7**                             | Code di lavori e caching                                                      |
+| **MinIO**                               | Archiviazione di oggetti compatibile S3 (avatar, screenshot)                  |
+| **Mailpit**                             | Sink SMTP locale + interfaccia web per email transazionali sulla porta `8025` |
+
+Chromium (utilizzato per la generazione di screenshot con Puppeteer) è incluso nell'immagine del backend — nessun container aggiuntivo necessario.
+
+---
+
+## Note di migrazione da v8
+
+Se stai eseguendo l'aggiornamento da v8, nota che la v9 non include breaking changes. Ma ecco le modifiche chiave:
+
+- **Compilatore disabilitato per impostazione predefinita**: `compiler.enabled` ora ha come valore predefinito `false`. Se dipendi dall'estrazione dei tuoi file `.content.ts` in fase di build, imposta `compiler.enabled: true` nel tuo `intlayer.config.ts`.
+- **Plugin Vite**: Il compilatore e il proxy di routing locale sono ora integrati in `intlayer()`. Se in precedenza hai registrato `intlayerCompiler()` o `intlayerProxy()` manualmente, puoi rimuoverli — vengono deduplicati automaticamente, quindi mantenerli è innocuo. Usa `routing.enableProxy: false` per disattivare il proxy.
+- **Locales & Dialects**: Se utilizzi dipendenze i18n esterne, aggiungi i rispettivi compat adapter plugin nella tua configurazione o setup del bundler per riscrivere automaticamente gli import.
+- **Custom Selectors**: Quando chiami `useIntlayer`, il secondo parametro è ora riservato a un oggetto di opzioni contenente `{ locale, item, variant }`. Se in precedenza passavi direttamente una stringa locale, puoi ancora farlo, ma l'utilizzo dell'oggetto di opzioni è consigliato per selezioni avanzate.
+- **React Native**: `react-native-intlayer` ora riesporta l'intera API di `react-intlayer`. In un'app React Native, importa tutto da `react-native-intlayer` e rimuovi la dipendenza diretta da `react-intlayer`. Gli import esistenti di `react-intlayer` continuano a funzionare.
+
+---
+
+## Link utili
+
+- [Guida ai Compat Adapter Packages](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/compat/index.md)
+- [Dizionari Dinamici - Collections & Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/index.md)
+- [Riferimento alla Configurazione](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md)
+- [SDK CMS - Accesso programmatico con @intlayer/api](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_CMS.md)
+- [Guida al Self-Hosting](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/self_hosting.md)

package/docs/it/roadmap.md

@@ -29,6 +29,12 @@ Intlayer è una soluzione per la gestione dei contenuti e l'internazionalizzazio
 
 ---
 
+## Sommario
+
+<TOC/>
+
+---
+
 ## Funzionalità Attuali
 
 ### 1. Dichiarazione dei Contenuti