@intlayer/docs 9.2.0 → 9.3.0

package/docs/it/bundle_optimization.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-06-07
+updatedAt: 2026-08-09
 title: Ottimizzazione delle dimensioni e delle prestazioni del bundle i18n
 description: Riduci le dimensioni del bundle della tua applicazione ottimizzando i contenuti di internazionalizzazione (i18n). Scopri come sfruttare il tree shaking e il lazy loading per i dizionari con Intlayer.
 keywords:
@@ -16,6 +16,12 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 9.2.1
+    date: 2026-08-09
+    changes: "`purge` e `minify` ora funzionano su Next.js tramite `@intlayer/swc` — nessun `babel.config.js` richiesto"
+  - version: 8.12.0
+    date: 2026-06-24
+    changes: "Elencare i plugin Babel nell'ordine di pipeline richiesto (extract → purge → minify → optimize) nelle tabelle di riferimento"
   - version: 8.12.0
     date: 2026-06-07
     changes: "Aggiunto `intlayerPurgeBabelPlugin` e `intlayerMinifyBabelPlugin` per Babel/Webpack; chiarimento della pipeline dei plugin"
@@ -191,12 +197,14 @@ L'ottimizzazione in fase di build di Intlayer è suddivisa tra diversi plugin di
 
 Questi sono usati direttamente nel file `babel.config.js` per i setup basati su Webpack (Next.js con Babel, CRA, Webpack personalizzato, ecc.).
 
+La tabella seguente li elenca nel loro ordine di pipeline richiesto (lo stesso ordine in cui devono comparire in `babel.config.js`):
+
 | Plugin                        | Cosa fa                                                                                                                                    |
 | :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
 | `intlayerExtractBabelPlugin`  | Scansiona i file `.content.ts` e scrive i dizionari compilati in `.intlayer/`                                                              |
-| `intlayerOptimizeBabelPlugin` | Riscrive `useIntlayer('key')` in `useDictionary(hash)` e inietta la dichiarazione di `import` corrispondente al dizionario                 |
 | `intlayerPurgeBabelPlugin`    | Scansiona tutti i file sorgente, rimuove i **campi di contenuto inutilizzati** dai file di dizionario JSON compilati `.intlayer/**/*.json` |
 | `intlayerMinifyBabelPlugin`   | **Rinomina le chiavi dei campi di contenuto** in brevi alias alfabetici (`title` → `a`) sia nei file JSON che nel codice sorgente          |
+| `intlayerOptimizeBabelPlugin` | Riscrive `useIntlayer('key')` in `useDictionary(hash)` e inietta la dichiarazione di `import` corrispondente al dizionario                 |
 
 > **L'ordine dei plugin è importante.** Nel tuo `babel.config.js` i plugin purge e minify devono apparire **prima** del plugin optimize. La fase optimize sostituisce `useIntlayer('key')` con una chiamata opaca a `useDictionary(hash)`, cancellando le informazioni della chiave del dizionario di cui le fasi purge e minify hanno bisogno per identificare quali campi vengono usati.
 
@@ -205,9 +213,9 @@ Ogni plugin Babel ha un relativo helper per le opzioni che legge il tuo `intlaye
 | Helper opzioni               | Usato con                     |
 | :--------------------------- | :---------------------------- |
 | `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 | `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
 | `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 
 ### Plugin Vite (`vite-intlayer`)
 
@@ -220,6 +228,20 @@ Gli utenti di Vite **non configurano mai questi direttamente**. Vengono cablati
 | Dictionary minify   | Stesso comportamento della fase di scrittura JSON in `intlayerMinifyBabelPlugin`                                    |
 | Babel transform     | Stesso comportamento di ridenominazione codice sorgente `intlayerMinifyBabelPlugin` + `intlayerOptimizeBabelPlugin` |
 
