@intlayer/docs 9.0.0-canary.6 → 9.0.0-canary.8

package/docs/ko/intlayer_with_tanstack+solid.md

@@ -228,11 +228,15 @@ export default defineConfig({
     tanstackStart({
       router: {
         routeFileIgnorePattern:
-          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5)$",
+          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
       },
     }),
     solidPlugin({ ssr: true }),
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```
@@ -568,22 +572,25 @@ const RootComponent: ParentComponent = (props) => {
 
 > 프로덕션에서 `intlayerProxy`를 사용하려면 `vite-intlayer` 패키지를 `devDependencies`에서 `dependencies`로 변경해야 합니다.
 
-```typescript {7,14-17} fileName="vite.config.ts"
+```typescript fileName="vite.config.ts"
 import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
 import solid from "vite-plugin-solid";
 import { nitro } from "nitro/vite";
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // Nitro를 사용하는 경우 프록시는 서버 앞에 배치되어야 합니다.
     nitro(),
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
     tanstackStart({
       router: {
         routeFileIgnorePattern:
-          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5)$",
+          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
       },
     }),
     solid(),
@@ -826,9 +833,9 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 컴파일러'>
 
-`intlayerCompiler` 플러그인을 포함하도록 `vite.config.ts`를 업데이트하세요.
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
 
-> Intlayer v9부터 컴파일러는 `intlayer()` 플러그인에 직접 번들로 제공되며 `compiler.enabled`가 설정되고 `compiler.output` 경로가 구성되면 자동으로 활성화됩니다. 아래와 같이 `intlayerCompiler()`를 별도로 등록하는 것은 이제 선택 사항입니다 — 추가되더라도 자체적으로 중복을 제거합니다. [v9 릴리스 노트](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/releases/v9.md)를 참조하세요.
+`intlayerCompiler` 플러그인을 포함하도록 `vite.config.ts`를 업데이트하세요.
 
 ```ts fileName="vite.config.ts"
 import { intlayer, intlayerCompiler } from "vite-intlayer";
@@ -843,12 +850,12 @@ export default defineConfig({
     tanstackStart({
       router: {
         routeFileIgnorePattern:
-          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5)$",
+          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
       },
     }),
     solidPlugin({ ssr: true }),
     intlayer(),
-    intlayerCompiler(),
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/ko/intlayer_with_tanstack.md

@@ -242,11 +242,15 @@ import { intlayer } from "vite-intlayer";
 const config = defineConfig({
   plugins: [
     nitro(),
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
     tanstackStart({
       router: {
         routeFileIgnorePattern:
-          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5)$",
+          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
       },
     }),
     viteReact(),
@@ -650,22 +654,25 @@ function RootDocument({ children }: { children: ReactNode }) {
 
 > 프로덕션에서 `intlayerProxy`를 사용하려면 `vite-intlayer` 패키지를 `devDependencies`에서 `dependencies`로 변경해야 합니다.
 
-```typescript {7,14-17} fileName="vite.config.ts"
+```typescript fileName="vite.config.ts"
 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
 import viteReact from "@vitejs/plugin-react";
 import { nitro } from "nitro/vite";
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // Nitro를 사용하는 경우 프록시를 서버 앞에 배치해야 합니다.
     nitro(),
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
     tanstackStart({
       router: {
         routeFileIgnorePattern:
-          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5)$",
+          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
       },
     }),
     viteReact(),
@@ -906,6 +913,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 컴파일러'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 `vite.config.ts`를 업데이트하여 `intlayerCompiler` 플러그인을 포함합니다.
 
 ```ts fileName="vite.config.ts"
@@ -915,7 +924,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 컴파일러 플러그인을 추가합니다
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/ko/intlayer_with_vite+lit.md

@@ -205,7 +205,13 @@ import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
-  plugins: [intlayer()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 
@@ -474,12 +480,15 @@ export class MyElement extends LitElement {
 
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```

package/docs/ko/intlayer_with_vite+preact.md

@@ -797,6 +797,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 컴파일러'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 `vite.config.ts`를 업데이트하여 `intlayerCompiler` 플러그인을 포함합니다.
 
 ```ts fileName="vite.config.ts"
@@ -806,7 +808,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 컴파일러 플러그인을 추가합니다
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/ko/intlayer_with_vite+react.md

@@ -424,6 +424,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 컴파일러'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 `vite.config.ts`를 업데이트하여 `intlayerCompiler` 플러그인을 포함합니다.
 
 ```ts fileName="vite.config.ts"
@@ -433,7 +435,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 컴파일러 플러그인을 추가합니다
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/ko/intlayer_with_vite+react_compiler.md

@@ -207,11 +207,18 @@ export default config;
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react-swc";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
-  plugins: [react(), intlayer(), intlayerCompiler()],
+  plugins: [
+    react(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 

package/docs/ko/intlayer_with_vite+svelte.md

@@ -295,6 +295,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 컴파일러'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 `vite.config.ts`를 업데이트하여 `intlayerCompiler` 플러그인을 포함합니다.
 
 ```ts fileName="vite.config.ts"
@@ -304,7 +306,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 컴파일러 플러그인을 추가합니다
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```
@@ -557,12 +559,12 @@ $: content = useIntlayer('app', locale);
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
 import { svelte } from "@sveltejs/vite-plugin-svelte";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 typescript {3,7} fileName="vite.config.ts" codeFormat="typescript"
 import { defineConfig } from "vite";
 import { svelte } from "@sveltejs/vite-plugin-svelte";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({

package/docs/ko/intlayer_with_vite+vanilla.md

@@ -205,7 +205,13 @@ import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
-  plugins: [intlayer()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 
@@ -466,12 +472,15 @@ document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =
 
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // 가장 먼저 위치해야 합니다
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```
@@ -603,6 +612,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 컴파일러'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 `intlayerCompiler` 플러그인을 포함하도록 `vite.config.ts`를 업데이트합니다:
 
 ```ts fileName="vite.config.ts"
@@ -612,7 +623,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 컴파일러 플러그인 추가
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/ko/intlayer_with_vite+vue.md

@@ -639,14 +639,17 @@ import LocaleSwitcher from "@components/LocaleSwitcher.vue";
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
 import vue from "@vitejs/plugin-vue";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
     vue(),
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```
@@ -970,6 +973,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 컴파일러'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 `vite.config.ts`를 업데이트하여 `intlayerCompiler` 플러그인을 포함합니다.
 
 ```ts fileName="vite.config.ts"
@@ -979,7 +984,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 컴파일러 플러그인을 추가합니다
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

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`이 와야 합니다.

package/docs/ko/packages/vite-intlayer/intlayerCompiler.md

@@ -0,0 +1,120 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: intlayerCompiler Vite 플러그인 문서 | vite-intlayer
+description: 빌드/변환 시점에 컴포넌트 파일에서 인라인 Intlayer 콘텐츠 선언을 추출하여 사전 JSON 파일에 기록하는 Vite 플러그인입니다.
+keywords:
+  - intlayerCompiler
+  - vite
+  - 플러그인
+  - 컴파일러
+  - 콘텐츠
+  - 사전
+  - 국제화
+  - i18n
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerCompiler
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "intlayer()에 포함됨; 문서 초기화"
+author: aymericzip
+---
+
+# intlayerCompiler
+
+`intlayerCompiler`는 컴포넌트 소스 파일에서 별도의 `.content.ts` 파일 대신 컴포넌트 내부에 직접 정의된 **인라인 Intlayer 콘텐츠 선언**을 스캔하여 변환(transform) 단계에서 사전 JSON 파일에 기록하는 Vite 플러그인입니다.
+
+> **Intlayer v9부터** `intlayerCompiler`는 Intlayer 설정에서 `compiler.enabled`가 `true`이고 `compiler.output`이 설정된 경우 기본 [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/vite-intlayer/intlayer.md) 플러그인 내에 자동으로 포함됩니다. 컴파일러 전용 설정을 완벽히 제어하고 싶을 때만 이 플러그인을 별도로 등록해야 합니다.
+
+## 사용법
+
+### `intlayer()`의 일부로 사용 (권장, v9+)
+
+Intlayer 설정을 통해 컴파일러를 활성화합니다:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  compiler: {
+    enabled: true,
+    output: "./src/dictionaries", // 추출된 사전이 작성될 경로
+  },
+});
+```
+
+그런 다음 추가 등록 없이 표준 플러그인을 사용합니다:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+### 독립 실행형(Standalone)으로 사용 (필요 시)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayerCompiler()],
+});
+```
+
+## 옵션
+
+```ts
+import type { IntlayerCompilerOptions } from "vite-intlayer";
+```
+
+| 옵션             | 타입                      | 설명                                                                              |
+| ---------------- | ------------------------- | --------------------------------------------------------------------------------- |
+| `configOptions`  | `GetConfigurationOptions` | `getConfiguration()`으로 전달되는 Intlayer 설정 재정의 옵션.                      |
+| `compilerConfig` | `Partial<CompilerConfig>` | 컴파일러 전용 설정 섹션(예: `enabled`, `output`, `filesList`)에 대한 재정의 옵션. |
+
+### 예시
+
+```ts
+intlayerCompiler({
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+  compilerConfig: { enabled: true, output: "./src/dictionaries" },
+});
+```
+
+## 동작 원리
+
+### 변환(Transform) 단계
+
+`compiler.filesList`와 일치하는 모든 소스 파일에 대해 컴파일러 플러그인은 다음을 수행합니다:
+
+1. 파일 콘텐츠를 `@intlayer/babel`의 `extractContent`에 전달합니다.
+2. 발견된 각 선언에 대해 `onExtract`를 호출하여 결과 사전 JSON을 `compiler.output`에 작성합니다.
+3. 인라인 선언이 표준 `useIntlayer('key')` / `getIntlayer('key')` 호출로 대체된 변환된 소스 코드를 반환합니다.
+
+지원되는 파일 형식: `.ts`, `.tsx`, `.js`, `.jsx`, `.vue`, `.svelte`, `.astro`.
+
+### HMR (Hot Module Replacement)
+
+개발 모드에서 컴포넌트 파일이 저장되면 컴파일러는 다음을 수행합니다:
+
+1. Vite의 `handleHotUpdate` 훅을 통해 파일 변경을 감지합니다.
+2. 업데이트된 파일에서 콘텐츠를 다시 추출합니다.
+3. 업데이트된 사전 JSON을 작성합니다.
+4. 페이지 전체 새로고침을 트리거합니다 (`server.ws.send({ type: 'full-reload' })`).
+
+500ms 디바운스(debounce)는 사전 작성 자체(파일 변경 이벤트를 트리거함)가 무한 추출 루프를 유발하는 것을 방지합니다.
+
+### 중복 제거 (Deduplication)
+
+`intlayerCompiler`는 다른 번들 플러그인과 동일한 `createPrimaryInstanceGuard` 중복 제거 메커니즘을 사용합니다. 컴파일러를 내포한 `intlayer()`와 수동 `intlayerCompiler()` 호출이 모두 존재하는 경우, 처음 등록된 인스턴스만 실행되어 사전이 중복으로 생성되지 않습니다.