@intlayer/docs 9.3.3 → 9.4.0

package/docs/ko/benchmark/tanstack.md

@@ -194,6 +194,8 @@ GitHub 스타는 프로젝트의 인기, 커뮤니티 신뢰 및 장기적인
 
 `Tolgee`는 앞에서 언급한 많은 문제들을 해결합니다. 비슷한 접근 방식을 가진 다른 도구들보다 시작하기 더 어렵다고 느꼈습니다. 타입 안전성을 제공하지 않아 컴파일 시점에 누락된 키를 찾는 것도 매우 어렵습니다. 누락된 키 감지 기능을 추가하기 위해 Tolgee의 API를 나의 API로 래핑해야 했습니다.
 
+이 패키지는 상당히 무거운 편입니다 (~11.1kb, 이는 `react-intlayer`의 2배 이상입니다).
+
 TanStack Start에서도 반응성 문제가 있었습니다: 로케일 변경 시 프로바이더를 강제 재렌더링하고 로케일 변경 이벤트를 구독하여 다른 언어로의 로딩이 올바르게 작동하도록 해야 했습니다.
 
 **(use-intl)** (`use-intl@4.9.1`):
@@ -208,6 +210,8 @@ TanStack Start에서는 Next.js 전용 함정(`setRequestLocale`, 정적 렌더
 
 여전히 `t('a.b.c')` 위에 구축된 스택과 동일한 주요 단점을 공유합니다: 최적화는 가능하지만 시간이 매우 많이 소요되며, 대규모 프로젝트는 나쁜 관행(네임스페이스 + 동적 로딩 + 타입)에 빠질 위험이 있습니다.
 
+이 패키지는 특히 무겁습니다 (~17.3kb, 이는 `react-intlayer`의 약 3.5배입니다).
+
 메시지 형식도 다릅니다: `use-intl`은 ICU MessageFormat을 사용하는 반면, `i18next`는 자체 형식을 사용하므로 이들을 섞어서 사용하면 도구 기술이나 마이그레이션이 복잡해집니다.
 
 **(Lingui)** (`@lingui/core@5.3.0`):
@@ -218,6 +222,8 @@ TanStack Start에서는 Next.js 전용 함정(`setRequestLocale`, 정적 렌더
 
 `react-intl`은 Format.js 팀의 성능 중심 구현입니다. DX는 여전히 장황합니다: `const intl = useIntl()` + `intl.formatMessage({ id: "xx.xx" })`는 복잡성과 추가 JavaScript 작업을 가중시키고 글로벌 i18n 인스턴스를 React 트리의 많은 노드에 묶어둡니다.
 
+패키지도 무겁습니다(~14.4kb, 이는 `react-intlayer`의 약 3배 정도).
+
 ### 4 - 추천 사항
 
 이 TanStack Start 벤치마크에는 `next-translate`(Next.js 플러그인 + `getStaticProps`)에 상응하는 직접적인 대안이 없습니다. 성숙한 에코시스템과 `t()` API를 진정으로 원하는 팀에게는 `react-i18next`와 `use-intl`이 "합리적인" 선택으로 남겠지만, 누수를 피하기 위해 최적화하는 데 많은 시간을 투자할 것을 각오해야 합니다.

package/docs/ko/bundle_optimization.md

@@ -476,7 +476,7 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-> `optimize`가 `false`이거나 `editor.enabled`가 `true`일 때(비주얼 에디터에서는 편집을 위해 원본 필드 이름이 필요함) 최소화는 건너뜁니다.
+> `optimize`가 `false`이면 최소화는 건너뜁니다. `editor.enabled`가 `true`이어도 계속 실행되지만, 필드 이름 변경 단계는 건너뜁니다 — 비주얼 에디터는 `keyPath`로 편집 내용을 해석하므로 원본 필드 이름이 그대로 유지되어야 합니다.
 
 > Next.js에서는 `@intlayer/swc`가 설치되지 않았거나 로드할 수 없는 경우(16.1.0 미만의 Next.js)에도 압축이 건너뛰어집니다. 소스 접근을 재작성하는 쪽이 바로 이 플러그인이므로, 이것 없이 사전만 이름을 바꾸면 코드가 더 이상 존재하지 않는 필드 이름을 읽게 됩니다.
 
@@ -508,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> `optimize`가 `false`이거나 `editor.enabled`가 `true`일 때 파지(purge)는 건너뜁니다. Next.js에서는 `@intlayer/swc`를 사용할 수 없을 때, 그리고 호환 어댑터 호출자가 설정된 경우에도 추가로 건너뜁니다.
+> `optimize`가 `false`이면 파지(purge)는 건너뜁니다. `editor.enabled`가 `true`일 때도 계속 활성 상태를 유지합니다 — 정리된 필드는 어떤 컴포넌트에서도 읽지 않으므로 에디터가 이를 렌더링하는 일은 없습니다. Next.js에서는 `@intlayer/swc`를 사용할 수 없을 때, 그리고 호환 어댑터 호출자가 설정된 경우에도 추가로 건너뜁니다.
 
 > 소스 파일을 구문 분석할 수 없거나 `useIntlayer`의 결과가 변수에 할당되고 정적 분석기가 추적할 수 없는 방식으로 전달될 때(예: 객체에 스프레드, 구조 분해 없이 prop으로 전달) 파지도 보수적으로 건너뜁니다. 이런 경우에는 전체 사전이 유지됩니다.
 

package/docs/ko/cli/ci.md

@@ -128,6 +128,8 @@ bun x intlayer ci fill --verbose --mode complete
 
 ### CI/CD 파이프라인에서 사용
 
+`intlayer init`을 실행하면 즉시 사용 가능한 두 가지 GitHub Actions workflow를 생성합니다 ([Scaffolded GitHub Actions](#scaffolded-github-actions) 참조). 아래 예제는 monorepo에서 `ci` 명령어를 사용한 동등한 설정을 보여주며, 여기서 자격증명은 `INTLAYER_PROJECT_CREDENTIALS`에서 프로젝트별로 주입됩니다.
+
 CI/CD 구성(예: GitHub Actions, GitLab CI)에서 `INTLAYER_PROJECT_CREDENTIALS`를 비밀 값으로 설정합니다:
 
 ```yaml

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

@@ -91,8 +91,16 @@ bun x intlayer doc review
 
 - **`--log`**: 로그 전용 모드. AI로 번역하지 않고, 대신 다른 에이전트가 번역을 생성할 수 있도록 기본 및 대상 로케일에 대해 주의가 필요한 블록(줄 번호 및 내용 포함)을 기록합니다.
 
+- **`apply`**: Translate diverging blocks and provide the complete updated file in Korean (ko)
+- **`report`**: Log blocks needing attention with line numbers and content (no AI translation)
+- **`synthesis`**: Skip per-block output and provide only a final recap of up-to-date vs. documents needing edits
+
   > 예시: `npx intlayer doc review --log`
 
+> 예시: `npx intlayer doc review --mode synthesis`
+
+어떤 모드이든, 실행은 기본 문서와 일치하는 문서와 편집할 블록이 남아 있는 문서를 나열하는 종합 보고서로 끝납니다.
+
 **출력 옵션:**
 
 - **`--locales [locales...]`**: 문서를 검토할 대상 로케일입니다.

package/docs/ko/cli/fill.md

@@ -39,14 +39,6 @@ bun x intlayer fill
 
 이 명령어는 누락된 번역, 구조적 불일치 또는 타입 불일치와 같은 잠재적인 문제를 찾기 위해 콘텐츠 선언 파일을 분석합니다. 문제가 발견되면, **intlayer fill**은 사전을 일관되고 완전하게 유지하기 위해 업데이트를 제안하거나 적용합니다.
 
-주요 사항:
-
-- AI 모델의 컨텍스트 창 제한 내에서 유지하기 위해 큰 JSON 파일을 청크로 분할합니다.
-- 출력 형식이 잘못된 경우 번역을 재시도합니다.
-- 번역 정확도를 향상시키기 위해 애플리케이션 및 파일별 컨텍스트를 통합합니다.
-- 기존 번역을 덮어쓰지 않아 기존 번역을 보존합니다.
-- 큐 시스템을 사용하여 파일, 청크 및 로케일을 병렬로 처리하여 속도를 높입니다.
-
 ## 주요 포인트:
 
 - 대규모 JSON 파일을 청크로 분할하여 AI 모델의 컨텍스트 윈도우 제한 내에 유지합니다.

package/docs/ko/cli/index.md

@@ -127,6 +127,8 @@ Intlayer는 여러 설정 파일 형식을 허용합니다:
 
 - **[로그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/login.md)** - Intlayer CMS에 인증하고 액세스 자격 증명을 가져옵니다.
 
+> `intlayer login`은 모든 자격 있는 명령어가 사용하는 **액세스 키**(`clientId` / `clientSecret`)를 발급합니다. 시크릿은 서버 측 자격증명이며 클라이언트 번들에 도달하지 않습니다 — [액세스 키 안전 유지](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/login.md#keeping-the-access-key-safe)를 참조하세요.
+
 ### 핵심 명령어
 
 - **[딕셔너리 빌드 (Build)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/build.md)** - 콘텐츠 선언 파일에서 딕셔너리를 빌드합니다.

package/docs/ko/cli/login.md

@@ -122,6 +122,34 @@ INTLAYER_CLIENT_SECRET=your_client_secret
 }
 ```
 
+## 접근 키 안전하게 유지하기
+
+`intlayer login`은 **접근 키**를 발급합니다: 모든 인증된 명령어(`push`, `pull`, `fill`, `configuration push`, `live`, …)가 인증할 때 사용하는 `clientId` / `clientSecret` 쌍입니다.
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+};
+
+export default config;
+```
+
+> **`clientSecret`은 서버 측 자격 증명입니다.** 프로젝트 범위의 전체 API 접근 권한을 부여합니다 — 사전, 프로젝트 및 조직을 읽고 쓸 수 있습니다. `.env`(git에서 무시됨) 또는 CI 비밀 저장소에 보관하고, 절대 구성 파일에 직접 작성하지 마세요.
+
+Intlayer는 이를 단지 문서화하는 것이 아니라 강제합니다:
+
+- `clientSecret`은 **번들러가 인라인하는 구성에서 제거**되므로 어떤 프레임워크 통합을 사용하든 브라우저 번들에 도달할 수 없습니다. 이는 런타임에 환경에서 서버 측에서만 읽힙니다.
+- `clientId`는 다릅니다: 이는 **공개** 프로젝트 키이며 안전하게 배포할 수 있으며, [`@intlayer/analytics`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/analytics.md#how-events-are-authenticated)에서 수명이 짧은 수집 전용 토큰을 얻기 위해 사용됩니다.
+
+`clientId`를 주석 처리하는 것만으로도 환경 변수가 여전히 정의되어 있을 때도 모든 인증된 동작 — 원격 사전 가져오기, CMS 접근, 분석 — 을 비활성화하기에 충분합니다.
+
+CI 파이프라인의 경우, 자격 증명을 유지하는 대신 단일 실행 기간 동안 주입하는 [`ci` 명령어](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/ci.md)를 선호하세요.
+
 ## 수동 구성
 
 브라우저가 자동으로 열리지 않는 경우, 터미널에 표시된 URL을 수동으로 방문할 수 있습니다.

package/docs/ko/cli/push.md

@@ -104,21 +104,6 @@ bun x intlayer dictionary push
 - **`--git-diff-current`**: git diff의 현재 참조를 지정합니다 (기본값 `HEAD`).
 - **`--uncommitted`**: 커밋되지 않은 변경 사항을 포함합니다.
 - **`--unpushed`**: 푸시되지 않은 변경 사항을 포함합니다.
-- **`--untracked`**: 추적되지 않은 파일을 포함합니다.
-
-- **`--build`**: 푸시 전에 사전을 빌드하여 콘텐츠가 최신 상태인지 확인합니다. true는 빌드를 강제 실행하고, false는 빌드를 건너뛰며, undefined는 빌드 캐시를 사용하도록 허용합니다.
-
-**로그 옵션:**
-
-- **`--verbose`**: 디버깅을 위한 자세한 로깅을 활성화합니다. (기본값은 CLI에서 true)
-
-**Git 옵션:**
-
-- **`--git-diff`**: 기본 브랜치(기본값: `origin/main`)와 현재 브랜치(기본값: `HEAD`) 간의 변경 사항이 포함된 사전에만 실행합니다.
-- **`--git-diff-base`**: git diff의 기준 참조를 지정합니다. (기본값: `origin/main`)
-- **`--git-diff-current`**: git diff의 현재 참조를 지정합니다. (기본값: `HEAD`)
-- **`--uncommitted`**: 커밋되지 않은 변경 사항을 포함합니다.
-- **`--unpushed`**: 푸시되지 않은 변경 사항을 포함합니다.
 - **`--untracked`**: 추적되지 않은 파일을 포함합니다.
 
   > 예시: `npx intlayer dictionary push --git-diff --git-diff-base origin/main --git-diff-current HEAD`

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

@@ -22,6 +22,8 @@ author: aymericzip
 
 # next-i18next에서 Intlayer로 마이그레이션
 
+완전하고 상세한 단계별 튜토리얼을 보려면 전체 [next-i18next 마이그레이션 가이드](../migration_from_next-i18next_to_intlayer.md)를 참고하세요.
+
 Intlayer는 모든 Next.js Pages Router 및 App Router 구현을 투명하게 처리합니다. adapter를 사용하면 코드를 전혀 다시 작성하지 않고 `next-i18next` 구현을 마이그레이션할 수 있습니다.
 
 ## 해야 할 일

package/docs/ko/compiler.md

@@ -40,6 +40,12 @@ author: aymericzip
 
 ## Intlayer 컴파일러를 사용하는 이유
 
+- **자동화**: 사전에 콘텐츠를 수동으로 복사-붙여넣기하는 작업을 제거합니다.
+
+- **Speed**: 최적화된 콘텐츠 추출로 빌드 프로세스를 빠르게 유지합니다.
+
+- **개발자 경험**: 콘텐츠 선언을 사용 위치에 가깝게 유지하여 유지보수성을 개선합니다.
+
 - **자동화**: 콘텐츠를 사전에 수동으로 복사하여 붙여넣는 작업을 제거합니다.
 - **속도**: 빌드 프로세스가 빠르게 유지되도록 최적화된 콘텐츠 추출을 제공합니다.
 - **개발자 경험**: 콘텐츠 선언을 사용되는 위치에 그대로 유지하여 유지보수성을 향상시킵니다.
@@ -54,6 +60,8 @@ author: aymericzip
 - **휴리스틱 모호성**: 컴파일러는 사용자 지향 콘텐츠와 애플리케이션 로직(예: `className="active"`, 상태 코드, 제품 ID)을 추측해야 합니다. 복잡한 코드베이스에서는 이것이 오탐지 또는 누락된 문자열로 이어질 수 있으며, 수동 주석 및 예외 처리가 필요합니다.
 - **정적 추출만**: 컴파일러 기반 추출은 정적 분석에 의존합니다. 런타임에만 존재하는 문자열(API 오류 코드, CMS 필드 등)은 컴파일러만으로는 발견하거나 번역할 수 없으므로 여전히 보완적인 런타임 i18n 전략이 필요합니다.
 
+- **정적 전용 추출**: 컴파일러 기반 추출은 정적 분석에 의존합니다. 런타임에만 존재하는 문자열(API 오류 코드, CMS 필드 등)은 컴파일러만으로는 발견하거나 번역할 수 없으므로, 여전히 보완적인 런타임 i18n 전략이 필요합니다.
+
 더 깊은 아키텍처 비교를 위해서는 블로그 게시물 [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ko/compiler_vs_declarative_i18n.md)을 참조하세요.
 
 대안으로, 콘텐츠에 대한 완전한 제어를 유지하면서 i18n 프로세스를 자동화하기 위해 Intlayer는 자동 추출 명령 `intlayer extract`([CLI 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/extract.md) 참조) 또는 Intlayer VS Code 확장의 `Intlayer: extract content to Dictionary` 명령([VS Code 확장 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/vs_code_extension.md) 참조)도 제공합니다.
@@ -94,6 +102,8 @@ export default defineConfig({
 });
 ```
 
+> 독립형 `intlayerCompiler()` 플러그인은 고급 설정을 위해 여전히 내보내집니다. `intlayer()`와 함께 등록하는 것은 안전합니다 — 컴파일러는 자신을 중복 제거하고 한 번만 실행됩니다.
+
 See complete tutorial: [Intlayer Compiler with Vite+React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_vite+react_compiler.md)
 
 #### 프레임워크 지원
@@ -104,6 +114,10 @@ Vite 플러그인은 다양한 파일 유형을 자동으로 감지하고 처리
 - **Vue**: `@intlayer/vue-compiler`가 필요합니다.
 - **Svelte**: `@intlayer/svelte-compiler`가 필요합니다.
 
+- **Vue**: `@intlayer/vue-compiler`가 필요합니다.
+
+- **Svelte**: `@intlayer/svelte-compiler`가 필요합니다.
+
 사용하는 프레임워크에 맞는 컴파일러 패키지를 반드시 설치하세요:
 
 ```bash

package/docs/ko/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-08-06
+updatedAt: 2026-08-22
 title: 구성 (Configuration)
 description: 애플리케이션에 Intlayer를 구성하는 방법을 알아보세요. 필요에 따라 Intlayer를 맞춤설정하는 데 사용할 수 있는 다양한 설정과 옵션을 이해하세요.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.3.3
+    date: 2026-08-22
+    changes: "`@intlayer/analytics`가 설치되면 애널리틱스를 기본적으로 활성화"
   - version: 9.1.3
     date: 2026-08-06
     changes: "`routing.enableProxy`를 3상태로 변경: 미설정(auto), `true`, `false`"
@@ -380,8 +383,8 @@ const config: IntlayerConfig = {
   analytics: {
     /**
      * 애널리틱스 수집 활성화 여부(페이지 뷰, 콘텐츠 노출, A/B 이벤트).
-     * 귀속(attribution)을 위해 `editor.clientId`가 설정되어 있어야 합니다.
-     * 기본값: false
+     * `@intlayer/analytics`가 설치되어 있고 귀속(attribution)을 위해 `editor.clientId`가 설정되어 있어야 합니다.
+     * 기본값: true
      */
     enabled: true,
 
@@ -729,19 +732,17 @@ export default config;
 | `liveSyncPort`               | Live Sync 서버 포트.                                                                                                                                              | `number`                          | `4000`                              | `4000`                                                                                          |                                                                                                                                                                                                                      |
 | `liveSyncURL`                | Live Sync 서버 URL.                                                                                                                                               | `string`                          | `'http://localhost:{liveSyncPort}'` | `'https://example.com'`                                                                         | 기본적으로 localhost를 가리키며, 원격 Live Sync 서버로 변경할 수 있습니다.                                                                                                                                           |
 
----
-
 ### 애널리틱스 구성 (Analytics)
 
 Intlayer 애널리틱스와 관련된 설정을 정의합니다: 사용자에게 실제로 표시되는 콘텐츠(페이지 뷰, 콘텐츠 노출)를 수집하고 콘텐츠에 대한 A/B 테스트를 지원합니다.
 
-애널리틱스는 철저히 옵트인(opt-in) 방식입니다: `analytics.enabled`가 명시적으로 `true`로 설정되고 **그리고** 귀속을 위한 프로젝트 키(`editor.clientId`)가 구성되지 않는 한 아무것도 수집되지 않습니다. 비활성화된 경우(기본값), 전체 애널리틱스 통합은 애플리케이션 번들에서 데드 코드 제거(dead-code elimination)됩니다.
+애널리틱스는 옵트아웃 방식입니다: 기본적으로 활성화되어 있으며, `@intlayer/analytics` 패키지가 설치되고 **그리고** 귀속을 위한 프로젝트 키(`editor.clientId`)가 구성되는 즉시 수집을 시작합니다. `analytics.enabled`를 `false`로 설정하거나 패키지를 설치하지 않으면, 전체 애널리틱스 통합이 애플리케이션 번들에서 데드 코드 제거(dead-code elimination)됩니다.
 
-| 필드            | 설명                                                                | 타입      | 기본값  | 예시    | 참고                                                                                                                                  |
-| --------------- | ------------------------------------------------------------------- | --------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `enabled`       | 애널리틱스 수집을 활성화합니다(페이지 뷰, 콘텐츠 노출, A/B 이벤트). | `boolean` | `false` | `true`  | 귀속을 위해 `editor.clientId`가 설정되어 있어야 합니다. 설정되지 않으면 `enabled`가 `true`여도 애널리틱스는 비활성 상태로 유지됩니다. |
-| `flushInterval` | 백엔드로 자동 일괄 전송하는 간격(밀리초).                           | `number`  | `20000` | `10000` |                                                                                                                                       |
-| `sampleRate`    | 기록할 세션의 비율, `0`(없음)에서 `1`(전체) 사이.                   | `number`  | `1`     | `0.5`   | 샘플링은 세션별로 결정적이므로, 기록된 세션은 자신의 모든 이벤트를 보고합니다(부분 퍼널 없음).                                        |
+| 필드            | 설명                                                                | 타입      | 기본값  | 예시    | 참고                                                                                                                                                                      |
+| --------------- | ------------------------------------------------------------------- | --------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`       | 애널리틱스 수집을 활성화합니다(페이지 뷰, 콘텐츠 노출, A/B 이벤트). | `boolean` | `true`  | `false` | `@intlayer/analytics`가 설치되어 있고 귀속을 위해 `editor.clientId`가 설정되어 있어야 합니다. 그렇지 않으면 `enabled`가 `true`여도 애널리틱스는 비활성 상태로 유지됩니다. |
+| `flushInterval` | 백엔드로 자동 일괄 전송하는 간격(밀리초).                           | `number`  | `20000` | `10000` |                                                                                                                                                                           |
+| `sampleRate`    | 기록할 세션의 비율, `0`(없음)에서 `1`(전체) 사이.                   | `number`  | `1`     | `0.5`   | 샘플링은 세션별로 결정적이므로, 기록된 세션은 자신의 모든 이벤트를 보고합니다(부분 퍼널 없음).                                                                            |
 
 ---
 
@@ -980,8 +981,15 @@ Intlayer의 내부 경로 및 출력 결과와 관련된 설정입니다. 이러
 
 ### 딕셔너리 구성 (Dictionary)
 
+사전 작업을 제어하는 설정입니다. 자동 채우기 동작 및 컨텐츠 생성을 포함합니다.
+
 자동 채우기 동작 및 콘텐츠 생성을 포함하여 딕셔너리 작업을 제어하기 위한 옵션입니다.
 
+1. **기본값**: 콘텐츠 선언 파일을 생성할 때 기본값 정의
+2. **폴백 동작**: 특정 필드가 정의되지 않을 때 폴백 값을 제공하여 사전 작업 동작을 전역적으로 정의할 수 있음
+
+content declaration 파일 및 configuration 값이 어떻게 적용되는지에 대한 자세한 내용은 [Content File Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/content_file.md)을 참조하세요.
+
 | 필드                        | 설명                                                                                                                                                   | 타입                                                                                                            | 기본값       | 예시                                                                                        | 참고                                                                                                                                                                                                                                                                                                                                                                           |
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `fill`                      | 자동 채우기(AI 번역) 출력 파일 생성을 제어합니다.                                                                                                      | `boolean` &#124; <br/> `FilePathPattern` &#124; <br/> `Partial<Record<Locale, boolean &#124; FilePathPattern>>` | `true`       | `{ en: '/locales/en/{{key}}.json', fr: ({ key }) => '/locales/fr/${key}.json', es: false }` | • `true`: 기본 경로(소스와 동일한 파일).<br/>• `false`: 비활성화.<br/>• 문자열/함수 패턴은 로케일별 생성을 허용합니다.<br/>• 로케일별 객체: 각 로케일이 자체 패턴을 가지며 `false`는 해당 로케일을 제외합니다.<br/>• `{{locale}}`을 포함하면 로케일별 생성이 가능합니다.<br/>• 딕셔너리 수준의 `fill` 설정은 항상 이 글로벌 설정보다 우선합니다.                               |
@@ -1021,8 +1029,6 @@ Intlayer 로그 출력 맞춤설정을 위한 설정입니다.
 | `mode`   | 로거 모드를 지정합니다.    | `'default'` &#124; <br/> `'verbose'` &#124; <br/> `'disabled'` | `'default'`     | `'verbose'`      | • `'verbose'`: 디버깅을 위해 더 많은 정보를 기록합니다.<br/>• `'disabled'`: 모든 로깅을 비활성화합니다. |
 | `prefix` | 모든 로그 메시지의 접두사. | `string`                                                       | `'[intlayer] '` | `'[my prefix] '` |                                                                                                         |
 
----
-
 ### AI 구성 (AI)
 
 프로바이더, 모델 및 API 키를 포함하여 Intlayer 내의 AI 기능을 관리하기 위한 설정입니다.
@@ -1062,8 +1068,6 @@ Intlayer는 최대의 유연성을 보장하기 위해 다양한 AI 프로바이
 | `baseURL`            | AI API에 대한 기본 URL.                                                                                          | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                             | 없음        | `'https://api.openai.com/v1'` <br/> `'http://localhost:5000'` | 로컬 또는 맞춤형 AI API 엔드포인트를 가리킬 수 있습니다.                                                                                                                                   |
 | `dataSerialization`  | AI 기능에 대한 데이터 직렬화 형식.                                                                               | `'json'` &#124; <br/> `'toon'`                                                                                                                                                                                                                                                                                                                                                                                                                       | `undefined` | `'toon'`                                                      | • `'json'`: 기본값, 안정적임; 더 많은 토큰 소비.<br/>• `'toon'`: 더 적은 토큰 소모, 덜 안정적임.<br/>• 모델에 로직 실행을 위한 추가 파라미터(추론 노력(reasoning effort) 등)를 전달합니다. |
 
----
-
 ### 빌드 구성 (Build)
 
 Intlayer가 애플리케이션의 국제화를 최적화하고 컴파일하는 방법을 제어하기 위한 설정입니다.
@@ -1101,8 +1105,6 @@ Intlayer가 애플리케이션의 국제화를 최적화하고 컴파일하는
 | `noMetadata`          | `true`인 경우 컴파일러는 출력물에서 딕셔너리 메타데이터(key, content wrapper)를 제거합니다.                                                                                                                                                                                                                   | `boolean`                                                                                                       | `false`     | `false` → `{"key":"my-key","content":{"key":"value"}}` <br/> `true` → `{"key":"value"}`                                                                  | • 로케일별 i18next 또는 ICU MessageFormat JSON 출력에 유용합니다.<br/>• `loadJSON` 플러그인과 잘 작동합니다.                                                                                              |
 | `dictionaryKeyPrefix` | 딕셔너리 키 접두사                                                                                                                                                                                                                                                                                            | `string`                                                                                                        | `''`        |                                                                                                                                                          | 추출된 딕셔너리 키에 선택적 접두사를 추가합니다.                                                                                                                                                          |
 
----
-
 ### 사용자 정의 스키마 (Custom Schemas)
 
 | 필드      | 설명                                                                     | 타입                        |

package/docs/ko/custom_domains.md

@@ -138,6 +138,38 @@ getMultilingualUrls("/about", { currentDomain: "intlayer.org" });
 
 이러한 절대 URL은 SEO를 위한 `<link rel="alternate" hreflang="...">` 태그에서 바로 사용할 수 있습니다.
 
+## 타입 추론
+
+`routing.domains`은 생성된 모듈 확장(module augmentation)으로 직렬화되므로,
+`getLocalizedUrl`과 `getLocalizedPath`는 도메인 라우팅된 로캘이 해석하는 정확한
+URL로 반환 타입을 좁혀줍니다 — 접두사 억제(prefix suppression)를 포함하여.
+
+```ts
+// routing: { mode: 'prefix-no-default', domains: { en: 'intlayer.org', zh: 'intlayer.zh' } }
+
+getLocalizedUrl("/about", "zh");
+//     ^? "https://intlayer.zh/about" | "/about"
+
+getLocalizedPath("/about", "zh");
+//     ^? "/about"   (origin이 없고, /zh/ 접두사도 없음)
+```
+
+URL 타입은 함수가 반환할 수 있는 두 값의 **합집합**입니다: 로캘의 도메인에서의
+절대 URL과 렌더링되는 페이지가 이미 해당 도메인에 있을 때 반환하는 상대 URL입니다.
+`getLocalizedPath`는 이러한 모호함이 없습니다 — origin을 내보내지 않으므로 —
+단일 리터럴로 유지됩니다.
+
+도메인을 공유하는 로캘은 타입에서도 일반적인 접두사를 유지합니다:
+
+```ts
+getLocalizedUrl("/about", "fr");
+//     ^? "https://intlayer.org/fr/about" | "/fr/about"
+```
+
+> `routing.domains`을 변경한 후 타입을 재생성하세요 (`npx intlayer build` 또는
+> 모든 dev server 실행) — 좁혀지는 타입은 설정 파일 자체가 아니라 생성된
+> `__RoutingRegistry`에서 나옵니다.
+
 ## 프록시 동작
 
 ### Next.js
@@ -170,6 +202,8 @@ GET intlayer.zh/about
 
 `intlayerProxy` Vite 플러그인은 개발 중에 동일한 로직을 적용합니다.
 
+> Intlayer v9부터 `intlayerProxy()`는 `intlayer()` 플러그인에 직접 번들로 포함되어 있으며 `routing.enableProxy` 옵션(`true`이 기본값)을 통해 기본적으로 활성화됩니다. 아래와 같이 별도로 등록하는 것은 이제 선택 사항이며, 이전 버전과의 호환성과 플러그인 순서를 제어해야 하는 설정을 위해 유지됩니다. `routing.enableProxy: false`로 설정하여 옵트아웃할 수 있습니다. [v9 릴리즈 노트](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/releases/v9.md)를 참조하세요.
+
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { intlayer } from "vite-intlayer";

package/docs/ko/custom_url_rewrites.md

@@ -248,7 +248,7 @@ Intlayer는 내부적으로 이러한 패턴을 통합된 문법으로 정규화
 
 <Tabs group='framework'>
   <Tab label="Next.js" value="nextjs">
-  
+
     ```tsx
     'use client';
 
@@ -263,7 +263,7 @@ Intlayer는 내부적으로 이러한 패턴을 통합된 문법으로 정규화
   </Tab>
 
   <Tab label="React Router" value="reactrouter">
-  
+
     ```tsx
     'use client';
 
@@ -279,7 +279,7 @@ Intlayer는 내부적으로 이러한 패턴을 통합된 문법으로 정규화
   </Tab>
 
   <Tab label="Vue" value="vue">
-  
+
     ```vue
     <script setup>
     import { useRewriteURL } from "vue-intlayer";
@@ -291,7 +291,7 @@ Intlayer는 내부적으로 이러한 패턴을 통합된 문법으로 정규화
 
   </Tab>
   <Tab label="Solid" value="solid">
-  
+
     ```tsx
     import { useRewriteURL } from "solid-intlayer";
 
@@ -303,7 +303,7 @@ Intlayer는 내부적으로 이러한 패턴을 통합된 문법으로 정규화
 
   </Tab>
   <Tab label="Svelte" value="svelte">
-  
+
     ```svelte
     <script>
     import { useRewriteURL } from "svelte-intlayer";
@@ -340,6 +340,8 @@ export function middleware(request: NextRequest) {
 
 SolidJS, Vue, Svelte의 경우, 개발 중 리라이트를 `intlayerProxy` Vite 플러그인이 관리합니다.
 
+> Intlayer v9부터 `intlayerProxy()`는 `intlayer()` 플러그인에 직접 번들되어 있으며 `routing.enableProxy` 옵션(`true`가 기본값)을 통해 기본적으로 활성화됩니다. 아래와 같이 별도로 등록하는 것은 이제 선택 사항입니다 — 이전 버전과의 호환성 및 플러그인 순서를 제어해야 하는 설정을 위해 유지됩니다. `routing.enableProxy: false`로 설정하여 옵트아웃할 수 있습니다. [v9 release notes](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/releases/v9.md)를 참조하세요.
+
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { intlayer } from "vite-intlayer";

package/docs/ko/dictionary/html.md

@@ -483,7 +483,9 @@ HTML 노드에서 `.use()` 메서드를 사용할 때, 제공하는 컴포넌트
 <Tabs group="framework">
   <Tab label="React / Next.js" value="react">
     #### `<HTMLRenderer />` 컴포넌트
-    
+
+특정 컴포넌트로 HTML 문자열을 렌더링합니다.
+
     ```tsx
     import { HTMLRenderer } from "react-intlayer/html";
 

package/docs/ko/dictionary/markdown.md

@@ -492,7 +492,7 @@ Markdown 렌더링은 **MDX**를 지원합니다 — Markdown 내에서 이름
 
 <Tabs group="framework">
   <Tab label="React" value="react">
-  
+
     #### `<MarkdownRenderer />` 컴포넌트
 
     특정 옵션으로 Markdown 문자열을 렌더링합니다.
@@ -531,7 +531,7 @@ Markdown 렌더링은 **MDX**를 지원합니다 — Markdown 내에서 이름
 
   </Tab>
   <Tab label="Next.js" value="nextjs">
-  
+
     #### `<MarkdownRenderer />` 컴포넌트
 
     특정 옵션으로 Markdown 문자열을 렌더링합니다.
@@ -957,6 +957,10 @@ Markdown 렌더링은 **MDX**를 지원합니다 — Markdown 내에서 이름
   </Tab>
   <Tab label="Angular" value="angular">
 
+> MDX가 지원됨 — Markdown 내에서 사용되는 모든 component 이름(예: `<MyCustomJSXComponent />`)은 `components` 맵에 대해 해석됩니다.
+
+자신의 markdown renderer를 사용할 수도 있습니다:
+
     ```typescript fileName="app.module.ts"
     import { NgModule } from '@angular/core';
     import { IntlayerMarkdownModule } from 'angular-intlayer/markdown';
@@ -1047,7 +1051,7 @@ const MyComponent = () => {
 ```
 
   </Tab>
- 
+
   <Tab label="Vue" value="vue">
 
 Vue에는 내장 `<Suspense>` 구성 요소가 있습니다. Markdown 콘텐츠를 렌더링하는 구성 요소를 `<Suspense>` 경계로 래핑하십시오.