+### Plugin SWC (`@intlayer/swc`)
+
+Nemmeno gli utenti di Next.js **configurano mai questi direttamente**. Dalla **v9.2.1**, `withIntlayer()` in `next.config.ts` esegue l'intera pipeline — purge, minify e riscrittura degli import — basandosi solo sui flag `build.purge` e `build.minify`.
+
+Il lavoro è diviso in due, perché un plugin Wasm SWC trasforma un file alla volta e non ha accesso al file system:
+
+| Passata                                           | Dove viene eseguita           | Cosa fa                                                                                                 |
+| :------------------------------------------------ | :---------------------------- | :------------------------------------------------------------------------------------------------------ |
+| Analisi d'uso + purge/minify del JSON             | Node, dentro `withIntlayer()` | Legge ogni file sorgente dei componenti, riscrive `.intlayer/**/*.json`, produce le tabelle di rinomina |
+| Riscrittura del sorgente (`content.title` → `.a`) | `@intlayer/swc` (Wasm)        | Applica le tabelle di rinomina agli accessi alle proprietà corrispondenti nel tuo codice                |
+| Riscrittura degli import (`useIntlayer` → dict)   | `@intlayer/swc` (Wasm)        | Come `intlayerOptimizeBabelPlugin`                                                                      |
+
+Decidere _quali_ campi sono inutilizzati e _quale_ alias assegnare a ciascuno richiede stato tra file e I/O su file, quindi quella metà viene eseguita in Node; il plugin SWC riceve solo le tabelle risultanti.
+
 ## Configurazione per Piattaforma
 
 <Tabs>
@@ -227,10 +249,12 @@ Gli utenti di Vite **non configurano mai questi direttamente**. Vengono cablati
 
 ### Next.js
 
-Next.js richiede il plugin `@intlayer/swc` per la fase optimize (riscrittura degli import), perché Next.js usa SWC per le build.
+Next.js richiede il plugin `@intlayer/swc`, perché Next.js usa SWC per le build. Dalla **v9.2.1** questo singolo pacchetto copre l'intera pipeline — ottimizzazione (riscrittura degli import), purge e minify.
 
 > Questo plugin non è installato di default perché i plugin SWC sono ancora sperimentali in Next.js. Questo aspetto potrebbe cambiare in futuro.
 
+> **Next.js 16.1.0 è la versione minima.** È la prima release costruita sull'ABI dei plugin Wasm di SWC compatibile in avanti; le release precedenti rifiutano il plugin. `withIntlayer` legge la tua versione di Next.js e semplicemente non registra il plugin sotto la 16.1.0 — quelle build riescono comunque, semplicemente girano senza l'ottimizzazione del bundle.
+
 <Tabs>
  <Tab value="npm">
 
@@ -265,33 +289,40 @@ intlayer-swc-plugin = "*"
 
 Una volta installato, Intlayer rileverà e utilizzerà automaticamente il plugin.
 
-Per i passaggi di **purge e minify** (rimozione dei campi e ridenominazione dei campi), installa `@intlayer/babel` insieme e aggiungi i plugin Babel. Dal momento che Next.js usa SWC per le trasformazioni ma valuta ancora `babel.config.js` per la configurazione dei plugin, i plugin Babel agiscono come fase preliminare rispetto ad SWC.
+Le passate di **purge e minify** (rimozione e rinomina dei campi) non richiedono alcun pacchetto aggiuntivo né `babel.config.js`. Avvolgi la tua configurazione con `withIntlayer` e attiva i flag in `intlayer.config.ts`:
 
-```bash packageManager="npm"
-npm install -D @intlayer/babel
+```typescript fileName="next.config.ts"
+import { withIntlayer } from "next-intlayer/server";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {/* la tua configurazione */};
+
+export default withIntlayer(nextConfig);
 ```
 
-```javascript fileName="babel.config.js"
-const {
-  intlayerPurgeBabelPlugin,
-  intlayerMinifyBabelPlugin,
-  getPurgePluginOptions,
-  getMinifyPluginOptions,
-} = require("@intlayer/babel");
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
 
-module.exports = {
-  presets: ["next/babel"],
-  plugins: [
-    // Purge: rimuove campi di contenuto inutilizzati da .intlayer/**/*.json
-    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
-    // Minify: rinomina le chiavi dei campi di contenuto nel JSON + codice sorgente
-    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
-    // Nota: intlayerOptimizeBabelPlugin NON è necessario qui perché
-    // @intlayer/swc gestisce la riscrittura da useIntlayer a useDictionary.
-  ],
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // rimuove i campi di contenuto inutilizzati dal JSON incluso nel bundle
+    minify: true, // rinomina le chiavi dei campi con alias brevi
+  },
 };
