@intlayer/docs 7.3.0 → 7.3.2-canary.0

package/docs/it/bundle_optimization.md

@@ -0,0 +1,184 @@
+---
+createdAt: 2025-11-25
+updatedAt: 2025-11-25
+title: Ottimizzazione della Dimensione e delle Prestazioni del Bundle i18n
+description: Riduci la dimensione del bundle dell'applicazione ottimizzando i contenuti di internazionalizzazione (i18n). Scopri come sfruttare il tree shaking e il lazy loading per i dizionari con Intlayer.
+keywords:
+  - Ottimizzazione del Bundle
+  - Automazione dei Contenuti
+  - Contenuti Dinamici
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - bundle-optimization
+history:
+  - version: 6.0.0
+    date: 2025-11-25
+    changes: Inizializzazione della cronologia
+---
+
+# Ottimizzazione della Dimensione e delle Prestazioni del Bundle i18n
+
+Una delle sfide più comuni con le soluzioni i18n tradizionali basate su file JSON è la gestione della dimensione dei contenuti. Se gli sviluppatori non separano manualmente i contenuti in namespace, gli utenti spesso finiscono per scaricare le traduzioni di ogni pagina e potenzialmente di ogni lingua solo per visualizzare una singola pagina.
+
+Ad esempio, un'applicazione con 10 pagine tradotte in 10 lingue potrebbe far sì che un utente scarichi il contenuto di 100 pagine, anche se ha bisogno solo di **una** (la pagina corrente nella lingua corrente). Questo comporta uno spreco di banda e tempi di caricamento più lenti.
+
+> Per rilevarlo, puoi utilizzare un bundle analyzer come `rollup-plugin-visualizer` (vite), `@next/bundle-analyzer` (next.js) o `webpack-bundle-analyzer` (React CRA / Angular / ecc).
+
+**Intlayer risolve questo problema attraverso l'ottimizzazione in fase di build.** Analizza il tuo codice per rilevare quali dizionari sono effettivamente utilizzati per ogni componente e reinserisce solo il contenuto necessario nel tuo bundle.
+
+## Indice
+
+<TOC />
+
+## Come Funziona
+
+Intlayer utilizza un **approccio per componente**. A differenza dei file JSON globali, il tuo contenuto è definito accanto o all'interno dei tuoi componenti. Durante il processo di build, Intlayer:
+
+1.  **Analizza** il tuo codice per trovare le chiamate a `useIntlayer`.
+2.  **Costruisce** il contenuto del dizionario corrispondente.
+3.  **Sostituisce** la chiamata a `useIntlayer` con codice ottimizzato basato sulla tua configurazione.
+
+Questo garantisce che:
+
+- Se un componente non è importato, il suo contenuto non viene incluso nel bundle (Eliminazione del codice morto).
+- Se un componente è caricato in modo lazy, anche il suo contenuto viene caricato in modo lazy.
+
+## Configurazione per Piattaforma
+
+### Next.js
+
+Next.js richiede il plugin `@intlayer/swc` per gestire la trasformazione, poiché Next.js utilizza SWC per le build.
+
+> Questo plugin è installato di default perché i plugin SWC sono ancora sperimentali per Next.js. Potrebbe cambiare in futuro.
+
+### Vite
+
+Vite utilizza il plugin `@intlayer/babel` che è incluso come dipendenza di `vite-intlayer`. L'ottimizzazione è abilitata di default.
+
+### Webpack
+
+Per abilitare l'ottimizzazione del bundle con Intlayer su Webpack, è necessario installare e configurare il plugin Babel (`@intlayer/babel`) o SWC (`@intlayer/swc`) appropriato.
+
+### Expo / Lynx
+
+L'ottimizzazione del bundle **non è ancora disponibile** per questa piattaforma. Il supporto sarà aggiunto in una futura release.
+
+## Configurazione
+
+Puoi controllare come Intlayer ottimizza il tuo bundle tramite la proprietà `build` nel tuo file `intlayer.config.ts`.
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  build: {
+    optimize: true,
+    importMode: "static", // oppure 'dynamic'
+    traversePattern: ["**/*.{js,ts,mjs,cjs,jsx,tsx}", "!**/node_modules/**"],
+  },
+};
+
+export default config;
+```
+
+> È consigliato mantenere l'opzione di default per `optimize` nella maggior parte dei casi.
+
+> Consulta la documentazione per maggiori dettagli: [Configurazione](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md)
+
+### Opzioni di Build
+
+Le seguenti opzioni sono disponibili sotto l'oggetto di configurazione `build`:
+
+| Proprietà             | Tipo                            | Predefinito                     | Descrizione                                                                                                                                                                                                                        |
+| :-------------------- | :------------------------------ | :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`optimize`**        | `boolean`                       | `undefined`                     | Controlla se l'ottimizzazione della build è abilitata. Se `true`, Intlayer sostituisce le chiamate al dizionario con inject ottimizzati. Se `false`, l'ottimizzazione è disabilitata. Idealmente impostato a `true` in produzione. |
+| **`importMode`**      | `'static' , 'dynamic' , 'live'` | `'static'`                      | Determina come vengono caricati i dizionari (vedi dettagli sotto).                                                                                                                                                                 |
+| **`traversePattern`** | `string[]`                      | `['**/*.{js,ts,jsx,tsx}', ...]` | Pattern glob che definiscono quali file Intlayer deve scansionare per l'ottimizzazione. Usalo per escludere file non correlati e velocizzare le build.                                                                             |
+| **`outputFormat`**    | `'esm', 'cjs'`                  | `'esm', 'cjs'`                  | Controlla il formato di output dei dizionari costruiti.                                                                                                                                                                            |
+
+## Modalità di Importazione
+
+L'impostazione `importMode` determina come il contenuto del dizionario viene iniettato nel tuo componente.
+
+### 1. Modalità Statica (`default`)
+
+In modalità statica, Intlayer sostituisce `useIntlayer` con `useDictionary` e inietta il dizionario direttamente nel bundle JavaScript.
+
+- **Vantaggi:** Rendering istantaneo (sincrono), nessuna richiesta di rete aggiuntiva durante l'hydration.
+- **Svantaggi:** Il bundle include le traduzioni per **tutte** le lingue disponibili per quel componente specifico.
+- **Ideale per:** Single Page Applications (SPA).
+
+**Esempio di codice trasformato:**
+
+```tsx
+// Il tuo codice
+const content = useIntlayer("my-key");
+
+// Codice ottimizzato (Statico)
+const content = useDictionary({
+  key: "my-key",
+  content: {
+    nodeType: "translation",
+    translation: {
+      en: "My title",
+      fr: "Mon titre",
+    },
+  },
+});
+```
+
+### 2. Modalità Dinamica
+
+In modalità dinamica, Intlayer sostituisce `useIntlayer` con `useDictionaryAsync`. Questo utilizza `import()` (meccanismo simile a Suspense) per caricare pigramente specificamente il JSON per la locale corrente.
+
+- **Vantaggi:** **Tree shaking a livello di locale.** Un utente che visualizza la versione inglese scaricherà _solo_ il dizionario inglese. Il dizionario francese non viene mai caricato.
+- **Svantaggi:** Genera una richiesta di rete (fetch dell'asset) per ogni componente durante l'hydration.
+- **Ideale per:** Blocchi di testo grandi, articoli o applicazioni che supportano molte lingue dove la dimensione del bundle è critica.
+
+**Esempio di codice trasformato:**
+
+```tsx
+// Il tuo codice
+const content = useIntlayer("my-key");
+
+// Codice ottimizzato (Dinamico)
+const content = useDictionaryAsync({
+  en: () =>
+    import(".intlayer/dynamic_dictionary/my-key/en.json").then(
+      (mod) => mod.default
+    ),
+  fr: () =>
+    import(".intlayer/dynamic_dictionary/my-key/fr.json").then(
+      (mod) => mod.default
+    ),
+});
+```
+
+> Quando si utilizza `importMode: 'dynamic'`, se si hanno 100 componenti che usano `useIntlayer` in una singola pagina, il browser tenterà 100 richieste separate. Per evitare questa "cascata" di richieste, raggruppare il contenuto in meno file `.content` (ad esempio, un dizionario per sezione della pagina) invece di uno per ogni componente atomico.
+
+> Attualmente, `importMode: 'dynamic'` non è completamente supportato per Vue e Svelte. Si consiglia di utilizzare `importMode: 'static'` per questi framework fino a futuri aggiornamenti.
+
+### 3. Modalità Live
+
+Si comporta in modo simile alla modalità Dynamic ma tenta prima di recuperare i dizionari dall'API Intlayer Live Sync. Se la chiamata API fallisce o il contenuto non è contrassegnato per aggiornamenti live, si ricade sull'importazione dinamica.
+
+> Consulta la documentazione CMS per maggiori dettagli: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_CMS.md)
+
+## Riepilogo: Static vs Dynamic
+
+| Caratteristica           | Modalità Static                                        | Modalità Dynamic                              |
+| :----------------------- | :----------------------------------------------------- | :-------------------------------------------- |
+| **Dimensione Bundle JS** | Più grande (include tutte le lingue per il componente) | Più piccolo (solo codice, nessun contenuto)   |
+| **Caricamento Iniziale** | Istantaneo (Il contenuto è nel bundle)                 | Leggero ritardo (Recupera JSON)               |
+| **Richieste di Rete**    | 0 richieste aggiuntive                                 | 1 richiesta per dizionario                    |
+| **Tree Shaking**         | A livello di componente                                | A livello di componente + a livello di lingua |
+| **Caso d'Uso Migliore**  | Componenti UI, Piccole App                             | Pagine con molto testo, Molte lingue          |

package/docs/it/compiler.md

@@ -0,0 +1,133 @@
+---
+createdAt: 2025-09-09
+updatedAt: 2025-09-09
+title: Intlayer Compiler | Estrazione Automatica dei Contenuti per i18n
+description: Automatizza il tuo processo di internazionalizzazione con Intlayer Compiler. Estrai contenuti direttamente dai tuoi componenti per un i18n più veloce ed efficiente in Vite, Next.js e altro.
+keywords:
+  - Intlayer
+  - Compiler
+  - Internazionalizzazione
+  - i18n
+  - Automazione
+  - Estrazione
+  - Velocità
+  - Vite
+  - Next.js
+  - React
+  - Vue
+  - Svelte
+slugs:
+  - doc
+  - compiler
+history:
+  - version: 7.3.1
+    date: 2025-11-27
+    changes: Rilascio Compiler
+---
+
+# Intlayer Compiler | Estrazione Automatica dei Contenuti per i18n
+
+## Cos'è Intlayer Compiler?
+
+Il **Intlayer Compiler** è uno strumento potente progettato per automatizzare il processo di internazionalizzazione (i18n) nelle tue applicazioni. Scansiona il tuo codice sorgente (JSX, TSX, Vue, Svelte) alla ricerca di dichiarazioni di contenuto, le estrae e genera automaticamente i file di dizionario necessari. Questo ti permette di mantenere i contenuti co-localizzati con i tuoi componenti mentre Intlayer gestisce la sincronizzazione e la gestione dei dizionari.
+
+## Perché Usare Intlayer Compiler?
+
+- **Automazione**: Elimina il copia-incolla manuale dei contenuti nei dizionari.
+- **Velocità**: Estrazione dei contenuti ottimizzata per garantire che il processo di build rimanga veloce.
+- **Esperienza Sviluppatore**: Mantieni le dichiarazioni di contenuto esattamente dove vengono utilizzate, migliorando la manutenibilità.
+- **Aggiornamenti in tempo reale**: Supporta Hot Module Replacement (HMR) per un feedback immediato durante lo sviluppo.
+
+Consulta il post sul blog [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/it/compiler_vs_declarative_i18n.md) per un confronto più approfondito.
+
+## Perché non usare Intlayer Compiler?
+
+Sebbene il compiler offra un'esperienza eccellente "funziona subito", introduce anche alcuni compromessi di cui dovresti essere consapevole:
+
+- **Ambiguità euristica**: Il compiler deve indovinare cosa è contenuto orientato all'utente rispetto alla logica dell'applicazione (ad esempio, `className="active"`, codici di stato, ID prodotto). In codebase complesse, questo può portare a falsi positivi o stringhe mancate che richiedono annotazioni manuali ed eccezioni.
+- **Estrazione solo statica**: L'estrazione basata sul compiler si basa sull'analisi statica. Le stringhe che esistono solo in fase di esecuzione (codici di errore API, campi CMS, ecc.) non possono essere scoperte o tradotte dal compiler da solo, quindi hai ancora bisogno di una strategia i18n di runtime complementare.
+
+Per un confronto architetturale più approfondito, consulta il post sul blog [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/it/compiler_vs_declarative_i18n.md).
+
+Come alternativa, per automatizzare il tuo processo i18n mantenendo il pieno controllo del tuo contenuto, Intlayer fornisce anche un comando di auto-estrazione `intlayer transform` (vedi [documentazione CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/transform.md)), o il comando `Intlayer: extract content to Dictionary` dall'estensione Intlayer VS Code (vedi [documentazione estensione VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/vs_code_extension.md)).
+
+## Utilizzo
+
+### Vite
+
+Per le applicazioni basate su Vite (React, Vue, Svelte, ecc.), il modo più semplice per utilizzare il compiler è tramite il plugin `vite-intlayer`.
+
+#### Installazione
+
+```bash
+npm install vite-intlayer
+```
+
+#### Configurazione
+
+Aggiorna il tuo `vite.config.ts` per includere il plugin `intlayerCompiler`:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer, intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer(),
+    intlayerCompiler(), // Aggiunge il plugin del compiler
+  ],
+});
+```
+
+#### Supporto per Framework
+
+Il plugin Vite rileva e gestisce automaticamente diversi tipi di file:
+
+- **React / JSX / TSX**: Gestito nativamente.
+- **Vue**: Richiede `@intlayer/vue-compiler`.
+- **Svelte**: Richiede `@intlayer/svelte-compiler`.
+
+Assicurati di installare il pacchetto compiler appropriato per il tuo framework:
+
+```bash
+# Per Vue
+npm install @intlayer/vue-compiler
+
+# Per Svelte
+npm install @intlayer/svelte-compiler
+```
+
+### Next.js (Babel)
+
+Per Next.js o altre applicazioni basate su Webpack che utilizzano Babel, puoi configurare il compiler usando il plugin `@intlayer/babel`.
+
+#### Installazione
+
+```bash
+npm install @intlayer/babel
+```
+
+#### Configurazione
+
+Aggiorna il tuo `babel.config.js` (o `babel.config.json`) per includere il plugin di estrazione. Forniamo un helper `getExtractPluginOptions` per caricare automaticamente la tua configurazione Intlayer.
+
+```js fileName="babel.config.js"
+const {
+  intlayerExtractBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    // Extract content from components into dictionaries
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    // Optimize imports by replacing useIntlayer with direct dictionary imports
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+Questa configurazione garantisce che il contenuto dichiarato nei tuoi componenti venga estratto automaticamente e utilizzato per generare i dizionari durante il processo di build.

package/docs/it/how_works_intlayer.md

@@ -141,7 +141,7 @@ Il pacchetto `vue-intlayer` è utilizzato per interpretare i dizionari di Intlay
 
 Il pacchetto `nuxt-intlayer` è un modulo Nuxt per rendere utilizzabili i dizionari Intlayer nelle applicazioni Nuxt. Integra funzionalità essenziali per far funzionare Intlayer in un ambiente Nuxt, come il middleware per la traduzione, il routing e la configurazione del file `nuxt.config.js`.
 
-### svelte-intlayer (WIP)
+### svelte-intlayer
 
 Il pacchetto `svelte-intlayer` è utilizzato per interpretare i dizionari di Intlayer e renderli utilizzabili nelle applicazioni Svelte.
 

package/docs/it/vs_code_extension.md

@@ -42,6 +42,10 @@ Link all'estensione: [https://marketplace.visualstudio.com/items?itemName=Intlay
 
 ## Funzionalità
 
+![Estrai contenuto](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_extract_content.gif?raw=true)
+
+- **Estrai Contenuto** – Estrai contenuto dai tuoi componenti React / Vue / Svelte
+
 ![Riempi dizionari](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_fill_active_dictionary.gif?raw=true)
 
 - **Navigazione Istantanea** – Passa rapidamente al file di contenuto corretto cliccando su una chiave `useIntlayer`.

package/docs/ja/bundle_optimization.md

@@ -0,0 +1,184 @@
+---
+createdAt: 2025-11-25
+updatedAt: 2025-11-25
+title: i18n バンドルサイズとパフォーマンスの最適化
+description: 国際化（i18n）コンテンツを最適化してアプリケーションのバンドルサイズを削減します。Intlayerを使った辞書のツリーシェイキングと遅延読み込みの活用方法を学びましょう。
+keywords:
+  - バンドル最適化
+  - コンテンツ自動化
+  - 動的コンテンツ
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - bundle-optimization
+history:
+  - version: 6.0.0
+    date: 2025-11-25
+    changes: 初期履歴
+---
+
+# i18n バンドルサイズとパフォーマンスの最適化
+
+従来のJSONファイルに依存するi18nソリューションで最も一般的な課題の一つは、コンテンツサイズの管理です。開発者が手動でコンテンツをネームスペースに分割しない場合、ユーザーは単一のページを閲覧するためだけに、すべてのページや場合によってはすべての言語の翻訳をダウンロードしてしまうことがよくあります。
+
+例えば、10ページが10言語に翻訳されたアプリケーションでは、ユーザーは実際に必要な**1ページ**（現在の言語の現在のページ）だけでよいにもかかわらず、100ページ分のコンテンツをダウンロードすることになりかねません。これにより、帯域幅の無駄遣いと読み込み時間の遅延が発生します。
+
+> これを検出するには、`rollup-plugin-visualizer`（vite）、`@next/bundle-analyzer`（next.js）、`webpack-bundle-analyzer`（React CRA / Angular / など）といったバンドルアナライザーを使用できます。
+
+**Intlayerはビルド時の最適化によってこの問題を解決します。** コードを解析して、各コンポーネントで実際に使用されている辞書を検出し、必要なコンテンツのみをバンドルに再注入します。
+
+## 目次
+
+<TOC />
+
+## 仕組み
+
+Intlayerは**コンポーネント単位のアプローチ**を採用しています。グローバルなJSONファイルとは異なり、コンテンツはコンポーネントのそばまたは内部に定義されます。ビルドプロセス中にIntlayerは以下を行います：
+
+1.  コードを**解析**して`useIntlayer`の呼び出しを見つけます。
+2.  対応する辞書コンテンツを**構築**します。
+3.  設定に基づいて`useIntlayer`の呼び出しを最適化されたコードに**置き換え**ます。
+
+これにより以下が保証されます：
+
+- コンポーネントがインポートされていなければ、そのコンテンツはバンドルに含まれません（デッドコード削除）。
+- コンポーネントがレイジーロードされる場合、そのコンテンツもレイジーロードされます。
+
+## プラットフォーム別セットアップ
+
+### Next.js
+
+Next.js はビルドに SWC を使用しているため、変換を処理するために `@intlayer/swc` プラグインが必要です。
+
+> このプラグインは、Next.js における SWC プラグインがまだ実験的なため、デフォルトでインストールされています。将来的に変更される可能性があります。
+
+### Vite
+
+Vite は `vite-intlayer` の依存として含まれている `@intlayer/babel` プラグインを使用します。最適化はデフォルトで有効になっています。
+
+### Webpack
+
+Webpack で Intlayer のバンドル最適化を有効にするには、適切な Babel (`@intlayer/babel`) または SWC (`@intlayer/swc`) プラグインをインストールして設定する必要があります。
+
+### Expo / Lynx
+
+このプラットフォームではバンドル最適化は**まだ利用できません**。将来のリリースでサポートが追加される予定です。
+
+## 設定
+
+Intlayerがバンドルを最適化する方法は、`intlayer.config.ts`の`build`プロパティで制御できます。
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  build: {
+    optimize: true,
+    importMode: "static", // または 'dynamic'
+    traversePattern: ["**/*.{js,ts,mjs,cjs,jsx,tsx}", "!**/node_modules/**"],
+  },
+};
+
+export default config;
+```
+
+> `optimize`のデフォルトオプションを維持することが、ほとんどの場合で推奨されます。
+
+> 詳細はドキュメントの設定をご覧ください: [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/configuration.md)
+
+### ビルドオプション
+
+`build`構成オブジェクトの下で利用可能なオプションは以下の通りです：
+
+| プロパティ            | 型                              | デフォルト                      | 説明                                                                                                                                                                                                         |
+| :-------------------- | :------------------------------ | :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`optimize`**        | `boolean`                       | `undefined`                     | ビルド最適化を有効にするかどうかを制御します。`true` の場合、Intlayer は辞書呼び出しを最適化されたインジェクトに置き換えます。`false` の場合、最適化は無効になります。通常は本番環境で `true` に設定します。 |
+| **`importMode`**      | `'static' , 'dynamic' , 'live'` | `'static'`                      | 辞書の読み込み方法を決定します（詳細は以下を参照）。                                                                                                                                                         |
+| **`traversePattern`** | `string[]`                      | `['**/*.{js,ts,jsx,tsx}', ...]` | Intlayerが最適化のためにスキャンするファイルを定義するグロブパターン。関連のないファイルを除外し、ビルドを高速化するために使用します。                                                                       |
+| **`outputFormat`**    | `'esm', 'cjs'`                  | `'esm', 'cjs'`                  | ビルドされた辞書の出力フォーマットを制御します。                                                                                                                                                             |
+
+## インポートモード
+
+`importMode`設定は、辞書の内容がコンポーネントにどのように注入されるかを決定します。
+
+### 1. スタティックモード（`default`）
+
+静的モードでは、Intlayerは `useIntlayer` を `useDictionary` に置き換え、辞書を直接JavaScriptバンドルに注入します。
+
+- **利点:** 即時レンダリング（同期的）、ハイドレーション時の追加ネットワークリクエストなし。
+- **欠点:** バンドルにはその特定のコンポーネントに対する**すべての**利用可能な言語の翻訳が含まれます。
+- **最適用途:** シングルページアプリケーション（SPA）。
+
+**変換後のコード例:**
+
+```tsx
+// あなたのコード
+const content = useIntlayer("my-key");
+
+// 最適化されたコード（静的）
+const content = useDictionary({
+  key: "my-key",
+  content: {
+    nodeType: "translation",
+    translation: {
+      en: "My title",
+      fr: "Mon titre",
+    },
+  },
+});
+```
+
+### 2. 動的モード
+
+動的モードでは、Intlayerは`useIntlayer`を`useDictionaryAsync`に置き換えます。これは`import()`（Suspenseのような仕組み）を使用して、現在のロケールのJSONを遅延ロードします。
+
+- **利点:** **ロケール単位のツリーシェイキング。** 英語版を閲覧しているユーザーは英語の辞書のみをダウンロードし、フランス語の辞書は一切ロードされません。
+- **欠点:** ハイドレーション時にコンポーネントごとにネットワークリクエスト（アセット取得）が発生します。
+- **最適な用途:** 大きなテキストブロック、記事、多言語対応でバンドルサイズが重要なアプリケーション。
+
+**変換後のコード例:**
+
+```tsx
+// あなたのコード
+const content = useIntlayer("my-key");
+
+// 最適化されたコード（動的）
+const content = useDictionaryAsync({
+  en: () =>
+    import(".intlayer/dynamic_dictionary/my-key/en.json").then(
+      (mod) => mod.default
+    ),
+  fr: () =>
+    import(".intlayer/dynamic_dictionary/my-key/fr.json").then(
+      (mod) => mod.default
+    ),
+});
+```
+
+> `importMode: 'dynamic'` を使用する場合、1ページに `useIntlayer` を使ったコンポーネントが100個あると、ブラウザは100回の個別フェッチを試みます。この「リクエストの滝」を避けるために、コンテンツをより少ない `.content` ファイル（例：ページセクションごとに1つの辞書）にまとめ、アトムコンポーネントごとに分けるのは避けてください。
+
+> 現時点で、`importMode: 'dynamic'` は Vue と Svelte で完全にはサポートされていません。これらのフレームワークでは、今後のアップデートまで `importMode: 'static'` の使用を推奨します。
+
+### 3. ライブモード
+
+動的モードと同様に動作しますが、最初にIntlayer Live Sync APIから辞書を取得しようとします。API呼び出しが失敗した場合やコンテンツがライブ更新用にマークされていない場合は、動的インポートにフォールバックします。
+
+> 詳細はCMSドキュメントをご覧ください: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/intlayer_CMS.md)
+
+## まとめ: 静的モード vs 動的モード
+
+| 機能                       | 静的モード                               | 動的モード                            |
+| :------------------------- | :--------------------------------------- | :------------------------------------ |
+| **JSバンドルサイズ**       | 大きい（コンポーネントの全言語を含む）   | 最小（コードのみ、コンテンツなし）    |
+| **初期読み込み**           | 即時（コンテンツはバンドル内に含まれる） | わずかな遅延（JSONを取得）            |
+| **ネットワークリクエスト** | 追加リクエストなし                       | 辞書ごとに1リクエスト                 |
+| **ツリーシェイキング**     | コンポーネントレベル                     | コンポーネントレベル + ロケールレベル |
+| **最適な使用例**           | UIコンポーネント、小規模アプリ           | テキスト量が多いページ、多言語対応    |

package/docs/ja/compiler.md

@@ -0,0 +1,133 @@
+---
+createdAt: 2025-09-09
+updatedAt: 2025-09-09
+title: Intlayer コンパイラー | i18n のための自動コンテンツ抽出
+description: Intlayer コンパイラーで国際化プロセスを自動化しましょう。コンポーネントから直接コンテンツを抽出し、Vite、Next.js などでより高速かつ効率的な i18n を実現します。
+keywords:
+  - Intlayer
+  - コンパイラー
+  - 国際化
+  - i18n
+  - 自動化
+  - 抽出
+  - 速度
+  - Vite
+  - Next.js
+  - React
+  - Vue
+  - Svelte
+slugs:
+  - doc
+  - compiler
+history:
+  - version: 7.3.1
+    date: 2025-11-27
+    changes: コンパイラーリリース
+---
+
+# Intlayer コンパイラー | i18n のための自動コンテンツ抽出
+
+## Intlayer コンパイラーとは？
+
+**Intlayer コンパイラー**は、アプリケーションの国際化（i18n）プロセスを自動化するために設計された強力なツールです。ソースコード（JSX、TSX、Vue、Svelte）内のコンテンツ宣言をスキャンし、それらを抽出して必要な辞書ファイルを自動的に生成します。これにより、コンテンツをコンポーネントと共に配置したままにでき、Intlayer が辞書の管理と同期を担当します。
+
+## なぜ Intlayer コンパイラーを使うのか？
+
+- **自動化**: コンテンツを辞書に手動でコピー＆ペーストする手間を排除します。
+- **高速化**: 最適化されたコンテンツ抽出により、ビルドプロセスの高速化を実現します。
+- **開発者体験**: コンテンツ宣言を使用箇所にそのまま保持し、保守性を向上させます。
+- **ライブアップデート**: 開発中に即時フィードバックを得られるホットモジュールリプレースメント（HMR）をサポートします。
+
+より詳しい比較については、[Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ja/compiler_vs_declarative_i18n.md) のブログ記事をご覧ください。
+
+## Intlayer コンパイラーを使わない理由
+
+コンパイラーは優れた「そのまま動作する」体験を提供しますが、いくつかのトレードオフも導入します：
+
+- **ヒューリスティックの曖昧さ**：コンパイラーは、ユーザー向けコンテンツとアプリケーションロジック（例：`className="active"`、ステータスコード、製品ID）を推測する必要があります。複雑なコードベースでは、これにより誤検出や見逃された文字列が発生し、手動での注釈と例外処理が必要になる場合があります。
+- **静的抽出のみ**：コンパイラーベースの抽出は静的解析に依存しています。実行時のみ存在する文字列（APIエラーコード、CMSフィールドなど）は、コンパイラー単独では発見または翻訳できないため、補完的なランタイムi18n戦略が必要です。
+
+より深いアーキテクチャの比較については、ブログ記事[Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ja/compiler_vs_declarative_i18n.md)を参照してください。
+
+代替として、コンテンツの完全な制御を維持しながらi18nプロセスを自動化するために、Intlayerは自動抽出コマンド `intlayer transform`（[CLIドキュメント](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/cli/transform.md)を参照）またはIntlayer VS Code拡張機能の `Intlayer: extract content to Dictionary` コマンド（[VS Code拡張機能ドキュメント](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/vs_code_extension.md)を参照）も提供しています。
+
+## 使い方
+
+### Vite
+
+Viteベースのアプリケーション（React、Vue、Svelteなど）では、`vite-intlayer` プラグインを使うのが最も簡単な方法です。
+
+#### インストール
+
+```bash
+npm install vite-intlayer
+```
+
+#### 設定
+
+`vite.config.ts` を更新して `intlayerCompiler` プラグインを含めます：
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer, intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer(),
+    intlayerCompiler(), // コンパイラプラグインを追加
+  ],
+});
+```
+
+#### フレームワークサポート
+
+Viteプラグインは自動的に異なるファイルタイプを検出し処理します：
+
+- **React / JSX / TSX**: ネイティブに対応。
+- **Vue**: `@intlayer/vue-compiler` が必要です。
+- **Svelte**: `@intlayer/svelte-compiler` が必要です。
+
+使用しているフレームワークに応じて、適切なコンパイラパッケージをインストールしてください：
+
+```bash
+# Vue用
+npm install @intlayer/vue-compiler
+
+# Svelte用
+npm install @intlayer/svelte-compiler
+```
+
+### Next.js (Babel)
+
+Next.jsやその他のWebpackベースのBabelを使用するアプリケーションでは、`@intlayer/babel`プラグインを使ってコンパイラを設定できます。
+
+#### インストール
+
+```bash
+npm install @intlayer/babel
+```
+
+#### 設定
+
+`babel.config.js`（または `babel.config.json`）を更新して、抽出プラグインを含めます。Intlayerの設定を自動的に読み込むためのヘルパー `getExtractPluginOptions` を提供しています。
+
+```js fileName="babel.config.js"
+const {
+  intlayerExtractBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    // Extract content from components into dictionaries
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    // Optimize imports by replacing useIntlayer with direct dictionary imports
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+この設定により、コンポーネント内で宣言されたコンテンツが自動的に抽出され、ビルドプロセス中に辞書の生成に使用されます。