@intlayer/docs 9.1.3 → 9.2.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/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-07-11
+updatedAt: 2026-08-06
 title: 구성 (Configuration)
 description: 애플리케이션에 Intlayer를 구성하는 방법을 알아보세요. 필요에 따라 Intlayer를 맞춤설정하는 데 사용할 수 있는 다양한 설정과 옵션을 이해하세요.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.1.3
+    date: 2026-08-06
+    changes: "`routing.enableProxy`를 3상태로 변경: 미설정(auto), `true`, `false`"
   - version: 9.0.0
     date: 2026-07-11
     changes: "`analytics` 구성 추가"
@@ -235,6 +238,19 @@ const config: IntlayerConfig = {
      */
     mode: "prefix-no-default",
 
+    /**
+     * Intlayer 로케일 라우팅 프록시(미들웨어)를 활성화합니다.
+     * dev, preview, SSR에서 로케일 감지, 리디렉션, 리라이트를 처리합니다.
+     * - 미설정(auto): dev 및 preview 서버는 쿠키와 헤더에 저장된 로케일을 무시하여
+     *   라우팅을 URL 기반으로 유지합니다. 접두사 해석, 로케일 저장,
+     *   Accept-Language 감지는 계속 동작합니다.
+     *   프로덕션에서는 `true`와 동일하게 동작합니다.
+     * - true: 모든 환경에서 완전한 동작.
+     * - false: 로케일 라우팅 없음.
+     * 기본값: undefined (auto)
+     */
+    enableProxy: undefined,
+
     /**
      * 사용자가 선택한 로케일 저장 위치.
      * 옵션: 'cookie', 'localStorage', 'sessionStorage', 'header' 또는 이들의 배열.
@@ -713,13 +729,14 @@ Intlayer 애널리틱스와 관련된 설정을 정의합니다: 사용자에게
 
 URL 구조, 로케일 저장 및 미들웨어 처리를 포함하여 라우팅 동작을 제어하기 위한 설정입니다.
 
-| 필드       | 설명                                                                                                                                                                               | 타입                                                                                                                                                                                                         | 기본값                 | 예시                                                                                                                                                                                         | 참고                                                                                                                                                                                                                                                                                          |
-| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mode`     | 로케일 처리를 위한 URL 라우팅 모드.                                                                                                                                                | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) 또는 `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: 로케일이 다른 수단으로 관리됨. `'search-params'`: `/dashboard?locale=fr` | 쿠키나 로컬 스토리지 관리에는 영향을 주지 않습니다.                                                                                                                                                                                                                                           |
-| `storage`  | 클라이언트에서 로케일을 저장하기 위한 구성.                                                                                                                                        | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                           | 아래의 저장소 옵션 표를 참조하세요.                                                                                                                                                                                                                                                           |
-| `basePath` | 애플리케이션 URL의 기본 경로.                                                                                                                                                      | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                                  | 앱이 `https://example.com/my-app`에 있는 경우 basePath는 `'/my-app'`이며 URL은 `https://example.com/my-app/en`이 됩니다.                                                                                                                                                                      |
-| `rewrite`  | 특정 로케일 경로에 대해 기본 라우팅 모드를 재정의하기 위한 사용자 정의 URL 재작성 규칙. 동적 `[param]` 매개변수를 지원합니다.                                                      | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | 아래 예시 참조                                                                                                                                                                               | • Rewrite 규칙은 `mode`보다 우선순위가 높습니다.<br/>• Next.js 및 Vite와 함께 작동합니다.<br/>• `getLocalizedUrl()`은 일치하는 규칙을 자동으로 적용합니다.<br/>• [사용자 정의 URL 재작성](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md)을 참조하세요. |
-| `domains`  | 도메인 기반 라우팅을 위해 로케일을 도메인 호스트 이름에 매핑합니다. 설정된 경우 로케일의 URL은 해당 도메인을 베이스(절대 URL)로 사용하며 경로에 로케일 접두사가 추가되지 않습니다. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                                  | • 호스트 이름에 포함되지 않은 경우 기본 프로토콜은 `https://`입니다.<br/>• 도메인 자체가 로케일을 식별하므로 `/zh/` 접두사가 추가되지 않습니다.<br/>• `getLocalizedUrl('/', 'zh')`는 `https://intlayer.zh/`를 반환합니다.                                                                     |
+| 필드          | 설명                                                                                                                                                                               | 타입                                                                                                                                                                                                         | 기본값                 | 예시                                                                                                                                                                                         | 참고                                                                                                                                                                                                                                                                                                                         |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`        | 로케일 처리를 위한 URL 라우팅 모드.                                                                                                                                                | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) 또는 `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: 로케일이 다른 수단으로 관리됨. `'search-params'`: `/dashboard?locale=fr` | 쿠키나 로컬 스토리지 관리에는 영향을 주지 않습니다.                                                                                                                                                                                                                                                                          |
+| `enableProxy` | Intlayer 로케일 라우팅 프록시(미들웨어)를 활성화합니다.                                                                                                                            | `boolean` &#124; <br/> `undefined`                                                                                                                                                                           | `undefined` (auto)     | `true`                                                                                                                                                                                       | • 미설정(auto): dev 및 preview 서버는 쿠키/헤더에 저장된 로케일을 리디렉션 소스로 무시합니다. 접두사, 저장, `Accept-Language` 감지는 계속 동작합니다. 프로덕션에서는 `true`와 동일합니다.<br/>• `true`: 어디서나 완전한 동작.<br/>• `false`: 로케일 라우팅 없음. Next.js에서는 `intlayerProxy` 미들웨어가 패스스루가 됩니다. |
+| `storage`     | 클라이언트에서 로케일을 저장하기 위한 구성.                                                                                                                                        | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                           | 아래의 저장소 옵션 표를 참조하세요.                                                                                                                                                                                                                                                                                          |
+| `basePath`    | 애플리케이션 URL의 기본 경로.                                                                                                                                                      | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                                  | 앱이 `https://example.com/my-app`에 있는 경우 basePath는 `'/my-app'`이며 URL은 `https://example.com/my-app/en`이 됩니다.                                                                                                                                                                                                     |
+| `rewrite`     | 특정 로케일 경로에 대해 기본 라우팅 모드를 재정의하기 위한 사용자 정의 URL 재작성 규칙. 동적 `[param]` 매개변수를 지원합니다.                                                      | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | 아래 예시 참조                                                                                                                                                                               | • Rewrite 규칙은 `mode`보다 우선순위가 높습니다.<br/>• Next.js 및 Vite와 함께 작동합니다.<br/>• `getLocalizedUrl()`은 일치하는 규칙을 자동으로 적용합니다.<br/>• [사용자 정의 URL 재작성](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md)을 참조하세요.                                |
+| `domains`     | 도메인 기반 라우팅을 위해 로케일을 도메인 호스트 이름에 매핑합니다. 설정된 경우 로케일의 URL은 해당 도메인을 베이스(절대 URL)로 사용하며 경로에 로케일 접두사가 추가되지 않습니다. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                                  | • 호스트 이름에 포함되지 않은 경우 기본 프로토콜은 `https://`입니다.<br/>• 도메인 자체가 로케일을 식별하므로 `/zh/` 접두사가 추가되지 않습니다.<br/>• `getLocalizedUrl('/', 'zh')`는 `https://intlayer.zh/`를 반환합니다.                                                                                                    |
 
 **`rewrite` 예시**:
 

package/docs/ko/dictionary/file.md

@@ -23,7 +23,9 @@ history:
 author: aymericzip 
 ---
 
-# 파일 콘텐츠 / Intlayer에서 파일 임베딩하기
+# Intlayer의 파일 콘텐츠 / 파일 임베딩
+
+Intlayer에서 `file` 함수는 외부 파일 콘텐츠를 딕셔너리에 임베드할 수 있게 합니다. 이 방식은 Intlayer이 소스 파일을 인식하도록 하여 Intlayer Visual Editor 및 CMS와의 seamless 통합을 가능하게 합니다.
 
 ## 파일 임베딩 작동 방식
 

package/docs/ko/dictionary/nesting.md

@@ -64,6 +64,53 @@ export default firstDictionary;
 }
 ```
 
+### Nest를 통한 참조
+
+이제 위의 콘텐츠를 참조하기 위해 `nest` 함수를 사용하는 다른 콘텐츠 모듈을 만듭니다. 전체 콘텐츠 또는 특정 중첩된 값을 참조할 수 있습니다:
+
+```typescript fileName="secondDictionary.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { nest, type Dictionary } from "intlayer";
+
+const myNestingContent = {
+  key: "key_of_my_second_dictionary",
+  content: {
+    // 전체 딕셔너리를 참조합니다:
+    fullNestedContent: nest("key_of_my_first_dictionary"),
+    // 특정 중첩된 값을 참조합니다:
+    partialNestedContent: nest(
+      "key_of_my_first_dictionary",
+      "subContent.contentNumber"
+    ),
+  },
+} satisfies Dictionary;
+
+export default myNestingContent;
+```
+
+```json fileName="secondDictionary.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "key_of_my_second_dictionary",
+  "content": {
+    "fullNestedContent": {
+      "nodeType": "nested",
+      "nested": {
+        "dictionaryKey": "key_of_my_first_dictionary"
+      }
+    },
+    "partialNestedContent": {
+      "nodeType": "nested",
+      "nested": {
+        "dictionaryKey": "key_of_my_first_dictionary",
+        "path": "subContent.contentNumber"
+      }
+    }
+  }
+}
+```
+
+두 번째 파라미터로는 해당 콘텐츠 내의 중첩된 값으로의 경로를 지정할 수 있습니다. 경로가 제공되지 않으면 참조된 딕셔너리의 전체 콘텐츠가 반환됩니다.
+
 ## 중첩 설정
 
 <Tabs group="framework">
@@ -258,36 +305,6 @@ document.getElementById("nested")!.textContent = content.partialNestedContent;
   </Tab>
 </Tabs>
 
-## React Intlayer와 함께 중첩 사용
-
-React 컴포넌트에서 중첩된 콘텐츠를 사용하려면 `react-intlayer` 패키지의 `useIntlayer` 훅을 활용하세요. 이 훅은 지정된 키를 기반으로 올바른 콘텐츠를 가져옵니다. 사용 예제는 다음과 같습니다:
-
-```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { useIntlayer } from "react-intlayer";
-
-const NestComponent: FC = () => {
-  const { fullNestedContent, partialNestedContent } = useIntlayer(
-    "key_of_my_second_dictionary"
-  );
-
-  return (
-    <div>
-      <p>
-        Full Nested Content: {JSON.stringify(fullNestedContent)}
-        {/* 출력: {"content": "content", "subContent": {"contentNumber": 0, "contentString": "string"}} */}
-      </p>
-      <p>
-        Partial Nested Value: {partialNestedContent}
-        {/* 출력: 0 */}
-      </p>
-    </div>
-  );
-};
-
-export default NestComponent;
-```
-
 ## 추가 자료
 
 구성 및 사용에 대한 자세한 정보는 다음 리소스를 참조하세요: