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

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

@@ -0,0 +1,172 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: intlayerProxy Vite 플러그인 문서 | vite-intlayer
+description: Vite dev/preview 서버 및 프로덕션 SSR용 언어 라우팅 미들웨어입니다. 언어 감지, URL 리다이렉트 및 내부 재작성을 처리합니다.
+keywords:
+  - intlayerProxy
+  - vite
+  - 플러그인
+  - 미들웨어
+  - 언어
+  - 라우팅
+  - 국제화
+  - i18n
+  - SSR
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerProxy
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "configOptions가 단일 options 객체로 병합됨; proxy가 intlayer()에 번들로 포함됨"
+author: aymericzip
+---
+
+# intlayerProxy
+
+`intlayerProxy`는 개발 서버, 미리보기 서버 및 프로덕션 SSR (Nitro / TanStack Start) 등 **모든 환경**에 대한 언어 라우팅 미들웨어를 등록하는 Vite 플러그인입니다.
+
+> **Intlayer v9부터** `intlayerProxy`는 기본 [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/vite-intlayer/intlayer.md) 플러그인 내에 자동으로 포함되며 `routing.enableProxy: true`를 통해 기본적으로 활성화됩니다. 더 정밀한 제어가 필요하거나 표준 `intlayer()` 구성 이외의 영역에서 사용하는 경우에만 이를 별도로 등록해야 합니다.
+
+## 사용법
+
+### `intlayer()`의 일부로 사용 (권장, v9+)
+
+`intlayerProxy`를 별도로 등록하는 대신 기본 플러그인에 `proxy` 옵션을 전달합니다:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
+});
+```
+
+### 독립 실행형(Standalone)으로 사용 (필요 시)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+## 옵션
+
+```ts
+import type { IntlayerProxyPluginOptions } from "vite-intlayer";
+```
+
+모든 옵션은 선택 사항이며 단일 객체로 전달됩니다:
+
+| 옵션            | 타입                                | 설명                                                                                                                                |
+| --------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `ignore`        | `(req: IncomingMessage) => boolean` | 특정 요청을 언어 라우팅에서 제외하는 서술 함수(predicate)입니다. 요청을 무시하려면 `true`를 반환합니다 (예: API 라우트, 헬스 체크). |
+| `configOptions` | `GetConfigurationOptions`           | `getConfiguration()`으로 전달되는 Intlayer 설정 재정의 옵션. 프록시가 특정 설정 파일을 읽거나 값을 덮어써야 할 때 사용합니다.       |
+
+### 예시
+
+```ts
+intlayerProxy({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+```
+
+## createIntlayerProxyHandler
+
+`createIntlayerProxyHandler`는 모든 언어 라우팅 로직을 포함하는 특정 프레임워크에 종속되지 않는 Node.js `(req, res, next)` 미들웨어를 생성합니다. Vite 플러그인 API를 사용할 수 없는 환경(예: 순수 Node.js 서버 또는 사용자 정의 Nitro 모듈)에서 유용합니다.
+
+```ts
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+const handler = createIntlayerProxyHandler({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+
+// Express / Connect
+app.use(handler);
+```
+
+### 프로덕션 SSR (TanStack Start / h3를 통한 Nitro)
+
+```ts
+// server/middleware/intlayerProxy.ts
+import { fromNodeMiddleware } from "h3";
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+export default fromNodeMiddleware(
+  createIntlayerProxyHandler({
+    ignore: (req) => req.url?.startsWith("/api"),
+  })
+);
+```
+
+## 라우팅 동작
+
+미들웨어는 `next-intlayer` 미들웨어의 라우팅 로직을 모방하며 모든 Intlayer 라우팅 모드를 지원합니다.
+
+### 라우팅 모드
+
+| 모드            | 브라우저 표시 URL        | 동작                                                                                                                             |
+| --------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| `prefix`        | `/ko/about`              | 기본값. URL의 언어 접두사. `prefix-all`이 활성화되어 있지 않으면 기본 언어는 접두사가 없는 URL로 리다이렉트됩니다.               |
+| `prefix-all`    | `/en/about`, `/ko/about` | 기본 언어를 포함한 모든 언어가 항상 접두사를 갖습니다.                                                                           |
+| `no-prefix`     | `/about`                 | URL에 언어가 포함되지 않습니다. 언어는 쿠키에만 저장되며 URL 재작성은 내부적으로 발생합니다.                                     |
+| `search-params` | `/about?locale=ko`       | 쿼리 파라미터로 언어를 전달합니다. 파라미터가 누락되었거나 오래된 경우 `locale` 파라미터를 추가/업데이트하도록 리다이렉트합니다. |
+
+### 감지 우선순위
+
+1. URL 경로 접두사 (예: `/ko/about` → `ko`).
+2. 쿠키 / localStorage 값 (`intlayer-locale`).
+3. `Accept-Language` 헤더.
+4. 설정 파일의 `defaultLocale`.
+
+### 자동 무시 (Bypass)
+
+미들웨어는 언어 처리 없이 다음 요청들을 항상 통과시킵니다:
+
+- `ignore` 조건과 일치하는 요청.
+- `/node_modules/**`
+- `/@**` – Vite 내부 리소스 (`@vite/`, `@fs/`, `@id/` 등).
+- `/_**` – 서버 내부 리소스 (`__vite_ping`, `__manifest` 등).
+- 파일 확장자로 끝나는 경로의 요청 (정적 에셋). 정적 에셋 경로에 언어 접두사(예: `/ko/logo.png`)가 있는 경우, 파일이 제대로 서빙될 수 있도록 접두사를 제거합니다.
+
+### 도메인 라우팅
+
+Intlayer 설정에 `routing.domains`가 구성된 경우, 미들웨어는 도메인 간의 언어 라우팅을 처리합니다:
+
+- `domains.zh = "intlayer.zh"`일 때, `intlayer.org`상의 `/zh/about` 요청은 `https://intlayer.zh/about`으로 리다이렉트됩니다.
+- `intlayer.zh/about` 요청은 `[locale]` 라우트 파라미터가 채워지도록 내부적으로 `/zh/about`으로 재작성됩니다.
+
+### 리다이렉트 루프 보호
+
+미들웨어는 2초 이동 창(sliding window) 내에서 `originalUrl → newUrl` 쌍당 리다이렉트 횟수를 추적합니다. 해당 창 내에서 10회를 초과하는 리다이렉트가 감지되면 무한 루프를 방지하기 위해 에러 설명과 함께 `500` 응답을 반환합니다.
+
+## Nitro / 프로덕션 SSR (자동 주입, v9+)
+
+`intlayerProxy`가 Vite 플러그인으로 사용될 때 `.nitro` 속성을 갖습니다. `nitro/vite` 빌드 플러그인은 이 속성을 읽어 `nitroConfig.modules`로 푸시하므로 `intlayerNitroHandler`가 Nitro 서버 미들웨어로 자동 등록됩니다. 프로덕션 SSR을 위해 수동으로 구성을 설정할 필요가 없습니다.
+
+Nitro 핸들러는 h3 v2의 Web Fetch API 이벤트 모델( `fromNodeMiddleware`이 아님)을 사용하므로 Node, Bun, Deno, edge 런타임 등 모든 Nitro 프리셋과 호환됩니다.
+
+## 사용되지 않는 별칭 (Deprecated)
+
+| 사용되지 않는 내보내기     | 대체품          |
+| -------------------------- | --------------- |
+| `intlayerMiddleware`       | `intlayerProxy` |
+| `intLayerMiddlewarePlugin` | `intlayerProxy` |

package/docs/ko/packages/vue-intlayer/exports.md

@@ -14,6 +14,9 @@ slugs:
   - vue-intlayer
   - exports
 history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "usePathname 유틸리티 추가"
   - version: 8.0.0
     date: 2026-01-21
     changes: "모든 내보내기(exports)에 대한 문서 통합"
@@ -59,6 +62,7 @@ import "vue-intlayer";
 | `useDictionaryAsync`   | `useDictionary`와 동일하지만 비동기 dictionary를 처리합니다.                                                                          | -                                                                                                                     |
 | `useDictionaryDynamic` | `useDictionary`와 동일하지만 동적 dictionary를 처리합니다.                                                                            | -                                                                                                                     |
 | `useLocale`            | 현재 locale과 이를 설정하는 함수를 반환합니다.                                                                                        | -                                                                                                                     |
+| `usePathname`          | 로케일 세그먼트가 제거된 현재 경로명(pathname)을 `ComputedRef<string>`으로 반환합니다. `popstate` 이벤트에 반응합니다.                | [usePathname](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/vue-intlayer/usePathname.md)     |
 | `useRewriteURL`        | 클라이언트 측에서 URL 재작성(rewrite)을 관리하는 composable입니다. 로컬라이즈된 재작성 규칙이 존재하면 자동으로 URL을 업데이트합니다. | [useRewriteURL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/vue-intlayer/useRewriteURL.md) |
 | `useIntl`              | 현재 로케일에 대한 Intl 객체를 반환합니다.                                                                                            | -                                                                                                                     |
 | `useLoadDynamic`       | 동적 딕셔너리를 로드하는 composable입니다.                                                                                            | -                                                                                                                     |

package/docs/ko/packages/vue-intlayer/usePathname.md

@@ -0,0 +1,109 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: usePathname 함수 문서 | vue-intlayer
+description: vue-intlayer 패키지의 usePathname 함수 사용 방법 알아보기
+keywords:
+  - usePathname
+  - pathname
+  - locale
+  - Intlayer
+  - 국제화 (Internationalization)
+  - 문서
+  - Vue
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - vue-intlayer
+  - usePathname
+history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "usePathname 유틸리티 추가"
+  - version: 8.2.0
+    date: 2026-06-22
+    changes: "초기 기록 작성"
+author: aymericzip
+---
+
+# Vue 통합: `usePathname` 문서
+
+`usePathname` 함수는 로케일 세그먼트가 제거된 현재 브라우저의 경로명(pathname)을 Vue의 `ComputedRef<string>` 형태로 반환합니다. 이는 로케일 접두사를 수동으로 제거할 필요 없이, 로케일을 인식하는 내비게이션(예: 현재 활성화된 내비게이션 항목 결정)을 구축할 때 유용합니다.
+
+## Vue에서 `usePathname` 가져오기
+
+```typescript
+import { usePathname } from "vue-intlayer";
+```
+
+## 개요
+
+`usePathname`은 `window.location.pathname`을 읽고, `getPathWithoutLocale`을 통해 로케일 접두사를 제거하며, 브라우저에서 `popstate` 이벤트(뒤로/앞으로 가기 내비게이션)가 발생할 때마다 해당 값을 업데이트하는 Vue 계산된 참조(computed ref)를 생성합니다. 이 값은 Vue 템플릿이나 `setup` 함수에서 직접 사용할 수 있습니다.
+
+## 사용법
+
+```vue fileName="src/components/NavItem.vue"
+<script setup lang="ts">
+import { usePathname } from "vue-intlayer";
+
+const props = defineProps<{
+  href: string;
+  label: string;
+}>();
+
+const pathname = usePathname();
+</script>
+
+<template>
+  <a :href="href" :aria-current="pathname === href ? 'page' : undefined">
+    {{ label }}
+  </a>
+</template>
+```
+
+## 반환 값
+
+| 타입                  | 설명                                                                                   |
+| --------------------- | -------------------------------------------------------------------------------------- |
+| `ComputedRef<string>` | 로케일 접두사가 없는 현재 브라우저의 경로명(pathname)이 포함된 Vue Computed Ref입니다. |
+
+## 동작 방식
+
+- **로케일 제거(Locale stripping)**: 앞의 로케일 세그먼트를 제거합니다(예: `/ko/dashboard` → `/dashboard`).
+- **반응성(Reactive)**: 모든 `popstate` 이벤트(브라우저 뒤로 가기 / 앞으로 가기) 발생 시 값을 업데이트합니다.
+- **SSR 안전성(SSR-safe)**: `window` 객체를 사용할 수 없는 경우 `""`를 반환합니다.
+- **정리(Cleanup)**: `popstate` 리스너는 초기화 시 전역적으로 추가되며, Vue가 컴포넌트 생명주기를 관리하는 방식 덕분에 일반적으로 각 컴포넌트별로 수동 정리를 할 필요가 없습니다.
+
+## 예시
+
+```vue fileName="src/components/Sidebar.vue"
+<script setup lang="ts">
+import { usePathname } from "vue-intlayer";
+
+const links = [
+  { href: "/dashboard", label: "대시보드" },
+  { href: "/settings", label: "설정" },
+];
+
+const pathname = usePathname();
+</script>
+
+<template>
+  <nav>
+    <a
+      v-for="link in links"
+      :key="link.href"
+      :href="link.href"
+      :style="{ fontWeight: pathname === link.href ? 'bold' : 'normal' }"
+    >
+      {{ link.label }}
+    </a>
+  </nav>
+</template>
+```
+
+## 관련 문서
+
+- [`useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/vue-intlayer/useLocale.md) — 현재 로케일 + 로케일 전환기(switcher)
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getPathWithoutLocale.md) — 이 훅에서 사용되는 기본 유틸리티

package/docs/ko/plugins/sync-json.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-12-13
+updatedAt: 2026-06-21
 title: Sync JSON 플러그인
 description: Intlayer 사전을 서드파티 i18n JSON 파일(i18next, next-intl, react-intl, vue-i18n 등)과 동기화합니다. 기존 i18n을 유지하면서 Intlayer를 사용하여 메시지를 관리, 번역 및 테스트할 수 있습니다.
 keywords:
@@ -24,6 +24,9 @@ slugs:
   - sync-json
 youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
 history:
+  - version: 9.0.0
+    date: 2026-06-21
+    changes: "splitKeys 옵션 추가 (next-intl / react-intl 단일 파일 레이아웃을 위한 최상위 네임스페이스 키당 하나의 사전)"
   - version: 7.5.0
     date: 2025-12-13
     changes: "ICU 및 i18next 형식 지원 추가"
@@ -62,7 +65,62 @@ pnpm add -D @intlayer/sync-json-plugin
 npm i -D @intlayer/sync-json-plugin
 ```
 
-## 빠른 시작
+## Plugins
+
+이 패키지는 두 가지 플러그인을 제공합니다:
+
+- `loadJSON`: JSON 파일을 Intlayer 사전으로 로드합니다.
+  - 이 플러그인은 소스에서 JSON 파일을 로드하고 Intlayer 사전으로 로드하는 데 사용됩니다. 모든 코드베이스를 스캔하고 특정 JSON 파일을 검색할 수 있습니다.
+    이 플러그인은 다음 경우에 사용할 수 있습니다.
+    - JSON 파일이 로드될 특정 위치를 강제하는 i18n 라이브러리(예: `next-intl`, `i18next`, `react-intl`, `vue-i18n` 등)를 사용하지만, 코드베이스의 원하는 위치에 콘텐츠 선언을 배치하려는 경우.
+    - 원격 소스(예: CMS, API 등)에서 메시지를 가져와 JSON 파일에 저장하려는 경우에도 사용할 수 있습니다.
+
+  > 내부적으로 이 플러그인은 모든 코드베이스를 스캔하고 특정 JSON 파일을 검색하여 Intlayer 사전으로 로드합니다.
+  > 이 플러그인은 출력 및 번역을 JSON 파일에 다시 쓰지 않습니다.
+
+- `syncJSON`: JSON 파일을 Intlayer 사전과 동기화합니다.
+  - 이 플러그인은 JSON 파일을 Intlayer 사전과 동기화하는 데 사용됩니다. 지정된 위치를 스캔하고 특정 JSON 파일의 패턴과 일치하는 JSON을 로드할 수 있습니다. 이 플러그인은 다른 i18n 라이브러리를 사용하면서 Intlayer의 이점을 얻으려는 경우에 유용합니다.
+
+## Using both plugins
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON, syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // 현재 JSON 파일을 Intlayer 사전과 동기화 상태로 유지
+  plugins: [
+    /**
+     * src에서 {key}.i18n.json 패턴과 일치하는 모든 JSON 파일을 로드합니다.
+     */
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      locale: Locales.ENGLISH,
+      priority: 1, // 이 JSON 파일이 `./locales/en/${key}.json`의 파일보다 우선하도록 보장합니다.
+      format: "intlayer", // JSON 콘텐츠의 형식
+    }),
+    /**
+     * 출력 및 번역을 로케일 디렉토리의 JSON 파일로 로드하고 다시 씁니다.
+     */
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      priority: 0,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
+```
+
+## `syncJSON` plugin
+
+### Quick start
 
 플러그인을 `intlayer.config.ts`에 추가하고 기존 JSON 구조를 가리키도록 설정하세요.
 
@@ -81,6 +139,7 @@ const config: IntlayerConfig = {
     syncJSON({
       // 로케일별, 네임스페이스별 레이아웃 (예: next-intl, 네임스페이스가 있는 i18next)
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "icu",
     }),
   ],
 };
@@ -91,14 +150,27 @@ export default config;
 대안: 로케일별 단일 파일 (i18next/react-intl 설정에서 일반적임):
 
 ```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      format: "i18next",
+      source: ({ locale }) => `./locales/${locale}.json`,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
 ```
 
-### 작동 방식
+#### 작동 방식
 
 - 읽기: 플러그인은 `source` 빌더에서 JSON 파일을 찾아 Intlayer 사전으로 로드합니다.
 - 쓰기: 빌드 및 채우기 후, 로컬라이즈된 JSON을 동일한 경로에 다시 씁니다 (포맷 문제를 방지하기 위해 마지막에 개행 포함).
@@ -112,6 +184,7 @@ syncJSON({
   location?: string, // 선택적 레이블, 기본값: "plugin"
   priority?: number, // 충돌 해결을 위한 선택적 우선순위, 기본값: 0
   format?: 'intlayer' | 'icu' | 'i18next', // 선택적 포맷터, Intlayer 런타임 호환성에 사용
+  splitKeys?: boolean, // 선택 사항, 단일 파일을 최상위 키당 하나의 사전으로 분할 (자동 감지)
 });
 ```
 
@@ -136,11 +209,43 @@ syncJSON({
 }),
 ```
 
-## 여러 JSON 소스 및 우선순위
+#### `splitKeys` (boolean)
+
+**최상위 키가 네임스페이스인** 단일 JSON 파일이 전체 파일을 담는 단일 사전 대신 최상위 키당 하나의 사전이 되어야 하는지 여부를 제어합니다.
+
+이는 `next-intl` 및 `react-intl`과 같은 라이브러리의 네임스페이스 모델과 일치합니다. 이 모델에서는 하나의 `messages/{locale}.json` 파일이 최상위 키별로 여러 네임스페이스를 그룹화하며, 각 네임스페이스는 독립적으로 처리됩니다 (예: `useTranslations('Hero')`는 `Hero` 사전을 해결합니다).
+
+- `undefined` (기본값): **자동 감지** — `source` 패턴에 `{key}` 세그먼트가 없는 경우 (하나의 파일이 모든 네임스페이스를 포함) 파일이 분할되고, 그렇지 않은 경우 (키당 하나의 파일) 단일 사전으로 유지됩니다.
+- `true`: 항상 각 최상위 키를 자체 사전으로 분할합니다.
+- `false`: 분할하지 않습니다; 전체 파일이 단일 사전이 됩니다.
+
+단일 `messages/{locale}.json` 파일이 주어졌을 때:
+
+```json fileName="messages/en.json"
+{
+  "Hero": { "title": "Full-stack developer" },
+  "Nav": { "work": "Work", "about": "About" },
+  "About": { "lead": "I build apps end to end." }
+}
+```
+
+```ts fileName="intlayer.config.ts"
+syncJSON({
+  format: "icu",
+  source: ({ locale }) => `./messages/${locale}.json`,
+  // splitKeys: true, // 패턴에 `{key}` 세그먼트가 없으므로 암시적으로 활성화됨
+}),
+```
+
+이는 `Hero`, `Nav`, `About` 세 개의 사전을 생성하므로 `useTranslations('Hero')` (next-intl)가 올바르게 해결됩니다. 다시 쓸 때, 모든 네임스페이스는 동일한 로케일별 파일로 재조립됩니다.
+
+> `source`에 명시적인 `{key}` 세그먼트를 유지하는 경우 (예: `./locales/${locale}/${key}.json`), 각 파일은 이미 하나의 네임스페이스이므로 분할은 기본적으로 비활성화됩니다.
+
+### Multiple JSON sources and priority
 
 여러 `syncJSON` 플러그인을 추가하여 서로 다른 JSON 소스를 동기화할 수 있습니다. 이는 프로젝트에 여러 i18n 라이브러리나 다양한 JSON 구조가 있을 때 유용합니다.
 
-### 우선순위 시스템
+#### Priority system
 
 여러 플러그인이 동일한 사전 키를 대상으로 할 때, `priority` 매개변수가 어떤 플러그인이 우선하는지 결정합니다:
 
@@ -189,73 +294,140 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-### 충돌 해결
+## Load JSON plugin
 
-동일한 번역 키가 여러 JSON 소스에 존재할 때:
+### Quick start
 
-1. 가장 높은 우선순위를 가진 플러그인이 최종 값을 결정합니다.
-2. 낮은 우선순위 소스는 누락된 키에 대한 대체로 사용됩니다.
-3. 이를 통해 점진적으로 새로운 구조로 이전하면서도 레거시 번역을 유지할 수 있습니다.
+`intlayer.config.ts`에 플러그인을 추가하여 기존 JSON 파일을 Intlayer 사전으로 가져옵니다. 이 플러그인은 읽기 전용입니다 (디스크에 쓰지 않음):
 
-## 통합
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
 
-아래는 일반적인 매핑 예시입니다. 런타임은 변경하지 말고 플러그인만 추가하세요.
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // 소스 트리의 어느 곳에나 있는 JSON 메시지를 가져옵니다.
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      // 플러그인 인스턴스당 단일 로케일을 로드합니다 (구성의 defaultLocale로 기본 설정됨).
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
 
-### i18next
+export default config;
+```
 
-일반적인 파일 구조: `./public/locales/{locale}/{namespace}.json` 또는 `./locales/{locale}/{namespace}.json`.
+대안: 로케일별 레이아웃, 여전히 읽기 전용 (선택된 로케일만 로드됨):
 
 ```ts fileName="intlayer.config.ts"
-import { syncJSON } from "@intlayer/sync-json-plugin";
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
 
-export default {
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
   plugins: [
-    syncJSON({
-      format: "i18next",
+    loadJSON({
+      // 이 패턴에서 Locales.FRENCH에 대한 파일만 로드됩니다.
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      locale: Locales.FRENCH,
     }),
   ],
 };
+
+export default config;
 ```
 
-### next-intl
+### How it works
 
-로케일별 JSON 메시지(보통 `./messages/{locale}.json`) 또는 네임스페이스별.
+- 발견: `source` 빌더에서 glob을 구축하고 일치하는 JSON 파일을 수집합니다.
+- 가져오기: 각 JSON 파일을 제공된 `locale`로 Intlayer 사전으로 로드합니다.
+- 읽기 전용: 출력 파일을 쓰거나 포맷하지 않습니다. 왕복 동기화가 필요한 경우 `syncJSON`을 사용하세요.
+- 자동 채우기 준비: `fill` 패턴을 정의하여 `intlayer content fill`이 누락된 키를 채울 수 있도록 합니다.
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
-  }),
-];
+### API
+
+```ts
+loadJSON({
+  // JSON 파일 경로를 빌드합니다. 구조에 로케일 세그먼트가 없는 경우 `locale`은 선택 사항입니다.
+  source: ({ key, locale }) => string,
+
+  // 이 플러그인 인스턴스에 의해 로드된 사전에 대한 대상 로케일
+  // configuration.internationalization.defaultLocale로 기본 설정됩니다.
+  locale?: Locale,
+
+  // 소스를 식별하는 선택적 레이블
+  location?: string, // default: "plugin"
+
+  // 다른 소스와의 충돌 해결에 사용되는 우선순위
+  priority?: number, // default: 0
+
+  // JSON 콘텐츠에 대한 선택적 포맷터
+  format?: 'intlayer' | 'icu' | 'i18next', // default: 'intlayer'
+
+  // 단일 파일을 최상위 키당 하나의 사전으로 분할 (자동 감지)
+  splitKeys?: boolean,
+});
 ```
 
