@intlayer/docs 9.5.5 → 9.5.7

package/blog/ko/vue-i18n_vs_intlayer-vue-i18n.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "vue-i18n vs @intlayer/vue-i18n: 동일한 API, 다른 Bundle"
 description: Vue 3 앱이 vue-i18n 호출을 유지하면서 @intlayer/vue-i18n compat adapter를 통해 제공할 때 어떤 변화가 발생하는지 알아봅니다. 동일한 Vite + Vue 코드에서 페이지별 JavaScript, runtime 크기, 컴포넌트 크기 및 누수를 측정하고, adapter가 유지하는 것, 무시하는 것, 그리고 대체할 수 없는 것을 비교합니다.
 keywords:
@@ -25,6 +25,8 @@ author: aymericzip
 
 # vue-i18n VS @intlayer/vue-i18n | 동일한 API, 다른 Bundle
 
+![Vue i18n library ecosystem](https://github.com/aymericzip/intlayer/blob/main/docs/assets/cloud_i18n_logo.webp?raw=true)
+
 `@intlayer/vue-i18n`은 compat 어댑터입니다: `vue-i18n` API (`createI18n`, `useI18n`, `t()`, `d()`, `n()`, `$t`, `v-t`, `i18n.global.locale`...)를 노출하고 Intlayer에 의해 컴파일된 딕셔너리에서 제공합니다. 당신의 `.vue` 파일은 변경되지 않습니다. `t("footer.github")`가 바인딩되는 대상만 변경됩니다.
 
 이 문서는 동일한 Vite + Vue 3 애플리케이션에서 `vue-i18n`으로 빌드한 경우와 어댑터로 빌드한 경우의 성능 변화를 측정합니다. 수치는 [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom)에서 나왔습니다. `vue-i18n`과 Intlayer를 라이브러리로 비교하려면 [vue-i18n vs Intlayer](https://intlayer.org/blog/vue-i18n-vs-intlayer)와 [vue-i18n vs Intlayer benchmark](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark)를 읽으세요. 이 문서는 컴포넌트를 그대로 유지했을 때 어댑터가 어떤 변화를 가져오는지에 관한 것입니다.
@@ -105,6 +107,10 @@ const { t } = useI18n(_dicHash_footer);
 
 ### Vite + Vue 3 결과
 
+관심 있는 메트릭과 라이브러리를 선택하세요:
+
+<I18nBenchmark framework="vite-vue" vertical/>
+
 | Setup                    | Strategy | Lib size (gz) | Lib size (min) | Page JS avg (gz) | Locale leak | Page leak | Component avg (gz) | E2E reactivity |  Page load |
 | ------------------------ | -------- | ------------: | -------------: | ---------------: | ----------: | --------: | -----------------: | -------------: | ---------: |
 | **base** (i18n 없음)     | -        |        0.0 KB |         0.0 KB |          41.3 KB |        0.0% |         - |             1.1 KB |         1.8 ms |    10.8 ms |
@@ -124,11 +130,24 @@ const { t } = useI18n(_dicHash_footer);
 - **반응성 및 페이지 로드.** 로캘 전환은 두 경우 모두 저렴합니다 (1.5-2.8 ms); 메시지가 메모리에 있으면 Vue의 반응성 시스템이 이를 가능하게 합니다. 페이지 로드는 13.6 ms에서 **9.3 ms**로 단축되며, 이는 파싱할 JavaScript가 88 KB 줄어든 것과 일치합니다.
 - **네이티브 행에 대해.** `vue-intlayer`는 이 실행에서 `static` 모드에서 모든 로케일을 번들링했으며 3.9 KB 런타임과 함께 57.1 KB에 도달했습니다. 어댑터의 동기화된 딕셔너리는 더 적은 외국 로케일 문자열을 포함했으므로 페이지당 수치가 더 낮습니다. 네이티브 런타임은 세 개 중 가장 가볍게 유지되며, 해당 `.content.ts` 모델은 SFC `<i18n>` 블록이 동등한 것을 찾는 곳입니다.
 
+<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;"
+/>
+
+> 모든 라이브러리와 전략이 포함된 전체 표는 [Vue 벤치마크 보고서](https://intlayer.org/ko/doc/benchmark/vue)에서 확인하세요.
+
 ## 숫자가 움직이는 이유
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 `src/components/`의 아무것도 변경되지 않았으므로 이득은 `useI18n`이 바인딩된 대상에서 나옵니다.
 
-**`vue-i18n`을 사용할 때**, 바인딩은 글로벌 인스턴스입니다. `createI18n({ messages: { en, fr, ... } })`은 모든 것을 포함하는 하나의 import이고, `useI18n()`을 호출하는 모든 컴포넌트가 모든 콘텐츠에 접근할 수 있으므로 번들러는 인스턴스 아래로 분할할 수 없습니다. 최적화는 _직접_ `en.json`을 라우트별로 분할하고, 라우터 가드에서 `setLocaleMessage()`를 호출하며, 컴포넌트가 이동할 때 라우트-파일 매핑을 올바르게 유지하는 것을 의미합니다.
+**`vue-i18n`을 사용할 때**, 바인딩은 글로벌 인스턴스입니다. `createI18n({ messages: { en, fr, ... } })`은 모든 것을 포함하는 하나의 import이고, `useI18n()`을 호출하는 모든 컴포넌트가 모든 콘텐츠에 접근할 수 있으므로 번들러는 인스턴스 아래로 분할할 수 없습니다. 최적화는 _직접_ `en.json`을 라우트별로 분할하고, 라우터 가드에서 `setLocaleMessage()`를 호출하며, 컴포넌트가 이동할 때 라우트-파일 매핑을 올바르게 유지하는 것을 의미합니다. 낭비는 페이지와 로케일이라는 두 축에서 동시에 증가합니다:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
 
 ```bash
 .
@@ -258,26 +277,107 @@ export const i18n = createI18n({ locale: "en" });
 
 ## 시작하기 전에 알아야 할 제한사항
 
-- **SFC `<i18n>` 블록은 읽히지 않습니다.** 메시지가 컴포넌트 내부에 있는 경우, 로케일 파일로 이동해야 합니다 (또는 타입이 있는 `.content.ts`로, 이는 같은 개념입니다).
-- **런타임 메시지 로딩이 제거되었습니다.** `setLocaleMessage()`와 `mergeLocaleMessage()`는 경고를 표시하고 반환합니다. 런타임에 CMS에서 가져온 번역은 Intlayer의 CMS를 사용하거나 `intlayer pull` / `push` 명령이 필요합니다.
-- **`messages`는 대체 수단일 뿐, 무료가 아닙니다.** `createI18n()`에서 JSON import를 유지하면 번들에 75 KB가 남습니다. `intlayer test`가 통과하면 삭제하세요.
-- **adapter는 native runtime이 아닙니다.** `vue-intlayer`의 3.9 KB에 비해 7.9 KB입니다. 모든 component가 `useIntlayer`로 이동하면 제거하세요.
+<AccordionGroup>
+<Accordion header="SFC <i18n> 블록은 읽히지 않음">
+
+메시지가 컴포넌트 내부에 있는 경우 로케일 파일이나 생성된 타입을 갖춘 동일한 개념의 `.content.ts`로 이동해야 합니다.
+
+</Accordion>
+<Accordion header="런타임 메시지 로딩 제거됨">
+
+`setLocaleMessage()` 및 `mergeLocaleMessage()`는 경고를 표시하고 반환합니다. 런타임에 CMS에서 가져오는 번역은 [Intlayer CMS](https://intlayer.org/ko/doc/concept/cms) 또는 `intlayer pull` / `push` 명령어가 필요합니다.
+
+</Accordion>
+<Accordion header="messages는 폴백일 뿐, 무료가 아님">
+
+`createI18n()`에서 JSON 임포트를 유지하면 번들에 75 KB가 그대로 남습니다. `intlayer test`가 통과되면 삭제하세요.
+
+</Accordion>
+<Accordion header="어댑터는 네이티브 런타임이 아님">
+
+`vue-intlayer`의 3.9 KB에 비해 어댑터는 7.9 KB입니다. 모든 컴포넌트가 `useIntlayer`로 전환되면 제거하세요.
+
+</Accordion>
+</AccordionGroup>
 
 ## 어떤 것을 언제 사용할까요?
 
-- **`vue-i18n`에 머물러있으세요** 앱이 SFC `<i18n>` 블록, runtime `setLocaleMessage()` 흐름에 의존하거나 페이지당 90 KB가 사용자에게 문제가 되지 않는 경우.
-- **`@intlayer/vue-i18n`을 사용하세요** `vue-i18n`을 사용 중이고 88 KB, 23배 더 작은 component, 0% page leakage, typed keys 및 `.vue` 파일을 수정하지 않고도 CI checks를 원하는 경우. 이것은 기존 `vue-i18n` codebase의 진입점입니다.
-- **native(`vue-intlayer`)로 이동하세요** 새로운 프로젝트이거나 adapter가 작업을 완료한 후. 가장 가벼운 runtime(3.9 KB)과 `<i18n>` 블록을 typed content로 대체하는 per-component `.content.ts` 모델이 있습니다.
+<AccordionGroup>
+<Accordion header="vue-i18n 유지">
+
+애플리케이션이 SFC `<i18n>` 블록이나 런타임 `setLocaleMessage()` 흐름에 의존하거나, 페이지당 90 KB가 사용자층에 문제가 되지 않는 경우.
+
+</Accordion>
+<Accordion header="@intlayer/vue-i18n 사용">
+
+`vue-i18n`을 사용 중이며 `.vue` 파일을 수정하지 않고 88 KB 절감, 23배 더 작은 컴포넌트, 0% 페이지 누수, 타입 정의된 키 및 CI 검사를 원하는 경우. 기존 `vue-i18n` 코드베이스의 진입점입니다.
+
+</Accordion>
+<Accordion header="네이티브로 전환 (vue-intlayer)">
+
+새 프로젝트이거나 어댑터가 역할을 다한 경우 적합합니다. 가장 가벼운 런타임(3.9 KB)과 `<i18n>` 블록을 타입이 지정된 콘텐츠로 대체하는 컴포넌트별 `.content.ts` 모델을 제공합니다. [Vue와 함께 사용하는 Intlayer](https://intlayer.org/ko/doc/environment/vite-and-vue) 또는 [Nuxt와 함께](https://intlayer.org/ko/doc/environment/nuxt-and-vue) 시작하세요.
+
+</Accordion>
+</AccordionGroup>
+
+## 자주 묻는 질문
+
+<FAQ>
+
+<Question title=".vue 파일을 수정해야 하나요?">
+
+아닙니다. 벤치마크 빌드는 `vite.config.ts`, `intlayer.config.ts` 및 `src/i18n.ts`의 `messages` 임포트 한 줄만 수정했습니다. 모든 `useI18n()`, `$t`, `v-t` 및 Options API 호출 부분은 그대로 유지되었습니다.
+
+</Question>
+
+<Question title="왜 컴포넌트 크기가 23배나 더 작나요?">
+
+`useI18n()`이 전역 인스턴스 접근을 중단하기 때문입니다. `createI18n({ messages })`는 모든 로케일의 모든 메시지를 보유하므로 독립적으로 컴파일된 컴포넌트라도 196 KB를 끌어옵니다. 어댑터를 사용하면 고유한 사전에만 접근합니다: 8.4 KB.
+
+</Question>
+
+<Question title="d() 및 n() 포맷팅은 어떻게 되나요?">
+
+유지됩니다. `createI18n()`에 전달된 `datetimeFormats` 및 `numberFormats`가 적용되며 네이티브 `Intl` API가 지원합니다. [날짜, 시간 및 숫자 형식 지정](https://intlayer.org/ko/blog/date-time-number-formatting-locales)을 참조하세요.
+
+</Question>
+
+<Question title="Nuxt에서도 작동하나요?">
+
+`@intlayer/vue-i18n`은 Vite + Vue를 대상으로 합니다. `@nuxtjs/i18n`의 경우 [Nuxt i18n 호환 어댑터](https://intlayer.org/ko/doc/compatibility/nuxtjs-i18n)를 사용하고, 네이티브 설정은 [Nuxt와 함께 사용하는 Intlayer](https://intlayer.org/ko/doc/environment/nuxt-and-vue)를 확인하세요.
+
+</Question>
+
+<Question title="컴포넌트 단위로 점진적 마이그레이션이 가능한가요?">
+
+네. 모든 컴포넌트는 함께 배치된 콘텐츠 파일을 통해 `useI18n()`에서 `useIntlayer("footer")`로 전환할 수 있습니다. JSON과 `.content.ts` 사전은 공존하며 병합됩니다.
+
+</Question>
+
+</FAQ>
 
 ## 관련 비교
 
-- [vue-i18n vs Intlayer](https://intlayer.org/blog/vue-i18n-vs-intlayer) (기능 및 DX)
-- [vue-i18n vs Intlayer 벤치마크](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark) (라이브러리, 동일한 벤치마크)
-- [next-intl vs @intlayer/next-intl](https://intlayer.org/blog/next-intl-vs-intlayer-next-intl) (동일한 어댑터 시리즈)
-- [i18next vs @intlayer/i18next](https://intlayer.org/blog/i18next-vs-intlayer-i18next) (동일한 어댑터 시리즈)
-- [Lingui vs @intlayer/lingui](https://intlayer.org/blog/lingui-vs-intlayer-lingui) (동일한 어댑터 시리즈)
-- [마이그레이션 가이드: vue-i18n에서 Intlayer로](https://intlayer.org/doc/migration/vue-i18n)
-- [Compat adapter reference: vue-i18n](https://intlayer.org/doc/compatibility/vue-i18n), [Nuxt i18n](https://intlayer.org/doc/compatibility/nuxtjs-i18n)
+동일한 어댑터 시리즈:
+
+- [next-intl vs @intlayer/next-intl](https://intlayer.org/ko/blog/next-intl-vs-intlayer-next-intl)
+- [i18next vs @intlayer/i18next](https://intlayer.org/ko/blog/i18next-vs-intlayer-i18next)
+- [Lingui vs @intlayer/lingui](https://intlayer.org/ko/blog/lingui-vs-intlayer-lingui)
+
+직접 비교된 라이브러리:
+
+- [vue-i18n vs Intlayer](https://intlayer.org/ko/blog/vue-i18n-vs-intlayer), features and DX
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/ko/blog/vue-i18n-vs-intlayer-benchmark)
+- [Is vue-i18n outdated?](https://intlayer.org/ko/blog/is-vue-i18n-outdated)
+- [How to pick a Vue i18n library](https://intlayer.org/ko/blog/how-to-pick-vue-i18n-library)
+
+참조 문서:
+
+- [Compat adapter: vue-i18n](https://intlayer.org/ko/doc/compatibility/vue-i18n) and [Nuxt i18n](https://intlayer.org/ko/doc/compatibility/nuxtjs-i18n)
+- [마이그레이션 가이드: vue-i18n에서 Intlayer로](https://intlayer.org/ko/doc/migration/vue-i18n)
+- [Vue 벤치마크 보고서](https://intlayer.org/ko/doc/benchmark/vue)
+- [번들 최적화](https://intlayer.org/ko/doc/concept/bundle-optimization) 및 [Intlayer 컴파일러](https://intlayer.org/ko/doc/compiler)
+- [비주얼 에디터](https://intlayer.org/ko/doc/concept/editor), [CMS](https://intlayer.org/ko/doc/concept/cms) 및 [AI 번역](https://intlayer.org/ko/doc/concept/auto-fill)
 
 ## 결론
 
@@ -285,4 +385,4 @@ export const i18n = createI18n({ locale: "en" });
 
 모든 원본 데이터, 테스트 앱 및 스크립트는 [Benchmark Bloom 저장소](https://github.com/intlayer-org/benchmark-bloom)에 있습니다. 직접 실행해보세요.
 
-자세한 내용은 ['Intlayer를 선택해야 하는 이유?' 문서](https://intlayer.org/doc/why)를 참조하세요.
+자세한 내용은 ['Intlayer를 선택해야 하는 이유?' 문서](https://intlayer.org/ko/doc/why)를 참조하세요.

package/blog/ko/vue-i18n_vs_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-11
-updatedAt: 2025-08-23
+updatedAt: 2026-09-22
 title: vue-i18n 대 Intlayer
 description: Vue/Nuxt 앱에서 국제화(i18n)를 위해 vue-i18n과 Intlayer를 비교
 keywords:
@@ -20,6 +20,8 @@ author: aymericzip
 
 # vue-i18n 대 Intlayer | Vue 국제화(i18n)
 
+![Vue i18n library ecosystem](https://github.com/aymericzip/intlayer/blob/main/docs/assets/cloud_i18n_logo.webp?raw=true)
+
 이 가이드는 **Vue 3** (및 **Nuxt**)용으로 인기 있는 두 가지 i18n 옵션인 **vue-i18n**과 **Intlayer**를 비교합니다.
 우리는 최신 Vue 도구(Vite, Composition API)에 중점을 두고 다음을 평가합니다:
 
@@ -31,6 +33,8 @@ author: aymericzip
 6. **개발자 경험(DX), 도구 및 유지보수**
 7. **SEO 및 대규모 프로젝트 확장성**
 
+<TOC/>
+
 > **요약**: 두 솔루션 모두 Vue 앱을 현지화할 수 있습니다. 만약 **컴포넌트 범위 콘텐츠**, **엄격한 TypeScript 타입**, **빌드 시 누락 키 검사**, **트리 쉐이킹된 사전**, 그리고 **기본 제공 라우터/SEO 도우미**와 더불어 **비주얼 에디터 및 AI 번역**을 원한다면, **Intlayer**가 더 완전하고 현대적인 선택입니다.
 
 ## 상위 수준 포지셔닝
@@ -38,6 +42,30 @@ author: aymericzip
 - **vue-i18n** - Vue의 사실상 표준 i18n 라이브러리입니다. 유연한 메시지 포맷팅(ICU 스타일), 로컬 메시지를 위한 SFC `<i18n>` 블록, 그리고 방대한 생태계를 갖추고 있습니다. 안전성과 대규모 유지보수는 주로 사용자의 몫입니다.
 - **Intlayer** - 엄격한 TS 타이핑, 빌드 타임 검사, 트리 쉐이킹, 라우터 및 SEO 도우미, 선택적 비주얼 에디터/CMS, AI 지원 번역 기능을 갖춘 Vue/Vite/Nuxt용 컴포넌트 중심 콘텐츠 모델입니다.
 
+## 빌드 시 발생하는 비용
+
+기능 비교표에 앞서, 실측된 데이터입니다. [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom)은 각 라이브러리를 사용하여 동일한 Vite + Vue 3 앱(10개 페이지, 10개 언어)을 빌드하고 브라우저가 다운로드하는 크기를 기록합니다:
+
+<I18nBenchmark framework="vite-vue" vertical/>
+
+| Setup                | Lib size (gz) | Page JS avg (gz) | Page leak | Component avg (gz) |
+| -------------------- | ------------: | ---------------: | --------: | -----------------: |
+| **base** (no i18n)   |        0.0 KB |          41.3 KB |         - |             1.1 KB |
+| `vue-i18n`           |       24.3 KB |         134.9 KB |     90.0% |           196.0 KB |
+| `@intlayer/vue-i18n` |        7.9 KB |          47.0 KB |      0.0% |             8.4 KB |
+| **`vue-intlayer`**   |    **3.9 KB** |      **57.1 KB** |  **0.0%** |         **7.7 KB** |
+
+`vue-i18n` 런타임 자체만으로도 Intlayer의 **6배**에 달하며, 각 페이지는 **90%의 타 페이지 문자열**을 포함하고, 격리되어 컴파일된 컴포넌트는 `useI18n()`이 전역 메시지 트리에 바인딩하기 때문에 **196 KB**를 끌어옵니다. 반응성 및 페이지 로드 시간을 포함한 전체 실행 결과는 [vue-i18n vs Intlayer 벤치마크](https://intlayer.org/ko/blog/vue-i18n-vs-intlayer-benchmark)에서 확인할 수 있습니다.
+
+<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;"
+/>
+
+> 전체 표는 [Vue 벤치마크 보고서](https://intlayer.org/ko/doc/benchmark/vue)에서 확인하세요.
+
 ## 나란히 기능 비교 (Vue 중심)
 
 | 기능                                        | **Intlayer**                                                                    | **vue-i18n**                                                               |
@@ -63,59 +91,74 @@ author: aymericzip
 
 ## 심층 비교
 
-### 1) 아키텍처 및 확장성
+<AccordionGroup>
+<Accordion header="1) 아키텍처 및 확장성">
 
-- **vue-i18n**: 일반적인 설정은 로케일별로 **중앙 집중식 카탈로그**를 사용하며(선택적으로 파일/네임스페이스로 분할 가능), SFC `<i18n>` 블록은 로컬 메시지를 허용하지만 프로젝트가 커짐에 따라 팀들은 종종 공유 카탈로그로 되돌아갑니다.
+- **vue-i18n**: 일반적인 설정은 로케일별로 **중앙 집중식 카탈로그**를 사용하며(선택적으로 파일/네임스페이스로 분할 가능), SFC `<i18n>` 블록은 로컬 메시지를 허용하지만 프로젝트가 커짐에 따라 팀들은 종종 공유 카탈로그로 되돌아갑니다. [컴포넌트별 vs 중앙 집중식 i18n](https://intlayer.org/ko/blog/per-component-vs-centralized-i18n)을 참조하세요.
 - **Intlayer**: 각 컴포넌트 옆에 저장되는 **컴포넌트별 사전**을 권장합니다. 이는 팀 간 충돌을 줄이고, 콘텐츠를 쉽게 찾을 수 있게 하며, 자연스럽게 사용되지 않는 키의 누락이나 분산을 제한합니다.
 
 **중요한 이유:** 대규모 Vue 앱이나 디자인 시스템에서는 **모듈화된 콘텐츠**가 단일 카탈로그보다 더 잘 확장됩니다.
 
-### 2) TypeScript 및 안정성
+</Accordion>
+<Accordion header="2) TypeScript 및 안전성">
 
 - **vue-i18n**: 좋은 TS 지원을 제공하지만, **엄격한 키 타입 지정**은 일반적으로 사용자 정의 스키마/제네릭 및 신중한 규칙이 필요합니다.
 - **Intlayer**: 콘텐츠에서 **엄격한 타입을 생성**하여 **IDE 자동완성**과 오타/누락 키에 대한 **컴파일 타임 오류**를 제공합니다.
 
 **중요한 이유:** 강력한 타입 검사는 **런타임 이전에** 문제를 잡아냅니다.
 
-### 3) 누락된 번역 처리
+</Accordion>
+<Accordion header="3) 누락된 번역 처리">
 
-- **vue-i18n**: **런타임** 경고/대체 처리(예: 대체 로케일 또는 키 사용).
-- **Intlayer**: 로케일과 키 전반에 걸친 경고/오류를 포함한 **빌드 타임** 감지.
+- **vue-i18n**: **런타임** 경고/대체 처리(예: 대체 로케일 또는 키 사용). [누락된 번역 감지](https://intlayer.org/ko/blog/detecting-missing-translations)를 참조하세요.
+- **Intlayer**: 로케일과 키 전반에 걸친 경고/오류를 포함한 **빌드 타임** 감지., 그리고 CI에서의 `npx intlayer test` 지원.
 
 **중요한 이유:** 빌드 타임 강제 적용으로 프로덕션 UI를 깔끔하고 일관되게 유지합니다.
 
-### 4) 라우팅 및 URL 전략 (Vue Router/Nuxt)
+</Accordion>
+<Accordion header="4) 라우팅 및 URL 전략 (Vue Router/Nuxt)">
 
-- **둘 다** 지역화된 라우트와 함께 작동할 수 있습니다.
+- **둘 다** 지역화된 라우트와 함께 작동할 수 있습니다. [hreflang 가이드](https://intlayer.org/ko/blog/hreflang-guide-multilingual-seo)를 참조하세요.
 - **Intlayer**는 **지역화된 경로 생성**, **로케일 접두사 관리**, 그리고 SEO를 위한 **`<link rel="alternate" hreflang>`** 발행을 돕는 헬퍼를 제공합니다. Nuxt와 함께 사용 시, 프레임워크의 라우팅을 보완합니다.
 
 **중요한 이유:** 맞춤형 연결 계층이 줄어들고, 여러 로케일에 걸쳐 **더 깔끔한 SEO**를 구현할 수 있습니다.
 
-### 5) 성능 및 로딩 동작
+</Accordion>
+<Accordion header="5) 성능 및 로딩 동작">
 
-- **vue-i18n**: 비동기 로케일 메시지를 지원하며, 과도한 번들링 방지는 사용자의 책임입니다(카탈로그를 신중히 분할해야 함).
+- **vue-i18n**: 비동기 로케일 메시지를 지원하며, 과도한 번들링 방지는 사용자의 책임입니다(카탈로그를 신중히 분할해야 함). 위의 벤치마크가 이를 수치로 보여줍니다: 페이지당 134.9 KB 대 57.1 KB.
 - **Intlayer**: 빌드 시 **트리 쉐이킹**을 수행하고, 사전/로케일별로 **지연 로딩**합니다. 사용하지 않는 콘텐츠는 포함되지 않습니다.
 
 **중요한 이유:** 더 작은 번들과 다중 로케일 Vue 앱의 더 빠른 시작 속도를 제공합니다.
 
-### 6) 개발자 경험 및 도구
+</Accordion>
+<Accordion header="6) 개발자 경험 및 툴링">
 
 - **vue-i18n**: 성숙한 문서와 커뮤니티를 갖추고 있으며, 일반적으로 편집 워크플로우를 위해 **외부 현지화 플랫폼**에 의존합니다.
-- **Intlayer**: **무료 비주얼 에디터**, 선택적 **CMS**(Git 친화적이거나 외부화 가능), **VSCode 확장**, **CLI/CI** 유틸리티, 그리고 사용자의 제공자 키를 활용한 **AI 지원 번역**을 제공합니다.
+- **Intlayer**: **무료 비주얼 에디터**, 선택적 **CMS**(Git 친화적이거나 외부화 가능), **VSCode 확장**, **CLI/CI** 유틸리티, 그리고 사용자의 제공자 키를 활용한 **AI 지원 번역**을 제공합니다., **MCP 서버**
 
 **중요한 이유:** 운영 비용 절감과 개발-콘텐츠 주기의 단축.
 
-### 7) SEO, SSR 및 SSG
+</Accordion>
+<Accordion header="7) SEO, SSR 및 SSG">
 
-- **두 솔루션 모두** Vue SSR과 Nuxt와 함께 작동합니다.
+- **두 솔루션 모두** Vue SSR과 Nuxt와 함께 작동합니다. [국제화 및 SEO](https://intlayer.org/ko/blog/SEO-and-i18n)를 참조하세요.
 - **Intlayer**: 프레임워크에 구애받지 않는 **SEO 도우미**(사이트맵/메타데이터/`hreflang`)를 추가하여 Vue/Nuxt 빌드와 원활하게 작동합니다.
 
 **중요한 이유:** 맞춤형 연결 없이 국제 SEO 구현 가능.
 
+</Accordion>
+</AccordionGroup>
+
 ## 왜 Intlayer인가? (문제점 및 접근법)
 
+![Centralized catalogs versus per-component dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/assets/project_stucture_18n_vs_intlayer.png?raw=true)
+
 대부분의 i18n 스택(예: **vue-i18n**)은 **중앙 집중식 카탈로그**에서 시작합니다:
 
+<Tabs defaultTab="per-locale" group="catalog">
+<Tab label="언어당 1개 파일" value="per-locale">
+
 ```bash
 .
 ├── locales
@@ -127,7 +170,8 @@ author: aymericzip
         └── MyComponent.vue
 ```
 
-또는 로케일별 폴더 구조:
+</Tab>
+<Tab label="언어당 1개 폴더" value="per-folder">
 
 ```bash
 .
@@ -146,6 +190,34 @@ author: aymericzip
         └── MyComponent.vue
 ```
 
+</Tab>
+</Tabs>
+
+이 폴더는 각 언어의 기능별 네임스페이스로 계속해서 비대해집니다:
+
+```txt
+locales
+├── EN
+│   ├── blog.json
+│   ├── about.json
+│   ├── auth.json
+│   ├── blog.json
+│   ├── cart.json
+│   ├── categories.json
+│   ├── contact.json
+│   ├── dashboard.json
+│   ├── errors.json
+│   ├── faq.json
+│   ├── footer.json
+│   ├── form.json
+│   ├── home.json
+│   ├── language.json
+│   ├── navbar.json
+│   ├── ... 65 files
+│   └── validation.json
+└── ES
+```
+
 이 방식은 앱이 커질수록 개발 속도를 저하시킵니다:
 
 1. **새 컴포넌트의 경우** 원격 카탈로그를 생성/편집하고, 네임스페이스를 연결하며, 번역 작업을 수행합니다 (종종 AI 도구에서 복사/붙여넣기 수동 작업 포함).
@@ -161,7 +233,33 @@ author: aymericzip
         └── MyComponent.vue
 ```
 
-**콘텐츠 선언** (컴포넌트별):
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="vue-i18n" value="vue-i18n">
+
+```json fileName="./locales/en.json"
+{
+  "componentExample": {
+    "greeting": "Hello World"
+  }
+}
+```
+
+```vue fileName="./components/MyComponent.vue"
+<script setup lang="ts">
+import { useI18n } from "vue-i18n";
+
+const { t } = useI18n();
+</script>
+
+<template>
+  <span>{{ t("componentExample.greeting") }}</span>
+</template>
+```
+
+모든 로케일 파일을 수동으로 편집해야 하며, 키는 일반 문자열입니다. 오타가 발생하면 프로덕션에서 `componentExample.greting`으로 그대로 렌더링됩니다.
+
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="./components/MyComponent/myComponent.content.ts"
 import { t, type Dictionary } from "intlayer";
@@ -171,8 +269,8 @@ const componentExampleContent = {
   content: {
     greeting: t({
       en: "Hello World",
-      es: "Hola Mundo",
       fr: "Bonjour le monde",
+      es: "Hola Mundo",
     }),
   },
 } satisfies Dictionary;
@@ -180,11 +278,10 @@ const componentExampleContent = {
 export default componentExampleContent;
 ```
 
-**Vue에서 사용법** (Composition API):
-
 ```vue fileName="./components/MyComponent/MyComponent.vue"
 <script setup lang="ts">
-import { useIntlayer } from "vue-intlayer"; // Vue 통합
+import { useIntlayer } from "vue-intlayer"; // Vue integration
+
 const { greeting } = useIntlayer("component-example");
 </script>
 
@@ -193,6 +290,11 @@ const { greeting } = useIntlayer("component-example");
 </template>
 ```
 
+모든 로케일이 컴포넌트 바로 옆의 단일 타입 파일에 위치합니다.
+
+</Tab>
+</Tabs>
+
 이 접근 방식:
 
 - **개발 속도 향상** (한 번 선언; IDE/AI 자동완성 지원).
@@ -220,22 +322,71 @@ const { greeting } = useIntlayer("component-example");
 
 ## 언제 어떤 것을 선택해야 할까요?
 
-- **vue-i18n을 선택하세요**: 표준 Vue 방식을 원하고, 카탈로그/네임스페이스 관리를 직접 할 수 있으며, 앱이 **소규모에서 중간 규모**이거나 이미 Nuxt i18n을 사용 중인 경우.
-- **Intlayer를 선택하세요**: **컴포넌트 범위 콘텐츠**, **엄격한 TypeScript**, **빌드 타임 보장**, **트리 쉐이킹**, 그리고 **포함된 라우팅/SEO/에디터 도구**를 중요시하며, 특히 **대규모 모듈형 Vue/Nuxt 코드베이스**에 적합합니다.
+<AccordionGroup>
+<Accordion header="vue-i18n 선택">
+
+**표준 Vue 접근 방식**을 선호하고 카탈로그와 네임스페이스를 직접 관리하는 데 익숙하며, 애플리케이션이 **중소 규모**인 경우(또는 이미 Nuxt i18n에 의존하고 있는 경우). SFC `<i18n>` 블록과 런타임 `setLocaleMessage()`는 Intlayer가 의도적으로 복제하지 않은 기능입니다.
+
+</Accordion>
+<Accordion header="Intlayer 선택">
+
+**컴포넌트 단위 콘텐츠**, **엄격한 TypeScript**, **빌드 시 안전성 보장**, **Tree-shaking**, 내장된 라우팅/SEO/에디터 툴링을 중시하는 경우, 특히 **대규모 모듈형 Vue/Nuxt 코드베이스** 및 디자인 시스템에 적합합니다. [Vue와 함께 사용하는 Intlayer](https://intlayer.org/ko/doc/environment/vite-and-vue) 또는 [Nuxt와 함께](https://intlayer.org/ko/doc/environment/nuxt-and-vue) 시작하세요.
+
+</Accordion>
+<Accordion header="@intlayer/vue-i18n 선택">
+
+현재 `vue-i18n`을 사용 중이며 `.vue` 파일을 수정하지 않고 번들 크기를 줄이고자 하는 경우. [호환 어댑터](https://intlayer.org/ko/doc/compatibility/vue-i18n)는 `createI18n`, `useI18n`, `t()`, `d()`, `n()`, `$t`, `v-t`를 유지하고 컴파일된 사전에서 제공합니다. [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/ko/blog/vue-i18n-vs-intlayer-vue-i18n)의 비교 결과를 확인하세요.
+
+</Accordion>
+</AccordionGroup>
+
+## vue-i18n과의 상호 운용성
+
+`intlayer`는 `vue-i18n` 네임스페이스 관리에도 도움이 될 수 있습니다.
+
+`intlayer`를 사용하면 선호하는 i18n 라이브러리 형식으로 콘텐츠를 선언할 수 있으며, intlayer는 선택한 위치(예: `/messages/{{locale}}/{{namespace}}.json`)에 네임스페이스를 생성합니다. [vue-i18n 호환성 문서](https://intlayer.org/ko/doc/compatibility/vue-i18n) 및 [Nuxt i18n 어댑터](https://intlayer.org/ko/doc/compatibility/nuxtjs-i18n)를 참조하세요.
+
+## 자주 묻는 질문
+
+<FAQ>
+
+<Question title="Intlayer는 vue-i18n의 대체재인가요, 아니면 그 위의 레이어인가요?">
+
+도입 방식에 따라 둘 다 해당됩니다. `vue-intlayer`는 고유한 `useIntlayer()` 컴포저블을 갖춘 네이티브 런타임입니다. `@intlayer/vue-i18n`은 `vue-i18n` API를 유지하면서 연결 대상을 변경하는 호환 어댑터로, 컴포넌트를 건드리지 않고 마이그레이션한 다음 점진적으로 파일 단위로 전환할 수 있습니다.
 
-## 실용적인 마이그레이션 노트 (vue-i18n → Intlayer)
+</Question>
 
-- **기능별로 시작하기**: 한 번에 하나의 라우트/뷰/컴포넌트를 로컬 Intlayer 사전으로 옮기세요.
-- **마이그레이션 중 브리지 유지**: vue-i18n 카탈로그를 병행 유지하며 점진적으로 조회를 대체하세요.
-- **엄격한 검사 활성화**: 빌드 시 누락된 키/로케일을 조기에 감지하도록 하세요.
-- **라우터/SEO 도우미 채택**: 로케일 감지와 `hreflang` 태그를 표준화하세요.
-- **번들 크기 측정**: 사용하지 않는 콘텐츠가 제외되면서 **번들 크기 감소**를 기대하세요.
+<Question title="내 SFC <i18n> 블록은 어떻게 되나요?">
+
+어댑터는 이를 읽지 않습니다. 해당 메시지를 로케일 JSON 파일로 옮기거나, 생성된 타입을 지원하는 컴포넌트 옆의 `.content.ts` 파일로 이동하세요. 이는 이전되지 않는 유일한 `vue-i18n` 기능입니다.
+
+</Question>
+
+<Question title="Intlayer가 Nuxt와 함께 작동하나요?">
+
+네. [Nuxt와 함께 사용하는 Intlayer](https://intlayer.org/ko/doc/environment/nuxt-and-vue)는 다국어 라우팅, 로케일 감지 미들웨어 및 사이트맵 생성을 지원합니다. `@nuxtjs/i18n`을 사용 중이라면 [Nuxt i18n 호환 어댑터](https://intlayer.org/ko/doc/compatibility/nuxtjs-i18n)가 마이그레이션 경로입니다.
+
+</Question>
+
+<Question title="locales/{locale}.json을 단일 진실 공급원(SSOT)으로 유지할 수 있나요?">
+
+네. [JSON 동기화 플러그인](https://intlayer.org/ko/doc/compatibility/vue-i18n)은 `vue-i18n` 문법(`{name}`, `{0}`, `"car | cars"` 파이프 복수형)으로 읽고 CLI나 CMS가 업데이트할 때 번역을 다시 기록합니다.
+
+</Question>
+
+<Question title="Vue에서 Intlayer와 함께 ICU가 작동하나요?">
+
+네이티브 ICU 지원은 작업 중입니다. `@intlayer/vue-i18n` 어댑터는 파이프 복수형, 명명된 보간 및 목록 보간을 포함한 `vue-i18n` 고유의 메시지 구문을 지원합니다. Intlayer의 복수화 모델에 대해서는 [열거형 콘텐츠](https://intlayer.org/ko/doc/concept/content/enumeration)를 참조하세요.
+
+</Question>
+
+</FAQ>
 
 ## GitHub STARs
 
 GitHub stars는 프로젝트의 인기도, 커뮤니티 신뢰도, 장기적 관련성의 강력한 지표입니다. 기술적 품질을 직접 측정하는 것은 아니지만, 얼마나 많은 개발자들이 프로젝트를 유용하게 생각하고, 진행 상황을 따르고 있으며, 채택할 가능성이 있는지를 반영합니다. 프로젝트의 가치를 추정하기 위해 stars는 대안들 간의 견인력을 비교하고 생태계 성장에 대한 통찰력을 제공합니다.
 
-[![Star History Chart](https://api.star-history.com/svg?repos=intlify/vue-i18n&repos=aymericzip/intlayer&type=Date)](https://star-history.com/#intlify/vue-i18n&aymericzip/intlayer)
+[![Star History Chart](https://api.star-history.com/chart?repos=intlify%2Fvue-i18n%2Caymericzip%2Fintlayer&type=date&legend=top-left)](https://star-history.com/#intlify/vue-i18n&aymericzip/intlayer)
 
 ## 결론
 
@@ -244,4 +395,15 @@ GitHub stars는 프로젝트의 인기도, 커뮤니티 신뢰도, 장기적 관
 - **Intlayer**는 **모듈화된 콘텐츠**, **엄격한 TS**, **빌드 시 안전성**, **트리 쉐이킹된 번들**, 그리고 **라우터/SEO/에디터 도구**를 **기본 제공**합니다.
 - 팀이 다중 로케일, 컴포넌트 기반 Vue/Nuxt 앱에서 **유지보수성과 속도**를 우선시한다면, Intlayer는 오늘날 **가장 완벽한** 경험을 제공합니다.
 
-자세한 내용은 ['Why Intlayer?' 문서](https://intlayer.org/doc/why)를 참조하세요.
+## 추가 자료
+
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/ko/blog/vue-i18n-vs-intlayer-benchmark), the measured run behind the table above
+- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/ko/blog/vue-i18n-vs-intlayer-vue-i18n), the adapter on the same app
+- [Is vue-i18n outdated?](https://intlayer.org/ko/blog/is-vue-i18n-outdated)
+- [How to pick a Vue i18n library](https://intlayer.org/ko/blog/how-to-pick-vue-i18n-library)
+- [Using Intlayer with vue-i18n](https://intlayer.org/ko/blog/intlayer-with-vue-i18n)
+- [Vue benchmark report](https://intlayer.org/ko/doc/benchmark/vue)
+- [Migration guide: vue-i18n to Intlayer](https://intlayer.org/ko/doc/migration/vue-i18n)
+- [Bundle optimization](https://intlayer.org/ko/doc/concept/bundle-optimization) and [the Intlayer compiler](https://intlayer.org/ko/doc/compiler)
+
+Refer to ['Why Intlayer?' doc](https://intlayer.org/ko/doc/why) for more details.