@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/docs/ko/cli/doc-review.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-11
-updatedAt: 2025-11-22
+updatedAt: 2026-06-17
 title: 문서 검토
 description: 다양한 로케일에서 문서 파일의 품질, 일관성 및 완전성을 검토하는 방법을 알아보세요.
 keywords:
@@ -15,6 +15,10 @@ slugs:
   - concept
   - cli
   - doc-review
+history:
+  - version: 9.0.0
+    date: 2026-06-17
+    changes: "--log 옵션 추가"
 author: aymericzip
 ---
 
@@ -55,8 +59,110 @@ bun x intlayer doc review
 
 ## 인수:
 
-`doc review` 명령어는 `doc translate`와 동일한 인수를 받아 특정 문서 파일을 검토하고 품질 검사를 적용할 수 있습니다.
+**파일 목록 옵션:**
 
-git 옵션 중 하나를 활성화한 경우, 명령어는 변경된 파일 부분만 검토합니다. 스크립트는 파일을 청크 단위로 처리하고 각 청크를 검토합니다. 청크에 변경 사항이 없으면 검토 프로세스를 가속화하고 AI 제공자 API 비용을 제한하기 위해 해당 청크를 건너뜁니다.
+- **`--doc-pattern [docPattern...]`**: 검토할 문서 파일과 일치하는 Glob 패턴입니다.
 