-참고: `docs/ko/intlayer_with_next-intl.md`.
+#### `format` ('intlayer' | 'icu' | 'i18next')
 
-### react-intl
+JSON 파일을 로드할 때 사전 콘텐츠에 사용할 포맷터를 지정합니다. 이를 통해 다양한 i18n 라이브러리와 호환되는 다양한 메시지 포맷팅 구문을 사용할 수 있습니다.
 
-로케일별 단일 JSON이 일반적입니다:
+- `'intlayer'`: 기본 Intlayer 포맷터 (기본값).
+- `'icu'`: ICU 메시지 포맷팅을 사용합니다 (react-intl, vue-i18n과 같은 라이브러리와 호환).
+- `'i18next'`: i18next 메시지 포맷팅을 사용합니다 (i18next, next-i18next, Solid-i18next와 호환).
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
+**예시:**
+
+```ts
+loadJSON({
+  source: ({ key }) => `./src/**/${key}.i18n.json`,
+  locale: Locales.ENGLISH,
+  format: "icu", // 호환성을 위해 ICU 포맷팅 사용
+}),
 ```
 
-### vue-i18n
+#### `splitKeys` (boolean)
 
-로케일별 단일 파일 또는 네임스페이스별 파일 중 하나를 사용합니다:
+[`syncJSON`](#splitkeys-boolean)과 동일한 동작: 단일 JSON 파일이 최상위 키별로 여러 네임스페이스를 그룹화할 때, 각 최상위 키는 자체 사전이 됩니다.
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
-  }),
-];
+- `undefined` (기본값): **자동 감지** — `source` 패턴에 `{key}` 세그먼트가 없는 경우 분할되고, 그렇지 않은 경우 단일 사전이 됩니다.
+- `true` / `false`: 분할을 강제하거나 비활성화합니다.
+
+```ts
+loadJSON({
+  source: ({ locale }) => `./messages/${locale}.json`,
+  format: "icu",
+  // splitKeys 자동 활성화: `Hero`, `Nav`, `About`, … 각각 사전이 됩니다.
+}),
 ```
 
