@intlayer/docs 9.0.0-canary.2 → 9.0.0-canary.21

package/docs/ko/live-sync.md

@@ -0,0 +1,187 @@
+---
+createdAt: 2026-07-08
+updatedAt: 2026-07-08
+title: 라이브 동기화 | CMS 콘텐츠 변경 사항을 실시간으로 반영
+description: 재빌드나 재배포 없이 Intlayer CMS 콘텐츠 변경 사항을 앱에 실시간으로 반영하세요.
+keywords:
+  - 라이브 동기화
+  - Live Sync
+  - CMS
+  - 비주얼 에디터
+  - 국제화
+  - 문서
+  - Intlayer
+  - Next.js
+  - Vite
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Intlayer CMS 문서에서 별도의 페이지로 이동"
+  - version: 6.0.1
+    date: 2025-09-22
+    changes: "라이브 동기화 문서 추가"
+  - version: 6.0.0
+    date: 2025-09-04
+    changes: "`hotReload` 필드를 `liveSync`로 교체"
+author: aymericzip
+---
+
+# 라이브 동기화
+
+라이브 동기화는 앱이 런타임에 CMS 콘텐츠 변경 사항을 반영할 수 있게 합니다. 재빌드나 재배포가 필요 없습니다. 활성화되면 업데이트가 라이브 동기화 서버로 스트리밍되어 애플리케이션이 읽는 사전을 갱신합니다.
+
+## 목차
+
+<TOC/>
+
+---
+
+## 라이브 동기화 활성화
+
+> Live Sync는 지속적인 서버 연결이 필요하며 엔터프라이즈 플랜에서만 사용할 수 있습니다.
+
+Intlayer 구성을 업데이트하여 Live Sync를 활성화하세요:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... 기타 구성 설정
+  editor: {
+    /**
+     * 변경 사항이 감지되면 로케일 구성을 핫 리로딩할 수 있도록 활성화합니다.
+     * 예를 들어, 사전이 추가되거나 업데이트되면 애플리케이션이
+     * 페이지에 표시되는 콘텐츠를 업데이트합니다.
+     *
+     * 핫 리로딩은 서버와의 지속적인 연결이 필요하기 때문에,
+     * `enterprise` 플랜 고객에게만 제공됩니다.
+     *
+     * 기본값: false
+     */
+    liveSync: true,
+  },
+  dictionary: {
+    /**
+     * 사전이 어떻게 가져오는지를 제어합니다:
+     *
+     * - "fetch": 사전은 Live Sync API를 사용하여 동적으로 가져옵니다.
+     *   useIntlayer를 useDictionaryDynamic으로 대체합니다.
+     *
+     * 참고: 라이브 모드는 Live Sync API를 사용하여 사전을 가져옵니다. API 호출이
+     * 실패하면 사전은 동적으로 가져옵니다.
+     * 참고: 원격 콘텐츠가 있고 "live" 플래그가 있는 사전만 라이브 모드를 사용합니다.
+     * 나머지는 성능을 위해 동적 모드를 사용합니다.
+     */
+    importMode: "fetch",
+  },
+};
+
+export default config;
+```
+
+애플리케이션을 감싸기 위해 Live Sync 서버를 시작하세요:
+
+독립형 서버 사용 예시:
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... 다른 스크립트들
+    "live:start": "npx intlayer live",
+  },
+}
+```
+
+`--process` 인수를 사용하여 애플리케이션 서버를 병렬로 사용할 수도 있습니다.
+
+Next.js 사용 예시:
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... 다른 스크립트들
+    "build": "next build",
+    "dev": "next dev",
+    "start": "npx intlayer live --with 'next start'",
+  },
+}
+```
+
+Vite 사용 예시:
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... 다른 스크립트들
+    "build": "vite build",
+    "dev": "vite dev",
+    "start": "npx intlayer live --with 'vite start'",
+  },
+}
+```
+
+Live Sync 서버는 애플리케이션을 감싸고 도착하는 업데이트된 콘텐츠를 자동으로 적용합니다.
+
+CMS로부터 변경 알림을 받기 위해, Live Sync 서버는 백엔드와 SSE 연결을 유지합니다. CMS에서 콘텐츠가 변경되면, 백엔드는 업데이트를 Live Sync 서버로 전달하고, Live Sync 서버는 새로운 사전을 기록합니다. 애플리케이션은 다음 탐색 또는 브라우저 새로고침 시 업데이트를 반영하며, 재빌드가 필요하지 않습니다.
+
+플로우 차트 (CMS/백엔드 -> Live Sync 서버 -> 애플리케이션 서버 -> 프론트엔드):
+
+![Live Sync Flow CMS/Backend/Live Sync Server/Application Server/Frontend Schema](https://github.com/aymericzip/intlayer/blob/main/docs/assets/live_sync_flow_scema.svg)
+
+작동 방식:
+
+![Live Sync Logic Schema](https://github.com/aymericzip/intlayer/blob/main/docs/assets/live_sync_logic_schema.svg)
+
+## 개발 워크플로우 (로컬)
+
+- 개발 중에는 애플리케이션이 시작될 때 모든 원격 사전을 가져오므로 업데이트를 빠르게 테스트할 수 있습니다.
+- Next.js로 로컬에서 Live Sync를 테스트하려면 개발 서버를 래핑하세요:
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... 다른 스크립트
+    "dev": "npx intlayer live --with 'next dev'",
+    // "dev": "npx intlayer live --with 'vite dev'", // Vite용
+  },
+}
+```
+
+개발 중에 Intlayer가 Live import 변환을 적용하도록 최적화를 활성화하세요:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    applicationURL: "http://localhost:5173",
+    liveSyncURL: "http://localhost:4000",
+    liveSync: true,
+  },
+  dictionary: {
+    importMode: "fetch",
+  },
+  build: {
+    optimize: true, // 기본값: process.env.NODE_ENV === 'production'
+  },
+};
+
+export default config;
+```
+
+이 설정은 개발 서버를 Live Sync 서버와 래핑하고, 시작 시 원격 사전을 가져오며, CMS에서 SSE를 통해 업데이트를 스트리밍합니다. 변경 사항을 보려면 페이지를 새로 고치세요.
+
+## 참고 사항 및 제약 조건
+
+- 라이브 싱크 출처를 사이트 보안 정책(CSP)에 추가하세요. 라이브 싱크 URL이 `connect-src`(및 관련이 있다면 `frame-ancestors`)에 허용되어 있는지 확인하세요.
+- 라이브 싱크는 정적 출력과 함께 작동하지 않습니다. Next.js의 경우, 런타임에 업데이트를 받으려면 페이지가 동적이어야 합니다(예: 전체 정적 전용 제약을 피하기 위해 `generateStaticParams`, `generateMetadata`, `getServerSideProps` 또는 `getStaticProps`를 적절히 사용).
+- CMS에서 각 사전에는 `live` 플래그가 있습니다. `live=true`인 사전만 라이브 싱크 API를 통해 가져오며, 나머지는 동적으로 가져와 런타임에 변경되지 않습니다.
+- `live` 플래그는 빌드 시 각 사전에 대해 평가됩니다. 빌드 시 원격 콘텐츠가 `live=true`로 표시되지 않았다면, 해당 사전에 대해 라이브 싱크를 활성화하려면 다시 빌드해야 합니다.
+- 라이브 싱크 서버는 `.intlayer`에 쓸 수 있어야 합니다. 컨테이너 환경에서는 `/.intlayer`에 쓰기 권한이 있는지 확인하세요.
+
+## 유용한 링크
+
+- [Intlayer CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_CMS.md)
+- [Intlayer 비주얼 에디터](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_visual_editor.md)
+- [구성 참조](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)
+- [자체 호스팅 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/self_hosting.md)