-전체 인수 목록은 [문서 번역](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/doc-translate.md) 명령어 문서를 참조하세요.
+  > 예시: `npx intlayer doc review --doc-pattern "docs/**/*.md" "src/**/*.mdx"`
+
+- **`--excluded-glob-pattern [excludedGlobPattern...]`**: 검토에서 제외할 Glob 패턴입니다.
+
+  > 예시: `npx intlayer doc review --excluded-glob-pattern "docs/internal/**"`
+
+- **`--skip-if-modified-before [skipIfModifiedBefore]`**: 지정된 시간 이전에 수정된 파일은 건너뜁니다.
+  - "2025-12-05"와 같은 절대 시간 (문자열 또는 Date)일 수 있습니다.
+  - `1 * 60 * 60 * 1000` (1시간)과 같은 상대 시간(ms)일 수 있습니다.
+  - 이 옵션은 `fs.stat` 메서드를 사용하여 파일의 수정 시간을 확인합니다. 따라서 Git이나 파일을 수정하는 다른 도구의 영향을 받을 수 있습니다.
+
+  > 예시: `npx intlayer doc review --skip-if-modified-before "2025-12-05"`
+
+- **`--skip-if-modified-after [skipIfModifiedAfter]`**: 지정된 시간 이내에 수정된 파일은 건너뜁니다.
+  - "2025-12-05"와 같은 절대 시간(문자열 또는 Date)일 수 있습니다.
+  - `1 * 60 * 60 * 1000` (1시간)과 같은 상대 시간(ms)일 수 있습니다.
+  - 이 옵션은 `fs.stat` 메서드를 사용하여 파일의 수정 시간을 확인합니다. 따라서 Git이나 파일을 수정하는 다른 도구의 영향을 받을 수 있습니다.
+
+  > 예시: `npx intlayer doc review --skip-if-modified-after "2025-12-05"`
+
+- **`--skip-if-exists`**: 파일이 이미 존재하면 건너뜁니다.
+
+  > 예시: `npx intlayer doc review --skip-if-exists`
+
+**검토 모드 옵션:**
+
+- **`--log`**: 로그 전용 모드. AI로 번역하지 않고, 대신 다른 에이전트가 번역을 생성할 수 있도록 기본 및 대상 로케일에 대해 주의가 필요한 블록(줄 번호 및 내용 포함)을 기록합니다.
+
+  > 예시: `npx intlayer doc review --log`
+
+**출력 옵션:**
+
+- **`--locales [locales...]`**: 문서를 검토할 대상 로케일입니다.
+
+  > 예시: `npx intlayer doc review --locales fr es de`
+
+- **`--base-locale [baseLocale]`**: 비교할 원본 로케일(기본 문서)입니다.
+
+  > 예시: `npx intlayer doc review --base-locale en`
+
+**파일 처리 옵션:**
+
+- **`--nb-simultaneous-file-processed [nbSimultaneousFileProcessed]`**: 동시에 검토할 파일 수입니다.
+
+  > 예시: `npx intlayer doc review --nb-simultaneous-file-processed 5`
+
+**AI 옵션:**
+
+- **`--model [model]`**: 검토에 사용할 AI 모델 (예: `gpt-3.5-turbo`).
+- **`--provider [provider]`**: 검토에 사용할 AI 제공자.
+- **`--temperature [temperature]`**: AI 모델의 온도 설정.
+- **`--api-key [apiKey]`**: AI 서비스에 사용할 API 키를 제공합니다.
+- **`--application-context [applicationContext]`**: AI 검토에 추가 컨텍스트를 제공합니다.
+- **`--data-serialization [dataSerialization]`**: Intlayer의 AI 기능에 사용할 데이터 직렬화 형식. 옵션: `json` (표준, 신뢰할 수 있음), `toon` (토큰 적음, 일관성 낮음).
+- **`--custom-prompt [prompt]`**: 검토에 사용되는 기본 프롬프트를 사용자 정의합니다. (참고: 대부분의 사용 사례에서는 동작을 더 잘 제어할 수 있는 `--custom-instructions` 옵션을 사용하는 것이 권장됩니다.)
+
+  > 예시: `npx intlayer doc review --model deepseek-chat --provider deepseek --temperature 0.5 --api-key sk-1234567890 --application-context "My application is a cat store"`
+
+**환경 변수 옵션:**
+
+- **`--env`**: 환경을 지정합니다 (예: `development`, `production`).
+- **`--env-file [envFile]`**: 변수를 로드할 사용자 정의 환경 파일을 제공합니다.
+- **`--base-dir`**: 프로젝트의 기본 디렉토리를 지정합니다.
+- **`--no-cache`**: 캐시를 비활성화합니다.
+
+  > 예시: `npx intlayer doc review --base-dir ./docs --env-file .env.production.local`
+
+**로그 옵션:**
+
+- **`--verbose`**: 디버깅을 위한 상세 로그 활성화. (CLI에서 기본값은 true)
+
+  > 예시: `npx intlayer doc review --verbose`
+
+**사용자 지정 지침 옵션:**
+
+- **`--custom-instructions [customInstructions]`**: 프롬프트에 추가되는 사용자 지정 지침. 포맷팅, URL 번역 등 특정 규칙을 적용할 때 유용합니다.
+
+  > 예시: `npx intlayer doc review --custom-instructions "URL 번역을 피하고, 마크다운 형식을 유지하세요"`
+
+  > 예시: `npx intlayer doc review --custom-instructions "$(cat ./instructions.md)"`
+
+**Git 옵션:**
+
+- **`--git-diff`**: 기준(기본값 `origin/main`)에서 현재 브랜치(기본값 `HEAD`)로 변경된 파일만 실행합니다.
+- **`--git-diff-base`**: git diff의 기준 참조를 지정합니다 (기본값 `origin/main`).
+- **`--git-diff-current`**: git diff의 현재 참조를 지정합니다 (기본값 `HEAD`).
+- **`--uncommitted`**: 커밋되지 않은 변경사항을 포함합니다.
+- **`--unpushed`**: 푸시되지 않은 변경사항을 포함합니다.
+- **`--untracked`**: 추적되지 않은 파일을 포함합니다.
+
+  > 예시: `npx intlayer doc review --git-diff --git-diff-base origin/main --git-diff-current HEAD`
+
+  > 예시: `npx intlayer doc review --uncommitted --unpushed --untracked`
+
+> 출력 파일 경로는 다음 패턴을 대체하여 결정됩니다:
+>
+> - `/{{baseLocale}}/` 는 `/{{locale}}/` 로 대체 (Unix)
+> - `\{{baseLocale}}\` 는 `\{{locale}}\` 로 대체 (Windows)
+> - `_{{baseLocale}}.` 는 `_{{locale}}.` 로 대체
+> - `{{baseLocale}}_` 는 `{{locale}}_` 로 대체
+> - `.{{baseLocaleName}}.` 는 `.{{localeName}}.` 로 대체
+>
+> 만약 패턴이 발견되지 않으면, 출력 파일은 파일 확장자에 `.{{locale}}` 를 추가합니다. 예를 들어 `./my/file.md` 는 검토되고, 프랑스어 로케일의 경우 `./my/file.fr.md` 로 업데이트됩니다.

package/docs/ko/cli/fill.md

@@ -47,6 +47,14 @@ bun x intlayer fill
 - 기존 번역을 덮어쓰지 않아 기존 번역을 보존합니다.
 - 큐 시스템을 사용하여 파일, 청크 및 로케일을 병렬로 처리하여 속도를 높입니다.
 
+## 주요 포인트:
+
+- 대규모 JSON 파일을 청크로 분할하여 AI 모델의 컨텍스트 윈도우 제한 내에 유지합니다.
+- 출력 형식이 올바르지 않으면 번역을 다시 시도합니다.
+- 번역 정확도 향상을 위해 애플리케이션 및 파일별 컨텍스트를 통합합니다.
+- 기존 번역을 덮어쓰지 않음으로써 보존합니다.
+- 큐 시스템을 사용하여 파일, 청크 및 로케일을 병렬로 처리하여 속도를 높입니다.
+
 ## 별칭:
 
 - `npx intlayer dictionaries fill`

package/docs/ko/cli/index.md

@@ -17,7 +17,7 @@ slugs:
   - concept
   - cli
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-11
     changes: "scan 명령어 추가"
   - version: 8.6.4

package/docs/ko/cli/login.md

@@ -78,42 +78,6 @@ bun x intlayer login --cms-url https://intlayer.org
 
 ### 구성 옵션
 
-일반적인 구성 옵션도 사용할 수 있습니다:
-
-- `--env-file <path>`: 환경 파일의 경로
-- `-e, --env <env>`: 실행 환경
-- `--base-dir <dir>`: 프로젝트의 기본 디렉터리
-- `--verbose`: 자세한 출력 활성화 (기본값: true)
-- `--prefix <prefix>`: 로그 접두사
-
-## 동작 방식
-
-1. **로컬 서버 시작**: 명령은 CMS로부터 자격증명을 수신하기 위해 무작위 포트에서 로컬 HTTP 서버를 시작합니다
-
-인증을 위해 연결할 Intlayer CMS의 URL을 지정합니다.
-
-- **형식**: `string`
-- **기본값**: `intlayer.config.*`에 구성된 값 또는 `https://intlayer.org`
-- **예제**:
-
-```bash packageManager="npm"
-npx intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="yarn"
-yarn intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="bun"
-bun x intlayer login --cms-url https://intlayer.org
-```
-
-### 구성 옵션
-
 다음과 같은 공통 구성 옵션도 사용할 수 있습니다:
 
 - `--env-file <path>`: 환경 파일의 경로