+
+export default config;
 ```
 
+Durante `next build`, `withIntlayer` analizza i tuoi sorgenti, riscrive i dizionari compilati e passa le tabelle di rinomina risultanti a `@intlayer/swc`, che aggiorna gli accessi alle proprietà corrispondenti nel tuo codice.
+
+> Usa il `withIntlayer` asincrono, non `withIntlayerSync`. La variante sincrona non esegue la pipeline di analisi, quindi purge e minify non hanno alcun effetto con essa.
+
+> Purge e minify vengono eseguiti solo con `next build` — la pipeline di ottimizzazione è disattivata durante `next dev`.
+
+> Sono inoltre disabilitati quando sono configurati chiamanti degli adattatori di compatibilità (`swcExtraCallers`, impostati dai pacchetti di compatibilità come `@intlayer/next-intl` o `@intlayer/react-i18next`): quei punti di chiamata sono invisibili all'analizzatore d'uso, quindi il purge rimuoverebbe campi che il codice legge ancora. La riscrittura degli import resta attiva.
+
+**Le versioni precedenti (prima della 9.2.1)** richiedevano `@intlayer/babel` e un `babel.config.js` che dichiarasse `intlayerPurgeBabelPlugin` e `intlayerMinifyBabelPlugin`. Quel file non è più necessario e può essere eliminato.
+
  </Tab>
  <Tab value="vite">
 
@@ -447,6 +478,8 @@ export default config;
 
 > La minificazione viene saltata quando `optimize` è `false` o quando `editor.enabled` è `true` (l'editor visuale richiede il nome completo della proprietà per consentire la modifica).
 
+> Su Next.js la minificazione viene saltata anche quando `@intlayer/swc` non è installato o non può essere caricato (Next.js sotto la 16.1.0). Il plugin è la metà che riscrive gli accessi nel sorgente, quindi rinominare i dizionari senza di esso lascerebbe il tuo codice a leggere nomi di campi che non esistono più.
+
 > La minificazione viene ignorata anche per i dizionari caricati tramite `importMode: 'fetch'` perché i loro JSON vengono serviti tramite API remote usando le chiavi dei campi originali; rinominarle rovinerebbe il contratto tra client e server.
 
 ### Purging (rimozione dei campi non usati)
@@ -475,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> Il purge viene saltato se `optimize` è `false` o quando `editor.enabled` è `true`.
+> Il purge viene saltato se `optimize` è `false` o quando `editor.enabled` è `true`. Su Next.js viene inoltre saltato quando `@intlayer/swc` non è disponibile e quando sono configurati chiamanti degli adattatori di compatibilità.
 
 > Il purge viene saltato per precauzione qualora un file non riesca a essere analizzato, oppure se l'oggetto `useIntlayer` viene riversato in altri valori usando parametri dinamici non analizzabili (come distruggere parti non strutturate, assegnazioni generiche ai props ecc.). In questi scenari viene conservato l'intero dizionario.
 

package/docs/it/live-sync.md

@@ -13,6 +13,10 @@ keywords:
   - Intlayer
   - Next.js
   - Vite
+slugs:
+  - doc
+  - concept
+  - live-sync
 history:
   - version: 9.0.0
     date: 2026-07-08

package/docs/ja/bundle_optimization.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-06-07
+updatedAt: 2026-08-09
 title: i18nバンドルサイズとパフォーマンスの最適化
 description: 国際化（i18n）コンテンツを最適化し、アプリケーションのバンドルサイズを削減します。Intlayerを使用して辞書のツリーシェイキングと遅延読み込みを活用する方法を学びます。
 keywords:
@@ -16,6 +16,12 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 9.2.1
+    date: 2026-08-09
+    changes: "`purge` と `minify` が `@intlayer/swc` を通じて Next.js で動作するようになりました — `babel.config.js` は不要です"
+  - version: 8.12.0
+    date: 2026-06-24
+    changes: "リファレンス表で Babel プラグインを必要なパイプライン順（extract → purge → minify → optimize）で列挙"
   - version: 8.12.0
     date: 2026-06-07
     changes: "Babel/Webpack用の `intlayerPurgeBabelPlugin` と `intlayerMinifyBabelPlugin` を追加、プラグインのパイプラインを明確化"
@@ -191,12 +197,14 @@ Intlayerのビルド最適化は、それぞれ単一の責任を持つ複数の
 
 これらは、Webpackベースのセットアップ（Babelを使用したNext.js、CRA、カスタムWebpackなど）の `babel.config.js` で直接使用されます。
 
+以下の表は、必要なパイプライン順（`babel.config.js` に記述しなければならない順序と同じ）で列挙しています:
+
 | プラグイン                    | 役割                                                                                                                                      |
 | :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
 | `intlayerExtractBabelPlugin`  | `.content.ts` ファイルをスキャンし、コンパイルされた辞書を `.intlayer/` に書き込みます                                                    |
-| `intlayerOptimizeBabelPlugin` | `useIntlayer('key')` を `useDictionary(hash)` に書き換え、一致する辞書の `import` を注入します                                            |
 | `intlayerPurgeBabelPlugin`    | すべてのソースファイルをスキャンし、コンパイルされた `.intlayer/**/*.json` から**未使用のフィールド**を削除します                         |
 | `intlayerMinifyBabelPlugin`   | JSONファイルとソースコードの両方で、**コンテンツフィールドキーを短いアルファベットのエイリアス**（例：`title` → `a`）に**名前変更**します |
+| `intlayerOptimizeBabelPlugin` | `useIntlayer('key')` を `useDictionary(hash)` に書き換え、一致する辞書の `import` を注入します                                            |
 
 > **プラグインの順序は重要です。** `babel.config.js` では、purgeとminifyのプラグインは、optimizeのプラグインの**前**に記述する必要があります。最適化パスは `useIntlayer('key')` を不透明な `useDictionary(hash)` 呼び出しに置き換えるため、purgeパスとminifyパスが使用されているフィールドを識別するために必要な辞書キー情報が消去されてしまいます。
 
@@ -205,9 +213,9 @@ Intlayerのビルド最適化は、それぞれ単一の責任を持つ複数の
 | オプションヘルパー           | 一緒に使用するプラグイン      |
 | :--------------------------- | :---------------------------- |
 | `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 | `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
 | `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 
 ### Vite プラグイン (`vite-intlayer`)
 
