@intlayer/docs 8.12.4 → 9.0.0-canary.10

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

@@ -0,0 +1,92 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: intlayerMinify Vite 플러그인 문서 | vite-intlayer
+description: 컴파일된 Intlayer 사전 JSON 파일을 압축(Minify)하고, 필요에 따라 콘텐츠 필드 이름을 난독화하여 번들 크기를 줄이는 Vite 플러그인입니다.
+keywords:
+  - intlayerMinify
+  - vite
+  - 플러그인
+  - 압축
+  - 번들 크기
+  - 사전
+  - 국제화
+  - i18n
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerMinify
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "문서 초기화"
+author: aymericzip
+---
+
+# intlayerMinify
+
+`intlayerMinify`는 프로덕션 빌드 중에 컴파일된 사전 JSON 파일을 압축(minify)하는 Vite 플러그인입니다. 불필요한 모든 공백을 제거하고, `intlayerPrune`과 결합하면 번들 크기를 더욱 줄이기 위해 콘텐츠 필드 이름을 짧은 알파벳 별칭(`a`, `b`, `c`, …)으로 선택적으로 변경합니다.
+
+> [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/vite-intlayer/intlayer.md)를 사용하면 이 플러그인은 자동으로 포함되고 구성됩니다. 플러그인 스택을 직접 구성할 때만 수동으로 등록해야 합니다.
+
+## 사용법
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerMinify, intlayerPrune } from "vite-intlayer";
+import { createPruneContext } from "@intlayer/babel";
+
+const pruneContext = createPruneContext();
+
+export default defineConfig({
+  plugins: [
+    intlayerPrune(intlayerConfig, pruneContext),
+    intlayerMinify(intlayerConfig, pruneContext),
+  ],
+});
+```
+
+## 활성화 조건
+
+`intlayerMinify`는 다음 세 가지가 모두 참일 때만 활성화됩니다:
+
+1. Vite 명령어가 `build`인 경우 ( `serve` / dev가 아님).
+2. `build.optimize`가 `true`이거나 (빌드의 기본값인 `undefined`여서 `true`로 설정된 경우).
+3. Intlayer 설정에서 `build.minify`가 `true`인 경우.
+
+에디터는 완전하고 사람이 읽을 수 있는 사전 콘텐츠를 필요로 하므로 `editor.enabled`가 `true`이면 자동으로 **비활성화**됩니다.
+
+## 압축 대상
+
+플러그인은 `intlayer.system`에서 확인된 다음 두 개의 사전 위치를 대상으로 합니다:
+
+- `dictionariesDir` — 정적 모든 언어 사전 (예: `.intlayer/dictionaries/*.json`)
+- `dynamicDictionariesDir` — 언어별 동적 사전
+
+> 페치 모드 사전(`fetchDictionariesDir`)은 런타임에 원래 필드 이름을 사용하여 원격 API에서 제공되므로 **절대** 압축되지 않습니다. 필드 이름을 바꾸면 서버 응답과 클라이언트 측 속성 액세스 사이에 불일치가 발생할 수 있기 때문입니다.
+
+## 필드 이름 난독화 (속성 압축)
+
+`intlayerPrune`이 코드베이스를 분석하고 `pruneContext.dictionaryKeyToFieldRenameMap`을 채우면, `intlayerMinify`도 콘텐츠 필드 이름을 짧은 별칭으로 바꿉니다. 예를 들어:
+
+```json
+// 변경 전
+{ "key": "myDict", "content": { "title": "Hello", "description": "World" } }
+
+// 변경 후 (난독화 포함)
+{ "key": "myDict", "content": { "a": "Hello", "b": "World" } }
+```
+
+이에 해당하는 소스 파일 속성 액세스는 `intlayerOptimize` 내부의 Babel 과정을 통해 이름이 변경되므로 런타임 동작은 그대로 유지됩니다.
+
+Intlayer 내부 필드(`nodeType`, `translation` 등)는 이름이 바뀌지 않습니다.
+
+## 예외적 사전 (Edge-cases)
+
+`pruneContext.dictionariesWithEdgeCases`에 플래그가 지정된 사전(정리 단계에서 감지된 구조적 기형)은 손상된 데이터가 전달되는 것을 방지하기 위해 완전히 무시되며, 압축되거나 난독화되지 않습니다.
+
+## 한정자 그룹 (컬렉션 / 변형 / 메타 레코드)
+
+`qualifierTypes` 배열을 갖는 사전(컬렉션, 변형 및 메타 레코드)의 경우 플러그인은 `qualifierTypes` 배열과 `meta` 사이드 맵을 그대로 유지합니다. `content` 항목의 필드 이름만 난독화됩니다. 런타임에 선택기 일치에 사용되는 복합 키는 절대 수정되지 않습니다.

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/vite-intlayer/intlayerPrune.md

@@ -21,6 +21,7 @@ history:
   - version: 8.0.0
     date: 2026-01-21
     changes: "문서 초기화"
+author: aymericzip
 ---
 
 # intlayerPrune Vite 플러그인 문서

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

@@ -14,9 +14,13 @@ 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)에 대한 문서 통합"
+author: aymericzip
 ---
 
 # vue-intlayer 패키지
@@ -58,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/packages/vue-intlayer/useRewriteURL.md

@@ -14,6 +14,7 @@ slugs:
   - packages
   - vue-intlayer
   - useRewriteURL
+author: aymericzip
 ---
 
 # useRewriteURL Composable

package/docs/ko/per_locale_file.md

@@ -18,6 +18,7 @@ history:
   - version: 5.5.10
     date: 2025-06-29
     changes: "초기 이력"
+author: aymericzip
 ---
 
 # Intlayer에서 `지역별` 콘텐츠 선언 방법