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

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

@@ -150,10 +150,10 @@ await scan("https://example.com", {
 });
 ```
 
-더 낮은 수준의 액세스를 위해 `@intlayer/chokidar/scan`의 `scanWebsite`는 구조화된 `ScanResult` 객체를 반환합니다:
+더 낮은 수준의 액세스를 위해 `@intlayer/engine/scan`의 `scanWebsite`는 구조화된 `ScanResult` 객체를 반환합니다:
 
 ```ts
-import { scanWebsite } from "@intlayer/chokidar/scan";
+import { scanWebsite } from "@intlayer/engine/scan";
 
 const result = await scanWebsite("https://example.com", { deep: false });
 console.log(result.score, result.totalPageSize, result.events);

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를 자동으로 조정합니다.

package/docs/ko/compat/polyglot.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Polyglot.js에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 Polyglot.js에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - polyglot
+  - airbnb
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - polyglot
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Polyglot.js에서 Intlayer로 마이그레이션
+
+Airbnb의 Polyglot.js를 사용 중이라면 compat layer를 사용하여 Intlayer로의 마이그레이션은 매우 간단합니다.
+
+## 해야 할 일
+
+프로젝트에서 initialization 명령을 실행하세요:
+
+```bash
+npx intlayer init
+```
+
+`intlayer.config.ts`가 생성됩니다. 그런 다음 bundler plugin alias를 사용하여 Polyglot imports를 `@intlayer/polyglot`으로 투명하게 리다이렉트할 수 있습니다.
+
+## 내부적으로 어떻게 작동하는지
+
+Polyglot.js 구문은 일반적으로 `polyglot.t('key', {name})`과 `%{name}` interpolations과 `"singular |||| plural"`로 구분된 `smart_count` plurals에 의존합니다.
+
+내부적으로:
+
+- **Interpolation:** compat layer는 `%{var}` placeholders를 네이티브로 처리합니다.
+- **Plurals:** 문자열은 `||||`에서 분할되어 active locale에 따라 native `Intl.PluralRules`에 대해 평가됩니다. 이는 locale당 Polyglot의 자신의 bucket 순서를 mirror합니다.
+- **Dictionaries:** `new Polyglot()`에 거대한 JSON 설정을 제공할 필요를 없앱니다. Intlayer는 dictionaries를 동적으로 처리하고 자동으로 prune합니다.

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

@@ -0,0 +1,58 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "react-i18next에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 React 애플리케이션을 react-i18next에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - react-i18next
+  - i18next
+  - intlayer
+  - 마이그레이션
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - react-i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# react-i18next에서 Intlayer로 마이그레이션
+
+완전하고 상세한 단계별 튜토리얼은 [react-i18next 마이그레이션 가이드](../migration_from_react-i18next_to_intlayer.md)를 참고하세요.
+
+Intlayer의 compat adapter를 사용하면 소스 코드 import에 변경 없이 `react-i18next`에서 마이그레이션할 수 있습니다.
+
+## 수행할 작업
+
+프로젝트를 초기화하려면 다음을 실행하세요:
+
+```bash
+npx intlayer init
+```
+
+초기화 중에 Intlayer는 `@intlayer/react-i18next`를 설치하고 `intlayer.config.ts`를 생성합니다. bundler(예: Vite)에서 Intlayer plugin을 적용하세요:
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { reactI18nextVitePlugin } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [react(), reactI18nextVitePlugin()],
+});
+```
+
+## 내부 동작 원리
+
+`reactI18nextVitePlugin`은 핵심 `vite-intlayer` plugin을 래핑하고 `react-i18next` 및 `i18next`에 대한 resolve alias를 주입하여 `@intlayer/react-i18next` 및 `@intlayer/i18next`로 리디렉션합니다.
+
+내부적으로:
+
+- **`useTranslation` & `withTranslation`:** Intlayer의 기본 hook을 사용하도록 다시 작성되어 dictionary key에 대한 자동 TypeScript 자동 완성을 제공합니다. namespace(예: `t('namespace:key')`)를 원활하게 지원합니다.
+- **복수형 & Context:** 네이티브 `Intl.PluralRules` 및 context 접미사(`key_male`)를 사용하여 i18next의 접미사 기반 복수화(`key_one`, `key_other`)를 처리합니다.
+- **`<Trans>` Component:** `components` prop, 객체 및 배열 형식, 그리고 번호가 매겨진 태그 `<1>...</1>`를 React 노드에 직접 매핑하도록 지원하도록 다시 구현되었습니다.
+- **`i18n` instance:** 대규모 JSON 파일을 가져오지 않고 Intlayer에서 직접 키를 해결하여 번들 크기를 훨씬 줄입니다.

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

@@ -0,0 +1,55 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "React Intl에서 Intlayer로 마이그레이션"
+description: "compat adapter를 사용하여 React 애플리케이션을 react-intl에서 Intlayer로 마이그레이션하는 방법을 알아보세요."
+keywords:
+  - react-intl
+  - formatjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - react-intl
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# React Intl에서 Intlayer로 마이그레이션
+
+React 애플리케이션이 `react-intl` (FormatJS)를 사용하는 경우 Intlayer로의 전환은 매우 쉽습니다. 우리의 compat layer는 ICU MessageFormat과 기존의 모든 `Formatted*` 컴포넌트를 완벽하게 처리합니다.
+
+## 해야 할 일
+
+프로젝트에서 initialization 명령을 실행하여 시작하세요:
+
+```bash
+npx intlayer init
+```
+
+그런 다음 설정에서 Intlayer Vite 또는 Next.js plugin을 설정하세요. 이 plugin은 `react-intl` imports를 `@intlayer/react-intl`로 리다이렉트할 수 있도록 빌드 타임 aliases를 주입합니다.
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import reactIntlVitePlugin from "@intlayer/react-intl/plugin";
+
+export default defineConfig({
+  plugins: [react(), reactIntlVitePlugin()],
+});
+```
+
+## 내부적으로 어떻게 작동하는지
+
+bundler plugin은 `react-intl`을 `@intlayer/react-intl`로 alias합니다. 큰 JSON 파일을 수동으로 파싱하고 앱을 `IntlProvider`로 감싸는 대신 Intlayer plugin은 빌드 타임에 keys를 정적으로 추출하고 런타임에 Intlayer dictionaries를 사용합니다.
+
+내부적으로:
+
+- **ICU MessageFormat:** Intlayer는 ICU pluralization, selection, date/number formatting, rich text tags를 네이티브로 완벽하게 지원하는 `resolveMessage(..., 'icu')` resolver를 사용합니다.
+- **Method & JSX callers:** `intl.formatMessage({ id: 'a.b' })`와 `<FormattedMessage id="a.b">`는 Intlayer compiler plugins (`@intlayer/babel` / `@intlayer/swc`)로 식별되어 flat dotted keys를 변환하므로 첫 번째 segment가 올바른 Intlayer dictionary key로 resolve됩니다.
+- **Formatters:** `<FormattedNumber>`, `<FormattedDate>` 등은 `Intl`을 사용하는 native `core/formatters`로 연결됩니다.