@@ -220,6 +228,20 @@ Viteユーザーは**これらを直接設定することはありません**。
 | Dictionary minify      | `intlayerMinifyBabelPlugin` のJSON書き込みパスと同じ                                    |
 | Babel transform        | `intlayerMinifyBabelPlugin` のソースコード名変更 + `intlayerOptimizeBabelPlugin` と同じ |
 
+### SWC プラグイン (`@intlayer/swc`)
+
+Next.js ユーザーも**これらを直接設定することはありません**。**v9.2.1** 以降、`next.config.ts` の `withIntlayer()` が `build.purge` と `build.minify` フラグだけを元に、パージ・ミニファイ・インポート書き換えというパイプライン全体を実行します。
+
+SWC の Wasm プラグインは一度に 1 ファイルしか変換できず、ファイルシステムにアクセスできないため、処理は 2 つに分かれています:
+
+| パス                                        | 実行場所                      | 処理内容                                                                                                         |
+| :------------------------------------------ | :---------------------------- | :--------------------------------------------------------------------------------------------------------------- |
+| 使用状況の解析 + JSON のパージ/ミニファイ   | Node、`withIntlayer()` の内部 | すべてのコンポーネントのソースファイルを読み取り、`.intlayer/**/*.json` を書き換え、リネームテーブルを生成します |
+| ソースの書き換え (`content.title` → `.a`)   | `@intlayer/swc` (Wasm)        | リネームテーブルをコード内の該当するプロパティアクセスに適用します                                               |
+| インポートの書き換え (`useIntlayer` → dict) | `@intlayer/swc` (Wasm)        | `intlayerOptimizeBabelPlugin` と同じ                                                                             |
+
+_どの_ フィールドが未使用か、そして各フィールドが _どの_ エイリアスを受け取るかを決定するには、ファイル横断の状態とファイル I/O が必要です。そのためこの半分は Node 上で実行され、SWC プラグインは生成されたテーブルだけを受け取ります。
+
 ## プラットフォーム別の設定
 
 <Tabs>
@@ -227,10 +249,12 @@ Viteユーザーは**これらを直接設定することはありません**。
 
 ### Next.js
 
-Next.jsはビルドにSWCを使用するため、最適化（インポートの書き換え）パスには `@intlayer/swc` プラグインが必要です。
+Next.js はビルドに SWC を使用するため、`@intlayer/swc` プラグインが必要です。**v9.2.1** 以降、このパッケージ 1 つでパイプライン全体 — 最適化（インポート書き換え）、パージ、ミニファイ — をカバーします。
 
 > SWCプラグインはNext.jsではまだ実験的であるため、このプラグインはデフォルトではインストールされません。将来的に変更される可能性があります。
 
+> **Next.js 16.1.0 が最小バージョンです。** SWC の前方互換な Wasm プラグイン ABI 上に構築された最初のリリースであり、それ以前のリリースはプラグインを拒否します。`withIntlayer` はプロジェクトの Next.js バージョンを読み取り、16.1.0 未満ではプラグインを登録しません — それらのビルドは引き続き成功し、単にバンドル最適化なしで実行されます。
+
 <Tabs>
  <Tab value="npm">
 
