@intlayer/docs 9.1.3 → 9.3.0

package/docs/ja/self_hosting.md

@@ -80,6 +80,18 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 ---
 
+## 初回セットアップ
+
+新規インスタンス（空のデータベース）でダッシュボードを開くと、**`/init`** ページにリダイレクトされます：
+
+1. 最初のアカウントを作成します。ユーザーコレクションが空のため、このアカウントは自動的に **super admin** に昇格されます。
+2. 検証メールが送信されます（Resend経由）。メール検証は **必須** です — これが `RESEND_API_KEY` を開始前に設定する必要がある理由です。
+3. メール内のリンクをクリックしてサインインします。
+
+管理者が存在すると、`/init` は標準的なサインインページにリダイレクトされます。
+
+---
+
 ## サービス
 
 | サービス    | イメージ                             | ホストポート                     | 目的                                                         |
@@ -99,7 +111,16 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 ## 環境変数
 
-インストーラーはすぐに使用できる `.env` を生成します。以下の表は、すべての変数について説明しています。
+### 必須
+
+| Variable               | Example                      | Description                                                                                                                                          |
+| ---------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DB_ID`                | `intlayer`                   | MongoDB Atlas ユーザー                                                                                                                               |
+| `DB_MDP`               | _(your password)_            | MongoDB Atlas パスワード                                                                                                                             |
+| `DB_CLUSTER`           | `cluster0.xxxxx.mongodb.net` | MongoDB Atlas クラスターホスト (`mongodb+srv://` URI で使用)                                                                                         |
+| `BETTER_AUTH_SECRET`   | _(generated)_                | セッション署名用の 32 バイトシークレット                                                                                                             |
+| `S3_SECRET_ACCESS_KEY` | _(generated)_                | バンドルされた MinIO のシークレット                                                                                                                  |
+| `RESEND_API_KEY`       | _(your key)_                 | Resend 経由のトランザクショナルメール。グローバル SMTP メーラーを設定しない限り、初回セットアップで必須 ([グローバルメーラー](#global-mailer)を参照) |
 
 ### 必須 (自動生成またはプロンプトによる入力)
 
@@ -141,6 +162,26 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 ---
 
+### グローバルメーラー
+
+デフォルトでは、すべてのトランザクションメールは `RESEND_API_KEY` を使用して Resend 経由で送信されます。セルフホストされたデプロイメントでは、パスワードリセットやマジックリンクなどの非組織メールを含む**すべての**メールを、環境変数で設定されたグローバルメーラー経由でルーティングできます。
+
+`MAIL_PROVIDER` を設定して有効にしてください。設定されていない場合は、デフォルトの Resend メーラーが使用されます。
+
+| Variable             | Example                        | Description                                                                                            |
+| -------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `MAIL_PROVIDER`      | `smtp`                         | グローバルトランスポート: `smtp` または `resend`。デフォルトを使用する場合は未設定のままにしてください |
+| `MAIL_FROM`          | `Intlayer <no-reply@acme.com>` | 送信者ヘッダー。ベアアドレスまたは `Name <email>` 形式を受け入れます                                   |
+| `MAIL_SMTP_HOST`     | `smtp.acme.com`                | SMTP ホスト (`MAIL_PROVIDER=smtp` の場合は必須)                                                        |
+| `MAIL_SMTP_PORT`     | `587`                          | SMTP ポート (デフォルトは `587`)                                                                       |
+| `MAIL_SMTP_SECURE`   | `false`                        | 暗黙的な TLS。ポート `465` の場合は `true` に設定してください                                          |
+| `MAIL_SMTP_USER`     | _(your user)_                  | SMTP ユーザー名 (オプション; 認証されていないリレーの場合は省略可)                                     |
+| `MAIL_SMTP_PASSWORD` | _(your password)_              | SMTP パスワード                                                                                        |
+
+> 優先順位: 組織独自のメーラー (**Organization** ダッシュボードから設定) が優先され、次にグローバルメーラーが優先され、最後にデフォルトの Resend キーが優先されます。
+
+---
+
 ## Intlayerプロジェクトの接続
 
 スタックが稼働したら、`intlayer.org` の代わりに自己ホスト型のバックエンドとダッシュボードを指すようにプロジェクトを設定します。
@@ -259,47 +300,11 @@ docker run --rm \
 
 ---
 
-## リバースプロキシの使用 (Nginx / Caddy)
-
-本番環境のデプロイでは、appコンテナとbackendコンテナを直接公開するのではなく、リバースプロキシをそれらの前に配置します。
+## 制限事項
 
-### Nginxの例
-
-```nginx
-server {
-    listen 80;
-    server_name cms.example.com;
-
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
-
-server {
-    listen 80;
-    server_name api.example.com;
-
-    location / {
-        proxy_pass http://localhost:3100;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
-```
-
-公開ドメインに合わせて、以下の `.env` 変数を更新してください。
-
-```sh
-BACKEND_URL=https://api.example.com
-APP_URL=https://cms.example.com
-DOMAIN=example.com
-VITE_BACKEND_URL=https://api.example.com
-VITE_DOMAIN=example.com
-```
-
-> `VITE_*` 変数はビルド時にダッシュボードイメージに組み込まれます。イメージがビルドされた後に変更した場合、`app` イメージをリビルドするか (`docker compose build app`)、ランタイム設定インジェクションを使用する必要があります。
+- **MongoDB は外部 (Atlas) である必要があります。** バックエンドは `mongodb+srv://` 経由でのみ接続します (`DB_ID` / `DB_MDP` / `DB_CLUSTER` から構築)。したがって、プレーンな `mongodb://host:27017` — コンテナにバンドルされた `mongod` を含む — は使用できません。MongoDB Atlas クラスタを提供してください。
+- **カスタムドメインはサポートされていません。** すべてのブラウザ向け `VITE_*` URL はビルド時にアプリにインラインされ、公開されたイメージには `localhost` の値が付属します。ダッシュボードには `http://localhost:3000` でアクセスする必要があります。パブリックドメインでサービスするには、イメージをターゲット URL を焼き込んで再構築する必要があり、そのままではサポートされていません。
+- **メールは機能するメーラーが必要です。** 初回実行セットアップではメール検証が強制されるため、`RESEND_API_KEY` または [グローバル SMTP メーラー](#global-mailer) (`MAIL_PROVIDER=smtp` + `MAIL_SMTP_*`) を設定する必要があります。最初の管理者がサインインした後、各組織はダッシュボードから独自の SMTP または Resend メーラーを設定することもできます。
 
 ---
 
@@ -315,15 +320,6 @@ docker compose logs mongo
 docker compose logs redis
 ```
 
-### ダッシュボードがAPIに到達できない
-
-`VITE_BACKEND_URL` が、バックエンドが**ブラウザ**から到達可能なURL (Dockerネットワークではなく) と一致していることを確認してください。バックエンドポートを変更したり、リバースプロキシを追加した場合は、ダッシュボードイメージをリビルドしてください。
-
-```sh
-docker compose build app
-docker compose up -d app
-```
-
 ### メールが送信されない
 
 デフォルトでは、すべての送信メールはMailpitによって捕捉されます。送信されたメッセージを確認するには、`http://localhost:8025` を開いてください。実際のメールを送信するには、`.env` で `MAIL_PROVIDER=resend` と `RESEND_API_KEY=<your-key>` を設定し、バックエンドを再起動します。

package/docs/ko/analytics.md

@@ -0,0 +1,222 @@
+---
+createdAt: 2026-07-08
+updatedAt: 2026-07-08
+title: Intlayer Analytics | 콘텐츠 노출 추적 및 A/B 테스트 실행
+description: "@intlayer/analytics가 페이지/로케일 뷰와 콘텐츠 노출을 추적하는 방법, 그리고 이를 활용해 Intlayer 콘텐츠에서 A/B 테스트를 실행하는 방법을 알아보세요."
+keywords:
+  - Analytics (분석)
+  - A/B 테스트
+  - Audience (오디언스)
+  - Internationalization (국제화)
+  - Documentation (문서)
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - analytics
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Init doc — @intlayer/analytics 패키지, 프로바이더/노드 레벨 추적, A/B 테스트, 대시보드"
+author: aymericzip
+---
+
+# Intlayer Analytics 문서
+
+`@intlayer/analytics`는 방문자에게 **어떤 콘텐츠가 실제로 노출되었는지**(어떤 페이지, 어떤 로케일에서, 번역된 콘텐츠 중 어떤 특정 항목이 노출되었는지)를 알려주는 선택적 보조 패키지입니다. 이를 통해 오디언스를 이해하고 **콘텐츠를 대상으로 A/B 테스트를 실행**할 수 있습니다.
+
+## 목차
+
+<TOC/>
+
+---
+
+## 추적 대상
+
+`@intlayer/analytics`는 다음 세 가지 종류의 익명 이벤트를 일괄 처리(batch)하여 수집합니다:
+
+| 이벤트 (Event)     | 캡처되는 위치                               | 알 수 있는 정보                                                                                                        |
+| ------------------ | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `page_view`        | 프로바이더 레벨 (`IntlayerProvider`)        | 초기 로드, 경로 변경, 또는 로케일 전환 시 세션이 어떤 페이지와 로케일을 조회했는지 확인.                               |
+| `content_exposure` | 노드 레벨 (`useIntlayer` / 해석기 플러그인) | 어떤 사전 키(dictionary key) / 키 경로가 실제로 해석되어 표시되었는지 — 실험의 일부인 경우 어떤 **변형(variant)**인지. |
+| `conversion`       | `useConversion()`을 호출하는 모든 곳        | 세션에 노출된 A/B 변형과 기여(attributed)된 달성 목표(가입, 클릭, 구매 등).                                            |
+
+이벤트는 메모리에 수집되어 키 입력이나 렌더링마다 전송되지 않고 **약 20초마다 한 번씩 일괄 요청(batch request)으로 전송**됩니다. 따라서 분석은 첫 렌더링 시간에 영향을 주지 않으며 사용자 상호작용마다 요청을 추가하지 않습니다.
+
+## 콘텐츠 A/B 테스트를 지원하는 방법
+
+Intlayer에서는 이미 콘텐츠 [변형(Variants)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/index.md)을 선언할 수 있습니다(예: `control` 및 `black_friday` 변형이 포함된 `hero-banner` 사전). `@intlayer/analytics`는 다음을 통해 사이클을 완성합니다:
+
+1. `getVariant(experimentKey, variants)`는 결정론적(deterministically)으로 각 익명 세션을 변형에 할당합니다 — 이는 세션 ID와 실험 키의 순수 함수이므로 할당은 **세션 전체에 걸쳐 안정적**이며 첫 렌더링 전에 **서버 왕복이 필요 없습니다**(깜빡임, 레이아웃 변경 없음).
+2. 모든 `content_exposure` 이벤트에는 화면에 표시된 `variant` 정보가 포함됩니다.
+3. `useConversion()`을 사용하면 해당 변형에 목표(예: `"cta_click"`)를 기여(attribute)시킬 수 있습니다.
+4. 대시보드의 실험 결과 엔드포인트는 통계적 유의성(z-test)을 포함하여 각 변형의 전환율을 비교합니다.
+
+## 설치
+
+`@intlayer/analytics`는 **선택적 피어 의존성(peer, optional dependency)**으로, 프레임워크 패키지에 의해 자동으로 설치되지 않습니다. `intlayer`와 함께 설치하세요:
+
+```bash packageManager="npm"
+npm install @intlayer/analytics
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/analytics
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/analytics
+```
+
+```bash packageManager="bun"
+bun add @intlayer/analytics
+```
+
+패키지를 설치하지 않으면 모든 통합 지점이 아무 동작도 수행하지 않는(no-op) 상태로 해석됩니다 — 아래의 [미설치 시 제로 비용](#미설치-시-제로-비용)을 참고하세요.
+
+## 구성
+
+Analytics는 **기존 `editor` 구성 블록을 재사용**합니다. 채워야 할 별도의 `analytics` 구성 스키마는 없습니다:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    backendURL: "https://back.intlayer.org", // Analytics 이벤트 수집 엔드포인트로도 사용됨
+    clientId: "your-client-id", // Analytics 프로젝트 키로도 사용됨
+    clientSecret: "your-client-secret",
+  },
+};
+
+export default config;
+```
+
+- `editor.backendURL` — 분석 이벤트가 전송되는 기본 URL (`POST {backendURL}/api/analytics/events`).
+- `editor.clientId` — 수집되는 모든 이벤트에 기여하는 퍼블릭 프로젝트 키. 이는 **활성화 스위치**의 역할도 합니다: `clientId`가 구성될 때까지 분석 기능은 완전히 비활성화(tree-shake 됨) 상태로 유지됩니다.
+
+직접 Intlayer를 호스팅(self-host)하는 경우, `editor.backendURL`을 공유하므로 분석은 자동으로 사용자 자체 인스턴스를 가리킵니다.
+
+## 프레임워크 지원
+
+Analytics는 `react-intlayer`의 공유된 `IntlayerProvider`와 연결되어 있으므로, 이 Provider가 사용되는 곳이라면 어디서든 바로 사용할 수 있습니다:
+
+| 프레임워크                                               | 상태                                                                                                  |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| React                                                    | ✅ 지원됨                                                                                             |
+| Next.js (`next-intlayer`)                                | ✅ 지원됨 (`react-intlayer`를 통해)                                                                   |
+| React Native / Expo (`react-native-intlayer`)            | ✅ 지원됨 (`react-intlayer`를 통해)                                                                   |
+| Vue, Svelte, Angular, Solid, Preact, Lit, Astro, Vanilla | 🚧 계획됨 — `@intlayer/editor` 배포 패턴을 따르는 동일한 클라이언트, 프로바이더 레벨 바인딩 제공 예정 |
+
+## 사용법
+
+### 자동 프로바이더 레벨 추적
+
+코드를 변경할 필요가 없습니다. `@intlayer/analytics`가 설치되고 `editor.clientId`가 구성되면, `IntlayerProvider`는 자동으로 다음을 수행합니다:
+
+- 마운트 시 Analytics 클라이언트를 초기화,
+- 초기 로드 시 `page_view`를 기록,
+- 로케일 변경 시마다 `page_view`를 기록,
+- 약 20초의 플러시 루프(flush loop)를 시작하고, 언마운트 / 탭 닫기 시 남은 이벤트를 플러시합니다 (`navigator.sendBeacon`을 사용하며, `fetch(..., { keepalive: true })`로 폴백).
+
+### 자동 노드 레벨 추적
+
+`useIntlayer`가 표시할 콘텐츠 조각을 해석할 때마다, 해석기(interpreter)는 해당 정확한 `dictionaryKey` + 키 경로 + 로케일에 대해 `content_exposure` 이벤트를 보고합니다 — 이 역시 코드를 변경할 필요가 없습니다. 플러시 창(flush window) 내에 같은 노드가 반복해서 노출되면 이벤트는 `count` 속성을 포함한 단일 이벤트로 병합(coalesced)되므로, 리스트가 50번 리렌더링된다고 해서 50개의 이벤트가 전송되지 않습니다.
+
+### A/B 테스트를 위한 전환(Conversion) 추적
+
+`useConversion()`을 사용하여 세션이 본 변형에 목표를 연결(attribute)하세요:
+
+```tsx fileName="CTAButton.tsx" codeFormat="tsx"
+import { useConversion } from "react-intlayer";
+
+const CTAButton = () => {
+  const trackConversion = useConversion();
+
+  return (
+    <button
+      onClick={() =>
+        trackConversion({
+          experimentKey: "homepage-hero",
+          variant: "black_friday",
+          goal: "cta_click",
+        })
+      }
+    >
+      시작하기
+    </button>
+  );
+};
+```
+
+### 클라이언트 측에서 변형 해결(Resolving a variant)
+
+```tsx fileName="useHeroVariant.ts" codeFormat="tsx"
+import { getGlobalAnalyticsClient } from "@intlayer/analytics/client";
+
+const client = getGlobalAnalyticsClient();
+const variant = client?.getVariant("homepage-hero", [
+  "control",
+  "black_friday",
+]);
+```
+
+## 프라이버시 & 성능
+
+- **설계상 익명(Anonymous by design)**: 세션은 회전하는(rotating) ID로 식별되며, 백엔드는 해당 ID의 **SHA-256 해시**만 저장합니다 — 원시 ID나 IP 주소는 절대 저장하지 않습니다.
+- **대략적인 위치 정보**: CDN 지리적 위치 헤더(`cf-ipcountry`, `x-vercel-ip-country` 등)에서 도출된 국가 코드만 포함되며 — IP를 읽거나 저장하지 않습니다.
+- **URL은 쿼리 매개변수 제외**: 쿼리 문자열은 절대 캡처되지 않도록 기본 설정되어 있습니다.
+- **샘플링**: 트래픽이 높은 앱의 경우 `sampleRate`를 사용하여 콘텐츠 노출 이벤트의 일부만 유지할 수 있습니다.
+- **일괄 처리(Batched)**: 약 20초마다 한 번씩 요청(`flushInterval`)하거나 버퍼가 가득 찼을 때(`maxBufferSize`) 요청을 보냅니다 — 이벤트별로 단일 요청을 보내는 일은 없습니다.
+
+### 미설치 시 제로 비용
+
+`@intlayer/analytics`는 `@intlayer/editor`와 완전히 동일한 선택적 의존성 패턴을 따릅니다:
+
+- 모든 통합 지점은 **`try/catch`로 래핑된 동적 `import()`**를 통해 패키지를 로드합니다 — `@intlayer/analytics`를 아예 설치하지 않는 앱은 번들 크기나 런타임 비용을 지불하지 않으며, 오류가 발생하지 않습니다.
+- `editor.clientId`가 구성되지 않은 경우 `@intlayer/config`에 의해 `'false'`로 자동 설정되는 컴파일 타임 환경 변수(`INTLAYER_ANALYTICS_ENABLED`)는, 번들러가 통합된 코드 전체를 **데드 코드 제거(dead-code-eliminate)**할 수 있게 해줍니다.
+- Intlayer 에디터/CMS 미리보기 iframe 내부에서는 Analytics 기능이 비활성화되므로 에디터 세션이 실제 트래픽으로 계산되지 않습니다.
+
+## 대시보드: Analytics 페이지
+
+프로젝트에 이벤트가 수집되기 시작하면, [Intlayer 대시보드](https://app.intlayer.org/analytics)의 **Analytics** 페이지(프로젝트 선택 후 사이드바에 표시됨)에서 다음을 확인할 수 있습니다:
+
+- **활성 사용자(Active users)** — 선택된 롤링 창(7 / 30 / 90일) 동안의 순 방문자.
+- **오늘의 사용자** 및 **지난 7일간 사용자**.
+- 선택된 기간 동안의 **페이지 뷰**.
+- 일별 순 방문자의 **변화 추이 그래프**.
+- **로케일(Locales)** 및 **위치(Location)** 분석 탭을 통해 로케일 및 국가별 오디언스 순위를 제공.
+
+## 백엔드 API 참조
+
+모든 읽기 엔드포인트는 인증이 필요합니다; 이벤트 수집(ingestion) 엔드포인트는 퍼블릭하며 본문의 `clientId`로 기여(attributed)를 수행합니다.
+
+| Method | Endpoint                                    | Description                                                            |
+| ------ | ------------------------------------------- | ---------------------------------------------------------------------- |
+| `POST` | `/api/analytics/events`                     | 일괄 이벤트를 수집(public, body의 `clientId`에 의해 귀속됨).           |
+| `GET`  | `/api/analytics/overview`                   | 인증된 프로젝트의 페이지/로케일 총합(totals).                          |
+| `GET`  | `/api/analytics/audience?days=30`           | 순 방문자, 페이지 뷰, 일별 시계열 데이터, 로케일 + 국가별 분석 데이터. |
+| `GET`  | `/api/analytics/content-stats`              | 콘텐츠 노출 총합(사전 키 / 키 경로 / 로케일 별로 그룹화됨).            |
+| `GET`  | `/api/analytics/experiments/:experimentKey` | A/B 실험을 위한 변형(variant)별 전환율 및 통계적 유의성.               |
+
+[CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_CMS.md)를 사용하여 프로그래밍 방식으로 호출할 수도 있습니다:
+
+```ts fileName="analytics.ts"
+import { createIntlayerCMS } from "@intlayer/api";
+import { analyticsEndpoint } from "@intlayer/api/analytics";
+
+const cms = createIntlayerCMS();
+
+const { data: audience } = await analyticsEndpoint(cms).getAudience(30);
+```
+
+## 유용한 링크
+
+- [Dynamic Dictionaries - Collections & Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/index.md)
+- [Intlayer CMS - CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_CMS.md)
+- [Intlayer Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_visual_editor.md)
+- [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)
+- [Self-Hosting Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/self_hosting.md)

package/docs/ko/autoFill.md

@@ -75,11 +75,30 @@ v7에서는 `fill` 명령 동작이 업데이트되었습니다:
 
 다른 파일에 쓰기 위해 경로 옵션을 사용할 때, fill 메커니즘은 콘텐츠 선언 파일 간의 _master-slave_ 관계를 통해 작동합니다. 메인(master) 파일이 소스 오브 트루스 역할을 하며, 업데이트될 때 Intlayer는 경로로 지정된 파생(filled) 선언 파일에 자동으로 그 변경 사항을 적용합니다.
 
-# 자동 채우기 콘텐츠 선언 파일 번역
+### 로케일별 커스터마이제이션
 
-**자동 채우기 콘텐츠 선언 파일**은 개발 워크플로우를 가속화하는 방법입니다.
+객체를 사용하여 각 로케일의 동작을 커스터마이즈할 수도 있습니다:
 
-자동 채우기 메커니즘은 콘텐츠 선언 파일 간의 _마스터-슬레이브_ 관계를 통해 작동합니다. 메인(마스터) 파일이 업데이트되면 Intlayer가 파생(자동 채우기된) 선언 파일에 해당 변경 사항을 자동으로 적용합니다.
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  content: {
+    internationalization: {
+      locales: [Locales.ENGLISH, Locales.FRENCH, Locales.POLISH],
+      defaultLocale: Locales.ENGLISH,
+      requiredLocales: [Locales.ENGLISH], // t 함수에서 Property 'pl' is missing in type '{ en: string; xxx }' 오류를 피하기 위해 권장됨
+    },
+  },
+  dictionary: {
+    fill: {
+      en: true, // 현재 파일을 영어로 채우고 편집
+      fr: "./translations/fr.json", // 프랑스어용 별도 파일 생성
+      es: false, // 스페인어 채우기 비활성화
+    },
+  },
+};
+```
+
+이를 통해 동일한 프로젝트 내에서 다양한 로케일에 대해 다른 fill 동작을 가질 수 있습니다.
 
 ```ts fileName="src/components/example/example.content.ts"
 import { Locales, type Dictionary } from "intlayer";
@@ -87,18 +106,18 @@ import { Locales, type Dictionary } from "intlayer";
 const exampleContent = {
   key: "example",
   locale: Locales.ENGLISH,
-  autoFill: "./example.content.json",
+  fill: "./example.content.json",
   content: {
-    contentExample: "이것은 콘텐츠의 예시입니다",
+    contentExample: "This is an example of content",
   },
 } satisfies Dictionary;
 
 export default exampleContent;
 ```
 
-다음은 `autoFill` 지시어를 사용한 [로케일별 콘텐츠 선언 파일](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/per_locale_file.md)입니다.
+다음은 `fill` 명령어를 사용하는 [로케일별 콘텐츠 선언 파일](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/per_locale_file.md)입니다.
 
-그런 다음, 다음 명령어를 실행하면:
+그런 다음 다음 명령어를 실행할 때:
 
 ```bash packageManager="npm"
 npx intlayer fill --file 'src/components/example/example.content.ts'
@@ -116,7 +135,7 @@ pnpm intlayer fill --file 'src/components/example/example.content.ts'
 bun x intlayer fill --file 'src/components/example/example.content.ts'
 ```
 
-Intlayer는 메인 파일에 아직 선언되지 않은 모든 로케일을 채워 `src/components/example/example.content.json`에 파생 선언 파일을 자동으로 생성합니다.
+Intlayer는 `src/components/example/example.content.json`에서 파생 선언 파일을 자동으로 생성하여 메인 파일에 아직 선언되지 않은 모든 로케일을 채웁니다.
 
 ```json5 fileName="src/components/example/example.content.json"
 {
@@ -133,7 +152,7 @@ Intlayer는 메인 파일에 아직 선언되지 않은 모든 로케일을 채
 }
 ```
 
-그 후, 두 선언 파일은 단일 사전으로 병합되어 표준 `useIntlayer("example")` 훅(react) / 컴포저블(vue)을 통해 접근할 수 있습니다.
+그 후, 두 선언 파일은 단일 dictionary로 병합되어 표준 `useIntlayer("example")` hook (react) / composable (vue)을 사용하여 접근할 수 있습니다.
 
 ## 글로벌 설정
 

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으로 전달) 파지도 보수적으로 건너뜁니다. 이런 경우에는 전체 사전이 유지됩니다.