package/docs/ko/cli/scan.md

@@ -18,7 +18,7 @@ slugs:
   - cli
   - scan
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-11
     changes: "scan 명령어 추가"
 author: aymericzip

package/docs/ko/compat/i18n-js.md

@@ -0,0 +1,44 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "i18n-js에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 애플리케이션을 i18n-js에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - i18n-js
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - i18n-js
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# i18n-js에서 Intlayer로 마이그레이션
+
+`i18n-js` 라이브러리에서 Intlayer로 전환하는 것은 큰 translations 설정을 Intlayer의 구조화된 파일 resolution 시스템으로 offload하도록 설계된 고도로 최적화된 마이그레이션입니다.
+
+## 해야 할 일
+
+리포지토리에서 다음 설정 명령을 실행하세요:
+
+```bash
+npx intlayer init
+```
+
+`intlayer.config.ts`가 준비되면 bundler 설정에 Intlayer alias를 추가하여 `i18n-js`의 모든 imports가 compat package `@intlayer/i18n-js`를 대상으로 하도록 할 수 있습니다.
+
+## 내부적으로 어떻게 작동하는지
+
+`i18n-js`는 `i18n.t('scope.key', {name})`과 같은 표현식을 통해 namespaces에 접근하며, locale fallbacks와 특정 plural mappings과 함께 합니다.
+
+내부적으로:
+
+- **Interpolation:** compat adapter는 `%{name}` mappings을 targeted runtime dictionary value로 쉽게 파싱합니다.
+- **Pluralization:** `one/other` subkeys를 교체하고 Intlayer의 강력한 underlying plural mechanisms (`Intl.PluralRules`)에 대해 매핑하여 수동 mappings을 추상화합니다.
+- **Locales:** bootstrap 시점에 monolithic language payloads를 로드하는 대신 dictionaries는 native Intlayer 설정을 통해 현재 context 설정에 따라 최적으로 제공됩니다.