@@ -265,33 +289,40 @@ intlayer-swc-plugin = "*"
 
 インストールされると、Intlayerはプラグインを自動的に検出して使用します。
 
-**purgeおよびminify**パス（フィールドの削除とフィールドの名前変更）については、一緒に `@intlayer/babel` をインストールし、Babelプラグインを追加します。Next.jsは変換にSWCを使用しますが、プラグイン設定のために `babel.config.js` を評価するため、BabelプラグインはSWCの前の事前パスとして実行されます。
+**パージとミニファイ**のパス（フィールドの削除とリネーム）には、追加パッケージも `babel.config.js` も不要です。設定を `withIntlayer` でラップし、`intlayer.config.ts` でフラグを有効にしてください:
 
-```bash packageManager="npm"
-npm install -D @intlayer/babel
+```typescript fileName="next.config.ts"
+import { withIntlayer } from "next-intlayer/server";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {/* あなたの設定 */};
+
+export default withIntlayer(nextConfig);
 ```
 
-```javascript fileName="babel.config.js"
-const {
-  intlayerPurgeBabelPlugin,
-  intlayerMinifyBabelPlugin,
-  getPurgePluginOptions,
-  getMinifyPluginOptions,
-} = require("@intlayer/babel");
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
 
-module.exports = {
-  presets: ["next/babel"],
-  plugins: [
-    // Purge: .intlayer/**/*.json から未使用のコンテンツフィールドを削除します
-    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
-    // Minify: JSON + ソースコード内のコンテンツフィールドキーの名前を変更します
-    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
-    // 注意: @intlayer/swc が useIntlayer → useDictionary の書き換えを処理するため、
-    // intlayerOptimizeBabelPluginはここでは不要です。
-  ],
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // バンドルされた JSON から未使用のコンテンツフィールドを削除します
+    minify: true, // コンテンツフィールドのキーを短いエイリアスにリネームします
+  },
 };
