@intlayer/docs 9.4.1 → 9.4.3

package/blog/ko/is_vue-i18n_outdated.md

@@ -0,0 +1,338 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: 2026년에도 vue-i18n을 계속 써야 할까요?
+description: vue-i18n은 지난 10년간 Vue 및 Nuxt 생태계의 표준이었습니다. 하지만 벤치마크 결과 웹에서 가장 무거운 i18n 런타임으로 나타났습니다. 그 원인을 분석합니다.
+keywords:
+  - vue-i18n
+  - Intlayer
+  - 국제화
+  - i18n
+  - Vue
+  - Nuxt
+  - 번들 크기
+  - 블로그
+slugs:
+  - blog
+  - is-vue-i18n-outdated
+author: aymericzip
+---
+
+# 2026년에도 vue-i18n을 계속 써야 할까요?
+
+Vue 생태계에서 `vue-i18n`만큼 압도적인 점유율을 기록한 라이브러리는 드뭅니다. Vue 2 시절부터 Kazupon의 주도하에 성장해 왔으며, `@nuxtjs/i18n`의 기반이자 다국어 지원 Vue 프로젝트의 사실상 표준이었습니다.
+
+그러나 2026년 벤치마크 결과는 놀라운 사실을 드러냈습니다. **`vue-i18n`은 테스트한 모든 주요 프론트엔드 프레임워크 중 가장 무거운 지역화 런타임이었습니다.**
+
+Vite + Vue 기반의 가벼운 기본 애플리케이션(31.5 KB)에 `vue-i18n`을 추가하자, 페이지당 평균 JavaScript 크기가 **136.4 KB**로 4배 이상 치솟았습니다.
+
+본래 가볍고 기민한 프레임워크로 사랑받는 Vue에서, 왜 i18n 도구만 이토록 비대해졌을까요? 그리고 순수 런타임 모델은 오늘날에도 유효할까요?
+
+<TOC/>
+
+## 핵심 요약
+
+**테스트 대상 중 가장 무거운 런타임:**
+
+텍스트를 추가하기도 전에 이미 **24.3 KB (gzip 기준, Minified 시 83.2 KB)**의 크기를 차지하여, `intlayer` 코어 런타임(2.7 KB) 대비 **약 9배 무겁습니다**.
+
+**페이지 페이로드 330% 증가:**
+
+`vue-i18n`은 31.5 KB에 불과했던 기본 Vue 페이지를 136.4 KB로 늘려놓았습니다. 반면 Intlayer는 59.3 KB에 그쳐 **56% 더 가벼운 페이로드**를 제공합니다.
+
+**브라우저로 번들링되는 컴파일러:**
+
+번들러에 특정 별칭(alias)을 수동 설정하지 않는 한, `vue-i18n`은 브라우저에서 텍스트를 실시간 파싱하기 위해 전체 메시지 컴파일러를 클라이언트로 전송합니다.
+
+**유지보수 추세:**
+
+지난 1년간 `vue-i18n`은 약 259개의 커밋을 기록했으나, 대부분 버그 수정과 Vue 마이너 버전 대응에 집중되었습니다.
+
+**공식 현대적 도구의 부재:**
+
+공식 Language Server (LSP), AI용 MCP 서버, CLI 기반 자동 번역 등 차세대 워크플로우를 위한 도구가 부족합니다.
+
+## 유지보수 vs. 현대적 도구 비교
+
+| 저장소                | 스타                                                                                                                                                   | 전체 커밋                                                                                                                                                           | 연간 커밋                                                                                                                                                          | 최근 커밋                                                                                                                                    |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `intlify/vue-i18n`    | [![stars](https://img.shields.io/github/stars/intlify/vue-i18n?style=for-the-badge&label=stars)](https://github.com/intlify/vue-i18n/stargazers)       | [![commits](https://img.shields.io/github/commit-activity/t/intlify/vue-i18n?style=for-the-badge&label=commits)](https://github.com/intlify/vue-i18n/commits)       | [![yearly](https://img.shields.io/github/commit-activity/y/intlify/vue-i18n?style=for-the-badge&label=%2Fyear)](https://github.com/intlify/vue-i18n/commits)       | [![last](https://img.shields.io/github/last-commit/intlify/vue-i18n?style=for-the-badge)](https://github.com/intlify/vue-i18n/commits)       |
+| `aymericzip/intlayer` | [![stars](https://img.shields.io/github/stars/aymericzip/intlayer?style=for-the-badge&label=stars)](https://github.com/aymericzip/intlayer/stargazers) | [![commits](https://img.shields.io/github/commit-activity/t/aymericzip/intlayer?style=for-the-badge&label=commits)](https://github.com/aymericzip/intlayer/commits) | [![yearly](https://img.shields.io/github/commit-activity/y/aymericzip/intlayer?style=for-the-badge&label=%2Fyear)](https://github.com/aymericzip/intlayer/commits) | [![last](https://img.shields.io/github/last-commit/aymericzip/intlayer?style=for-the-badge)](https://github.com/aymericzip/intlayer/commits) |
+
+최근 12개월 활동 비교:
+
+- `intlify/vue-i18n`: **259 커밋** (Vue 3 및 Nuxt 유지보수 위주).
+- `aymericzip/intlayer`: **4,343 커밋** (컴파일러 고도화, LSP 도구, AI 에이전트 연동 작업 등 지속 개발).
+
+[![Star History Chart](https://api.star-history.com/chart?repos=intlify%2Fvue-i18n%2Caymericzip%2Fintlayer&type=date&legend=top-left)](https://www.star-history.com/#intlify/vue-i18n&aymericzip/intlayer)
+
+오래된 라이브러리는 안정성이 뛰어납니다. 하지만 오늘날의 프론트엔드는 빌드 타임 AST 변환, 데드 코드 제거, AI 자동화에 기반하고 있습니다. 런타임에 종속된 구조로는 이러한 혁신을 온전히 따라잡기 어렵습니다.
+
+## Vite + Vue 성능 측정 결과
+
+Vite 및 Vue 3 기반 10개 페이지, 10개 언어 애플리케이션 측정:
+
+<I18nBenchmark framework="vite-vue" vertical/>
+
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-vite_vue.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> 프로덕션 gzip 압축을 적용하여 실제 브라우저에서 측정했습니다. 세부 사항은 [Vue 벤치마크 문서](https://intlayer.org/ko/doc/benchmark/vue)에서 확인할 수 있습니다.
+
+### 라이브러리 초기 오버헤드
+
+번역 텍스트를 불러오기 전의 순수 라이브러리 크기:
+
+| 라이브러리        | Gzip 기준  | Minified 기준 |
+| ----------------- | ---------- | ------------- |
+| `vue-i18n@11.4.0` | 24.3 KB    | 83.2 KB       |
+| `intlayer@8.7.12` | **2.7 KB** | **7.6 KB**    |
+
+`vue-i18n`의 런타임 엔진만으로 **24.3 KB (gzip)**에 달해 Vue 코어 전체 크기와 맞먹습니다. 반면 Intlayer는 단 **2.7 KB**만 차지합니다.
+
+### 페이지 크기 및 불필요한 번역 누수
+
+| 구성            | 평균 페이지 JS (gz) | 타 언어 누수율 | 타 페이지 누수율 | 평균 컴포넌트 (gz) |
+| --------------- | ------------------- | -------------- | ---------------- | ------------------ |
+| 기본(i18n 없음) | 31.5 KB             | 0.0%           | 90.0%            | 0.9 KB             |
+| `vue-i18n`      | **136.4 KB**        | 50.2%          | 90.0%            | 196.0 KB           |
+| Intlayer        | **59.3 KB**         | 51.1%          | **0.0%**         | **6.5 KB**         |
+
+### 측정 주요 결과
+
+**높은 상대적 증가율:**
+
+Vue 프레임워크 자체의 기본 크기가 워낙 작기 때문에(~31 KB), `vue-i18n`을 도입하면 페이지 페이로드가 4배 이상 커집니다.
+
+**타 페이지로의 번역 데이터 누수:**
+
+기본 설정 상태에서는 특정 라우트에 내려오는 **텍스트 데이터의 90%**가 다른 페이지용입니다. Intlayer는 이를 완전히 제거하여 누수율 **0.0%**를 기록했습니다.
+
+**개별 컴포넌트의 비대화:**
+
+사전이 반복 복제되면서 `vue-i18n`의 지역 스코프 컴포넌트 크기는 평균 196 KB까지 치솟았으나, Intlayer에서는 **6.5 KB**에 불과했습니다.
+
+## vue-i18n이 무거운 이유
+
+### 브라우저로 전송되는 AST 컴파일러
+
+`vue-i18n`은 자체 메시지 형식 컴파일러를 내장하고 있습니다. 복수형 규칙이나 변수 치환 로직이 브라우저 런타임에서 AST(추상 구문 트리)로 실시간 변환됩니다.
+
+이를 방지하려면 번들러에서 `vue-i18n/dist/vue-i18n.runtime.esm-bundler.js`로 별칭을 지정하고 `@intlify/unplugin-vue-i18n`을 통해 사전 컴파일을 수행해야 하지만, 많은 프로젝트에서 이 과정이 생략됩니다.
+
+### 모놀리식 기능 구조
+
+날짜 및 숫자 포매터, 링크드 메시지, 레거시 Options API 지원 브리지(`$t`, `v-t`), 반응형 프록시가 모두 포함되어 있습니다. `<script setup>` 내에서 단순 텍스트만 표시하고 싶더라도 전체 시스템이 함께 로드됩니다.
+
+### 동적 키로 인한 트리 쉐이킹 차단
+
+`"home.hero.title"` 키가 런타임에 평가되므로 번들러는 실제로 쓰이는 텍스트를 식별할 수 없습니다. 쓰이지 않는 문구도 번들에 남아 있게 됩니다.
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="vue-i18n" value="vue-i18n">
+
+```vue fileName="Hero.vue"
+<script setup>
+import { useI18n } from "vue-i18n";
+
+const { t } = useI18n();
+</script>
+
+<template>
+  <h1>{{ t("home.hero.title") }}</h1>
+</template>
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```vue fileName="Hero.vue"
+<script setup>
+import { useIntlayer } from "vue-intlayer";
+
+const { title } = useIntlayer("hero");
+</script>
+
+<template>
+  <h1>{{ title }}</h1>
+</template>
+```
+
+  </Tab>
+</Tabs>
+
+[Intlayer 컴파일러](https://intlayer.org/ko/doc/compiler)는 컴포넌트가 접근하는 프로퍼티를 명확히 파악하여 클라이언트 번들 생성 전에 미사용 번역을 안전하게 배제합니다. 자세한 내용은 [번들 최적화](https://intlayer.org/ko/doc/concept/bundle-optimization)를 참고하세요.
+
+## 개발자 경험 (DX) 비교
+
+### 격리된 JSON 폴더 vs. 컴포넌트와 함께 배치
+
+`vue-i18n`에서는 텍스트가 멀리 떨어진 `locales/` 디렉터리에 머뭅니다. Intlayer를 사용하면 컴포넌트 파일 바로 옆에 콘텐츠 파일을 선언할 수 있습니다.
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="vue-i18n" value="vue-i18n">
+
+```json fileName="locales/en.json"
+{
+  "hero": {
+    "title": "Ship in every language"
+  }
+}
+```
+
+```json fileName="locales/ko.json"
+{
+  "hero": {
+    "title": "모든 언어로 출시하세요"
+  }
+}
+```
+
+```vue fileName="Hero.vue"
+<script setup>
+import { useI18n } from "vue-i18n";
+
+const { t } = useI18n();
+</script>
+
+<template>
+  <h1>{{ t("hero.title") }}</h1>
+</template>
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```ts fileName="Hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero",
+  content: {
+    title: t({
+      en: "Ship in every language",
+      ko: "모든 언어로 출시하세요",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+```vue fileName="Hero.vue"
+<script setup>
+import { useIntlayer } from "vue-intlayer";
+
+const { title } = useIntlayer("hero");
+</script>
+
+<template>
+  <h1>{{ title }}</h1>
+</template>
+```
+
+  </Tab>
+</Tabs>
+
+`Hero.vue`를 삭제하거나 이동하면 해당 콘텐츠 선언 파일도 자연스럽게 함께 관리됩니다.
+
+### 에디터 자동완성 vs. 엄격한 완전성 보장
+
+`DefineLocaleMessage`를 통해 기본 스키마 기준의 자동완성은 지원됩니다. 하지만 모든 언어의 완결성을 보장하지는 못합니다. `ko.json`에서 키를 지워도 TypeScript 빌드가 멈추지 않습니다.
+
+Intlayer는 사전을 엄격하게 검증합니다. [`strictMode`](https://intlayer.org/ko/doc/concept/configuration)를 활성화하면 어떤 언어에서든 번역이 누락될 경우 즉각 빌드 에러가 발생합니다.
+
+### IDE 및 AI 도구 지원
+
+| 기능                      | `vue-i18n`           | Intlayer                                                               |
+| ------------------------- | -------------------- | ---------------------------------------------------------------------- |
+| **VS Code 확장 프로그램** | 서드파티 (i18n Ally) | ✅ [공식 확장 프로그램](https://intlayer.org/ko/doc/vs-code-extension) |
+| **Language Server (LSP)** | ❌ 없음              | ✅ [전용 LSP](https://intlayer.org/ko/doc/lsp)                         |
+| **AI용 MCP 서버**         | ❌ 없음              | ✅ [내장 MCP 서버](https://intlayer.org/ko/doc/mcp-server)             |
+| **에이전트 스킬 세트**    | ❌ 없음              | ✅ [자율 에이전트 스킬](https://intlayer.org/ko/doc/agent_skills)      |
+| **인컨텍스트 비주얼 CMS** | ❌ 없음              | ✅ [무료 오픈소스 CMS](https://intlayer.org/ko/doc/concept/editor)     |
+
+## 번역 워크플로우
+
+`vue-i18n`에는 자체적인 번역 생성 명령어가 없습니다. 개발자들은 파일을 Crowdin이나 Phrase 같은 외부 플랫폼으로 내보내야 합니다.
+
+Intlayer는 완전한 네이티브 도구를 기본 제공합니다.
+
+**로컬 AI 자동 채우기 (`intlayer fill`):**
+
+소유한 OpenAI, Anthropic, Mistral, Gemini API 키를 사용하여 누락된 번역을 자동으로 생성합니다.
+
+**자체 호스팅 비주얼 CMS:**
+
+[Intlayer CMS](https://intlayer.org/ko/doc/concept/cms)를 연동하면 기획자나 마케터가 웹 UI에서 문구를 직접 수정하고 변경 사항을 Git에 커밋할 수 있습니다.
+
+**오픈소스 라이선스:**
+
+모든 컴포넌트가 Apache 2.0 라이선스로 제공됩니다.
+
+## 지금도 vue-i18n이 유효한 경우는?
+
+<AccordionGroup>
+<Accordion header="기존 대규모 Nuxt 2/3 프로젝트">
+
+라우팅 구조가 `@nuxtjs/i18n`과 깊게 얽혀 있다면 시스템을 전면 개편하는 것이 부담스러울 수 있습니다.
+
+</Accordion>
+<Accordion header="특수한 ICU 포맷팅 요구사항">
+
+고도로 중첩된 메시지 링크나 복잡한 숫자/날짜 규칙을 폭넓게 사용 중인 경우.
+
+</Accordion>
+<Accordion header="가벼운 토이 프로젝트">
+
+번들 크기가 성능이나 사용자 경험에 결정적인 영향을 미치지 않는 경우.
+
+</Accordion>
+</AccordionGroup>
+
+## 기존 vue-i18n 설정을 어떻게 개선할 수 있을까요?
+
+Intlayer는 `vue-i18n` 및 `@nuxtjs/i18n`의 함수 시그니처(`useI18n`, `$t`, `<i18n-t>`)를 그대로 재현하는 드롭인 호환성 패키지를 제공합니다. 템플릿이나 Composable을 다시 작성하지 않고도 컴파일러 기반의 가벼운 아키텍처가 제공하는 혜택을 누릴 수 있습니다.
+
+설정은 단 한 줄의 명령어로 완료됩니다:
+
+```bash packageManager="npm"
+npx intlayer init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer init --interactive
+```
+
+이 대화형 CLI는 다음 작업을 자동으로 수행합니다:
+
+1. `@intlayer/vue-i18n` 또는 `@intlayer/nuxt-i18n` 호환성 패키지를 설치합니다.
+2. Vite 또는 Nuxt 번들러 별칭(alias)을 설정하여 기존 임포트 및 템플릿 태그가 Intlayer로 원활하게 라우팅되도록 연결하므로, `vue-i18n`을 `package.json`에서 안전하게 제거할 수 있습니다.
+3. 에디터 내 언어 서버(LSP) 진단을 즉시 활성화하고, 클라이언트 번들에서 24KB 크기의 AST 파서를 완전히 제거하며, 대대적인 리팩토링 없이 로컬 AI 번역 워크플로우를 사용할 수 있게 합니다.
+
+단계별 세부 내용은 다음 가이드를 참고하세요:
+
+- **쉬운 호환성:** [`vue-i18n` 호환성 레이어](https://intlayer.org/ko/doc/compatibility/vue-i18n) 또는 [`@nuxtjs/i18n` 호환性 레이어](https://intlayer.org/ko/doc/compatibility/nuxtjs-i18n)를 이용해 기존 템플릿 코드를 그대로 유지할 수 있습니다.
+- **단계별 이전 가이드:** JSON 파일을 구조화된 사전으로 변환하는 가이드를 참고하세요: [vue-i18n 마이그레이션](https://intlayer.org/ko/doc/migration/vue-i18n), [@nuxtjs/i18n 마이그레이션](https://intlayer.org/ko/doc/migration/nuxtjs-i18n).
+- **하이브리드 구성:** `vue-i18n`을 런타임으로 유지하면서, [Intlayer와 vue-i18n을 함께 활용](https://intlayer.org/ko/blog/intlayer-with-vue-i18n)하여 엄격한 타입 검사와 로컬 AI 번역만 먼저 도입할 수도 있습니다.
+
+무료 [i18n SEO 스캐너](https://intlayer.org/i18n-seo-scanner)를 통해 현재 웹사이트의 번들 누수와 크기를 분석해 보세요:
+
+<ClickToOpenIframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## 관련 글 보기
+
+- [Vue & Vite i18n 벤치마크: 성능 세부 분석](https://intlayer.org/ko/doc/benchmark/vue)
+- [vue-i18n vs Intlayer 비교 분석](https://intlayer.org/ko/blog/vue-i18n-vs-intlayer)
+- [2026년에도 next-intl을 계속 써야 할까요?](https://intlayer.org/ko/blog/is-next-intl-outdated)
+- [컴파일러 기반 i18n과 선언적 접근법의 차이](https://intlayer.org/ko/blog/compiler-vs-declarative-i18n)

package/blog/ko/list_i18n_technologies/build-tools/vite.md

@@ -0,0 +1,179 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Vite i18n: glob import, 청크 분할 및 빌드 타임 메시지"
+description: i18n에서 실제로 Vite 고유의 영역은 무엇인가. import.meta.glob을 활용한 지연 로딩, 라우트별 분할이 의도대로 동작하지 않는 이유, HMR 누락과 빌드 타임 플러그인을 다룹니다.
+keywords:
+  - vite i18n
+  - import.meta.glob
+  - vite 코드 분할
+  - 번역 지연 로딩
+  - vite 플러그인 i18n
+  - rollup 청크
+slugs:
+  - blog
+  - i18n-technologies
+  - build-tools
+  - vite
+author: aymericzip
+---
+
+# Vite i18n: 프레임워크가 아닌 Vite 자체에 관한 아키텍처
+
+대부분의 "Vite i18n" 튜토리얼은 단지 Vite를 번들러로 사용할 뿐인 React나 Vue 튜토리얼에 가깝습니다. 이 글은 그 아래 계층을 다룹니다: 카탈로그가 어떻게 임포트되고, Rollup이 이를 어떻게 번들링하며, 직접 작성한 지연 로딩(lazy loading) 코드가 왜 실제로는 지연 로딩되지 않는지 살펴봅니다.
+
+## 목차
+
+<TOC/>
+
+## 정적 임포트는 기본 동작이며 즉시 로딩됩니다
+
+가장 단순한 설정은 모듈 최상단에서 모든 언어 카탈로그를 정적으로 임포트하는 것입니다:
+
+```ts fileName="src/i18n.ts"
+import en from "./locales/en.json";
+import fr from "./locales/fr.json";
+import ja from "./locales/ja.json";
+```
+
+이렇게 하면 세 개의 카탈로그가 엔트리 청크에 포함되어 모든 페이지, 모든 사용자에게 전달됩니다. 지원 언어가 두 개이고 텍스트가 백 개 정도라면 문제없지만, 언어가 열 개를 넘어서면 번들 크기에서 가장 불필요한 낭비 요소가 됩니다.
+
+## `import.meta.glob`과 흔히 범하는 설정 실수
+
+Vite의 glob import 기능은 이에 대한 일반적인 해결책입니다:
+
+```ts
+const catalogs = import.meta.glob("./locales/*.json");
+
+export const loadCatalog = async (locale: string) => {
+  const load = catalogs[`./locales/${locale}.json`];
+  return (await load()) as Record<string, string>;
+};
+```
+
+지연 로딩(Lazy)이 기본값입니다. 각 엔트리는 동적 임포트를 반환하는 함수가 되며, Rollup은 파일별로 독립된 청크를 생성합니다. 여기에 `{ eager: true }`를 추가하면 모든 파일이 부모 모듈 안에 인라인으로 포함되어, 방지하고자 했던 바로 그 문제가 다시 발생합니다:
+
+```ts
+// 모든 언어가 엔트리 청크에 한꺼번에 포함됩니다 (비권장)
+const catalogs = import.meta.glob("./locales/*.json", { eager: true });
+```
+
+주의할 점은 개발 환경에서는 Vite가 개별 모듈을 번들링하지 않고 직접 제공하므로 두 방식 모두 정상 작동한다는 것입니다. 차이는 빌드 결과물인 `dist` 디렉터리에서만 나타납니다. `npx vite build && npx vite preview` 명령으로 빌드한 뒤 엔트리 청크에 무엇이 포함되어 있는지 직접 확인해 보세요.
+
+## 라우트별 분할이 의도대로 쪼개지지 않는 이유
+
+많은 개발자들이 예상치 못하는 부분입니다. 페이지별로 카탈로그를 분리했다고 가정해 봅시다:
+
+```
+locales/en/home.json
+locales/en/checkout.json
+```
+
+그런 다음 서로 다른 두 라우트가 `checkout.json`을 임포트하면, Rollup은 이를 두 페이지 모두에서 로드되는 공통 청크(shared chunk)로 격상시킵니다. Rollup의 청크 분할 알고리즘은 폴더 이름이 아니라 모듈 그래프의 의존 관계를 기반으로 작동합니다. 두 개 이상의 엔트리 포인트에서 접근 가능한 모듈은 자동으로 공통 청크가 됩니다. 세 번째 라우트가 추가되어도 변함이 없으며, 네 번째 라우트가 추가되면 청크 구성이 전혀 다르게 재편될 수도 있습니다.
+
+따라서 라우트별 카탈로그 분할은 임포트 그래프가 완전히 독립적일 때만 유지됩니다. 번들 최적화가 중요하다면 추측에 의존하지 말고 시각화 도구로 검증하세요:
+
+```bash
+npx vite build && npx vite-bundle-visualizer
+```
+
+청크 경계를 강제해야 한다면 `build.rollupOptions.output.manualChunks`를 활용할 수 있지만 수동 관리 비용이 발생합니다.
+
+## 카탈로그는 자동으로 핫 리로드(HMR)되지 않습니다
+
+컴포넌트를 수정하면 Vite가 즉시 화면을 교체합니다. 그러나 `locales/fr.json`을 수정하면 임포트 방식에 따라 아무 일도 일어나지 않을 수 있습니다. 동적으로 임포트된 JSON 파일은 자체적인 HMR 경계가 없으므로 모듈 그래프가 이를 사용하는 컴포넌트를 무효화해야 하는지 알지 못합니다.
+
+텍스트를 수정할 때마다 개발 서버를 재시작하는 개발자가 많지만, 이는 플러그인 레벨에서 해결 가능한 문제입니다. i18n 플러그인이 HMR 업데이트를 수신하여 실행 중인 앱에 새로운 메시지를 즉시 주입해 주어야 합니다. 라이브러리를 검토할 때 해당 Vite 플러그인이 이를 지원하는지 확인하세요.
+
+## `define`은 로케일을 빌드 결과물에 박아 넣습니다
+
+빌드 시점에 기본 로케일을 고정하고 싶은 유혹이 들 수 있습니다:
+
+```ts fileName="vite.config.ts"
+export default defineConfig({
+  define: {
+    __DEFAULT_LOCALE__: JSON.stringify(process.env.LOCALE ?? "en"),
+  },
+});
+```
+
+`define`은 컴파일 시점에 수행되는 단순 텍스트 치환입니다. 빌드 시 지정된 값이 코드에 영구적으로 박히기 때문에, 결과적으로 언어별로 별도의 빌드를 수행해야 합니다. 이는 Angular의 공식 i18n처럼 유효한 전략 중 하나이지만, 단일 배포본으로 모든 언어를 서비스하려는 목적에는 부합하지 않습니다.
+
+요청별로 달라져야 하는 값은 `define`에 넣지 말고 런타임에서 결정하도록 유지해야 합니다.
+
+## 메시지 파싱을 빌드 타임으로 이전하기
+
+이 생태계의 성숙한 도구들은 공통적으로 브라우저 내부에서 메시지를 파싱하는 방식을 중단하고 있습니다.
+
+| 플러그인                     | 빌드 타임으로 이전하는 작업                                             |
+| :--------------------------- | :---------------------------------------------------------------------- |
+| `@intlify/unplugin-vue-i18n` | vue-i18n 메시지를 렌더 함수로 컴파일 (런타임 전용 가벼운 번들 배포)     |
+| Lingui (매크로 + 플러그인)   | 카탈로그를 추출 및 컴파일하고 매크로를 메시지 ID로 치환                 |
+| Paraglide (inlang)           | 각 메시지를 트리쉐이킹 가능한 개별 함수로 컴파일                        |
+| `vite-intlayer`              | 컴포넌트 단위 딕셔너리 구축, 미사용 필드 제거(purge) 및 키 단축(minify) |
+
+이로써 두 가지 이점을 얻습니다: 런타임 메시지 컴파일러가 최종 번들에서 제외되고, 사용되지 않는 번역 항목을 정적으로 제거할 수 있습니다. 반면 개발 서버와 CI 모두에 플러그인이 필수적이며, Vite 환경 밖에서 단독 `tsc`나 테스트를 실행할 때 추가 설정이 필요합니다.
+
+vue-i18n이 대표적입니다. `@intlify/unplugin-vue-i18n`이 없으면 브라우저에서 `new Function`을 호출하는 컴파일러를 배포해야 하므로 불필요한 번들 크기와 CSP(Content Security Policy) 문제가 발생합니다.
+
+## SSR: 로케일 상태를 모듈 스코프에 보관하지 마세요
+
+프레임워크나 `vite-plugin-ssr`을 통해 SSR을 도입할 때 반드시 지켜야 할 원칙이 있습니다: 현재 로케일을 저장하는 모듈 레벨 변수는 해당 서버 프로세스의 모든 동시 요청 간에 공유됩니다.
+
+```ts
+// 브라우저에서는 안전하지만 서버에서는 요청 간 데이터 유출을 유발합니다
+export let currentLocale = "en";
+```
+
+동시에 서버에 접속한 두 사용자는 레이스 컨디션에 빠지게 되며, 한 사용자가 다른 사용자의 언어로 렌더링된 화면을 보게 됩니다. 로컬 개발 환경에서는 단일 요청만 발생하므로 재현되지 않습니다. 로케일은 반드시 매 요청마다 결정하여 컨텍스트나 프레임워크의 요청 로컬 저장소를 통해 명시적으로 전달하세요.
+
+## Intlayer의 Vite 플러그인
+
+Intlayer는 딕셔너리 빌드, 개발 모드 감시, 번들 최적화 파이프라인을 통합 처리하는 단일 플러그인을 제공합니다:
+
+```ts fileName="vite.config.ts"
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [react(), intlayer()],
+});
+```
+
+임포트 재작성, 미사용 콘텐츠 제거(purge), 키 축약(minify)이 기본 활성화되어 있습니다. 핵심 옵션은 `intlayer.config.ts`에서 설정합니다:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // 컴포넌트가 읽지 않는 콘텐츠 필드 자동 제거
+    minify: true, // 콘텐츠 키를 짧은 별칭으로 축약
+  },
+};
+
+export default config;
+```
+
+콘텐츠가 거대한 전역 파일 대신 각 컴포넌트 단위로 선언되므로, purge 단계에서 모듈 의존성 그래프를 정확히 분석하여 안전하게 사용되지 않는 텍스트를 걸러낼 수 있습니다. 자세한 내용은 [번들 최적화 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/bundle_optimization.md)를 참고하세요.
+
+## 흔한 실수들
+
+- **지연 로딩하려던 glob에 `{ eager: true }` 설정.** 개발 환경에서는 잘 돌아가지만 프로덕션에 모든 언어가 함께 배포됩니다.
+- **폴더 구조가 알아서 청크를 나눌 것이라 신뢰.** Rollup은 폴더가 아니라 임포트 관계를 따릅니다. 빌드 결과를 직접 측정하세요.
+- **번역 변경 사항을 보려고 개발 서버를 재시작.** 정상적인 동작이 아니며 플러그인의 HMR 핸들러 부재 때문입니다.
+- **`define`에 로케일을 주입.** 언어별 독립 빌드를 강제하게 됩니다.
+- **SSR 환경에서 모듈 레벨에 로케일 상태 저장.** 동시 요청 시 언어가 뒤섞이는 심각한 버그가 발생합니다.
+- **개발 서버에서 번들 성능 벤치마크.** 번들링되지 않은 모듈의 동작은 프로덕션 번들과 아무 상관이 없습니다.
+
+## 더 알아보기
+
+- [번들 최적화: purge, minify 및 실제 브라우저로 전송되는 데이터](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/bundle_optimization.md)
+- [프레임워크 간 벤치마크 리포트](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/benchmark/index.md)
+- [설정 레퍼런스](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)
+- [Vite 및 React 환경에서 Intlayer 설정하기](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_vite+react.md)
+- [i18next 호환 어댑터](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compat/i18next.md)
+- [React i18n: 프로바이더 모델의 동작 원리](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ko/list_i18n_technologies/frameworks/react.md)
+- [Vue i18n: 작동 원리와 주의점](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ko/list_i18n_technologies/frameworks/vue.md)
+- [컴포넌트 단위 i18n vs 중앙 집중식 i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ko/per-component_vs_centralized_i18n.md)

package/blog/ko/list_i18n_technologies/frameworks/angular.md

@@ -23,8 +23,6 @@ author: aymericzip
 
 오늘날의 상호 연결된 세계에서 웹사이트를 여러 언어로 제공하는 것은 사용자 경험을 개선하고 도달 범위를 크게 확장할 수 있습니다. Angular로 작업하는 개발자에게 국제화(i18n)를 구현하는 것은 애플리케이션 구조, SEO 및 성능을 보존하면서 번역 관리를 효율적으로 수행하는 데 중요합니다. 이 문서에서는 Angular의 내장 솔루션부터 인기 있는 서드파티 라이브러리까지 다양한 i18n 접근 방식을 탐구하여 프로젝트에 가장 적합한 선택을 할 수 있도록 도와줍니다.
 
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
-
 ## 국제화(i18n)가 무엇인가요?
 
 국제화는 종종 i18n이라고 불리며, 애플리케이션이 여러 언어와 문화적 맥락을 지원하도록 설계하고 준비하는 과정입니다. Angular에서는 텍스트, 날짜, 숫자 및 UI 레이아웃이 다양한 로케일에 원활하게 적응할 수 있도록 앱을 구성하는 것을 의미합니다. 이러한 기초 작업을 올바르게 수행하면 앞으로의 번역 통합이 조직적이고 효율적으로 유지될 수 있습니다.

package/blog/ko/list_i18n_technologies/frameworks/react-native.md

@@ -25,8 +25,6 @@ author: aymericzip
 
 ---
 
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
-
 ## 국제화(i18n)란 무엇인가요?
 
 국제화(i18n)는 애플리케이션을 다양한 언어, 지역 형식 및 문화적 관습에 쉽게 적응할 수 있도록 구조화하는 것을 포함합니다. React Native에서 i18n은 버튼과 라벨의 문자열을 처리하는 것뿐만 아니라 사용자의 로케일에 따라 날짜, 시간, 통화 등을 형식화하는 것을 포함합니다. 적절하게 준비된 React Native 앱을 사용하면 대대적인 리팩토링 없이도 나중에 추가 언어와 로케일별 동작을 원활하게 통합할 수 있습니다.

package/blog/ko/list_i18n_technologies/frameworks/react.md

@@ -25,8 +25,6 @@ author: aymericzip
 
 ---
 
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
-
 ## 국제화(i18n)란 무엇인가요?
 
 국제화란 i18n의 약어로, 웹사이트가 여러 언어와 문화적 맥락을 지원할 수 있도록 디자인하고 준비하는 과정입니다. React에서 이는 문자열, 날짜 형식, 숫자 형식 및 레이아웃이 서로 다른 지역의 사용자에 맞게 쉽게 조정될 수 있도록 앱을 설정하는 것을 의미합니다. React 앱을 i18n에 대비시키는 것은 번역 및 기타 지역화 기능을 깔끔하게 통합할 수 있는 기초를 마련합니다.

package/blog/ko/list_i18n_technologies/frameworks/svelte.md

@@ -25,8 +25,6 @@ author: aymericzip
 
 ---
 
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/assets/i18n.webp)
-
 ## 국제화 (i18n)란 무엇인가요?
 
 국제화, 일반적으로 i18n으로 약칭되는 것은 귀하의 애플리케이션을 설계하고 구축하는 과정으로, 다양한 언어, 지역 및 문화 관습에 쉽게 적응할 수 있도록 하는 것입니다. Svelte에서는 일반적으로 번역 문자열을 설정하고, 날짜, 시간 및 숫자를 지역화하며, 사용자 인터페이스가 주요 코드 수정 없이 다양한 로케일 간에 동적으로 전환할 수 있도록 하는 것을 의미합니다.

package/blog/ko/list_i18n_technologies/frameworks/vue.md

@@ -25,8 +25,6 @@ author: aymericzip
 
 ---
 
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
-
 ## 국제화(i18n)란 무엇인가요?
 
 국제화(i18n)는 소프트웨어 애플리케이션(또는 웹사이트)을 여러 언어 및 문화적 관습에 맞게 준비하는 관행입니다. Vue.js 생태계 내에서, 이는 텍스트, 날짜, 숫자, 통화 및 기타 로컬화 가능한 요소가 다양한 로케일에 맞게 어떻게 조정될 수 있는지를 설정하는 것을 포함합니다. 처음부터 i18n을 설정함으로써, 새로운 언어를 추가하고 미래의 로컬화 요구를 처리할 수 있는 조직적이고 확장 가능한 구조를 보장하게 됩니다.

package/blog/ko/what_is_internationalization.md

@@ -20,8 +20,6 @@ author: aymericzip
 
 # 국제화(i18n)란? 정의 및 도전 과제
 
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/assets/i18n.webp)
-
 ## 국제화(i18n) 이해하기
 
 **국제화**(Internationalization), 줄여서 **i18n**은 코드베이스에 큰 변경 없이 여러 언어, 문화 및 지역 관습을 지원하도록 애플리케이션을 설계하고 준비하는 과정입니다. i18n이라는 이름은 “internationalization”이라는 단어에서 **i**와 **n** 사이에 18개의 문자가 있다는 사실에서 유래되었습니다.