@intlayer/docs 9.5.6 → 9.5.8

package/blog/ko/i18next_vs_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "i18next vs Intlayer: 2026 벤치마크 및 비교"
 description: "Next.js 및 TanStack Start 환경에서 react-i18next와 next-i18next를 Intlayer와 비교 측정한 결과. 번들 크기, 콘텐츠 누출, 로케일 전환 반응성 및 개발자 경험 분석."
 keywords:
@@ -25,6 +25,8 @@ author: aymericzip
 
 # i18next VS Intlayer | React & Next.js 국제화 (i18n) 벤チ마크 비교
 
+![i18next VS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18next-next-intl-intlayer.webp?raw=true)
+
 `i18next`는 JavaScript 생태계에서 가장 널리 사용되는 i18n 프레임워크입니다. `react-i18next`와 `next-i18next`를 통해 수많은 React 및 Next.js 애플리케이션의 다국어를 지원하고 있습니다. Intlayer는 컴파일러 기반의 컴포넌트 스코프 콘텐츠 아키텍처를 제공하는 대안입니다.
 
 이 글에서는 단순한 기능 나열 대신 실제 측정 지표를 바탕으로 두 솔루션을 비교합니다. 모든 수치는 동일한 애플리케이션을 각 라이브러리로 빌드하고 브라우저가 실제로 다운로드하는 리소스를 기록하는 오픈 소스 벤치마크 제품군 [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom)에서 추출되었습니다.
@@ -74,9 +76,7 @@ author: aymericzip
 
 ### 측정 기준 및 환경
 
-[Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom) 테스트 스위트는 각 라이브러리를 사용하여 **완전히 동일한 애플리케이션**을 빌드합니다: **10개 페이지**(홈, 소개, 블로그, 채용, 문의, FAQ, 가격, 제품, 설정, 팀), **10개 로케일**(`en`, `fr`, `es`, `de`, `it`, `pt`, `zh`, `ja`, `ko`, `ru`), 동일한 컴포넌트 및 동일한 콘텐츠. 측정은 `en`과 `fr` 페이지를 대상으로 진행되었습니다.
-
-각 라이브러리는 최소 설정부터 최적화 설정까지 최대 네 가지 **로딩 전략**으로 구현되었습니다:
+[Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom) 테스트 스위트는 각 라이브러리를 사용하여 **완전히 동일한 애플리케이션**을 빌드합니다: **10개 페이지**(홈, 소개, 블로그, 채용, 문의, FAQ, 가격, 제품, 설정, 팀), **10개 로케일**(`en`, `fr`, `es`, `de`, `it`, `pt`, `zh`, `ja`, `ko`, `ru`), 동일한 컴포넌트 및 동일한 콘텐츠. 측정은 `en`과 `fr` 페이지를 대상으로 진행되었습니다. 각 라이브러리는 최소 설정부터 최적화 설정까지 최대 네 가지 **로딩 전략**으로 구현되었습니다:
 
 | 전략               | 설명                                                                              | 사용 사례                              |
 | ------------------ | --------------------------------------------------------------------------------- | -------------------------------------- |
@@ -101,6 +101,10 @@ Intlayer는 별도의 "scoped" 변형이 없습니다. 컴파일러가 콘텐츠
 
 ### Next.js 결과 (`next-i18next`)
 
+관심 있는 지표와 라이브러리를 선택하세요:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | 라이브러리                      | 전략           | Lib size (gz) | Page JS avg (gz) | Locale leak | Page leak | Component avg (gz) |  E2E 반응성 | Hydration |
 | ------------------------------- | -------------- | ------------: | ---------------: | ----------: | --------: | -----------------: | ----------: | --------: |
 | **base** (i18n 없음)            | -              |        0.0 KB |         141.0 KB |        0.0% |      0.0% |             0.9 KB |     13.4 ms |   11.8 ms |
@@ -121,6 +125,15 @@ Intlayer는 별도의 "scoped" 변형이 없습니다. 컴파일러가 콘텐츠
 - **컴포넌트 크기**: `useTranslation()`을 호출하는 컴포넌트는 설정에 따라 26~79 KB에 달하지만, `useIntlayer()`를 사용하는 동일 컴포넌트는 6.9 KB에 불과합니다.
 - **하이드레이션 지연**: `dynamic` 구성에서 하이드레이션 시간이 27.7 ms로 급증합니다. React가 하이드레이션을 수행하기 전에 클라이언트에서 i18next 인스턴스가 초기화되고 백엔드를 처리해야 하기 때문입니다.
 
