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

package/docs/ko/migration_from_vue-i18n_to_intlayer.md

@@ -17,7 +17,7 @@ slugs:
   - migration
   - vue-i18n
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-05
     changes: "Init history"
 author: aymericzip
@@ -99,24 +99,40 @@ Intlayer는 단순한 i18n 솔루션을 넘어, 자체 호스팅이 가능한 **
 
 Intlayer 핵심 패키지와 호환성 어댑터를 설치합니다:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` 플래그는 선택 사항입니다. AI 에이전트인 경우 `intlayer-cli init`를 사용하세요.
+
+> 이 명령은 환경을 감지하고 필요한 패키지를 설치합니다. 예를 들어:
+
 ```bash packageManager="npm"
 npm install intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer vue-intlayer @intlayer/vue-i18n @intlayer/sync-json-plugin
-bun x intlayer init
 ```
 
 > `vue-i18n`을 계속 설치해 둘 수 있습니다 — 호환성 어댑터는 TypeScript 타입을 위해 이를 `devDependency` / `peerDependency`로 사용합니다.

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/angular-intlayer/exports.md

@@ -14,9 +14,12 @@ slugs:
   - angular-intlayer
   - exports
 history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "usePathname 유틸리티 추가"
   - version: 8.0.0
     date: 2026-01-21
-    changes: "모든 exports에 대한 문서 통합"
+    changes: "모든 내보내기에 대한 통합 문서" 통합"
 author: aymericzip
 ---
 
@@ -46,15 +49,16 @@ import "angular-intlayer";
 
 ### 훅
 
-| 훅                     | 설명                                                                                           | 관련 문서 |
-| ---------------------- | ---------------------------------------------------------------------------------------------- | --------- |
-| `useIntlayer`          | `useDictionary`를 기반으로 하며, 생성된 declaration에서 딕셔너리의 최적화된 버전을 주입합니다. | -         |
-| `useDictionary`        | 사전(key, content)처럼 보이는 객체를 처리합니다. `t()` 번역, 열거형 등도 처리합니다.           | -         |
-| `useDictionaryAsync`   | `useDictionary`와 동일하지만 비동기 사전을 처리합니다.                                         | -         |
-| `useDictionaryDynamic` | `useDictionary`와 동일하지만 동적 사전을 처리합니다.                                           | -         |
-| `useLocale`            | 현재 로케일과 이를 설정하는 함수를 반환합니다.                                                 | -         |
-| `useIntl`              | 현재 로케일에 대한 Intl 객체를 반환합니다.                                                     | -         |
-| `useLoadDynamic`       | 동적 사전을 로드하는 훅.                                                                       | -         |
+| 훅                     | 설명                                                                                                               | 관련 문서                                                                                                             |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `useIntlayer`          | `useDictionary`를 기반으로 하며, 생성된 declaration에서 딕셔너리의 최적화된 버전을 주입합니다.                     | -                                                                                                                     |
+| `useDictionary`        | 사전(key, content)처럼 보이는 객체를 처리합니다. `t()` 번역, 열거형 등도 처리합니다.                               | -                                                                                                                     |
+| `useDictionaryAsync`   | `useDictionary`와 동일하지만 비동기 사전을 처리합니다.                                                             | -                                                                                                                     |
+| `useDictionaryDynamic` | `useDictionary`와 동일하지만 동적 사전을 처리합니다.                                                               | -                                                                                                                     |
+| `useLocale`            | 현재 로케일과 이를 설정하는 함수를 반환합니다.                                                                     | -                                                                                                                     |
+| `usePathname`          | 로케일 세그먼트가 제거된 현재 경로를 `Signal<string>`으로 반환합니다. `DestroyRef`를 통해 `popstate`에 반응합니다. | [usePathname](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/angular-intlayer/usePathname.md) |
+| `useIntl`              | 현재 로케일에 대한 Intl 객체를 반환합니다.                                                                         | -                                                                                                                     |
+| `useLoadDynamic`       | 동적 사전을 로드하는 훅.                                                                                           | -                                                                                                                     |
 
 ### 컴포넌트
 

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

@@ -0,0 +1,119 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: usePathname Hook 문서 | angular-intlayer
+description: angular-intlayer 패키지에서 usePathname 훅을 사용하는 방법을 확인하세요
+keywords:
+  - usePathname
+  - pathname
+  - locale
+  - Intlayer
+  - Internationalization
+  - Documentation
+  - Angular
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - packages
+  - angular-intlayer
+  - usePathname
+history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "usePathname 유틸리티 추가"
+  - version: 8.2.0
+    date: 2026-06-22
+    changes: "히스토리 초기화"
+author: aymericzip
+---
+
+# Angular 통합: `usePathname` Hook 문서
+
+`usePathname` 훅은 로케일 세그먼트가 제거된 현재 브라우저 경로를 Angular `Signal<string>`로 반환합니다. 이는 로케일 접두사를 수동으로 제거할 필요 없이, 예를 들어 어떤 내비게이션 항목이 활성화되었는지 파악하는 등 로케일을 고려한 내비게이션을 구축할 때 유용합니다.
+
+## Angular에서 `usePathname` 가져오기
+
+```typescript
+import { usePathname } from "angular-intlayer";
+```
+
+## 개요
+
+`usePathname`은 `window.location.pathname`을 읽고, `getPathWithoutLocale`을 통해 로케일 접두사를 제거하며, 브라우저가 `popstate` 이벤트(뒤로/앞으로 가기)를 발생시킬 때마다 시그널을 업데이트합니다. 컴포넌트가 파괴될 때 이벤트 리스너를 자동으로 정리하기 위해 Angular의 `DestroyRef`를 사용합니다.
+
+## 사용법
+
+```typescript fileName="src/app/nav-item.component.ts"
+import { Component, input } from "@angular/core";
+import { usePathname } from "angular-intlayer";
+
+@Component({
+  standalone: true,
+  selector: "app-nav-item",
+  template: `
+    <a
+      [href]="href()"
+      [attr.aria-current]="pathname() === href() ? 'page' : null"
+    >
+      {{ label() }}
+    </a>
+  `,
+})
+export class NavItemComponent {
+  readonly href = input.required<string>();
+  readonly label = input.required<string>();
+
+  readonly pathname = usePathname();
+}
+```
+
+## 반환 값
+
+| 타입             | 설명                                                      |
+| ---------------- | --------------------------------------------------------- |
+| `Signal<string>` | 로케일 접두사가 없는 현재 경로를 포함하는 Angular 시그널. |
+
+## 동작
+
+- **로케일 제거**: 선행 로케일 세그먼트를 제거합니다 (예: `/ko/dashboard` → `/dashboard`).
+- **반응형**: `popstate` 이벤트(브라우저 뒤로 / 앞으로 탐색)에 자동으로 업데이트됩니다.
+- **SSR 안전성**: `window`를 사용할 수 없을 때는 `""`를 반환합니다.
+- **정리(Cleanup)**: 호스트 컴포넌트가 파괴될 때 `DestroyRef.onDestroy`를 통해 `popstate` 리스너가 제거됩니다.
+
+## 예제
+
+```typescript fileName="src/app/sidebar.component.ts"
+import { Component } from "@angular/core";
+import { usePathname } from "angular-intlayer";
+
+@Component({
+  standalone: true,
+  selector: "app-sidebar",
+  template: `
+    <nav>
+      @for (link of links; track link.href) {
+        <a
+          [href]="link.href"
+          [style.font-weight]="pathname() === link.href ? 'bold' : 'normal'"
+        >
+          {{ link.label }}
+        </a>
+      }
+    </nav>
+  `,
+})
+export class SidebarComponent {
+  readonly links = [
+    { href: "/dashboard", label: "대시보드" },
+    { href: "/settings", label: "설정" },
+  ];
+
+  readonly pathname = usePathname();
+}
+```
+
+## 관련
+
+- [`useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/angular-intlayer/exports.md) — 현재 로케일 + 로케일 전환기
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getPathWithoutLocale.md) — 이 훅에서 사용하는 기본 유틸리티

package/docs/ko/packages/express-intlayer/t.md

@@ -334,15 +334,6 @@ app.get("/morning", (_req, res) => {
 
 ---
 
-## 효과적인 사용을 위한 팁
-
-1. **번역 중앙 집중화**: 유지 관리를 개선하기 위해 번역 관리를 중앙 집중화된 모듈이나 JSON 파일을 사용하세요.
-2. **번역 검증**: 불필요한 대체를 방지하기 위해 모든 언어 변형에 해당하는 번역이 있는지 확인하세요.
-3. **프론트엔드 i18n과 결합**: 앱 전반에 걸쳐 원활한 사용자 경험을 위해 프론트엔드 국제화와 동기화하세요.
-4. **성능 벤치마크**: 번역을 추가할 때 앱의 응답 시간을 테스트하여 최소한의 영향을 보장하세요.
-
----
-
 ## 결론
 
 1. **번역 중앙화**: 유지보수를 용이하게 하기 위해 번역 관리를 중앙화된 모듈이나 JSON 파일로 수행하세요.

package/docs/ko/packages/intlayer/comparePaths.md

@@ -0,0 +1,173 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: comparePaths 함수 문서 | intlayer
+description: intlayer 패키지의 comparePaths 함수 사용법 알아보기
+keywords:
+  - comparePaths
+  - normalizePath
+  - 활성 링크
+  - 네비게이션
+  - Intlayer
+  - intlayer
+  - 다국어 처리
+  - 문서
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - comparePaths
+history:
+  - version: 9.0.0
+    date: 2026-06-22
+    changes: "초기 문서 작성"
+author: aymericzip
+---
+
+# 문서: `intlayer`의 `comparePaths` 함수
+
+## 설명
+
+`comparePaths` 함수는 로케일 세그먼트, 프로토콜/호스트, 쿼리 문자열, 해시 및 후행 슬래시를 무시하면서 두 URL 또는 경로명이 같은지 비교합니다. 내비게이션 링크가 현재 페이지를 가리키는지 판단할 때(예: 활성 링크 강조 표시) 오류가 발생하기 쉬운 자체 정규화 로직을 만들 필요 없이 사용하는 권장 방법입니다.
+
+내부적으로 [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getPathWithoutLocale.md)을 재사용하여 로케일 세그먼트를 제거하므로, 설정된 라우팅 모드와 로케일을 따릅니다.
+
+이 패키지는 또한 비교에 사용되는 로케일 독립적인 정규화된 경로명을 반환하는 기본 도우미인 [`normalizePath`](#normalizepath)를 내보냅니다.
+
+**주요 기능:**
+
+- 로케일 독립적 비교(`/ko/about`과 `/about`은 일치함)
+- 절대 URL과 상대 경로 모두에서 작동
+- 쿼리 문자열, 해시 및 후행 슬래시 무시
+- 선행 슬래시 누락 및 빈 값 허용(`/`로 정규화)
+- 가벼움 — `getPathWithoutLocale`을 기반으로 구축됨
+
+---
+
+## 함수 시그니처
+
+```typescript
+comparePaths(
+  pathname: string,  // 필수
+  href: string,      // 필수
+  locales?: Locales[] // 선택
+): boolean
+
+normalizePath(
+  inputUrl: string,   // 필수
+  locales?: Locales[] // 선택
+): string
+```
+
+---
+
+## 매개변수
+
+- `pathname: string`
+  - **설명**: 비교할 첫 번째 URL 문자열 또는 경로명(일반적으로 현재 경로).
+  - **타입**: `string`
+  - **필수**: 예
+
+- `href: string`
+  - **설명**: 비교할 두 번째 URL 문자열 또는 경로명(일반적으로 내비게이션 링크의 `href`).
+  - **타입**: `string`
+  - **필수**: 예
+
+- `locales: Locales[]`
+  - **설명**: 지원되는 로케일의 선택적 배열입니다. 기본값은 프로젝트에 구성된 로케일입니다.
+  - **타입**: `Locales[]`
+  - **필수**: 아니오 (선택)
+
+### 반환값
+
+- **타입**: `boolean`
+- **설명**: 두 입력이 동일한 로케일 독립적인 경로로 확인되면 `true`, 그렇지 않으면 `false`를 반환합니다.
+
+---
+
+## 사용 예시
+
+### 기본 사용법
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { comparePaths } from "intlayer";
+
+comparePaths("/ru/path", "/path"); // true
+comparePaths("/ru/path/", "/path"); // true
+comparePaths("/ru/path", "/path/"); // true
+comparePaths("/ru/", "/"); // true
+comparePaths("/ru", "/"); // true
+comparePaths("ru/path", "/path"); // true
+comparePaths("", "/"); // true
+comparePaths("/ru", ""); // true
+comparePaths("/ru/path", "/other"); // false
+```
+
+### 절대 및 상대 URL
+
+```typescript
+import { comparePaths } from "intlayer";
+
+comparePaths("https://example.com/ru/path", "/path"); // true
+```
+
+### 활성 내비게이션 링크 강조 표시
+
+```tsx
+import { comparePaths } from "intlayer";
+import { useLocation } from "react-router";
+
+const NavLink = ({ href, children }) => {
+  const { pathname } = useLocation();
+  const isActive = comparePaths(pathname, href);
+
+  return (
+    <a href={href} aria-current={isActive ? "page" : undefined}>
+      {children}
+    </a>
+  );
+};
+```
+
+---
+
+## normalizePath
+
+`normalizePath`는 `comparePaths`에서 사용하는 로케일 독립적인 정규 경로명을 반환합니다. 로케일 세그먼트, 프로토콜/호스트, 쿼리 문자열 및 해시를 제거하고, 단일 선행 슬래시를 확인하며, 루트를 제외한 모든 후행 슬래시를 제거하고, 빈 값의 경우 `/`로 대체합니다.
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { normalizePath } from "intlayer";
+
+normalizePath("/ru/path"); // "/path"
+normalizePath("/ru/path/"); // "/path"
+normalizePath("ru/path"); // "/path"
+normalizePath("/ru/"); // "/"
+normalizePath("/ru"); // "/"
+normalizePath(""); // "/"
+normalizePath("https://example.com/ru/path"); // "/path"
+```
+
+---
+
+## 관련 함수
+
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getPathWithoutLocale.md): URL 또는 경로에서 로케일 세그먼트를 제거합니다.
+- [`getPrefix`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getPrefix.md): 주어진 로케일에 대한 URL 접두사를 결정합니다.
+- [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getLocalizedUrl.md): 특정 로케일에 대한 현지화된 URL을 생성합니다.
+
+---
+
+## TypeScript
+
+```typescript
+function normalizePath(inputUrl: string, locales?: Locales[]): string;
+
+function comparePaths(
+  pathname: string,
+  href: string,
+  locales?: Locales[]
+): boolean;
+```

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

@@ -14,6 +14,9 @@ slugs:
   - intlayer
   - exports
 history:
+  - version: 9.0.0
+    date: 2026-06-23
+    changes: "comparePaths 유틸리티 추가"
   - version: 8.0.0
     date: 2026-01-21
     changes: "모든 내보내기에 대한 문서 통합"
@@ -119,6 +122,8 @@ import "intlayer";
 | `getMultilingualUrls`  | `Function` | 지원되는 모든 로케일에 대한 URL을 생성합니다. | [getMultilingualUrls](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getMultilingualUrls.md)   |
 | `getPathWithoutLocale` | `Function` | 경로에서 로케일 접두사를 제거합니다.          | [getPathWithoutLocale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getPathWithoutLocale.md) |
 | `getPrefix`            | `Function` | 경로에서 로케일 접두사를 가져옵니다.          | [getPrefix](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getPrefix.md)                       |
+| `comparePaths`         | `Function` | 로케일을 무시하고 두 경로를 비교합니다.       | [comparePaths](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/comparePaths.md)                 |
+| `normalizePath`        | `Function` | 경로를 로케일 독립적인 경로로 정규화합니다.   | [comparePaths](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/comparePaths.md)                 |
 | `getHTMLTextDir`       | `Function` | 텍스트 방향(LTR/RTL)을 가져옵니다.            | [getHTMLTextDir](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getHTMLTextDir.md)             |
 | `validatePrefix`       | `Function` | 로케일 접두사를 검증합니다.                   | [validatePrefix](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/validatePrefix.md)             |
 

package/docs/ko/packages/intlayer/getLocalizedUrl.md

@@ -36,6 +36,36 @@ author: aymericzip
 
 ---
 
+## 함수 서명
+
+```typescript
+getLocalizedUrl(
+  url: string,                   // 필수
+  currentLocale: Locales,        // 필수
+  options?: {                    // 선택사항
+    locales?: Locales[];
+    defaultLocale?: Locales;
+    mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params';
+  }
+): string
+```
+
+---
+
+## 매개변수
+
+### 필수 파라미터
+
+- `url: string`
+  - **Description**: 로케일을 접두사로 추가할 원본 URL 문자열입니다.
+  - **Type**: `string`
+  - **Required**: Yes
+
+- `currentLocale: Locales`
+  - **Description**: URL이 로컬라이제이션되는 현재 로케일입니다.
+  - **Type**: `Locales`
+  - **Required**: Yes
+
 ## 매개변수
 
 - `url: string`
@@ -70,6 +100,25 @@ author: aymericzip
 
 ## 사용 예시
 
+### 기본 사용법 (필수 매개변수만 사용)
+
+국제화 설정으로 프로젝트를 구성한 후에는 필수 매개변수만으로 함수를 사용할 수 있습니다:
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { getLocalizedUrl, Locales } from "intlayer";
+
+// 프로젝트의 locales, defaultLocale 및 mode 구성을 사용합니다
+getLocalizedUrl("/about", Locales.FRENCH);
+// 출력: "/fr/about" (French가 지원되고 mode가 'prefix-no-default'라고 가정)
+
+getLocalizedUrl("/about", Locales.ENGLISH);
+// 출력: "/about" 또는 "/en/about" (mode 설정에 따라 다름)
+```
+
+### 고급 사용법 (선택적 매개변수 포함)
+
+선택적 `options` 매개변수를 제공하여 기본 구성을 재정의할 수 있습니다:
+
 ### 상대 URL
 
 ```typescript codeFormat={["typescript", "esm"]}
@@ -117,6 +166,30 @@ getLocalizedUrl(
 // 출력: 기본(영어) 로케일의 경우 "/about"
 ```
 
+### 부분 Configuration Override
+
+선택적 매개변수 중 일부만 제공할 수도 있습니다. 함수는 지정하지 않은 매개변수에 대해 프로젝트 configuration을 사용합니다:
+
+```typescript codeFormat="typescript"
+import { getLocalizedUrl, Locales } from "intlayer";
+
+// locales만 override, defaultLocale과 mode는 프로젝트 config 사용
+getLocalizedUrl("/about", Locales.SPANISH, {
+  locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+});
+
+// mode만 override, locales과 defaultLocale은 프로젝트 config 사용
+getLocalizedUrl("/about", Locales.ENGLISH, {
+  mode: "prefix-all", // 기본 locale을 포함한 모든 locale에 prefix 강제
+});
+
+// 여러 옵션 override
+getLocalizedUrl("/about", Locales.FRENCH, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "search-params", // 쿼리 매개변수 사용: /about?locale=fr
+});
+```
+
 ### 절대 URL
 
 ```typescript