@intlayer/docs 7.0.0-canary.2 → 7.0.0

package/docs/it/releases/v7.md

@@ -0,0 +1,504 @@
+---
+createdAt: 2025-09-22
+updatedAt: 2025-09-23
+title: Nuovo Intlayer v7 - Novità
+description: Scopri le novità di Intlayer v7. Miglioramenti significativi nelle prestazioni, nell'esperienza dello sviluppatore e nuove funzionalità per migliorare il tuo flusso di lavoro di internazionalizzazione.
+keywords:
+  - Intlayer
+  - Localizzazione
+  - Sviluppo
+  - Prestazioni
+  - Esperienza dello sviluppatore
+  - Funzionalità
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - releases
+  - v7
+---
+
+# Nuovo Intlayer v7 - Novità
+
+Benvenuto in Intlayer v7! Questa versione principale introduce miglioramenti significativi nelle prestazioni, nella sicurezza dei tipi e nell'esperienza dello sviluppatore. Di seguito i punti salienti, con note di migrazione ed esempi pratici.
+
+## Punti salienti
+
+- Strategia di caching per build più veloci
+- Generazione migliorata dei tipi TypeScript con tipi specifici per locale
+- Ottimizzazione del bundle: Locali come stringhe invece che enum
+- Nuove modalità di routing: `prefix-no-default`, `prefix-all`, `no-prefix`, `search-params`
+- Archiviazione locale conforme al GDPR con localStorage come predefinito
+- Configurazione flessibile dello storage: cookie, localStorage, sessionStorage o multipli
+- Dimensione del pacchetto Visual Editor ridotta del 30%
+- Opzioni di configurazione middleware migliorate
+- Comportamento aggiornato del comando fill per una migliore gestione dei contenuti
+- Stabilità migliorata con aggiornamenti completi dei file di dichiarazione dei contenuti
+- Gestione intelligente dei retry per una maggiore accuratezza delle traduzioni
+- Parallelizzazione per un'elaborazione delle traduzioni più veloce
+- Suddivisione intelligente per gestire file di grandi dimensioni entro i limiti del contesto AI
+
+---
+
+## Prestazioni: Caching per build più veloci
+
+Invece di ricostruire le dichiarazioni di contenuto con esbuild a ogni build, la versione 7 implementa una strategia di caching che accelera il processo di build.
+
+```bash
+npx intlayer build
+```
+
+Il nuovo sistema di caching:
+
+- Memorizza le dichiarazioni di contenuto compilate per evitare elaborazioni ridondanti
+- Rileva le modifiche e ricostruisce solo i file modificati
+- Riduce significativamente i tempi di build per progetti di grandi dimensioni
+
+---
+
+## TypeScript: Generazione di tipi specifici per locale
+
+I tipi TypeScript ora vengono generati per ogni locale, offrendo un typing più forte ed eliminando i tipi unione tra tutti i locali.
+
+**Comportamento v6:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }
+```
+
+**Comportamento v7:**
+
+```tsx
+tsx;
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" }
+```
+
+Vantaggi:
+
+- Completamento automatico più preciso nel tuo IDE
+- Maggiore sicurezza dei tipi senza inquinamento tra tipi di diverse localizzazioni
+- Prestazioni migliorate riducendo la complessità dei tipi
+
+---
+
+## Ottimizzazione del bundle: Locali come stringhe
+
+Il tipo `Locales` non è più un enum, il che significa che ora è completamente tree-shakeable e non appesantirà il tuo bundle con migliaia di record di localizzazione inutilizzati.
+
+**v6:**
+
+```typescript
+import { Locales } from "intlayer";
+// Enum che include tutte le localizzazioni -> non tree-shakeable
+
+const locale: Locales = Locales.ENGLISH;
+```
+
+**v7:**
+
+```typescript
+import { Locales, Locale } from "intlayer";
+// Tipo stringa -> completamente tree-shakeable
+
+const locale: Locale = Locales.ENGLISH;
+```
+
+> Poiché `Locales` non è più un enum, dovrai cambiare il tipo da `Locales` a `Locale` per ottenere la localizzazione come tipo.
+
+Consulta i [dettagli di implementazione](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts) per maggiori informazioni.
+
+---
+
+## Nuove modalità di routing per una maggiore flessibilità
+
+La versione 7 introduce una configurazione unificata `routing.mode` che sostituisce le precedenti opzioni `prefixDefault` e `noPrefix`, offrendo un controllo più granulare sulla struttura degli URL.
+
+### Modalità di routing disponibili
+
+- **`prefix-no-default`** (predefinita): la localizzazione predefinita non ha prefisso, le altre localizzazioni sì
+  - `/dashboard` (en) o `/fr/dashboard` (fr)
+- **`prefix-all`**: tutte le localizzazioni hanno un prefisso
+  - `/en/dashboard` (en) o `/fr/dashboard` (fr)
+- **`no-prefix`**: Nessun prefisso di localizzazione negli URL (la localizzazione è gestita tramite storage/header)
+  - `/dashboard` per tutte le localizzazioni
+- **`search-params`**: La localizzazione viene passata come parametro di query
+  - `/dashboard?locale=en` o `/dashboard?locale=fr`
+
+### Configurazione di base
+
+```typescript
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default", // predefinito
+  },
+};
+```
+
+---
+
+## Conformità GDPR: storage in localStorage / cookie
+
+La versione 7 dà priorità alla privacy dell'utente utilizzando `localStorage` come meccanismo di storage predefinito invece dei cookie. Questo cambiamento aiuta a rispettare il GDPR evitando la necessità del consenso per i cookie relativi alle preferenze di localizzazione.
+
+### Opzioni di configurazione dello storage
+
+Il nuovo campo `routing.storage` è disponibile in aggiunta alle precedenti opzioni `middleware.cookieName` e `middleware.serverSetCookie`, offrendo configurazioni di storage flessibili:
+
+```typescript
+// Disabilita lo storage
+storage: false
+
+// Tipi di storage semplici
+storage: 'cookie'
+storage: 'localStorage'
+storage: 'sessionStorage'
+
+// Cookie con attributi personalizzati
+storage: {
+  type: 'cookie',
+  name: 'custom-locale',
+  domain: '.example.com',
+  secure: true,
+  sameSite: 'strict'
+}
+
+// localStorage con chiave personalizzata
+storage: {
+  type: 'localStorage',
+  name: 'custom-locale'
+}
+
+// Più tipi di storage per ridondanza
+storage: ['cookie', 'localStorage']
+```
+
+### Esempio di configurazione conforme al GDPR
+
+Per applicazioni in produzione che devono bilanciare funzionalità e conformità al GDPR:
+
+```typescript
+typescript;
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default",
+    storage: [
+      {
+        type: "localStorage", // Archiviazione primaria (non necessita di consenso)
+        name: "user-locale",
+      },
+      {
+        type: "cookie", // Archiviazione cookie opzionale (richiede consenso)
+        name: "user-locale",
+        secure: true,
+        sameSite: "strict",
+        httpOnly: false,
+      },
+    ],
+  },
+};
+```
+
+### Abilitare / disabilitare l'archiviazione tramite cookie
+
+Esempio con React / Next.js:
+
+Può essere definito globalmente:
+
+```typescript
+<IntlayerProvider isCookieEnabled={false}>
+  <App />
+</IntlayerProvider>
+```
+
+Può essere sovrascritto localmente per ogni hook:
+
+```ts
+const { setLocale } = useLocale({ isCookieEnabled: false });
+
+setLocale("en");
+```
+
+**Nota:** I cookie sono abilitati di default.
+**Nota:** Controlla i [requisiti GDPR per i cookie](https://gdpr.eu/cookies/) per il tuo caso specifico.
+
+---
+
+## Visual Editor: pacchetto ridotto del 30%
+
+Il pacchetto Visual Editor è stato ottimizzato per essere il 30% più piccolo rispetto alla versione precedente, grazie a:
+
+- Miglioramenti delle prestazioni dell'editor di codice
+- Rimozione di dipendenze non necessarie dai pacchetti core di Intlayer
+- Migliore tree-shaking e bundling dei moduli
+
+Questo si traduce in tempi di download più rapidi e prestazioni di runtime migliorate per la tua applicazione.
+
+---
+
+## Comando Fill: comportamento aggiornato per una migliore gestione dei contenuti
+
+La versione 7 introduce un comportamento migliorato per il comando `fill`, offrendo una gestione dei contenuti più prevedibile e flessibile:
+
+### Nuovo comportamento di fill
+
+- **`fill: true`** - Riscrive il file corrente con il contenuto compilato per tutte le localizzazioni
+- **`fill: "path/to/file"`** - Compila il file specificato senza modificare il file corrente
+- **`fill: false`** - Disabilita completamente l'auto-fill
+
+### Supporto migliorato per strutture di contenuto complesse
+
+Il comando fill ora supporta strutture complesse di dichiarazione del contenuto, inclusi:
+
+- **Oggetti composti**: Dichiarazioni di contenuto che fanno riferimento ad altri oggetti
+- **Contenuto destrutturato**: Contenuto che utilizza pattern di destrutturazione
+- **Riferimenti annidati**: Oggetti che si richiamano a vicenda in gerarchie complesse
+- **Strutture di contenuto dinamiche**: Contenuto con proprietà condizionali o calcolate
+
+### Vantaggi
+
+- **Intento più chiaro**: Il comportamento è ora più esplicito su cosa viene modificato
+- **Migliore separazione**: I file di contenuto possono essere mantenuti separati dalle traduzioni compilate
+- **Flusso di lavoro migliorato**: Gli sviluppatori hanno un maggiore controllo su dove vengono memorizzate le traduzioni
+- **Supporto per strutture complesse**: Gestione di architetture di contenuto sofisticate con molteplici oggetti interconnessi
+
+### Esempio di utilizzo
+
+```typescript
+// Riscrive il file corrente con tutte le localizzazioni
+const content = {
+  key: "example",
+  fill: true, // Riscrive questo file
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Compila un file separato senza modificare il file corrente
+const content = {
+  key: "example",
+  fill: "./translations.json", // Crea/aggiorna translations.json
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Disabilita il riempimento automatico
+const content = {
+  key: "example",
+  fill: false, // Nessun riempimento automatico
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Struttura di contenuto complessa con oggetti composti
+const sharedContent = {
+  buttons: {
+    save: "Salva",
+    cancel: "Annulla",
+  },
+};
+
+const content = {
+  key: "complex-example",
+  fill: true,
+  content: {
+    // Riferimenti ad altri oggetti
+    sharedContent,
+
+    // Contenuto destrutturato
+    ...sharedContent,
+
+    // Riferimenti annidati
+    sections: [
+      {
+        ...sharedContent.buttons,
+        header: "Sezione 1",
+      },
+    ],
+  },
+};
+```
+
+---
+
+## Maggiore stabilità e gestione delle traduzioni
+
+La versione 7 introduce diversi miglioramenti per rendere la traduzione dei contenuti più affidabile ed efficiente:
+
+### Aggiornamenti completi dei file di dichiarazione dei contenuti
+
+Il sistema ora aggiorna i file `.content.{ts,js,cjs,mjs}` invece di aggiornamenti parziali, garantendo:
+
+- **Integrità dei dati**: La riscrittura completa dei file previene aggiornamenti parziali che potrebbero corrompere il contenuto
+- **Coerenza**: Tutte le localizzazioni vengono aggiornate in modo atomico, mantenendo la sincronizzazione
+- **Affidabilità**: Riduce il rischio di file di contenuto incompleti o malformati
+
+### Gestione intelligente dei tentativi di ripetizione
+
+I nuovi meccanismi di retry impediscono di inviare contenuti in formati errati e evitano che l'intero processo di fill si interrompa se una richiesta fallisce.
+
+### Parallelizzazione per un'elaborazione più veloce
+
+Le operazioni di traduzione ora vengono eseguite in coda per poter essere processate in parallelo. Questo accelera significativamente il processo.
+
+### Suddivisione intelligente per file di grandi dimensioni
+
+Strategie avanzate di chunking gestiscono file di contenuto di grandi dimensioni senza superare i limiti del contesto AI:
+
+### Esempio di flusso di lavoro
+
+```typescript
+// Il file di contenuto di grandi dimensioni viene automaticamente suddiviso in chunk
+const content = {
+  key: "large-documentation",
+  fill: true,
+  content: {
+    // Contenuto grande automaticamente suddiviso in chunk per l'elaborazione AI
+    introduction: "..." // oltre 5000 caratteri
+    sections: [
+      // Più sezioni grandi
+    ]
+  }
+};
+```
+
+Il sistema automaticamente:
+
+1. Analizza la dimensione e la struttura del contenuto
+2. Suddivide il contenuto in chunk appropriati
+3. Elabora i chunk in parallelo
+4. Valida e ritenta se necessario
+5. Ricostruisce il file completo
+
+---
+
+## Note di migrazione dalla versione v6
+
+### Configurazioni rimosse
+
+- **`middleware.cookieName`**: Sostituito da `routing.storage`
+- **`middleware.serverSetCookie`**: Sostituito da `routing.storage`
+- **`middleware.prefixDefault`**: Sostituito da `routing.mode`
+- **`middleware.noPrefix`**: Sostituito da `routing.mode`
+
+### Mappatura della migrazione
+
+#### Mappatura della configurazione
+
+| Configurazione v6          | Configurazione v7                                             |
+| -------------------------- | ------------------------------------------------------------- |
+| `autoFill: xxx`            | `fill: xxx`                                                   |
+| `prefixDefault: false`     | `mode: 'prefix-no-default'`                                   |
+| `prefixDefault: true`      | `mode: 'prefix-all'`                                          |
+| `noPrefix: true`           | `mode: 'no-prefix'`                                           |
+| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }`              |
+| `serverSetCookie: 'never'` | `storage: false` o rimuovere il cookie dall'array di storage` |
+
+#### Esempio di migrazione
+
+**Prima (v6):**
+
+````typescript
+export default {
+#### Mappatura della configurazione
+
+| Configurazione v6         | Configurazione v7                                    |
+| ------------------------ | --------------------------------------------------- |
+| `autoFill: xxx`          | `fill: xxx`                                         |
+| `prefixDefault: false`   | `mode: 'prefix-no-default'`                         |
+| `prefixDefault: true`    | `mode: 'prefix-all'`                                |
+| `noPrefix: true`         | `mode: 'no-prefix'`                                 |
+| `cookieName: 'my-locale'`| `storage: { type: 'cookie', name: 'my-locale' }`   |
+| `serverSetCookie: 'never'`| `storage: false` o rimuovere il cookie dall'array di storage |
+
+#### Esempio di migrazione
+
+**Prima (v6):**
+
+```typescript
+export default {
+  middleware: {
+    headerName: "x-intlayer-locale",
+    cookieName: "intlayer-locale",
+    prefixDefault: false,
+    basePath: "",
+    serverSetCookie: "always",
+    noPrefix: false,
+  },
+};
+````
+
+**Dopo (v7):**
+
+```typescript
+export default {
+  routing: {
+    mode: "prefix-no-default",
+    storage: "localStorage", // oppure 'cookie' se è necessario lo storage tramite cookie
+    headerName: "x-intlayer-locale",
+    basePath: "",
+  },
+};
+```
+
+#### Mappatura del contenuto del dizionario
+
+| Contenuto dizionario v6 | Contenuto dizionario v7 |
+| ----------------------- | ----------------------- |
+| `autoFill: xxx`         | `fill: xxx`             |
+
+#### Esempio di migrazione
+
+**Prima (v6):**
+
+```typescript
+const content = {
+  key: "example",
+  autoFill: true, // Riscrive questo file
+  content: {
+    title: "Hello World",
+  },
+};
+```
+
+**Dopo (v7):**
+
+```typescript
+const content = {
+  key: "example",
+  fill: true, // Riscrive questo file
+  content: {
+    title: "Hello World",
+  },
+};
+```
+
+---
+
+## Note di migrazione da v5 a v6
+
+Consulta le [note di migrazione da v5 a v6](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/releases/v6.md) per maggiori informazioni.
+
+---
+
+## Link utili
+
+- [Riferimento alla configurazione](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md)
+- [Documentazione Middleware](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/next-intlayer/index.md)
+- [Tipi TypeScript](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)
+- [Linee guida GDPR sui cookie](https://gdpr.eu/cookies/)

package/docs/ja/configuration.md

@@ -333,30 +333,6 @@ module.exports = config;
       - `noPrefix = false` の場合: URLは `https://example.com/my-app/en`
       - `noPrefix = true` の場合: URLは `https://example.com`
 
-- **detectLocaleOnPrefetchNoPrefix**:
-  - _タイプ_: `boolean`
-  - _デフォルト_: `false`
-  - _説明_: Next.jsのプリフェッチリクエスト時にロケール検出を行うかどうかを制御します。
-  - _例_: `true`
-  - _注意_: この設定はNext.jsのロケールプリフェッチの動作に影響します：
-    - **例のシナリオ:**
-      - ユーザーのブラウザ言語が `'fr'`
-      - 現在のページが `/fr/about`
-      - リンクが `/about` をプリフェッチする
-    - **`detectLocaleOnPrefetchNoPrefix: true` の場合:**
-      - プリフェッチはブラウザから `'fr'` ロケールを検出
-      - プリフェッチを `/fr/about` にリダイレクト
-    - **`detectLocaleOnPrefetchNoPrefix: false`（デフォルト）の場合:**
-      - プリフェッチはデフォルトロケールを使用
-      - プリフェッチを `/en/about` にリダイレクト（`'en'` がデフォルトの場合）
-    - **`true` を使うべき場合:**
-      - アプリがローカライズされていない内部リンクを使用している場合（例：`<a href="/about">`）
-      - 通常のリクエストとプリフェッチリクエスト間で一貫したロケール検出動作を望む場合
-    - **`false`（デフォルト）を使用する場合：**
-      - アプリがロケール接頭辞付きリンクを使用している場合（例：`<a href="/fr/about">`）
-      - プリフェッチのパフォーマンスを最適化したい場合
-      - リダイレクトループの可能性を回避したい場合
-
 ---
 
 ### コンテンツ設定

package/docs/ja/intlayer_CMS.md

@@ -510,15 +510,6 @@ module.exports = config;
 
 注意事項と制約：
 
-- サイトのセキュリティポリシー（CSP）にLive Syncのオリジンを追加してください。`connect-src`（および該当する場合は`frame-ancestors`）にLive SyncのURLが許可されていることを確認してください。
-- Live Syncは静的出力では動作しません。Next.jsの場合、ページは動的である必要があり、ランタイムで更新を受け取るために（例：`generateStaticParams`、`generateMetadata`、`getServerSideProps`、または`getStaticProps`を適切に使用して）完全な静的のみの制約を回避してください。
-
-```
-
-このセットアップは、開発サーバーを Live Sync サーバーでラップし、起動時にリモート辞書を取得し、CMS からの更新を SSE 経由でストリーミングします。変更を確認するにはページをリフレッシュしてください。
-
-注意事項と制約：
-
 - Live Sync のオリジンをサイトのセキュリティポリシー（CSP）に追加してください。Live Sync の URL が `connect-src`（および該当する場合は `frame-ancestors`）で許可されていることを確認してください。
 - Live Sync は静的出力では動作しません。Next.js の場合、ページはランタイムで更新を受け取るために動的である必要があります（例：完全な静的のみの制約を避けるために、`generateStaticParams`、`generateMetadata`、`getServerSideProps`、または `getStaticProps` を適切に使用してください）。
 - CMSでは、各辞書に`live`フラグがあります。`live=true`の辞書のみがライブ同期APIを通じて取得され、それ以外は動的にインポートされ、実行時には変更されません。