+<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;"
+/>
+
+> 전체 라이브러리와 전략이 포함된 상세 표는 [Next.js 벤치마크 보고서](https://intlayer.org/ko/doc/benchmark/nextjs)에서 확인하세요.
+
 ### TanStack Start 결과 (`react-i18next`)
 
 Next.js 특유의 구조적 차이를 배제하고 TanStack Start 환경에서 순수 `react-i18next`로 측정한 결과입니다.
@@ -143,8 +156,19 @@ Next.js 특유의 구조적 차이를 배제하고 TanStack Start 환경에서
 - Intlayer의 `static`은 해당 페이지의 컴포넌트가 직접 임포트한 사전만 포함하므로 이미 **페이지 누출 0%**를 달성합니다. `importMode: 'dynamic'`을 활성화하면 로케일 누출도 완전히 제거됩니다.
 - **컴포넌트 크기**: `react-i18next` 컴포넌트가 24-27 KB인 반면 Intlayer는 6-8 KB입니다.
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> 상세 표는 [TanStack Start 벤치마크 보고서](https://intlayer.org/ko/doc/benchmark/tanstack)에서 확인하세요.
+
 ## 차이의 원인: 글로벌 인스턴스 vs 컴파일된 사전
 
+![Centralized catalogs versus per-component dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/assets/project_stucture_18n_vs_intlayer.png?raw=true)
+
 `i18next`는 2012년에 런타임 중심 모델로 설계되었습니다: 글로벌 인스턴스가 리소스 저장소를 관리하고 플러그인이 이를 확장하며, 렌더링 시 `t()`가 키를 조회합니다. 이는 매우 유연하지만(어떤 프레임워크나 포맷도 지원) 구조적인 오버헤드를 유발합니다:
 
 ```bash
@@ -168,7 +192,13 @@ Next.js 특유의 구조적 차이를 배제하고 TanStack Start 환경에서
                 └── page.tsx     # ["common", "about"] 필요 여부를 직접 알아야 함
 ```
 
-인스턴스는 컴포넌트가 어떤 키를 요청할지 미리 알 수 없으므로 지시된 모든 네임스페이스를 유지합니다. 따라서 최적화를 위해 **개발자**가 카탈로그를 분할하고, 페이지별 네임스페이스를 정의하고, 컴포넌트 이동 시마다 이를 관리해야 합니다. [벤치마크 노트](https://github.com/intlayer-org/benchmark-bloom/blob/main/report/NOTE.md)에서 언급하듯 "타입 안전성을 유지하면서 각 페이지에 필요한 네임스페이스를 완벽히 파악하는 것은 매우 번거로운 일"입니다.
+인스턴스는 컴포넌트가 어떤 키를 요청할지 미리 알 수 없으므로 지시된 모든 네임스페이스를 유지합니다. 따라서 최적화를 위해 **개발자**가 카탈로그를 분할하고, 페이지별 네임스페이스를 정의하고, 컴포넌트 이동 시마다 이를 관리해야 합니다.
+
+낭비되는 리소스는 페이지와 로케일 두 가지 축으로 동시에 증가합니다:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
+
+[벤치마크 노트](https://github.com/intlayer-org/benchmark-bloom/blob/main/report/NOTE.md)에서 언급하듯 "타입 안전성을 유지하면서 각 페이지에 필요한 네임스페이스를 완벽히 파악하는 것은 매우 번거로운 일"입니다.
 
 Intlayer는 글로벌 인스턴스를 사용하지 않습니다. 콘텐츠가 컴포넌트 옆에 선언되며 컴파일러가 빌드 타임에 종속성 트리를 분석합니다:
 
@@ -195,7 +225,8 @@ Intlayer는 글로벌 인스턴스를 사용하지 않습니다. 콘텐츠가
 
 ### 초기 설정 비교
 
-**next-i18next (App Router)**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-i18next" value="i18next">
 
 ```ts fileName="src/app/i18n/server.ts"
 import { createInstance } from "i18next";
@@ -230,7 +261,8 @@ export const initI18next = async (
 
 여기에 추가로 클라이언트용 `I18nProvider`, `generateStaticParams`, 그리고 각 페이지의 `namespaces` 목록 관리가 필요합니다.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="intlayer.config.ts"
 import { type IntlayerConfig, Locales } from "intlayer";
@@ -266,9 +298,13 @@ const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
 export default LocaleLayout;
 ```
 
+</Tab>
+</Tabs>
+
 ### 클라이언트 컴포넌트
 
-**react-i18next**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="react-i18next" value="i18next">
 
 ```json fileName="src/locales/en/about.json"
 {
@@ -306,7 +342,8 @@ export const Counter = () => {
 
 > 이 컴포넌트를 렌더링하는 페이지는 `about` 네임스페이스를 로드해야 하며, `CustomTypeOptions`를 확장하지 않으면 `t("counter.label")`에 엄격한 타입이 적용되지 않습니다.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/components/Counter/index.content.ts"
 import { t, type Dictionary } from "intlayer";
@@ -347,9 +384,13 @@ export const Counter = () => {
 
 `label`과 `increment`는 엄격히 타입이 지정됩니다. 오타는 TypeScript 에러가 되고, 프랑스어 번역 누락은 빌드 에러로 처리됩니다.
 
+</Tab>
+</Tabs>
+
 ### 동기식 서버 컴포넌트
 
-**next-i18next**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-i18next" value="i18next">
 
 ```tsx fileName="src/components/ServerCounter.tsx"
 type ServerCounterProps = {
@@ -368,7 +409,8 @@ export const ServerCounter = ({ t, locale, count }: ServerCounterProps) => (
 
 페이지에서 `i18n.getFixedT(locale, "about")`를 호출한 후 하위 컴포넌트로 `t`와 `locale`을 넘겨주어야 합니다.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```tsx fileName="src/components/ServerCounter.tsx"
 import { useIntlayer } from "next-intlayer/server";
@@ -387,6 +429,9 @@ export const ServerCounter = ({ count }: { count: number }) => {
 };
 ```
 
+</Tab>
+</Tabs>
+
 ## i18next API를 유지하면서 Intlayer의 성능 얻기
 
 기존 컴포넌트를 전부 다시 작성하지 않고도 벤치마크 성능을 누릴 수 있습니다. `@intlayer/i18next`, `@intlayer/react-i18next`, `@intlayer/next-i18next`는 드롭인 호환 어댑터입니다: `useTranslation`, `t()`, `<Trans>`, `{{interpolation}}`, 복수형 접미사, 컨텍스트 접미사 및 `returnObjects`가 그대로 작동하며, 백그라운드에서는 Intlayer 컴파일러가 사전을 공급합니다.
@@ -417,18 +462,85 @@ export default defineConfig({
 
 ## 어떤 도구를 선택해야 할까요?
 
-- **i18next를 선택할 경우**: 광범위한 플러그인 생태계(감지기, 백엔드, ICU, Locize 등)가 필수적이거나, React 외부 환경(Node 서비스, Vanilla JS, 기타 프레임워크)에서도 동일하게 사용해야 하거나, 팀원들이 이미 익숙하거나, 번역 플랫폼이 `locales/{lng}/{ns}.json`을 요구할 때. 단, 성능이 중요하다면 네임스페이스 분할과 라우트 매핑 관리에 시간을 투자해야 합니다.
-- **Intlayer를 선택할 경우**: **컴포넌트 중심의 콘텐츠 관리**, **엄격한 TypeScript 타입 지원**, **빌드 시 누락 번역 감지**, **무설정 트리 쉐이킹 및 지연 로딩**, 즉각적인 로케일 전환, 동기식 서버 컴포넌트, 통합 편집 도구(비주얼 에디터, CMS, AI 번역, MCP 서버)를 원할 때. 모듈식 코드베이스 및 디자인 시스템에 특히 적합합니다.
-- **`@intlayer/*-i18next` 어댑터를 선택할 경우**: 이미 i18next를 사용 중이며 코드 리팩토링 없이 번들 크기와 반응성을 대폭 개선하고 싶을 때.
+<AccordionGroup>
+<Accordion header="i18next를 선택해야 하는 경우">
+
+광범위한 플러그인 생태계(감지기, 백엔드, ICU, Locize 등)가 필수적이거나, React 외부 환경(Node 서비스, Vanilla JS, 기타 프레임워크)에서도 동일하게 사용해야 하거나, 팀원들이 이미 익숙하거나, 번역 플랫폼이 `locales/{lng}/{ns}.json`을 요구할 때. 단, 성능이 중요하다면 네임스페이스 분할과 라우트 매핑 관리에 시간을 투자해야 합니다.
+
+</Accordion>
+<Accordion header="Intlayer를 선택해야 하는 경우">
+
+**컴포넌트 단위 콘텐츠 관리**, **엄격한 TypeScript 지원**, **빌드 시점 누락 키 감지**, **별도 설정 없는 Tree-shaking 및 지연 로딩**, 즉각적인 로케일 전환, 동기식 서버 컴포넌트, 내장 편집 도구([시각적 편집기](https://intlayer.org/ko/doc/concept/editor), [CMS](https://intlayer.org/ko/doc/concept/cms), [AI 자동 번역](https://intlayer.org/ko/doc/concept/auto-fill), [MCP 서버](https://intlayer.org/ko/doc/mcp-server))를 원할 때 적합합니다. 대규모 모듈식 코드베이스와 디자인 시스템에 특히 유용합니다.
+
+</Accordion>
+<Accordion header="@intlayer/*-i18next 어댑터를 선택해야 하는 경우">
+
+이미 i18next를 사용 중이며 컴포넌트를 다시 작성하지 않고 번들 크기 축소와 반응성 향상을 원할 때 적합합니다. 기존 `locales/{lng}/{ns}.json` 파일이 그대로 진실의 원천으로 유지됩니다. [i18next vs @intlayer/i18next](https://intlayer.org/ko/blog/i18next-vs-intlayer-i18next)에서 나란히 측정되었습니다.
+
+</Accordion>
+</AccordionGroup>
+
+## 자주 묻는 질문 (FAQ)
+
+<FAQ>
+
+<Question title="왜 i18next는 다른 최신 라이브러리보다 훨씬 무거운가요?">
+
+프레임워크에 구애받지 않는 범용 런타임으로 설계되었기 때문입니다. 전역 인스턴스, 플러그인 파이프라인, 리소스 저장소, 키 해석기를 포함합니다. 이러한 유연성이 모든 번들에 컴파일됩니다. 라이브러리만 임포트하는 빈 컴포넌트도 `next-i18next`는 **19.7 KB gzip**, `next-intlayer`는 **5.5 KB**를 차지하며, 이 비용은 콘텐츠 크기와 무관하게 모든 페이지에서 발생합니다.
+
+</Question>
+
+<Question title="백엔드를 통한 지연 로딩으로 해결할 수 있나요?">
+
+용량은 줄어들지만 지연 시간(레이턴시)은 해결되지 않습니다. `i18next-resources-to-backend`로 전환하면 페이지당 약 49 KB가 절약되지만, 언어 전환 시 네트워크 왕복이 발생합니다. Intlayer의 **3-4 ms**에 비해 `dynamic` 설정은 **123 ms**, `scoped-static`은 **185 ms**가 걸립니다. 또한 React가 하이드레이션하기 전에 인스턴스가 백엔드를 해석해야 하므로 하이드레이션 시간도 27.7 ms로 급증합니다.
+
+</Question>
+
+<Question title="i18next로 0% 콘텐츠 누출을 달성할 수 있나요?">
+
+네, `scoped-dynamic` 설정을 통해 가능합니다. 라우트당 하나의 네임스페이스, 리소스 백엔드, 직접 유지 관리하는 페이지-네임스페이스 맵이 필요합니다. Next.js에서 페이지당 163.4 KB에 도달하지만, 아무런 설정도 필요 없는 Intlayer(141.3 KB)보다 여전히 **+22 KB** 무겁습니다. [번들 최적화](https://intlayer.org/ko/doc/concept/bundle-optimization)를 참조하세요.
+
+</Question>
+
+<Question title="마이그레이션하려면 컴포넌트를 모두 다시 작성해야 하나요?">
+
+아닙니다. `@intlayer/i18next`, `@intlayer/react-i18next`, `@intlayer/next-i18next`는 `useTranslation`, `t()`, `<Trans>`, `{{interpolation}}`, `_one` / `_other` 복수형, 컨텍스트 접미사, `returnObjects`를 그대로 유지합니다. `next.config.ts`나 `vite.config.ts`에 플러그인 한 줄만 추가하면 됩니다. 단계별 안내는 [next-i18next 마이그레이션 가이드](https://intlayer.org/ko/doc/migration/next-i18next)를 확인하세요.
+
+</Question>
+
+<Question title="기존 i18next 플러그인은 어떻게 되나요?">
+
+백엔드 및 언어 감지 플러그인은 허용되지만 비활성 상태로 유지됩니다. 런타임에 로드하거나 감지할 것이 남아있지 않기 때문입니다. 언어 감지는 Intlayer의 라우팅 설정(URL 접두사, 쿠키, 헤더)으로 대체됩니다. 앱이 요청 시 CMS에서 번역을 가져오는 구조라면 [Intlayer CMS](https://intlayer.org/ko/doc/concept/cms)나 `intlayer pull` / `push`를 사용하세요.
+
+</Question>
+
+</FAQ>
 
 ## 관련 비교 자료
 
-- [next-intl vs Intlayer](https://intlayer.org/ko/blog/next-intl-vs-intlayer) (동일 벤치마크)
-- [Lingui vs Intlayer](https://intlayer.org/ko/blog/lingui-vs-intlayer) (동일 벤치마크)
-- [vue-i18n vs Intlayer 벤치마크](https://intlayer.org/ko/blog/vue-i18n-vs-intlayer-benchmark) (동일 벤치마크)
+동일 벤치마크, 다른 라이브러리 비교:
+
+- [next-intl vs Intlayer](https://intlayer.org/ko/blog/next-intl-vs-intlayer)
+- [Lingui vs Intlayer](https://intlayer.org/ko/blog/lingui-vs-intlayer)
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/ko/blog/vue-i18n-vs-intlayer-benchmark)
 - [next-i18next vs next-intl vs Intlayer](https://intlayer.org/ko/blog/next-i18next-vs-next-intl-vs-intlayer)
 - [react-i18next vs react-intl vs Intlayer](https://intlayer.org/ko/blog/react-i18next-vs-react-intl-vs-intlayer)
+
+i18next에 대해 더 알아보기:
+
+- [i18next vs @intlayer/i18next](https://intlayer.org/ko/blog/i18next-vs-intlayer-i18next), 동일한 앱에서 측정된 어댑터 비교
 - [i18next는 구식인가요?](https://intlayer.org/ko/blog/is-i18next-outdated)
+- [i18next와 함께 Intlayer 사용하기](https://intlayer.org/ko/blog/intlayer-with-i18next) 및 [react-i18next와 함께 사용](https://intlayer.org/ko/blog/intlayer-with-react-i18next)
+- [next-i18next로 Next.js 앱 국제화하기](https://intlayer.org/ko/blog/nextjs-internationalization-using-next-i18next)
+
+참고 문서:
+
+- [Next.js 벤치마크 보고서](https://intlayer.org/ko/doc/benchmark/nextjs) 및 [TanStack Start 벤치마크 보고서](https://intlayer.org/ko/doc/benchmark/tanstack)
+- 호환 어댑터: [i18next](https://intlayer.org/ko/doc/compatibility/i18next), [react-i18next](https://intlayer.org/ko/doc/compatibility/react-i18next), [next-i18next](https://intlayer.org/ko/doc/compatibility/next-i18next)
+- 마이그레이션 가이드: [i18next](https://intlayer.org/ko/doc/migration/i18next), [react-i18next](https://intlayer.org/ko/doc/migration/react-i18next), [next-i18next](https://intlayer.org/ko/doc/migration/next-i18next)
+- [번들 최적화](https://intlayer.org/ko/doc/concept/bundle-optimization) 및 [Intlayer 컴파일러](https://intlayer.org/ko/doc/compiler)
+- [컴포넌트별 vs 중앙 집중식 i18n](https://intlayer.org/ko/blog/per-component-vs-centralized-i18n)
+- [컴파일러 기반 vs 선언적 i18n](https://intlayer.org/ko/blog/compiler-vs-declarative-i18n)
 
 ## GitHub 스타
 

package/blog/ko/is_intlayer_lighter_than_paraglide.md

@@ -0,0 +1,284 @@
+---
+createdAt: 2026-09-23
+updatedAt: 2026-09-23
+title: Intlayer는 Paraglide보다 가벼운가요?
+description: Paraglide는 코드가 저장소 내부로 생성되기 때문에 i18n 벤치마크에서 거의 무료처럼 보입니다. 그 용량이 실제로 어디로 가는지, 노드별 로케일 조회가 성능을 저하시키는 이유, 그리고 Intlayer의 동적 로딩이 모든 언어 대신 단 하나의 로케일만 번들에 포함시키는 방식을 살펴봅니다.
+keywords:
+  - Paraglide
+  - Intlayer
+  - 국제화
+  - i18n
+  - Bundle size
+  - Tree shaking
+  - Benchmark
+  - Blog
+slugs:
+  - blog
+  - is-intlayer-lighter-than-paraglide
+author: aymericzip
+---
+
+# Intlayer는 Paraglide보다 가벼운가요?
+
+네, 그렇습니다.
+
+`Paraglide`는 가장 가벼운 i18n 솔루션으로 널리 알려져 있으며, 얼핏 보면 [벤치마크](https://intlayer.org/ko/doc/benchmark/tanstack) 결과도 이에 동의하는 것처럼 보입니다. 라이브러리 크기가 거의 0에 가깝기 때문입니다. 하지만 라이브러리 크기가 0이라고 해서 브라우저로 전송되는 바이트가 0이라는 의미는 아닙니다. 그 바이트들이 해당 지표가 측정하지 않는 다른 위치에 존재한다는 뜻일 뿐입니다.
+
+<TOC/>
+
+## 핵심 요약
+
+**라이브러리 크기가 사라진 것이 아니라 숨겨진 것입니다:**
+
+Paraglide는 런타임과 메시지 함수를 사용자의 코드베이스 내부에 생성합니다. 이 코드는 브라우저로 전송되지만, 라이브러리가 아닌 _사용자의_ 코드로 집계됩니다.
+
+**Provider가 없다고 해서 공짜 이득은 아닙니다:**
+
+모든 `m.my_key()` 호출은 컨텍스트에서 한 번만 읽는 대신, 렌더링되는 노드마다 독립적으로 쿠키나 스토리지를 직접 읽어 로케일을 결정합니다.
+
+**동적 로딩(Dynamic Loading) 부재:**
+
+Paraglide는 메시지의 모든 로케일을 클라이언트 번들로 가져옵니다. 반면 Intlayer에서 `importMode: 'dynamic'` 또는 `'fetch'`를 사용하면 현재 렌더링 중인 단 하나의 로케일만 로드합니다.
+
+**Tree Shaking이 보장되지 않습니다:**
+
+일부 벤치마크 환경에서는 Paraglide가 홍보하는 Tree Shaking이 적용되지 않았습니다. 자체 번들을 반드시 확인해 보시기 바랍니다.
+
+## Paraglide의 용량은 실제로 어디로 가는가?
+
+벤치마크 보고서의 "라이브러리 크기" 지표는 콘텐츠가 추가되기 전, 빈 컴포넌트에서 각 i18n 라이브러리의 Provider와 훅(hook) 용량만을 측정합니다.
+
+| 라이브러리 (TanStack Start)   | 라이브러리 크기 (gz) | 라이브러리 크기 (min) |
+| ----------------------------- | -------------------- | --------------------- |
+| `@inlang/paraglide-js@2.15.1` | 1.8 KB               | 4.5 KB                |
+| `react-intlayer@9.5.1`        | 5.0 KB               | 15.2 KB               |
+
+이 수치만 따로 떼어놓고 보면 Paraglide가 이기는 것처럼 보입니다. 하지만 Paraglide는 컴파일러입니다. `messages/*.json` 파일을 읽어 프로젝트 저장소에 `paraglide/` 폴더를 생성하고, 여기에 `runtime.js`(로케일 감지, 쿠키 및 스토리지 전략, URL 현지화)와 메시지당 하나의 JavaScript 함수를 생성합니다.
+
+```bash
+src/paraglide/
+├── runtime.js      # 로케일 감지, 전략, URL 헬퍼
+├── server.js
+├── messages.js     # 모든 메시지 재내보내기
+└── messages/
+    ├── _index.js
+    ├── en.js
+    └── fr.js
+```
+
+이 코드는 사용자의 `src/` 폴더에 위치하고 상대 경로로 가져오기 때문에, 번들러는 이를 `node_modules` 패키지가 아니라 애플리케이션 자체 코드로 분류합니다. 결과적으로 라이브러리 크기 열에는 거의 아무것도 나타나지 않지만, 동일한 로직이 페이지 번들에 그대로 포함되어 브라우저로 전송됩니다.
+
+코드 생성 자체가 나쁜 접근법은 아닙니다. 생성된 런타임에는 설정에 필요한 로직(접두사 전략, 쿠키 vs 로컬 스토리지 등)만 포함됩니다. Intlayer는 빌드 시점에 환경 변수를 주입하여 설정에서 사용하지 않는 분기를 번들러가 자동으로 제거하는 방식으로 동일한 결과를 달성합니다. 두 방식 모두 `i18next`나 `next-intl`보다 3배에서 10배 더 가볍습니다.
+
+따라서 공정한 비교 기준은 라이브러리 크기가 아닙니다. **페이지당 실제로 전송되는 JavaScript의 양**입니다.
+
+## 실측된 페이지 용량
+
+TanStack Start 앱, 10개 페이지, `en` 및 `fr` 라우트 측정, gzip 압축:
+
+| 구성                               | 페이지 JS 평균 (gz) | 베이스 대비 | 로케일 누수 | 타 페이지 누수 |
+| ---------------------------------- | ------------------- | ----------- | ----------- | -------------- |
+| 베이스 (i18n 없음)                 | 111.0 KB            | -           | 0.0%        | 0.0%           |
+| `paraglide` (모든 전략)            | 125.1 KB            | +14.1 KB    | 49.7%       | 0.0%           |
+| `intlayer` (`importMode: static`)  | 125.8 KB            | +14.8 KB    | 50.0%       | 0.0%           |
+| `intlayer` (`importMode: dynamic`) | **118.6 KB**        | **+7.6 KB** | **0.0%**    | **0.0%**       |
+
+Next.js 16 App Router, 동일 애플리케이션:
+
+| 구성               | 페이지 JS 평균 (gz) | 베이스 대비 |
+| ------------------ | ------------------- | ----------- |
+| 베이스 (i18n 없음) | 141.0 KB            | -           |
+| `paraglide-next`   | 155.3 KB            | +14.3 KB    |
+| `next-intlayer`    | **141.3 KB**        | **+0.3 KB** |
+
+<I18nBenchmark framework="tanstack" vertical/>
+
+> 전체 데이터는 [TanStack Start 벤치마크 보고서](https://intlayer.org/ko/doc/benchmark/tanstack)와 [Next.js 벤치마크 보고서](https://intlayer.org/ko/doc/benchmark/nextjs)에서 확인할 수 있습니다. 모든 번들은 [벤치마크 저장소](https://github.com/intlayer-org/benchmark-i18n)에서 직접 분석할 수 있습니다.
+
+두 가지 주목할 만한 점이 드러납니다:
+
+- `static` 모드에서 Intlayer는 Paraglide와 사실상 동일한 양의 콘텐츠를 전송합니다(125.8 KB vs. 125.1 KB). 이는 자연스러운 결과입니다. 둘 다 페이지에서 사용하는 메시지의 모든 로케일을 포함하기 때문입니다.
+- Paraglide는 동적 모드를 지원하지 않으므로 어떤 전략을 사용하든 125.1 KB로 유지됩니다. 위의 표에 있는 모든 행이 정적 방식에 해당합니다.
+
+## Provider 부재: 좋아 보이지만 실상은 그렇지 않은 설계
+
+Paraglide에는 Provider가 없습니다. 메시지를 가져와 바로 호출하기만 하면 됩니다:
+
+```tsx fileName="Hero.tsx"
+import { m } from "../paraglide/messages.js";
+
+export const Hero = () => (
+  <section>
+    <h1>{m.hero_title()}</h1>
+    <p>{m.hero_description()}</p>
+    <button>{m.hero_cta()}</button>
+  </section>
+);
+```
+
+컨텍스트도, 래퍼도, 훅도 없습니다. 겉보기에는 훨씬 단순해 보입니다. 그러나 로케일 정보는 여전히 어디선가 읽어와야 합니다. 생성된 각 메시지 함수는 대략 다음과 같이 생겼습니다(단순화한 코드):
+
+```js fileName="paraglide/messages/_index.js"
+export const hero_title = (inputs = {}, options = {}) => {
+  const locale = options.locale ?? getLocale(); // 매 호출마다 실행됨
+
+  if (locale === "en") return en.hero_title(inputs);
+  if (locale === "fr") return fr.hero_title(inputs);
+  // ...로케일별 분기
+};
+```
+
+그리고 `getLocale()`은 설정된 전략(쿠키, 로컬 스토리지, URL, 기본 로케일)을 순회하며 현재 로케일을 찾습니다. 즉, 렌더링되는 모든 텍스트 노드(`<>{m.my_key()}</>`)가 브라우저의 `document.cookie` 읽기를 포함하여 자체적으로 로케일 확인 로직을 수행합니다. 200개의 번역 문자열이 있는 페이지는 렌더링당 200번의 로케일 조회를 실행하고, 리렌더링마다 이를 반복합니다.
+
+반면 Provider 기반 라이브러리는 로케일을 **단 한 번만** 읽어 컨텍스트(또는 시그널, 스토어)에 저장하고, 각 노드는 이미 메모리에 저장된 값을 참조합니다. Provider의 크기는 수백 바이트에 불과합니다. 이를 생략하면 렌더링마다 CPU 오버헤드가 발생하며, 이는 벤치마크 결과에 뚜렷하게 반영됩니다. TanStack Start에서 Paraglide의 페이지 로드 및 언어 전환 속도는 Intlayer에 일관되게 뒤처집니다(페이지 로드 22.1 ms vs 14.6 ms, E2E 반응 속도 4.3 ms vs 3.2 ms).
+
+## 개발자 경험 (Developer Experience)
+
+Paraglide의 원본 소스는 JSON이지만, 개발자가 JSON을 직접 가져오지는 않습니다. 컴파일러가 생성한 `.js` 파일을 가져옵니다:
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="Paraglide" value="paraglide">
+
+```json fileName="messages/en.json"
+{
+  "hero_title": "Ship your app in every language"
+}
+```
+
+```json fileName="messages/ko.json"
+{
+  "hero_title": "모든 언어로 앱을 배포하세요"
+}
+```
+
+```tsx fileName="Hero.tsx"
+// 컴파일러가 JSON을 바탕으로 다시 생성한 이후에만 사용 가능
+import { m } from "../paraglide/messages.js";
+
+export const Hero = () => <h1>{m.hero_title()}</h1>;
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```ts fileName="Hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero",
+  content: {
+    title: t({
+      ko: "모든 언어로 앱을 배포하세요",
+      en: "Ship your app in every language",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+```tsx fileName="Hero.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export const Hero = () => {
+  const { title } = useIntlayer("hero");
+
+  return <h1>{title}</h1>;
+};
+```
+
+  </Tab>
+</Tabs>
+
+이러한 개발 워크플로우에는 단점이 따릅니다:
+
+- JSON 파일이 변경될 때마다 import가 정상 인식되거나 타입이 갱신되기 전에 재생성 과정을 거쳐야 합니다.
+- 생성된 `paraglide/` 폴더를 Git에 커밋하거나(텍스트를 변경하는 PR마다 생성 파일 충돌 발생) Git에서 무시해야(타입 체크, 테스트, CI 작업 전에 매번 생성 단계 필수) 합니다.
+- 모든 문자열이 함수 호출로 변환됩니다. 단순한 고정 값으로 충분한 곳을 포함하여 모든 곳에서 상수가 `m.key()`로 바뀝니다.
+
+## Tree Shaking: 자체 번들을 점검하세요
+
+Paraglide의 핵심 장점은 각 메시지가 독립적인 export이므로 사용되지 않는 메시지가 Tree Shaking으로 제거된다는 점입니다. Svelte + Vite 벤치마크에서는 이 기능이 설명대로 잘 작동했습니다.
+
+하지만 다른 환경에서는 그렇지 못했습니다. [Next.js](https://intlayer.org/ko/doc/benchmark/nextjs) 측정에서 Paraglide 페이지는 기본 앱보다 14 KB 무거웠던 반면, `next-intlayer`는 0.3 KB만 추가했습니다. TanStack Start의 이전 테스트에서도 다른 페이지의 메시지가 현재 라우트 번들에 섞여 들어가는 현상이 확인되었습니다.
+
+Tree Shaking은 번들러(Turbopack, Rolldown, Rollup), 메시지 import 방식(`import { m }` vs. `import * as m`), 부수 효과(side effect) 분석에 크게 의존합니다. 번들 크기 때문에 Paraglide를 고려하고 있다면, 번들 분석기를 열어 프로젝트에서 실제로 Tree Shaking이 정상 작동하는지 확인하시기 바랍니다.
+
+## 동적 로딩 부재
+
+이것은 구조적인 한계입니다. Paraglide에는 한 번에 하나의 로케일만 로드할 수 있는 메커니즘이 없습니다. 모든 메시지 함수가 각 언어의 구현을 정적으로 가져오므로 모든 언어가 클라이언트 번들에 고스란히 포함됩니다.
+
+2개 언어를 지원할 경우 번역 데이터의 절반이 낭비되며, 이는 위에서 측정한 ~50%의 로케일 누수와 정확히 일치합니다. 10개 언어의 경우 90%, 30개 언어의 경우 97%가 낭비됩니다.
+
+이를 동적 로딩으로 바꾼다고 해결되지는 않습니다. 메시지마다 별도의 함수가 존재하므로, 각 함수를 지연 로딩하면 수천 번의 네트워크 요청이 발생하게 됩니다.
+
+Intlayer는 전역 또는 딕셔너리별로 유연한 선택권을 제공합니다:
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  dictionary: {
+    importMode: "dynamic", // 'static' | 'dynamic' | 'fetch'
+  },
+};
+
+export default config;
+```
+
+| `importMode` | 클라이언트로 전송되는 내용                 | vs. Paraglide                     |
+| ------------ | ------------------------------------------ | --------------------------------- |
+| `static`     | 페이지에서 사용하는 딕셔너리의 모든 로케일 | 이론적으로 동일한 용량            |
+| `dynamic`    | 현재 로케일만 딕셔너리 단위로 지연 로드    | N개 로케일 기준 **N배 더 가벼움** |
+| `fetch`      | 현재 로케일만 Live Sync API를 통해 가져옴  | N개 로케일 기준 **N배 더 가벼움** |
+
+[빌드 변환](https://intlayer.org/ko/doc/concept/bundle-optimization)과 `importMode: 'static'`을 사용하면, Intlayer는 이론상 Paraglide와 완전히 동일한 크기의 콘텐츠를 전송합니다. `'dynamic'` 또는 `'fetch'` 모드에서는 현재 로케일에 필요한 내용만 가져오므로, N개 언어를 지원하는 애플리케이션의 경우 번역 페이로드가 Paraglide 대비 N분의 1로 줄어듭니다.
+
+## Paraglide가 여전히 유용한 경우
+
+<AccordionGroup>
+<Accordion header="지원 언어가 적은 Svelte + Vite 환경">
+
+스택이 Svelte + Vite 기반이고 2~3개 언어만 지원한다면, Tree Shaking이 정상 작동하여 추가 언어로 인한 오버헤드가 적습니다.
+
+</Accordion>
+<Accordion header="기존 inlang 워크플로우를 사용하는 팀">
+
+이미 inlang 생태계(Fink, Sherlock, 메시지 포맷 플러그인)를 활용하고 있는 팀이라면 Paraglide와 원활하게 통합할 수 있습니다.
+
+</Accordion>
+</AccordionGroup>
+
+## 실제 애플리케이션에서 테스트해 보세요
+
+무료 [i18n SEO Scanner](https://intlayer.org/i18n-seo-scanner)를 통해 프로덕션 애플리케이션의 번들 크기와 로케일 누수를 확인해 보세요:
+
+<ClickToOpenIframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+Intlayer 설정 방법:
+
+```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
+```
+
+## 추가 자료
+
+- [TanStack Start i18n 벤치마크](https://intlayer.org/ko/doc/benchmark/tanstack)
+- [Next.js i18n 벤치마크](https://intlayer.org/ko/doc/benchmark/nextjs)
+- [번들 최적화 및 `importMode`](https://intlayer.org/ko/doc/concept/bundle-optimization)
+- [React i18n 라이브러리 선택 가이드](https://intlayer.org/ko/blog/how-to-pick-react-i18n-library)
+- [컴파일러 기반 국제화의 장단점](https://intlayer.org/ko/blog/compiler-vs-declarative-i18n)