package/docs/ko/mcp_server.md

@@ -248,6 +248,28 @@ ChatGPT에서 MCP 서버를 구성하려면 [공식 문서](https://platform.ope
 
 ---
 
+## Claude Code (CLI)에서 설정
+
+Claude Code에서 MCP 서버를 구성하려면 [공식 문서](https://modelcontextprotocol.io/quickstart/user)를 따르세요.
+
+### Local server (stdio) (권장)
+
+Intlayer MCP 서버를 stdio를 사용하여 Claude Code에 연결하려면:
+
+```bash
+claude mcp add intlayer npx -y @intlayer/mcp
+```
+
+### 원격 서버 (Streamable HTTP)
+
+Streamable HTTP (SSE)를 사용하여 Intlayer MCP 서버를 Claude Code에 연결하려면:
+
+```bash
+claude mcp add intlayer https://mcp.intlayer.org -t http
+```
+
+---
+
 ## CLI를 통한 MCP 서버 사용
 
 테스트, 디버깅 또는 다른 도구와의 통합을 위해 Intlayer MCP 서버를 명령줄에서 직접 실행할 수도 있습니다.

package/docs/ko/migration_from_i18next_to_intlayer.md

@@ -98,24 +98,44 @@ Intlayer는 단순한 i18n 솔루션을 넘어, 자체 호스팅이 가능한 **
 
 Intlayer 핵심 패키지와 호환성 어댑터를 설치합니다:
 
+```bash packageManager="npm"
+npx intlayer@canary init --interactive    # v9
+# npx intlayer init                       # v8
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer@canary init --interactive   # v9
+# pnpm dlx intlayer init                      # v8
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer@canary init --interactive   # v9
+# yarn dlx intlayer init                      # v8
+```
+
+```bash packageManager="bun"
+bunx intlayer@canary init --interactive   # v9
+# bunx intlayer init                      # v8
+```
+
+> `--interactive` 플래그는 선택 사항입니다. AI 에이전트인 경우 `intlayer-cli init`를 사용하세요.
+
+> 이 명령은 환경을 감지하고 필요한 패키지를 설치합니다. 예를 들어:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/i18next @intlayer/sync-json-plugin
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/i18next @intlayer/sync-json-plugin
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/i18next @intlayer/sync-json-plugin
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/i18next @intlayer/sync-json-plugin
-bun x intlayer init
 ```
 
 > `i18next`를 계속 설치해 둘 수 있습니다 — 호환성 어댑터는 TypeScript 타입을 위해 이를 `devDependency` / `peerDependency`로 사용합니다.

package/docs/ko/migration_from_next-i18next_to_intlayer.md

@@ -101,24 +101,44 @@ Intlayer는 단순한 i18n 솔루션을 넘어, 자체 호스팅이 가능한 **
 
 Intlayer 핵심 패키지와 호환성 어댑터를 설치합니다:
 
+```bash packageManager="npm"
+npx intlayer@canary init --interactive    # v9
+# npx intlayer init                       # v8
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer@canary init --interactive   # v9
+# pnpm dlx intlayer init                      # v8
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer@canary init --interactive   # v9
+# yarn dlx intlayer init                      # v8
+```
+
+```bash packageManager="bun"
+bunx intlayer@canary init --interactive   # v9
+# bunx intlayer init                      # v8
+```
+
+> `--interactive` 플래그는 선택 사항입니다. AI 에이전트인 경우 `intlayer-cli init`를 사용하세요.
+
+> 이 명령은 환경을 감지하고 필요한 패키지를 설치합니다. 예를 들어:
+
 ```bash packageManager="npm"
 npm install intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer next-intlayer react-intlayer @intlayer/next-i18next @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
-bun x intlayer init
 ```
 
 > 마이그레이션 도중 별칭 설정이 완료될 때까지 `next-i18next`, `react-i18next`, `i18next`를 계속 설치해 둘 수 있습니다.

package/docs/ko/migration_from_next-intl_to_intlayer.md

@@ -97,24 +97,44 @@ Intlayer는 단순한 i18n 솔루션을 넘어, 자체 호스팅이 가능한 **
 
 Intlayer 핵심 패키지와 `@intlayer/next-intl` 호환성 어댑터를 설치합니다:
 
+```bash packageManager="npm"
+npx intlayer@canary init --interactive    # v9
+# npx intlayer init                       # v8
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer@canary init --interactive   # v9
+# pnpm dlx intlayer init                      # v8
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer@canary init --interactive   # v9
+# yarn dlx intlayer init                      # v8
+```
+
+```bash packageManager="bun"
+bunx intlayer@canary init --interactive   # v9
+# bunx intlayer init                      # v8
+```
+
+> `--interactive` 플래그는 선택 사항입니다. AI 에이전트인 경우 `intlayer-cli init`를 사용하세요.
+
+> 이 명령은 환경을 감지하고 필요한 패키지를 설치합니다. 예를 들어:
+
 ```bash packageManager="npm"
 npm install intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-plugin
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-plugin
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-plugin
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer next-intlayer @intlayer/next-intl @intlayer/sync-json-plugin
-bun x intlayer init
 ```
 
 > `next-intl`은 계속 설치해 두세요 — **URL 라우팅**(`createNavigation`, `createMiddleware`, `Link`, `redirect`, `usePathname`, `useRouter`)을 위해 계속 필요합니다. 호환성 어댑터는 라우팅 레이어를 교체**하지 않습니다**.
@@ -168,9 +188,7 @@ import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
 
 const withIntlayer = createNextIntlPlugin();
 
-const nextConfig: NextConfig = {
-  /* 기존 설정 옵션들 */
-};
+const nextConfig: NextConfig = {/* 기존 설정 옵션들 */};
 
 export default withIntlayer(nextConfig);
 ```

package/docs/ko/migration_from_nuxtjs_i18n_to_intlayer.md

@@ -100,24 +100,44 @@ Intlayer는 단순한 i18n 솔루션을 넘어, 자체 호스팅이 가능한 **
 
 Intlayer 핵심 패키지와 호환성 어댑터를 설치합니다:
 
+```bash packageManager="npm"
+npx intlayer@canary init --interactive    # v9
+# npx intlayer init                       # v8
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer@canary init --interactive   # v9
+# pnpm dlx intlayer init                      # v8
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer@canary init --interactive   # v9
+# yarn dlx intlayer init                      # v8
+```
+
+```bash packageManager="bun"
+bunx intlayer@canary init --interactive   # v9
+# bunx intlayer init                      # v8
+```
+
+> `--interactive` 플래그는 선택 사항입니다. AI 에이전트인 경우 `intlayer-cli init`를 사용하세요.
+
+> 이 명령은 환경을 감지하고 필요한 패키지를 설치합니다. 예를 들어:
+
 ```bash packageManager="npm"
 npm install intlayer vue-intlayer nuxt-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer vue-intlayer nuxt-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer vue-intlayer nuxt-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer vue-intlayer nuxt-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
-bun x intlayer init
 ```
 
 > 조만간 Nuxt 설정에서 `@nuxtjs/i18n`을 제거하겠지만 마이그레이션하는 동안 안전하게 설치해 둘 수 있습니다.

package/docs/ko/migration_from_react-i18next_to_intlayer.md

@@ -100,24 +100,44 @@ Intlayer는 단순한 i18n 솔루션을 넘어, 자체 호스팅이 가능한 **
 
 Intlayer 핵심 패키지와 호환성 어댑터를 설치합니다:
 
+```bash packageManager="npm"
+npx intlayer@canary init --interactive    # v9
+# npx intlayer init                       # v8
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer@canary init --interactive   # v9
+# pnpm dlx intlayer init                      # v8
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer@canary init --interactive   # v9
+# yarn dlx intlayer init                      # v8
+```
+
+```bash packageManager="bun"
+bunx intlayer@canary init --interactive   # v9
+# bunx intlayer init                      # v8
+```
+
+> `--interactive` 플래그는 선택 사항입니다. AI 에이전트인 경우 `intlayer-cli init`를 사용하세요.
+
+> 이 명령은 환경을 감지하고 필요한 패키지를 설치합니다. 예를 들어:
+
 ```bash packageManager="npm"
 npm install intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer react-intlayer @intlayer/react-i18next @intlayer/i18next @intlayer/sync-json-plugin
-bun x intlayer init
 ```
 
 > `react-i18next`와 `i18next`를 계속 설치해 둘 수 있습니다 — 호환성 어댑터는 TypeScript 타입을 위해 이를 선택적 `devDependencies` / `peerDependencies`로 사용합니다. `package.json`에서 peer 의존성을 변경할 필요가 없습니다.
@@ -193,9 +213,7 @@ import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
 
 const withIntlayer = createNextI18nPlugin();
 
-const nextConfig: NextConfig = {
-  /* 귀하의 설정 옵션 */
-};
+const nextConfig: NextConfig = {/* 귀하의 설정 옵션 */};
 
 export default withIntlayer(nextConfig);
 ```

package/docs/ko/migration_from_vue-i18n_to_intlayer.md

@@ -99,24 +99,44 @@ Intlayer는 단순한 i18n 솔루션을 넘어, 자체 호스팅이 가능한 **
 
 Intlayer 핵심 패키지와 호환성 어댑터를 설치합니다:
 
+```bash packageManager="npm"
+npx intlayer@canary init --interactive    # v9
+# npx intlayer init                       # v8
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer@canary init --interactive   # v9
+# pnpm dlx intlayer init                      # v8
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer@canary init --interactive   # v9
+# yarn dlx intlayer init                      # v8
+```
+
+```bash packageManager="bun"
+bunx intlayer@canary init --interactive   # v9
+# bunx intlayer init                      # v8
+```
+
+> `--interactive` 플래그는 선택 사항입니다. AI 에이전트인 경우 `intlayer-cli init`를 사용하세요.
+
+> 이 명령은 환경을 감지하고 필요한 패키지를 설치합니다. 예를 들어:
+
 ```bash packageManager="npm"
 npm install intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
-bun x intlayer init
 ```
 
 > `vue-i18n`을 계속 설치해 둘 수 있습니다 — 호환성 어댑터는 TypeScript 타입을 위해 이를 `devDependency` / `peerDependency`로 사용합니다.

package/docs/ko/packages/@intlayer_babel/export.md

@@ -0,0 +1,131 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: "@intlayer/babel 패키지 문서"
+description: 빌드 중에 콘텐츠 추출, 가져오기 최적화, 사용되지 않는 필드 정리, 필드 이름 난독화를 처리하기 위한 Intlayer용 Babel 플러그인입니다.
+keywords:
+  - "@intlayer/babel"
+  - babel
+  - plugin
+  - 국제화
+  - i18n
+  - 컴파일러
+  - 최적화
+  - 정리
+  - 축소
+slugs:
+  - doc
+  - packages
+  - "@intlayer/babel"
+  - export
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "모든 내보내기 문서 통합"
+author: aymericzip
+---
+
+# @intlayer/babel 패키지
+
+`@intlayer/babel` 패키지는 Intlayer를 위한 전문적인 Babel 플러그인 모음을 제공합니다. 이 플러그인들은 콘텐츠 선언 추출, `useIntlayer` / `getIntlayer` 호출을 최적화된 사전 가져오기로 재작성, 사용되지 않는 필드 정리, 필드 이름 압축 등 전체 빌드 주기를 다룹니다.
+
+## 설치
+
+```bash
+npm install @intlayer/babel
+```
+
+## 내보내기
+
+가져오기:
+
+```ts
+import { ... } from "@intlayer/babel";
+```
+
+---
+
+### 플러그인
+
+| 함수 / 클래스                  | 설명                                                                                                                                                                                     |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `intlayerExtractBabelPlugin`   | 소스 파일에서 번역 가능한 콘텐츠를 추출하고 `useIntlayer` / `getIntlayer` 훅을 자동으로 주입하는 Babel 플러그인입니다. Next.js 및 Babel 기반 빌드 도구와 함께 사용하도록 설계되었습니다. |
+| `intlayerOptimizeBabelPlugin`  | `useIntlayer` 및 `getIntlayer` 호출을 변환하고 가져오기를 최적화된 JSON 사전 가져오기(정적, 동적 또는 fetch를 통한 가져오기)로 재작성하는 Babel 플러그인입니다.                          |
+| `intlayerPurgeBabelPlugin`     | 소스 파일을 분석하고 컴파일된 사전 JSON 파일을 재작성하여 사용되지 않는 필드를 제거(`build.purge`)하거나 짧은 알파벳 별칭으로 이름을 변경(`build.minify`)하는 Babel 플러그인입니다.      |
+| `intlayerMinifyBabelPlugin`    | 축소(minify) 단계에서 할당된 짧은 필드 별칭(예: `content.title` ← `content.a`)을 사용하도록 소스 파일을 재작성하는 Babel 플러그인입니다. `intlayerPurgeBabelPlugin`에 의존합니다.        |
+| `makeFieldRenameBabelPlugin`   | `PruneContext`에 채워진 `dictionaryKeyToFieldRenameMap`에 따라 소스 파일의 사전 콘텐츠 필드 액세스 이름을 바꾸는 Babel 플러그인을 생성하는 팩토리 함수입니다.                            |
+| `makeUsageAnalyzerBabelPlugin` | 소스 코드에서 `useIntlayer` / `getIntlayer`의 사용을 분석하고 공유 `PruneContext`에 필드 사용 데이터를 집계하는 Babel 플러그인을 생성하는 팩토리 함수입니다.                             |
+| `getSharedPruneContext`        | 지정된 기본 디렉토리에 대한 공유 `PruneContext` 객체를 반환하거나 아직 초기화되지 않은 경우 `null`을 반환하는 도우미 함수입니다.                                                         |
+
+---
+
+### 플러그인 설정 유틸리티
+
+| 함수                       | 설명                                                                                                                                |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `getExtractPluginOptions`  | Intlayer 설정을 로드하고 `intlayerExtractBabelPlugin`과 함께 사용할 수 있는 `ExtractPluginOptions`를 반환합니다.                    |
+| `getOptimizePluginOptions` | Intlayer 설정 및 컴파일된 사전을 로드하고 `intlayerOptimizeBabelPlugin`과 함께 사용할 수 있는 `OptimizePluginOptions`를 반환합니다. |
+| `getPurgePluginOptions`    | Intlayer 설정을 로드하고 `intlayerPurgeBabelPlugin`과 함께 사용할 수 있는 `PurgePluginOptions`를 반환합니다.                        |
+| `getMinifyPluginOptions`   | Intlayer 설정을 로드하고 `intlayerMinifyBabelPlugin`과 함께 사용할 수 있는 `MinifyPluginOptions`를 반환합니다.                      |
+
+---
+
+### 타입
+
+| 타입                    | 설명                                                                                           |
+| ----------------------- | ---------------------------------------------------------------------------------------------- |
+| `CompilerMode`          | 컴파일러 모드: `'dev'` HMR 지원 개발을 위한 모드 또는 `'build'` 프로덕션 빌드를 위한 모드.     |
+| `ExtractPluginOptions`  | `intlayerExtractBabelPlugin`의 옵션: 파일 목록, 설정, `onExtract` 콜백 등.                     |
+| `ExtractResult`         | 추출 결과: 사전 키, 파일 경로, 콘텐츠 및 로케ール.                                             |
+| `OptimizePluginOptions` | `intlayerOptimizeBabelPlugin`의 옵션: 사전 경로, 가져오기 모드, 사전별 모드 맵 등.             |
+| `PurgePluginOptions`    | `intlayerPurgeBabelPlugin`의 옵션: 기본 디렉토리, 제거/축소/최적화 플래그, 컴포넌트 파일 목록. |
+| `MinifyPluginOptions`   | `intlayerMinifyBabelPlugin`의 옵션: 기본 디렉토리, 축소/최적화/editorEnabled 플래그.           |
+| `PruneContext`          | 분석 및 정리 플러그인 간에 공유되는 상태: 필드 사용 맵, 이름 바꾸기 맵 등.                     |
+| `DictionaryFieldUsage`  | 단일 사전에 대한 필드 사용 결과: 정적 분석이 결정적이지 않은 경우 `Set<string>` 또는 `'all'`.  |
+| `NestedRenameEntry`     | 이름 바꾸기 트리의 노드: `shortName` 및 자식 맵.                                               |
+| `NestedRenameMap`       | 이름 바꾸기 트리의 단일 수준: `Map<string, NestedRenameEntry>`.                                |
+| `CompatCallerConfig`    | 호환성 어댑터(compat-adapter) 패키지용 호환 사용 분석기 설정 (호출자 이름 및 처리 옵션).       |
+| `ScriptBlock`           | SFC 파일(Vue 또는 Svelte)에서 추출된 스크립트 블록: 콘텐츠, 시작 오프셋 및 끝 오프셋.          |
+
+---
+
+### 유틸리티 함수
+
+| 함수                              | 설명                                                                                                                                    |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `generateShortFieldName`          | 정수(0부터 시작)를 짧은 알파벳 식별자로 변환합니다: `0` → `'a'`, `25` → `'z'`, `26` → `'aa'` 등.                                        |
+| `buildNestedRenameMapFromContent` | Intlayer 노드 구조(translation, enumeration 등)를 존중하여 컴파일된 사전의 콘텐츠 값으로부터 `NestedRenameMap`을 재귀적으로 빌드합니다. |
+| `createPruneContext`              | 기본값으로 초기화된 빈 새 `PruneContext` 객체를 생성합니다.                                                                             |
+| `extractScriptBlocks`             | Babel 분석을 위해 SFC 파일(Vue / Svelte)에서 `<script>` 블록을 추출합니다.                                                              |
+| `BABEL_PARSER_OPTIONS`            | 지원되는 프레임워크(React/Vue/Svelte/Angular/...)를 다루는 Babel 파서 옵션을 나타내는 상수.                                             |
+| `INTLAYER_CALLER_NAMES`           | 원래 Intlayer 호출자 이름의 상수 목록: `['useIntlayer', 'getIntlayer']`.                                                                |
+
+---
+
+## 사용 예시
+
+```js
+// babel.config.js
+const {
+  intlayerExtractBabelPlugin,
+  intlayerPurgeBabelPlugin,
+  intlayerMinifyBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getPurgePluginOptions,
+  getMinifyPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
+    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+> **참고:** `intlayerPurgeBabelPlugin`은 `intlayerMinifyBabelPlugin`이 전자에 의해 빌드된 이름 바꾸기 맵을 읽기 때문에 반드시 `intlayerMinifyBabelPlugin` **전에** 선언되어야 합니다. 또한 `useIntlayer` 호출이 재작성되기 전에 사전 키를 볼 수 있도록 두 플러그인 모두 앞에 `intlayerOptimizeBabelPlugin`이 와야 합니다.