@intlayer/docs 9.5.6 → 9.5.8

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.

package/blog/pl/i18next_vs_intlayer-i18next.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "i18next vs @intlayer/i18next: To samo API, inny bundle"
 description: "Co się zmienia, gdy aplikacja React lub Next.js zachowuje wywołania i18next, react-i18next i next-i18next, ale obsługuje je za pośrednictwem adapterów @intlayer/i18next. JavaScript na stronę, rozmiar komponentów, wycieki i hydratacja zmierzone na tym samym kodzie, a także co adaptery zachowują, ignorują i czego nie mogą zastąpić."
 keywords:
@@ -28,6 +28,8 @@ author: aymericzip
 
 # i18next VS @intlayer/i18next | To samo API, inny bundle
 
+![i18next VS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18next-next-intl-intlayer.webp?raw=true)
+
 `@intlayer/i18next`, `@intlayer/react-i18next` i `@intlayer/next-i18next` to adaptery kompatybilności. Udostępniają API `i18next`, którego Twój kod już używa (`useTranslation`, `t()`, `<Trans>`, `i18n.changeLanguage()`, `getFixedT`, `serverSideTranslations`...) i obsługują je ze słowników skompilowanych przez Intlayer. Komponenty się nie zmieniają. Zmienia się runtime pod nimi.
 
 Ten artykuł mierzy tę zamianę na tej samej aplikacji Next.js, zbudowanej raz z `next-i18next`, a raz z `@intlayer/next-i18next`. Liczby pochodzą z [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom). Aby porównać `i18next` i Intlayer jako biblioteki, przeczytaj [i18next vs Intlayer](https://intlayer.org/pl/blog/i18next-vs-intlayer). Ten artykuł dotyczy tego, co zmienia adapter, gdy zachowujesz swój kod bez zmian.
@@ -109,6 +111,10 @@ Dla każdego buildu zestaw rejestruje:
 
 ### Wyniki w Next.js
 
+Wybierz metryki i biblioteki, które Cię interesują:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | Konfiguracja                 | Strategia      | Lib size (gz) | Page JS avg (gz) | Locale leak | Page leak | Component avg (gz) | E2E reactivity |   Hydration |
 | ---------------------------- | -------------- | ------------: | ---------------: | ----------: | --------: | -----------------: | -------------: | ----------: |
 | **base** (brak i18n)         | -              |        0.0 KB |         141.0 KB |        0.0% |      0.0% |             0.9 KB |        13.4 ms |     11.8 ms |
@@ -129,10 +135,21 @@ Dla każdego buildu zestaw rejestruje:
 - **Hydratacja i przełączanie są szybsze.** Hydratacja przyspiesza z 15.6 ms do **11.3 ms** (oraz z 27.7 ms w konfiguracji `dynamic`, gdzie pobieranie z backendu znajduje się na ścieżce krytycznej). Przełączanie języka przyspiesza z 15-16 ms do **11-12 ms**.
 - **Adapter to nie natywny runtime.** `next-intlayer` osiąga **141.3 KB**, czyli +0.3 KB względem bazowej aplikacji. Adapter wnosi powierzchnię API `i18next` (dialekt interpolacji, rozwiązywanie sufiksów liczby mnogiej i kontekstu, parsowanie tagów `<Trans>`) na wierzchu rdzenia Intlayer: 9.4 KB i +9.4 KB na stronę ponad natywną implementację. To pomost, a nie ostateczny cel.
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> Pełna tabela, każda biblioteka i każda strategia, w [raporcie benchmarku Next.js](https://intlayer.org/pl/doc/benchmark/nextjs).
+
 > Adapter `react-i18next` w Vite / TanStack Start nie brał udziału w tym uruchomieniu. Wartość bazowa `react-i18next` w TanStack Start znajduje się w [i18next vs Intlayer](https://intlayer.org/pl/blog/i18next-vs-intlayer): 127-184 KB na stronę i 123-185 ms przełączania języka przy leniwym backendzie.
 
 ## Dlaczego liczby się zmieniają
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 W katalogu `components/` nic się nie zmieniło, więc zyski wynikają z tego, z czym powiązane jest `useTranslation`.
 
 **W przypadku `i18next`** powiązaniem jest instancja globalna. Cokolwiek zostało do niej załadowane (wszystkie języki w `static`, cała przestrzeń nazw aktywnego języka w `dynamic`), jest dostępne z każdego komponentu wywołującego `useTranslation()`. Bundler nie może dokonać podziału poniżej tego, co zawiera instancja, a runtime nie może wiedzieć, o które klucze zapyta komponent.
@@ -149,6 +166,10 @@ W katalogu `components/` nic się nie zmieniło, więc zyski wynikają z tego, z
     └── About.tsx                     # useTranslation(); t("about.title")
 ```
 
+Wszystko, co zawiera instancja, jest przesyłane na każdą stronę, a marnotrawstwo rośnie na dwóch osiach, stron i języków:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
+
 **W przypadku `@intlayer/next-i18next`** powiązaniem jest słownik. `syncJSON` przekształca każdy plik przestrzeni nazw w słownik; krok optymalizacji przekazuje komponentowi słownik, do którego się odwołuje, jako import, który bundler może śledzić i dzielić według stron i języków.
 
 ```bash
@@ -297,26 +318,112 @@ export default defineConfig({
 
 ## Ograniczenia, które warto znać przed rozpoczęciem
 
-- **Backendy i detektory są nieaktywne.** `i18n.use(HttpBackend)` wywołuje `init` wtyczki i nic więcej. Jeśli Twoja aplikacja polegała na pobieraniu tłumaczeń z CMS w czasie wykonywania, ten mechanizm już nie działa; użyj CMS Intlayer lub poleceń `intlayer pull` / `push`.
-- **`resources` jest ignorowane, a nie scalane.** W przeciwieństwie do niektórych innych adapterów, `@intlayer/i18next` nie używa wbudowanych `resources` jako mechanizmu fallback. Każdy klucz musi istnieć w zsynchronizowanych słownikach, co weryfikuje `intlayer test`.
-- **App Router wymaga edycji providera.** Jeden plik, pokazany powyżej. Pages Router z `appWithTranslation` nie wymaga żadnych zmian.
-- **`next-i18next.config.js` nie jest odczytywany.** `localePath`, `fallbackLng`, `reloadOnPrerender` i pokrewne nie mają odpowiedników; języki i fallback pochodzą z `intlayer.config.ts`.
-- **Adapter nie jest darmowy.** 9.4 KB runtime i +9.4 KB na stronę względem `next-intlayer`. Gdy każdy komponent przejdzie na `useIntlayer`, można go usunąć.
+<AccordionGroup>
+<Accordion header="Backendy i detektory są bezczynne">
+
+`i18n.use(HttpBackend)` wywołuje jedynie init wtyczki i nic więcej. Jeśli Twoja aplikacja polegała na pobieraniu tłumaczeń z CMS w czasie wykonywania, ten przepływ znika; użyj zamiast tego [Intlayer CMS](https://intlayer.org/pl/doc/concept/cms) lub poleceń `intlayer pull` / `push`. Wykrywanie języka staje się konfiguracją routingu Intlayer (prefiks URL, cookie, nagłówek).
+
+</Accordion>
+<Accordion header="resources jest ignorowane, nie scalane">
+
+W przeciwieństwie do innych adapterów, `@intlayer/i18next` nie używa wbudowanych `resources` jako rozwiązania awaryjnego. Każdy klucz musi istnieć w zsynchronizowanych słownikach, co weryfikuje `intlayer test`.
+
+</Accordion>
+<Accordion header="App Router wymaga modyfikacji providera">
+
+Jeden plik, pokazany powyżej. Pages Router z `appWithTranslation` nie wymaga żadnych zmian.
+
+</Accordion>
+<Accordion header="next-i18next.config.js nie jest odczytywany">
+
+`localePath`, `fallbackLng`, `reloadOnPrerender` i pokrewne nie mają odpowiedników; języki i wartości domyślne pochodzą z `intlayer.config.ts`.
+
+</Accordion>
+<Accordion header="Adapter nie jest darmowy">
+
+9.4 KB runtime i +9.4 KB na stronę w stosunku do `next-intlayer`. Gdy każdy komponent przejdzie na `useIntlayer`, usuń go.
+
+</Accordion>
+</AccordionGroup>
 
 ## Kiedy używać którego rozwiązania?
 
-- **Pozostań przy `i18next`**, jeśli Twoja aplikacja zależy od backendów czasu wykonywania (tłumaczenia serwowane przez CMS w momencie żądania), od ekosystemu wtyczek lub od środowiska innego niż React, którego adaptery nie obsługują.
-- **Użyj `@intlayer/*`**, jeśli używasz `react-i18next` / `next-i18next` i zależy Ci na zaoszczędzeniu 68 KB, 8-krotnie mniejszych komponentach, 0% wycieków, typowanych kluczach i testach w CI bez konieczności przepisywania kodu. To idealny punkt wyjścia dla istniejącej bazy kodu `i18next`.
-- **Wybierz rozwiązanie natywne (`next-intlayer` / `react-intlayer`)** dla nowych projektów lub gdy adapter spełnił już swoje zadanie. Jest najlżejszy z całej trójki (5.5 KB, +0.3 KB na stronę) i odblokowuje synchroniczne komponenty serwerowe oraz pliki `.content.ts` powiązane z komponentami.
+<AccordionGroup>
+<Accordion header="Pozostań przy i18next">
+
+Twoja aplikacja zależy od backendów w czasie wykonywania (tłumaczenia serwowane przez CMS w momencie żądania), od ekosystemu wtyczek lub od środowiska innego niż React, którego adaptery nie obsługują.
+
+</Accordion>
+<Accordion header="Użyj @intlayer/*">
+
+Używasz `react-i18next` / `next-i18next` i chcesz zaoszczędzić 68 KB, mieć 8-krotnie mniejsze komponenty, 0% wycieków, typowane klucze i testy CI bez przepisywania kodu. To punkt wejścia dla istniejącej bazy kodu `i18next`.
+
+</Accordion>
+<Accordion header="Przejdź na rozwiązanie natywne (next-intlayer / react-intlayer)">
+
+Dla nowych projektów lub po zakończeniu pracy przez adapter. Ma najlżejszy runtime (5.5 KB, +0.3 KB na stronę) i odblokowuje synchroniczne Server Components oraz pliki `.content.ts` dla każdego komponentu. Zacznij od [Intlayer z Next.js](https://intlayer.org/pl/doc/environment/nextjs) lub [z Vite i React](https://intlayer.org/pl/doc/environment/vite-and-react).
+
+</Accordion>
+</AccordionGroup>
+
+## Często zadawane pytania
+
+<FAQ>
+
+<Question title="Skąd bierze się 68 KB?">
+
+Z `resources: { en, fr, ... }`. Domyślna konfiguracja `next-i18next` importuje JSON każdego języka do `init()`, przez co każda strona przenosi każdy namespace w każdym języku: **218.5 KB** na stronę. Adapter nigdy nie dołącza tego bloku w całości; przekazuje każdemu komponentowi tylko żądany słownik w aktywnym języku.
+
+</Question>
+
+<Question title="Czy moje komponenty <Trans> nadal działają?">
+
+Tak, z `components`, numerowanymi tagami `<1>...</1>` oraz `values`. Podobnie z `{{interpolation}}`, zagnieżdżaniem `$t(key)`, formami mnogimi `key_one` / `key_other` (ocenianymi za pomocą `Intl.PluralRules`), sufiksami kontekstowymi i `returnObjects`.
+
+</Question>
+
+<Question title="Co jeśli używam pojedynczego translation.json na język?">
+
+Ustaw `splitKeys: false` we wtyczce `syncJSON`. Cały plik pozostanie jednym słownikiem, a standardowe wywołanie `useTranslation()` będzie nadal na niego wskazywać.
+
+</Question>
+
+<Question title="Czy to to samo co migracja do Intlayer?">
+
+Nie, to pomost. Adapter zachowuje API `i18next` i kosztuje 9.4 KB runtime; natywny `next-intlayer` kosztuje 5.5 KB i dodaje synchroniczne Server Components oraz pliki `.content.ts` umieszczone obok komponentów. Możesz migrować komponent po komponencie, ponieważ słowniki JSON i `.content.ts` współistnieją.
+
+</Question>
+
+<Question title="Czy tłumacze mogą nadal pracować tak jak dzisiaj?">
+
+Tak. `locales/{lng}/{ns}.json` pozostaje źródłem prawdy: `syncJSON` odczytuje go w dialekcie i18next i zapisuje tłumaczenia z powrotem, gdy CLI lub CMS je zaktualizuje.
+
+</Question>
+
+</FAQ>
 
 ## Powiązane porównania
 
-- [i18next vs Intlayer](https://intlayer.org/pl/blog/i18next-vs-intlayer) (biblioteki, ten sam benchmark)
-- [next-intl vs @intlayer/next-intl](https://intlayer.org/pl/blog/next-intl-vs-intlayer-next-intl) (ta sama seria adapterów)
-- [Lingui vs @intlayer/lingui](https://intlayer.org/pl/blog/lingui-vs-intlayer-lingui) (ta sama seria adapterów)
-- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/pl/blog/vue-i18n-vs-intlayer-vue-i18n) (ta sama seria adapterów)
-- Przewodniki migracji: [i18next](https://intlayer.org/pl/doc/migration/i18next), [react-i18next](https://intlayer.org/pl/doc/migration/react-i18next), [next-i18next](https://intlayer.org/pl/doc/migration/next-i18next)
-- Dokumentacja adapterów kompatybilności: [i18next](https://intlayer.org/pl/doc/compatibility/i18next), [react-i18next](https://intlayer.org/pl/doc/compatibility/react-i18next), [next-i18next](https://intlayer.org/pl/doc/compatibility/next-i18next)
+Ta sama seria adapterów:
+
+- [next-intl vs @intlayer/next-intl](https://intlayer.org/pl/blog/next-intl-vs-intlayer-next-intl)
+- [Lingui vs @intlayer/lingui](https://intlayer.org/pl/blog/lingui-vs-intlayer-lingui)
+- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/pl/blog/vue-i18n-vs-intlayer-vue-i18n)
+
+Biblioteki w bezpośrednim porównaniu:
+
+- [i18next vs Intlayer](https://intlayer.org/pl/blog/i18next-vs-intlayer), same benchmark
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/pl/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/pl/blog/react-i18next-vs-react-intl-vs-intlayer)
+- [Is i18next outdated?](https://intlayer.org/pl/blog/is-i18next-outdated)
+
+Dokumentacja referencyjna:
+
+- Compat adapters: [i18next](https://intlayer.org/pl/doc/compatibility/i18next), [react-i18next](https://intlayer.org/pl/doc/compatibility/react-i18next), [next-i18next](https://intlayer.org/pl/doc/compatibility/next-i18next)
+- Migration guides: [i18next](https://intlayer.org/pl/doc/migration/i18next), [react-i18next](https://intlayer.org/pl/doc/migration/react-i18next), [next-i18next](https://intlayer.org/pl/doc/migration/next-i18next)
+- [Next.js benchmark report](https://intlayer.org/pl/doc/benchmark/nextjs) and [TanStack Start benchmark report](https://intlayer.org/pl/doc/benchmark/tanstack)
+- [Bundle optimization](https://intlayer.org/pl/doc/concept/bundle-optimization) and [the Intlayer compiler](https://intlayer.org/pl/doc/compiler)
+- [Visual Editor](https://intlayer.org/pl/doc/concept/editor), [CMS](https://intlayer.org/pl/doc/concept/cms) and [AI translation](https://intlayer.org/pl/doc/concept/auto-fill)
 
 ## Podsumowanie