package/docs/ko/compat/i18next.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "i18next에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 Vanilla JS/TS 애플리케이션을 i18next에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - i18next
+  - vanilla
+  - javascript
+  - typescript
+  - intlayer
+  - 마이그레이션
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# i18next에서 Intlayer로 마이그레이션
+
+상세한 단계별 튜토리얼은 [i18next 마이그레이션 가이드](../migration_from_i18next_to_intlayer.md)를 참고하세요.
+
+Intlayer는 `i18next`의 핵심 런타임 특성을 완벽하게 복제합니다. compat package를 활용하면 Vanilla 애플리케이션이나 내부 모듈에서 익숙한 구문을 계속 사용할 수 있습니다.
+
+## 수행할 작업
+
+먼저 프로젝트에서 Intlayer를 초기화하세요:
+
+```bash
+npx intlayer init
+```
+
+Vite를 사용 중인 경우 Intlayer plugin을 포함하여 import를 `@intlayer/i18next`로 라우팅하세요:
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { i18nextVitePlugin } from "@intlayer/i18next/plugin";
+
+export default defineConfig({
+  plugins: [i18nextVitePlugin()],
+});
+```
+
+## 내부 동작 원리
+
+`i18nextVitePlugin`은 `i18next` import를 `@intlayer/i18next`로 별칭 지정하여 JSON 파일 포함으로 인한 bundle 팽창을 방지합니다.
+
+내부적으로:
+
+- **Instance 구성:** `createInstance`는 namespace fallback을 올바르게 파싱하고 적용하며 dictionary 검색을 위해 Intlayer의 컴파일 파이프라인을 활용합니다.
+- **Interpolation:** `{{name}}` 대체 및 `$t(key)` nesting 재귀에 대한 기본 지원.
+- **Context & Plurals:** `key_male` 및 `key_one`/`key_other` 같은 접미사 형식을 식별하고 해결하며 표준 `Intl.PluralRules`에 대해 평가합니다.
+- **Return objects:** `returnObjects: true` 모드는 Intlayer dictionary에서 트리를 안전하게 추출합니다.

package/docs/ko/compat/index.md

@@ -0,0 +1,51 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Intlayer Compat Adapters"
+description: "compat adapter를 사용하여 기존 i18n 솔루션을 Intlayer로 마이그레이션하세요."
+keywords:
+  - compat
+  - 마이그레이션
+  - 국제화
+  - i18n
+  - Intlayer
+slugs:
+  - doc
+  - compatibility
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Intlayer Compat Adapters
+
+대규모 애플리케이션을 새로운 국제화 라이브러리로 마이그레이션하는 것은 어려울 수 있습니다. 이 전환을 쉽게 하기 위해 Intlayer는 에코시스템에서 가장 인기 있는 i18n 라이브러리를 위한 **compat adapter**를 제공합니다.
+
+이 adapter package들은 기존 i18n 라이브러리와 **동일한 공개 API**를 노출하지만, 런타임에 모든 번역 작업을 Intlayer에 위임합니다.
+
+## 작동 방식
+
+compat adapter를 사용할 때, 애플리케이션의 import를 다시 작성하거나 번역 hook 및 component 사용 방법을 변경할 필요가 없습니다. 대신 Intlayer의 bundler plugin이 기존 import를 자동으로 Intlayer compat package로 별칭 지정합니다.
+
+예를 들어, 개발자가 `import { useTranslation } from 'react-i18next'`를 `import { useTranslation } from '@intlayer/react-i18next'`로 대체하면(bundler plugin을 통해 자동으로 수행됨), 앱은 Intlayer 사전에서 제공되는 번역과 함께 계속 작동합니다. 키도 Intlayer 사전에 대해 타입이 지정됩니다!
+
+## 사용 가능한 Compat Adapters
+
+아래에서 기존 라이브러리를 선택하여 원활하게 마이그레이션하는 방법을 확인하세요:
+
+- [Vue I18n](./vue-i18n.md)
+- [Transloco](./transloco.md)
+- [React Intl](./react-intl.md)
+- [Svelte I18n](./svelte-i18n.md)
+- [React i18next](./react-i18next.md)
+- [Polyglot.js](./polyglot.md)
+- [NuxtJS I18n](./nuxtjs-i18n.md)
+- [NGX Translate](./ngx-translate.md)
+- [Next Translate](./next-translate.md)
+- [Next Intl](./next-intl.md)
+- [Next i18next](./next-i18next.md)
+- [i18next](./i18next.md)
+- [Lingui](./lingui.md)
+- [I18n-js](./i18n-js.md)

package/docs/ko/compat/lingui.md

@@ -0,0 +1,44 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Lingui에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 애플리케이션을 Lingui에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - lingui
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - lingui
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Lingui에서 Intlayer로 마이그레이션
+
+프로젝트가 현재 Lingui의 macro 기반 컴파일에 의존하고 있다면 Intlayer로 전환하면 강력한 macro workflows를 유지하면서 네이티브로 Intlayer의 JSON compilation strategy를 지원할 수 있습니다.
+
+## 해야 할 일
+
+프로젝트에서 Intlayer를 초기화하여 시작하세요:
+
+```bash
+npx intlayer init
+```
+
+`intlayer.config.ts`가 생성됩니다. build step에서 `@lingui/babel-plugin-lingui-macro` / `@lingui/swc-plugin`을 유지하여 Intlayer compiler _이전에_ 실행되도록 하세요. 그런 다음 bundler plugin alias를 사용하여 `@lingui/core`과 `@lingui/react`을 `@intlayer/lingui`로 라우팅하세요.
+
+## 내부적으로 어떻게 작동하는지
+
+Lingui는 macros (`` t`Hello ${name}` ``과 `<Trans>` 같은)를 사용하며, 이는 `i18n._(id, values)` 같은 runtime 호출로 컴파일됩니다.
+
+내부적으로:
+
+- **Macros:** 이전과 정확히 동일하게 컴파일되어 소스 구문에 중단이 없음을 보장합니다.
+- **Runtime translation:** aliased `i18n._()`은 Intlayer dictionaries를 사용합니다. 명시적으로 이름이 지정된 IDs와 hashed IDs 모두 Intlayer의 `.po` sync plugins을 사용하여 완전히 매핑되며 keys를 안전하게 aggregate하고 prune합니다.
+- **ICU capabilities:** pluralization, selection, ICU variants에 대한 지원은 Intlayer의 unified ICU parser 덕분에 강력하게 유지되어 동일한 렌더링 출력을 보장합니다.

package/docs/ko/compat/next-i18next.md

@@ -0,0 +1,55 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "next-i18next에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 Next.js 애플리케이션을 next-i18next에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - next-i18next
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# next-i18next에서 Intlayer로 마이그레이션
+
+Intlayer는 모든 Next.js Pages Router 및 App Router 구현을 투명하게 처리합니다. adapter를 사용하면 코드를 전혀 다시 작성하지 않고 `next-i18next` 구현을 마이그레이션할 수 있습니다.
+
+## 해야 할 일
+
+시작하려면 다음을 실행하세요:
+
+```bash
+npx intlayer init
+```
+
+필요한 Intlayer 설정 파일을 만듭니다. 백그라운드에서 Intlayer로 변경하려면 `next.config.ts`를 업데이트하세요:
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+
+const withIntlayer = createNextI18nPlugin();
+
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+## 내부적으로 어떻게 작동하는지
+
+`createNextI18nPlugin`은 Next.js의 네이티브 동작과 core `next-intlayer` plugin을 구성하여 `next-i18next`, `react-i18next`, `i18next`에 대한 모든 필요한 Webpack/Turbopack aliases를 주입합니다.
+
+내부적으로:
+
+- **`serverSideTranslations` & `appWithTranslation`:** 이제 Intlayer의 내부 loaders를 위한 wrapper 함수로 작동하여 대규모 정적 JSON injection을 우회합니다.
+- **Client hooks:** 즉시 `@intlayer/react-i18next`로 위임하여 모든 formatting, plurals, nested namespace 기능을 유지합니다.

package/docs/ko/compat/next-intl.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "next-intl에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 Next.js 애플리케이션을 next-intl에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - next-intl
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-intl
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# next-intl에서 Intlayer로 마이그레이션
+
+완전하고 상세한 단계별 튜토리얼을 보려면 전체 [next-intl 마이그레이션 가이드](../migration_from_next-intl_to_intlayer.md)를 참조하세요.
+
+`next-intl`에서 Intlayer로 마이그레이션하면 애플리케이션의 라우팅과 구문을 완전히 유지할 수 있습니다.
+
+## 해야 할 일
+
+리포지토리에서 다음 명령을 실행하세요:
+
+```bash
+npx intlayer init
+```
+
+이렇게 하면 `intlayer.config.ts`가 생성됩니다. `next.config.ts`에서 plugin wrapper를 사용하여 `next-intl` aliases를 `@intlayer/next-intl`로 완벽하게 주입합니다.
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
+
+const withIntlayer = createNextIntlPlugin();
+
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+## 내부적으로 어떻게 작동하는지
+
+bundler wrapper는 번역을 교체하지만 **`next-intl/navigation` 기능은 그대로 유지합니다** (예: `Link`, `redirect`, `usePathname`).
+
+내부적으로:
+
+- **ICU runtime:** Plurals (`=0`, `one`, `other`), select/selectordinal, `#` arguments, formatted args (`{ts, date, long}`)는 공유 `resolveMessage(..., 'icu')` resolver를 사용하여 올바르게 실행됩니다.
+- **`useTranslations()` & `getTranslations()`:** bare scope 호출은 첫 번째 key segment를 올바른 dictionary identifier로 추출합니다. Nested namespaces는 dictionary paths와 prefixes로 우아하게 분할됩니다.
+- **Rich formatting:** `t.rich()`와 `t.markup()` 모두 완전히 네이티브로 구현되어 HTML 같은 노드를 렌더링된 React chunks로 변환합니다.
+- **`useFormatter`:** `relativeTime`, `list`, `dateTimeRange`, 설정의 named formats는 core native `Intl` formatters로 연결됩니다.