+### Behavior and conventions
+
+- `source` 마스크에 로케일 플레이스홀더가 포함된 경우, 선택된 `locale`에 대한 파일만 가져옵니다.
+- 마스크에 `{key}` 세그먼트가 없는 경우, 파일의 각 최상위 키는 기본적으로 자체 사전이 됩니다 ([`splitKeys`](#splitkeys-boolean) 참조). 대신 전체 파일을 단일 `index` 사전으로 로드하려면 `splitKeys: false`로 설정하세요.
+- 키는 `source` 빌더의 `{key}` 플레이스홀더를 대체하여 파일 경로에서 파생됩니다.
+- 플러그인은 발견된 파일만 사용하며 누락된 로케일이나 키를 생성하지 않습니다.
+- `fill` 경로는 `source`에서 추론되며, 선택 시 CLI를 통해 누락된 값을 업데이트하는 데 사용됩니다.
+
+## Conflict resolution
+
+동일한 번역 키가 여러 JSON 소스에 존재할 때:
+
+1. 가장 높은 우선순위를 가진 플러그인이 최종 값을 결정합니다.
+2. 낮은 우선순위 소스는 누락된 키에 대한 대체로 사용됩니다.
+3. 이를 통해 점진적으로 새로운 구조로 이전하면서도 레거시 번역을 유지할 수 있습니다.
+
 ## CLI
 
 동기화된 JSON 파일은 다른 `.content` 파일로 간주됩니다. 즉, 모든 intlayer 명령어가 동기화된 JSON 파일에 대해 사용 가능합니다. 포함되는 명령어는 다음과 같습니다:
@@ -268,13 +440,13 @@ plugins: [
 
 자세한 내용은 [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/index.md)를 참조하세요.
 
-## 제한 사항 (현재)
+## Limitations (current)
 
 - 타사 라이브러리를 대상으로 할 때 삽입 또는 복수형/ICU 지원이 없습니다.
 - 비-Intlayer 런타임에 대한 시각적 편집기는 아직 제공되지 않습니다.
 - JSON 동기화만 지원하며, 비-JSON 카탈로그 형식은 지원되지 않습니다.
 
-## 이 점이 중요한 이유
+## Why this matters
 
 - 검증된 i18n 솔루션을 추천하고 Intlayer를 애드온으로 위치시킬 수 있습니다.
 - 튜토리얼에서 Intlayer를 사용하여 JSON을 관리하도록 제안함으로써 SEO/키워드를 활용할 수 있습니다.