+
+export default config;
 ```
 
+`next build` の実行中、`withIntlayer` はソースを解析し、コンパイル済み辞書を書き換え、生成されたフィールドのリネームテーブルを `@intlayer/swc` に渡します。プラグインはコード内の該当するプロパティアクセスを更新します。
+
+> `withIntlayerSync` ではなく、非同期の `withIntlayer` を使用してください。同期版は解析パイプラインを実行しないため、パージとミニファイは効果がありません。
+
+> パージとミニファイは `next build` 時にのみ実行されます — 最適化パイプラインは `next dev` 中は無効です。
+
+> 互換アダプターの呼び出し元が設定されている場合（`swcExtraCallers`。`@intlayer/next-intl` や `@intlayer/react-i18next` などの互換パッケージが設定します）も無効になります。これらの呼び出し箇所は使用状況アナライザーから見えないため、パージするとコードがまだ読んでいるフィールドを削除してしまいます。インポートの書き換えは有効なままです。
+
+**それ以前のバージョン（9.2.1 より前）** では `@intlayer/babel` と、`intlayerPurgeBabelPlugin` および `intlayerMinifyBabelPlugin` を宣言する `babel.config.js` が必要でした。このファイルはもう不要で、削除できます。
+
  </Tab>
  <Tab value="vite">
 
@@ -447,6 +478,8 @@ export default config;
 
 > `optimize` が `false` の場合、または `editor.enabled` が `true` の場合（ビジュアルエディタでは編集を可能にするために元のフィールド名が必要なため）、最小化はスキップされます。
 
+> Next.js では、`@intlayer/swc` がインストールされていない、または読み込めない場合（16.1.0 未満の Next.js）にもミニファイはスキップされます。ソース側のアクセスを書き換えるのはこのプラグインなので、これなしで辞書をリネームすると、コードが存在しないフィールド名を読むことになります。
+
 > `importMode: 'fetch'` 経由で読み込まれた辞書の場合も最小化はスキップされます。これは、そのJSONが元のフィールド名を使用してリモートAPIから提供されるためであり、クライアント側のキーの名前を変更するとサーバー/クライアントの規約が壊れるためです。
 
 ### パージ（Purging - 未使用フィールドの削除）
@@ -475,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> `optimize` が `false` の場合、または `editor.enabled` が `true` の場合、パージはスキップされます。
+> `optimize` が `false` の場合、または `editor.enabled` が `true` の場合、パージはスキップされます。 Next.js では、さらに `@intlayer/swc` が利用できない場合、および互換アダプターの呼び出し元が設定されている場合にもスキップされます。
 
 > ソースファイルが解析できない場合、または `useIntlayer` の結果が変数に割り当てられ、静的アナライザーが追跡できない方法（例：オブジェクトへのスプレッド、分割代入せずにプロップとして渡すなど）で渡された場合も、パージは保守的にスキップされます。このような場合は、完全な辞書が保持されます。
 

package/docs/ja/live-sync.md

@@ -13,6 +13,10 @@ keywords:
   - Intlayer
   - Next.js
   - Vite
+slugs:
+  - doc
+  - concept
+  - live-sync
 history:
   - version: 9.0.0
     date: 2026-07-08

package/docs/ko/bundle_optimization.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-06-07
+updatedAt: 2026-08-09
 title: i18n 번들 크기 및 성능 최적화
 description: 국제화(i18n) 콘텐츠를 최적화하여 애플리케이션 번들 크기를 줄이세요. Intlayer를 통해 사전(dictionary)의 트리 쉐이킹(tree shaking)과 지연 로딩(lazy loading)을 활용하는 방법을 알아봅니다.
 keywords:
@@ -16,6 +16,12 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 9.2.1
+    date: 2026-08-09
+    changes: "`purge`와 `minify`가 이제 `@intlayer/swc`를 통해 Next.js에서 동작합니다 — `babel.config.js`가 필요 없습니다"
+  - version: 8.12.0
+    date: 2026-06-24
+    changes: "참조 표에서 Babel 플러그인을 필수 파이프라인 순서(extract → purge → minify → optimize)로 나열"
   - version: 8.12.0
     date: 2026-06-07
     changes: "Babel/Webpack용 `intlayerPurgeBabelPlugin` 및 `intlayerMinifyBabelPlugin` 추가, 플러그인 파이프라인 명확화"
@@ -191,12 +197,14 @@ Intlayer의 빌드 최적화는 각각 단일 책임을 갖는 여러 개별 플
 
 이들은 Webpack 기반 설정(Babel을 사용하는 Next.js, CRA, 커스텀 Webpack 등)의 `babel.config.js`에서 직접 사용됩니다.
 
+아래 표는 필수 파이프라인 순서(즉 `babel.config.js`에 나타나야 하는 순서와 동일)로 나열합니다:
+
 | 플러그인                      | 기능                                                                                                               |
 | :---------------------------- | :----------------------------------------------------------------------------------------------------------------- |
 | `intlayerExtractBabelPlugin`  | `.content.ts` 파일을 스캔하여 컴파일된 사전을 `.intlayer/`에 작성합니다.                                           |
-| `intlayerOptimizeBabelPlugin` | `useIntlayer('key')`를 `useDictionary(hash)`로 재작성하고 일치하는 사전의 `import`를 주입합니다.                   |
 | `intlayerPurgeBabelPlugin`    | 모든 소스 파일을 스캔하여 컴파일된 `.intlayer/**/*.json` 사전 파일에서 **사용되지 않는 콘텐츠 필드**를 제거합니다. |
 | `intlayerMinifyBabelPlugin`   | JSON 파일과 소스 코드 모두에서 **콘텐츠 필드 키를 짧은 알파벳 별칭**(`title` → `a`)으로 **이름을 변경**합니다.     |
+| `intlayerOptimizeBabelPlugin` | `useIntlayer('key')`를 `useDictionary(hash)`로 재작성하고 일치하는 사전의 `import`를 주입합니다.                   |
 
 > **플러그인 순서가 중요합니다.** `babel.config.js`에서 purge 및 minify 플러그인은 optimize 플러그인 **앞에** 나타나야 합니다. optimize 패스는 `useIntlayer('key')`를 불투명한 `useDictionary(hash)` 호출로 대체하여 purge 및 minify 패스가 어떤 필드가 사용되는지 식별하는 데 필요한 사전 키 정보를 지웁니다.
 
@@ -205,9 +213,9 @@ Intlayer의 빌드 최적화는 각각 단일 책임을 갖는 여러 개별 플
 | 옵션 헬퍼                    | 사용하는 플러그인             |
 | :--------------------------- | :---------------------------- |
 | `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 | `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
 | `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 
 ### Vite 플러그인 (`vite-intlayer`)
 
@@ -220,6 +228,20 @@ Vite 사용자는 **이를 직접 구성하지 않습니다**. `vite.config.ts`
 | Dictionary minify  | `intlayerMinifyBabelPlugin`의 JSON 작성 패스와 동일                                      |
 | Babel transform    | `intlayerMinifyBabelPlugin`의 소스 코드 이름 변경 + `intlayerOptimizeBabelPlugin`과 동일 |
 
+### SWC 플러그인 (`@intlayer/swc`)
+
+Next.js 사용자도 **이것들을 직접 설정하지 않습니다**. **v9.2.1**부터 `next.config.ts`의 `withIntlayer()`가 `build.purge`와 `build.minify` 플래그만으로 퍼지, 압축, 임포트 재작성이라는 전체 파이프라인을 실행합니다.
+
+SWC Wasm 플러그인은 한 번에 한 파일만 변환하고 파일 시스템에 접근할 수 없기 때문에 작업이 둘로 나뉩니다:
+
+| 패스                                 | 실행 위치                   | 하는 일                                                                                         |
+| :----------------------------------- | :-------------------------- | :---------------------------------------------------------------------------------------------- |
+| 사용 분석 + JSON 퍼지/압축           | Node, `withIntlayer()` 내부 | 모든 컴포넌트 소스 파일을 읽고 `.intlayer/**/*.json`을 재작성하며 이름 변경 테이블을 생성합니다 |
+| 소스 재작성 (`content.title` → `.a`) | `@intlayer/swc` (Wasm)      | 이름 변경 테이블을 코드의 해당 속성 접근에 적용합니다                                           |
+| 임포트 재작성 (`useIntlayer` → dict) | `@intlayer/swc` (Wasm)      | `intlayerOptimizeBabelPlugin`과 동일                                                            |
+
+_어떤_ 필드가 사용되지 않는지, 각 필드가 _어떤_ 별칭을 받을지 결정하려면 파일 간 상태와 파일 I/O가 필요하므로 그 절반은 Node에서 실행되며, SWC 플러그인은 결과 테이블만 전달받습니다.
+
 ## 플랫폼별 설정
 
 <Tabs>
@@ -227,10 +249,12 @@ Vite 사용자는 **이를 직접 구성하지 않습니다**. `vite.config.ts`
 
 ### Next.js
 
-Next.js는 빌드 시 SWC를 사용하므로 optimize(가져오기 재작성) 패스를 위해 `@intlayer/swc` 플러그인이 필요합니다.
+Next.js는 빌드에 SWC를 사용하므로 `@intlayer/swc` 플러그인이 필요합니다. **v9.2.1**부터 이 하나의 패키지가 최적화(임포트 재작성), 퍼지, 압축 등 전체 파이프라인을 담당합니다.
 
 > Next.js에서 SWC 플러그인이 아직 실험 단계이므로 이 플러그인은 기본적으로 설치되지 않습니다. 향후 변경될 수 있습니다.
 
+> **Next.js 16.1.0이 최소 버전입니다.** SWC의 상위 호환 Wasm 플러그인 ABI 위에 구축된 첫 릴리스이며, 이전 릴리스는 플러그인을 거부합니다. `withIntlayer`는 프로젝트의 Next.js 버전을 읽고 16.1.0 미만에서는 플러그인을 아예 등록하지 않습니다 — 해당 빌드는 여전히 성공하며 단지 번들 최적화 없이 실행됩니다.
+
 <Tabs>
  <Tab value="npm">
 
@@ -265,33 +289,40 @@ intlayer-swc-plugin = "*"
 
 설치되면 Intlayer가 플러그인을 자동으로 감지하여 사용합니다.
 
-**purge 및 minify** 패스(필드 제거 및 필드 이름 변경)의 경우 `@intlayer/babel`을 함께 설치하고 Babel 플러그인을 추가합니다. Next.js는 변환을 위해 SWC를 사용하지만 플러그인 구성을 위해 `babel.config.js`를 계속 평가하므로 Babel 플러그인은 SWC 이전의 사전 패스(pre-pass)로 실행됩니다.
+**퍼지와 압축** 패스(필드 제거 및 필드 이름 변경)에는 추가 패키지도 `babel.config.js`도 필요하지 않습니다. 설정을 `withIntlayer`로 감싸고 `intlayer.config.ts`에서 플래그를 켜십시오:
 
-```bash packageManager="npm"
-npm install -D @intlayer/babel
+```typescript fileName="next.config.ts"
+import { withIntlayer } from "next-intlayer/server";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {/* 당신의 설정 */};
+
+export default withIntlayer(nextConfig);
 ```
 
-```javascript fileName="babel.config.js"
-const {
-  intlayerPurgeBabelPlugin,
-  intlayerMinifyBabelPlugin,
-  getPurgePluginOptions,
-  getMinifyPluginOptions,
-} = require("@intlayer/babel");
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
 