package/docs/ko/compat/next-translate.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Next Translate에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 Next.js 애플리케이션을 next-translate에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - next-translate
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-translate
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Next Translate에서 Intlayer로 마이그레이션
+
+`next-translate`에서 Intlayer로의 마이그레이션은 기존 구문과 tags를 유지하는 거의 drop-in 대체입니다.
+
+## 해야 할 일
+
+프로젝트에서 Intlayer를 초기화하세요:
+
+```bash
+npx intlayer init
+```
+
+CLI는 설정을 scaffold합니다. 그런 다음 Intlayer plugin을 `next.config.ts`에 적용할 수 있으며, 이는 `next-translate/useTranslation`을 `@intlayer/next-translate`로 매핑하는 build-time subpath aliases를 주입합니다.
+
+## 내부적으로 어떻게 작동하는지
+
+`next-translate`는 `useTranslation('ns')`, `t('ns:key.path')`, `<Trans>` 컴포넌트 같은 hooks를 제공합니다.
+
+내부적으로:
+
+- **Interpolation & Plurals:** `react-i18next` adapter 동작에 매우 유사합니다. 동적으로 처리되는 것은 `{{var}}` placeholders와 `key_0`, `key_one`, `key_other` 같은 suffixes로부터 매핑된 pluralization입니다.
+- **`<Trans>` component:** HTML 같은 tag parsing과 array 기반 `components` prop과 함께 직접 지원됩니다.
+- **Namespaces:** Subpath aliasing은 수동 수정 없이 `useTranslation` 참조가 올바른 내부 dictionary namespaces를 참조하도록 보장합니다.

package/docs/ko/compat/ngx-translate.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "NGX-Translate에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 Angular 애플리케이션을 ngx-translate에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - ngx-translate
+  - angular
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - ngx-translate
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# NGX-Translate에서 Intlayer로 마이그레이션
+
+compat adapter를 사용하면 Angular 애플리케이션을 `ngx-translate`에서 Intlayer로 쉽게 마이그레이션할 수 있으며 모든 template을 다시 작성할 필요가 없습니다.
+
+## 해야 할 일
+
+다음을 실행하여 시작하세요:
+
+```bash
+npx intlayer init
+```
+
+`intlayer.config.ts`를 설정합니다. `TranslateModule.forRoot()` setups를 바꾸고 import aliases를 적절하게 업데이트하여 `@intlayer/ngx-translate`를 가리키도록 합니다.
+
+## 내부적으로 어떻게 작동하는지
+
+`ngx-translate`는 `TranslateService` (`instant`, `get`, `stream`)와 `{{ 'KEY' | translate:params }}` pipe, `[translate]` directive를 사용합니다.
+
+내부적으로:
+
+- **Services:** `TranslateService`는 `getIntlayer`와 locale observable을 래핑하여 정확히 동일한 methods를 제공합니다.
+- **Pipes & Directives:** Intlayer dictionaries에 대해 직접 resolve되도록 다시 구현됩니다.
+- **Loaders:** `TranslateHttpLoader` setups은 warning stubs로 변환됩니다. 왜냐하면 Intlayer는 본래적으로 build time에 dictionaries를 resolve하고 bundle합니다 (또는 표준 dynamic imports를 통해), HTTP loaders의 필요성을 완전히 제거합니다.