-module.exports = {
-  presets: ["next/babel"],
-  plugins: [
-    // Purge: .intlayer/**/*.json에서 사용되지 않는 콘텐츠 필드 제거
-    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
-    // Minify: JSON + 소스 코드에서 콘텐츠 필드 키의 이름 변경
-    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
-    // 주의: @intlayer/swc가 useIntlayer → useDictionary 재작성을 처리하므로
-    // intlayerOptimizeBabelPlugin은 여기서 필요하지 않습니다.
-  ],
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // 번들된 JSON에서 사용되지 않는 콘텐츠 필드를 제거합니다
+    minify: true, // 콘텐츠 필드 키를 짧은 별칭으로 변경합니다
+  },
 };
+
+export default config;
 ```
 
+`next build` 동안 `withIntlayer`가 소스를 분석하고 컴파일된 사전을 재작성한 뒤, 생성된 필드 이름 변경 테이블을 `@intlayer/swc`에 전달하면 플러그인이 코드의 해당 속성 접근을 갱신합니다.
+
+> `withIntlayerSync`가 아니라 비동기 `withIntlayer`를 사용하십시오. 동기 버전은 분석 파이프라인을 실행하지 않으므로 퍼지와 압축이 적용되지 않습니다.
+
+> 퍼지와 압축은 `next build`에서만 실행됩니다 — 최적화 파이프라인은 `next dev` 중에는 꺼져 있습니다.
+
+> 호환 어댑터 호출자가 설정된 경우에도 비활성화됩니다(`swcExtraCallers`, `@intlayer/next-intl`이나 `@intlayer/react-i18next` 같은 호환 패키지가 설정합니다). 이러한 호출 지점은 사용 분석기에 보이지 않으므로 퍼지하면 코드가 여전히 읽는 필드를 제거하게 됩니다. 임포트 재작성은 계속 활성 상태로 유지됩니다.
+
+**이전 버전(9.2.1 이전)** 에서는 `@intlayer/babel`과 `intlayerPurgeBabelPlugin` 및 `intlayerMinifyBabelPlugin`을 선언하는 `babel.config.js`가 필요했습니다. 이 파일은 더 이상 필요하지 않으며 삭제할 수 있습니다.
+
  </Tab>
  <Tab value="vite">
 
@@ -447,6 +478,8 @@ export default config;
 
 > `optimize`가 `false`이거나 `editor.enabled`가 `true`일 때(비주얼 에디터에서는 편집을 위해 원본 필드 이름이 필요함) 최소화는 건너뜁니다.
 
+> Next.js에서는 `@intlayer/swc`가 설치되지 않았거나 로드할 수 없는 경우(16.1.0 미만의 Next.js)에도 압축이 건너뛰어집니다. 소스 접근을 재작성하는 쪽이 바로 이 플러그인이므로, 이것 없이 사전만 이름을 바꾸면 코드가 더 이상 존재하지 않는 필드 이름을 읽게 됩니다.
+
 > `importMode: 'fetch'`를 통해 로드된 사전에서도 최소화는 건너뜁니다. JSON이 원본 필드 이름을 사용하여 원격 API에서 제공되기 때문입니다(클라이언트 측 키의 이름을 변경하면 서버/클라이언트 규약이 깨짐).
 
 ### 파지 (사용하지 않는 필드 제거)
@@ -475,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> `optimize`가 `false`이거나 `editor.enabled`가 `true`일 때 파지(purge)는 건너뜁니다.
+> `optimize`가 `false`이거나 `editor.enabled`가 `true`일 때 파지(purge)는 건너뜁니다. Next.js에서는 `@intlayer/swc`를 사용할 수 없을 때, 그리고 호환 어댑터 호출자가 설정된 경우에도 추가로 건너뜁니다.
 
 > 소스 파일을 구문 분석할 수 없거나 `useIntlayer`의 결과가 변수에 할당되고 정적 분석기가 추적할 수 없는 방식으로 전달될 때(예: 객체에 스프레드, 구조 분해 없이 prop으로 전달) 파지도 보수적으로 건너뜁니다. 이런 경우에는 전체 사전이 유지됩니다.
 

package/docs/ko/live-sync.md

@@ -13,6 +13,10 @@ keywords:
   - Intlayer
   - Next.js
   - Vite
+slugs:
+  - doc
+  - concept
+  - live-sync
 history:
   - version: 9.0.0
     date: 2026-07-08