package/docs/ko/compat/nuxtjs-i18n.md

@@ -0,0 +1,46 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "NuxtJS I18n에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 Nuxt.js 애플리케이션을 @nuxtjs/i18n에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - nuxtjs-i18n
+  - nuxt
+  - vue
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - nuxtjs-i18n
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# NuxtJS I18n에서 Intlayer로 마이그레이션
+
+Nuxt 애플리케이션을 `@nuxtjs/i18n`에서 Intlayer로 마이그레이션하는 것은 Nuxt adapter module을 사용하여 매끄러운 프로세스입니다.
+
+## 해야 할 일
+
+프로젝트를 초기화하려면 다음을 실행하세요:
+
+```bash
+npx intlayer init
+```
+
+이렇게 하면 `intlayer.config.ts`가 설정됩니다. 그런 다음 `nuxt.config.ts` modules 배열에 Intlayer Nuxt module (예: `@intlayer/nuxt-i18n`)을 추가하세요. 이것은 애플리케이션에 compat 설정을 자동으로 적용합니다.
+
+## 내부적으로 어떻게 작동하는지
+
+`@nuxtjs/i18n`은 `vue-i18n`을 래핑하면서 Nuxt 특화 routing composables (`useLocalePath`, `useSwitchLocalePath`, `<NuxtLinkLocale>`)를 제공합니다.
+
+내부적으로:
+
+- **Translations:** 모든 문자열 translation 작업에 대해 네이티브로 `@intlayer/vue-i18n` compat layer를 사용합니다 (완벽하게 `vue-i18n` formats, pipe plurals, reactivity를 지원합니다).
+- **Routing:** Intlayer의 localized URL helpers를 사용하여 routing composables를 mirror합니다.
+- **Configuration:** `intlayer.config.ts`에서 `availableLocales`과 기본 설정을 직접 읽어 Nuxt pages를 자동으로 조정합니다.