@intlayer/docs 9.5.5 → 9.5.7

package/blog/ko/next-intl_vs_intlayer-next-intl.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "next-intl vs @intlayer/next-intl: 동일한 API, 다른 번들"
 description: Next.js 앱의 next-intl imports가 @intlayer/next-intl compat adapter에 의해 제공될 때 어떤 변화가 생기는지 알아봅니다. 동일한 코드에서 측정된 번들 크기, leakage, 컴포넌트 크기 및 hydration, 그리고 adapter가 유지하는 것, 무시하는 것 및 대체할 수 없는 것.
 keywords:
@@ -26,6 +26,8 @@ author: aymericzip
 
 # next-intl VS @intlayer/next-intl | 동일한 API, 다른 번들
 
+![next-intl VS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18next-next-intl-intlayer.webp?raw=true)
+
 `@intlayer/next-intl`는 호환성 어댑터입니다. `next-intl` API (`useTranslations`, `getTranslations`, `useLocale`, `t.rich()`, ICU plurals, `NextIntlClientProvider`...)를 노출하고 Intlayer에서 컴파일한 딕셔너리로부터 제공합니다. 애플리케이션 코드는 변경되지 않습니다. 번들만 달라집니다.
 
 이 글은 동일한 Next.js 애플리케이션에서 `next-intl`로 한 번 빌드하고 어댑터로 한 번 빌드한 것을 비교합니다. 수치는 브라우저가 실제로 다운로드하는 내용을 기록하는 오픈소스 도구인 [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom)에서 나옵니다. 라이브러리로서의 `next-intl` vs Intlayer 비교를 원한다면 [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer)를 읽어보세요. 이 글은 컴포넌트를 그대로 유지할 때 어댑터가 어떤 변화를 가져오는지에 관한 것입니다.
@@ -109,6 +111,10 @@ const AboutPage = () => {
 
 ### Next.js 결과
 
+관심 있는 지표와 라이브러리를 선택하세요:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | Setup                     | Strategy       | Lib size (gz) | Page JS avg (gz) | Locale leak | Page leak | Component avg (gz) | E2E reactivity |   Hydration |
 | ------------------------- | -------------- | ------------: | ---------------: | ----------: | --------: | -----------------: | -------------: | ----------: |
 | **base** (i18n 없음)      | -              |        0.0 KB |         141.0 KB |        0.0% |      0.0% |             0.9 KB |        13.4 ms |     11.8 ms |
@@ -129,6 +135,15 @@ const AboutPage = () => {
 - **Hydration이 2ms 더 빠릅니다** (12.8 vs 14.7 ms): React가 hydrate되기 전에 RSC payload에서 deserialize할 message object가 없습니다.
 - **adapter는 native runtime이 아닙니다.** `next-intlayer`는 **141.3 KB**에 위치하며, base app보다 +0.3 KB이고, 5.5 KB runtime을 가집니다. adapter는 Intlayer의 core 위에 `next-intl` API surface (`useFormatter`, `t.rich`, the ICU resolver)를 제공하므로, 8.0 KB이고 page당 +6 KB입니다. 이것은 bridge이지, destination이 아닙니다.
 
+<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 (`use-intl`)에서의 결과
 
 `use-intl`은 `next-intl`의 framework-agnostic core입니다. 이의 adapter인 `@intlayer/use-intl`은 Vite plugin (`@intlayer/use-intl/plugin`)과 함께 동일한 design을 따릅니다.
@@ -152,11 +167,24 @@ const AboutPage = () => {
 - **로케일 전환이 더 빠릅니다.** 최적화된 `use-intl` 설정은 `html[lang]`을 업데이트하는 데 **13-21 ms**가 소요되고, 어댑터는 **4-9 ms**가 소요됩니다. 더 적은 컴포넌트가 다시 렌더링되고, 메시지 트리에서 아무것도 다시 선택되지 않습니다.
 - **`static`은 모든 로케일을 유지합니다.** 어댑터의 `static` 행은 49.7%의 로케일 누수를 표시하며, 이는 `static` 모드의 네이티브 Intlayer와 동일합니다. 모든 로케일이 번들로 제공되지만 페이지의 사전만 번들로 제공됩니다. 한 줄의 설정 (`importMode: 'dynamic'`)으로 이를 제거할 수 있습니다.
 
+<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)에서 확인하세요.
+
 ## 숫자가 변하는 이유
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 컴포넌트에서 아무것도 변경되지 않았으므로, 이득은 전적으로 `useTranslations`가 바인딩된 대상에서 비롯됩니다.
 
-**`next-intl`을 사용할 때**, 바인딩은 provider입니다. `NextIntlClientProvider`는 locale에 대한 전체 `messages` 객체를 받으며, 모든 `useTranslations("about")`은 이것을 읽습니다. bundler는 하나의 컴포넌트가 하나의 hook을 import하고 하나의 context를 읽는 것을 보지만, 오직 `about` 브랜치만 사용되는지 알 수 없습니다. 아래의 routes는 모두 동일한 message 객체를 공유하므로, page-leak 열은 파일을 직접 분할할 때까지 ~90%를 표시합니다.
+**`next-intl`을 사용할 때**, 바인딩은 provider입니다. `NextIntlClientProvider`는 locale에 대한 전체 `messages` 객체를 받으며, 모든 `useTranslations("about")`은 이것을 읽습니다. bundler는 하나의 컴포넌트가 하나의 hook을 import하고 하나의 context를 읽는 것을 보지만, 오직 `about` 브랜치만 사용되는지 알 수 없습니다. 아래의 routes는 모두 동일한 message 객체를 공유하므로, page-leak 열은 파일을 직접 분할할 때까지 ~90%를 표시합니다, 그리고 불필요한 오버헤드는 페이지와 로케일이라는 두 축에서 동시에 증가합니다:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
 
 ```bash
 .
@@ -280,25 +308,106 @@ export default withIntlayer(nextConfig);
 
 ## 시작하기 전에 알아야 할 제한사항
 
-- **라우팅 설정이 `intlayer.config.ts`로 이동합니다.** `createNavigation(routing)`과 `createMiddleware(routing)`은 시그니처를 유지하지만 인수는 무시합니다: locale, 기본 locale, prefix 전략은 Intlayer의 `routing` 설정에서 가져옵니다. `next-intl`의 로컬라이제이션된 `pathnames`(`/about` → `/a-propos`)을 사용하는 경우, 어댑터는 이를 보간하지 않습니다; Intlayer의 `routing.rewrite`가 해당 경우를 다루지만 별도의 변경입니다.
-- **Namespace 없는 `useTranslations()`은 바인드되지 않습니다.** 최적화 패스는 어떤 dictionary를 import할지 알기 위해 정적 namespace가 필요합니다. 베어 호출은 여전히 작동하지만, 모든 dictionary를 참조하는 runtime registry를 통해 작동하며, 이는 정확히 제거하려고 했던 누수입니다. namespace를 전달하세요.
-- **어댑터는 무료가 아닙니다.** 8.0 KB의 런타임 대 `next-intlayer`의 5.5 KB, 그리고 네이티브 빌드에 비해 페이지당 +6-7 KB입니다. 이는 `next-intl` API 표면의 비용입니다. 모든 컴포넌트가 `useIntlayer`로 이동된 지점에 도달하면 어댑터를 제거하세요.
-- **공급자의 `messages`, `timeZone`, `now`는 무시됩니다.** 포매터는 네이티브 `Intl`로 지원되며 로케일만이 출력에 영향을 미칩니다. 강제 타임존 또는 하이드레이션 안정적인 날짜를 위한 고정된 `now`에 의존하는 경우 호출 사이트에서 처리하세요.
+<AccordionGroup>
+<Accordion header="라우팅 설정이 intlayer.config.ts로 이동합니다">
+
+`createNavigation(routing)` 및 `createMiddleware(routing)`는 시그니처를 유지하지만 인수는 무시합니다. 지원 로케일, 기본 로케일 및 접두사 전략은 Intlayer의 `routing` 설정에서 가져옵니다. `next-intl`의 현지화된 `pathnames`(`/about` -> `/a-propos`)를 사용하는 경우 어댑터는 이를 보간하지 않습니다. Intlayer의 `routing.rewrite`가 해당 사례를 다루지만 이는 별도의 설정 변경입니다.
+
+</Accordion>
+<Accordion header="네임스페이스가 없는 useTranslations()는 바인딩되지 않습니다">
+
+최적화 단계에서는 가져올 사전을 파악하기 위해 정적 네임스페이스가 필요합니다. 네임스페이스 없이 호출해도 모든 사전을 참조하는 런타임 레지스트리를 통해 작동하지만, 이는 바로 제거하려던 누출에 해당합니다. 네임스페이스를 전달하세요.
+
+</Accordion>
+<Accordion header="어댑터는 무료가 아닙니다">
+
+`next-intlayer`의 5.5 KB 대비 8.0 KB의 런타임이며, 네이티브 빌드에 비해 페이지당 +6-7 KB가 추가됩니다. 이는 `next-intl` API 표면을 유지하기 위한 대가입니다. 모든 컴포넌트가 `useIntlayer`로 이전되면 어댑터를 제거하세요.
+
+</Accordion>
+<Accordion header="provider의 messages, timeZone, now는 무시됩니다">
+
+포매터는 네이티브 `Intl`을 기반으로 하며 로케일만이 출력에 영향을 미칩니다. 수화 과정에서 안정적인 날짜를 위해 강제 시간대나 고정된 `now`에 의존하는 경우 호출 위치에서 직접 처리하세요. [날짜, 시간 및 숫자 포맷팅](https://intlayer.org/ko/blog/date-time-number-formatting-locales)을 참조하세요.
+
+</Accordion>
+</AccordionGroup>
 
 ## 어느 것을 언제 사용할까요?
 
-- **`next-intl`에 머물러야 합니다** 앱이 작고, 번들이 걱정사항이 아니며, 팀이 네임스페이스와 페이지당 `pick()`을 관리하는 데 능숙한 경우입니다.
-- **`@intlayer/next-intl`를 사용하세요.** 현재 `next-intl`을 사용 중이며 번들 크기, 누수 및 하이드레이션 개선, 타입 안전 키, CLI/CMS 도구를 원하지만 전체 재작성은 피하고 싶다면 이를 사용하세요. 이것은 기존의 모든 `next-intl` codebase를 위한 권장되는 진입점입니다.
-- **네이티브 (`next-intlayer`)로 이동하세요.** 새로운 프로젝트에서, 또는 adapter가 역할을 다한 후에 이동하세요. 이는 세 가지 중 가장 가벼운 옵션입니다 (5.5 KB, 페이지당 +0.3 KB) 그리고 동기식 서버 컴포넌트, 컴포넌트별 `.content.ts` 파일 및 전체 기능 세트를 활용할 수 있습니다.
+<AccordionGroup>
+<Accordion header="next-intl 유지하기">
+
+앱이 작고 번들 크기가 크게 문제되지 않으며, 팀이 페이지당 네임스페이스와 `pick()`을 수동 관리하는 데 익숙한 경우.
+
+</Accordion>
+<Accordion header="@intlayer/next-intl 사용하기">
+
+현재 이미 `next-intl`을 사용하고 있으며, 코드 재작성 없이 번들 감소, 누출 방지, 빠른 수화, 타입 안전 키 및 CLI / CMS 도구를 활용하고 싶은 경우. 기존 `next-intl` 코드베이스에 권장되는 전환 진입점입니다.
+
+</Accordion>
+<Accordion header="네이티브(next-intlayer)로 전환하기">
+
+신규 프로젝트나 어댑터가 과도기적 역할을 다한 경우에 적합합니다. 셋 중 가장 가벼우며(5.5 KB, 페이지당 +0.3 KB 추가), 동기식 서버 컴포넌트, 컴포넌트별 `.content.ts` 파일 및 모든 기능을 지원합니다. [Next.js에서 Intlayer 시작하기](https://intlayer.org/ko/doc/environment/nextjs)를 참조하세요.
+
+</Accordion>
+</AccordionGroup>
+
+## 자주 묻는 질문
+
+<FAQ>
+
+<Question title="내 애플리케이션 코드가 정말 전혀 바뀌지 않나요?">
+
+Next.js에서 컴포넌트 코드는 변경되지 않습니다. 벤치마크 빌드에서는 `next.config.ts`와 `intlayer.config.ts`만 수정했습니다. `src/i18n.ts`의 `getRequestConfig`, provider의 `messages` prop 및 페이지별 `pick()` 호출은 나중에 삭제할 수 있는 데드 코드가 됩니다.
+
+</Question>
+
+<Question title="ICU 메시지는 어떻게 처리되나요?">
+
+정상적으로 계속 작동합니다. `t("key", { count })`, `t.rich()`, `t.markup()`, `select`, `selectordinal`, `#`, `{ts, date, long}`은 Intlayer의 ICU 해석기를 통해 처리됩니다. [ICU 메시지 형식](https://intlayer.org/ko/blog/icu-message-format)을 참조하세요.
+
+</Question>
+
+<Question title="어댑터가 네이티브 next-intlayer보다 무거운 이유는 무엇인가요?">
+
+Intlayer 코어 위에 `next-intl` API 표면(`useFormatter`, `t.rich`, ICU 해석기, 내비게이션 헬퍼)을 탑재하기 때문입니다. 5.5 KB 대비 8.0 KB이며, 페이지당 +6 KB가 추가됩니다. 이는 임시 가교일 뿐 최종 목적지가 아닙니다.
+
+</Question>
+
+<Question title="컴포넌트 단위로 점진적 마이그레이션이 가능한가요?">
+
+네. 어떤 컴포넌트든 바로 옆에 `.content.ts` 파일을 두고 `useTranslations("about")`에서 `useIntlayer("about")`로 전환할 수 있습니다. JSON 사전과 `.content.ts` 사전은 함께 공존하며 병합됩니다.
+
+</Question>
+
+<Question title="현지화된 경로(pathnames)가 작동하나요?">
+
+`next-intl`의 `pathnames`를 통해서는 작동하지 않습니다. 어댑터는 타입 지정을 위해 이를 허용하지만 보간하지는 않습니다. 대신 Intlayer의 `routing.rewrite`를 사용하세요.
+
+</Question>
+
+</FAQ>
 
 ## 관련 비교
 
-- [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer) (라이브러리, 동일한 벤치마크)
-- [i18next vs @intlayer/i18next](https://intlayer.org/blog/i18next-vs-intlayer-i18next) (동일한 adapter 시리즈)
-- [Lingui vs @intlayer/lingui](https://intlayer.org/blog/lingui-vs-intlayer-lingui) (동일 어댑터 시리즈)
-- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/blog/vue-i18n-vs-intlayer-vue-i18n) (동일 어댑터 시리즈)
-- [마이그레이션 가이드: next-intl to Intlayer](https://intlayer.org/doc/migration/next-intl)
-- [호환성 어댑터 레퍼런스: next-intl](https://intlayer.org/doc/compatibility/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/vue-i18n](https://intlayer.org/ko/blog/vue-i18n-vs-intlayer-vue-i18n)
+
+두 라이브러리 직접 비교:
+
+- [next-intl vs Intlayer](https://intlayer.org/ko/blog/next-intl-vs-intlayer), 동일한 벤치마크
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/ko/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [Is next-intl outdated?](https://intlayer.org/ko/blog/is-next-intl-outdated)
+
+참조 문서:
+
+- [Compat adapter: next-intl](https://intlayer.org/ko/doc/compatibility/next-intl)
+- [마이그레이션 가이드: next-intl에서 Intlayer로](https://intlayer.org/ko/doc/migration/next-intl)
+- [Next.js 벤치마크 보고서](https://intlayer.org/ko/doc/benchmark/nextjs) 및 [TanStack Start 벤치마크 보고서](https://intlayer.org/ko/doc/benchmark/tanstack)
+- [번들 최적화](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)
 
 ## 결론
 

package/blog/ko/next-intl_vs_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "next-intl vs Intlayer: 2026 벤치마크 및 비교"
 description: "Next.js App Router와 TanStack Start에서 next-intl과 Intlayer를 비교 측정했습니다. 번들 크기, 콘텐츠 누출, 컴포넌트 크기, 하이드레이션, 로케일 전환 속도 및 개발자 경험."
 keywords:
@@ -22,11 +22,11 @@ author: aymericzip
 
 # next-intl VS Intlayer | React & Next.js 국제화(i18n) 벤치마크
 
-`next-intl`은 오늘날 Next.js App Router의 기본 선택지입니다. 라우팅과의 긴밀한 통합, 완전한 ICU MessageFormat 지원, 전통적인 i18n 시스템을 사용해 본 사람이라면 누구나 익숙한 개발자 경험을 제공합니다.
+![next-intl VS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18next-next-intl-intlayer.webp?raw=true)
 
-반면 `Intlayer`는 문제를 근본적으로 재구성합니다. 중앙 집중식 사전이 없으며, 네임스페이스와 라우트를 수동으로 일치시킬 필요가 없습니다. 콘텐츠는 각 컴포넌트 바로 옆에 선언되며, 빌드 타임 컴파일러가 각 페이지에 필요한 콘텐츠만 자동으로 번들링합니다.
+`next-intl`은 Next.js에서 가장 널리 사용되는 i18n 라이브러리입니다. Intlayer는 컴파일러 기반의 컴포넌트 스코프 대안입니다. 두 라이브러리 모두 App Router 애플리케이션을 현지화합니다. 질문은 앱이 빌드된 후 각각의 비용이 얼마인가 하는 것입니다.
 
-이 글은 각 라이브러리로 동일한 애플리케이션을 빌드하고 브라우저가 실제로 다운로드하고 실행하는 항목을 기록하는 오픈 소스 테스트 스위트인 [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom)의 데이터를 바탕으로 두 라이브러리를 비교합니다.
+이 기사는 튜토리얼이 아닙니다. 각 라이브러리로 동일한 애플리케이션을 빌드하고 브라우저가 실제로 다운로드하고 실행하는 것을 측정하는 오픈 소스 벤치마크 스위트인 [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom)의 수치로 뒷받침된 비교입니다.
 
 <TOC/>
 
@@ -89,6 +89,10 @@ Intlayer에는 "scoped" 변형이 없습니다. 컴파일러가 콘텐츠 범위
 
 ### Next.js (App Router) 결과
 
+관심 있는 메트릭과 라이브러리를 선택하세요:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | 라이브러리                   | 전략           | 라이브러리 크기 (gz) | 평균 페이지 JS (gz) | 로케일 누출 | 페이지 누출 | 평균 컴포넌트 (gz) |  E2E 반응성 | 하이드레이션 |
 | ---------------------------- | -------------- | -------------------: | ------------------: | ----------: | ----------: | -----------------: | ----------: | -----------: |
 | **기본 앱** (i18n 없음)      | -              |               0.0 KB |            141.0 KB |        0.0% |        0.0% |             0.9 KB |     13.4 ms |      11.8 ms |
@@ -107,8 +111,19 @@ Intlayer에는 "scoped" 변형이 없습니다. 컴파일러가 콘텐츠 범위
 - **콘텐츠 누출.** 가장 흔히 사용되는 설정(`static` 및 `dynamic`)에서 `next-intl`은 전체 `en.json`이 클라이언트 공급자에 들어가기 때문에 페이지마다 **다른 페이지 문자열의 약 90%**를 전송합니다. 이를 0%로 만들려면 복잡한 수동 네임스페이스 분할이 필요하지만, Intlayer는 기본적으로 0%입니다.
 - **컴포넌트 크기.** `useTranslations()`를 호출하는 컴포넌트는 평균 21.8 KB로 컴파일되지만, `useIntlayer()`를 사용하는 동일한 컴포넌트는 단 6.9 KB입니다.
 
+<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 (`use-intl`) 결과
 
+`use-intl`은 `next-intl`의 프레임워크 독립적인 핵심 코어입니다. 동일한 API, 동일한 메시지 형식을 사용합니다. TanStack Start에서 이를 `intlayer`와 비교하면 방정식에서 Next.js 관련 요소를 배제할 수 있습니다.
+
 | 라이브러리                  | 전략           | 라이브러리 크기 (gz) | 평균 페이지 JS (gz) | 로케일 누출 | 페이지 누출 | 평균 컴포넌트 (gz) | E2E 반응성 |
 | --------------------------- | -------------- | -------------------: | ------------------: | ----------: | ----------: | -----------------: | ---------: |
 | **기본 앱** (i18n 없음)     | -              |               0.0 KB |            111.0 KB |        0.0% |        0.0% |             0.7 KB |     8.1 ms |
@@ -127,8 +142,19 @@ Intlayer에는 "scoped" 변형이 없습니다. 컴파일러가 콘텐츠 범위
 - 아키텍처의 차이는 **컴포넌트 크기**에서 명확히 드러납니다. `use-intl`의 76-87 KB 대비 Intlayer는 6-8 KB에 불과합니다.
 - **로케일 전환 속도**는 Intlayer가 2~4배 더 빠릅니다(3 ms vs 7-21 ms).
 
+<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)
+
 `next-intl`은 전통적인 방식을 따릅니다. 로케일당 하나의 JSON 파일이 `getRequestConfig`에서 로드되고, `NextIntlClientProvider`에 전달되며, `t("namespace.key")`로 읽힙니다.
 
 ```bash
@@ -150,6 +176,10 @@ Intlayer에는 "scoped" 변형이 없습니다. 컴파일러가 콘텐츠 범위
 
 런타임은 페이지에서 어떤 키가 사용될지 미리 알 수 없으므로 전체 카탈로그를 전송하는 것이 유일하게 안전한 기본값입니다.
 
+최적화에 도달하지 못할 때 발생하는 비용은 페이지와 언어라는 두 축에서 동시에 증가합니다:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
+
 Intlayer는 이 구조를 완전히 뒤집습니다. 콘텐츠는 컴포넌트 바로 옆에 선언됩니다.
 
 ```bash
@@ -177,7 +207,8 @@ Intlayer는 이 구조를 완전히 뒤집습니다. 콘텐츠는 컴포넌트
 
 ### 클라이언트 컴포넌트
 
-**next-intl**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-intl" value="next-intl">
 
 ```json fileName="messages/en.json"
 {
@@ -188,7 +219,7 @@ Intlayer는 이 구조를 완전히 뒤집습니다. 콘텐츠는 컴포넌트
 }
 ```
 
-```tsx fileName="src/components/Counter.tsx"
+```tsx fileName="src/components/ClientCounter.tsx"
 "use client";
 
 import { useState } from "react";
@@ -210,7 +241,10 @@ export const Counter = () => {
 };
 ```
 
-**Intlayer**
+> 이 컴포넌트를 렌더링하는 모든 페이지에서 `NextIntlClientProvider`에 전달되는 메시지에 `counter` 네임스페이스를 포함해야 합니다.
+
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/components/Counter/index.content.ts"
 import { t, type Dictionary } from "intlayer";
@@ -249,11 +283,16 @@ export const Counter = () => {
 };
 ```
 
+페이지에 등록할 것이 전혀 없습니다: 컴포넌트가 자체 콘텐츠를 직접 가져옵니다.
+
+</Tab>
+</Tabs>
 ### 동기식 서버 컴포넌트
 
 디자인 시스템 요소(내비게이션 바, 바닥글, 카드 등)는 클라이언트 컴포넌트의 자식으로 렌더링되는 서버 컴포넌트인 경우가 많으므로 비동기(`async`)일 수 없습니다.
 
-**next-intl**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-intl" value="next-intl">
 
 ```tsx fileName="src/components/ServerCounter.tsx"
 type ServerCounterProps = {
@@ -269,7 +308,10 @@ export const ServerCounter = ({ t, formattedCount }: ServerCounterProps) => (
 );
 ```
 
-**Intlayer**
+페이지에서 `await getTranslations("counter")` 및 `await getFormatter()`를 실행한 다음 결과를 props로 전달해야 합니다. 컴포넌트는 더 이상 독립적이지 않습니다.
+
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```tsx fileName="src/components/ServerCounter.tsx"
 import { useIntlayer } from "next-intlayer/server";
@@ -288,9 +330,12 @@ export const ServerCounter = ({ count }: { count: number }) => {
 };
 ```
 
+</Tab>
+</Tabs>
 ### 메타데이터
 
-**next-intl**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-intl" value="next-intl">
 
 ```tsx fileName="src/app/[locale]/about/page.tsx"
 import type { Metadata } from "next";
@@ -323,7 +368,8 @@ export const generateMetadata = async ({
 };
 ```
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```tsx fileName="src/app/[locale]/about/page.tsx"
 import { getIntlayer, getMultilingualUrls } from "intlayer";
@@ -347,6 +393,9 @@ export const generateMetadata = async ({
 };
 ```
 
+</Tab>
+</Tabs>
+
 ## next-intl API 유지 및 Intlayer 출력 획득
 
 위의 벤치마크 결과를 얻기 위해 기존 컴포넌트를 모두 다시 작성할 필요는 없습니다. `@intlayer/next-intl`은 드롭인 어댑터입니다. `useTranslations`, `getTranslations`, `useFormatter`, `t.rich()`, ICU 복수형을 그대로 유지하면서 Intlayer 컴파일러로 컴파일된 Intlayer 사전에서 콘텐츠를 제공합니다.
@@ -368,17 +417,84 @@ export default withIntlayer(nextConfig);
 
 ## 언제 무엇을 선택해야 할까요?
 
-- **next-intl 선택**: Next.js의 광범위한 생태계 표준을 원하거나, ICU MessageFormat에 크게 의존하거나, 앱이 중소 규모이거나, 중앙 집중식 번역 플랫폼(Crowdin, Phrase, Lokalise 등)과 연동하는 경우.
-- **Intlayer 선택**: **컴포넌트 단위 콘텐츠 관리**, **엄격한 TypeScript 지원**, **빌드 타임 누락 키 감지**, **설정 없는 자동 트리 셰이킹 및 지연 로딩**, 동기식 서버 컴포넌트, 내장 편집 도구(비주얼 에디터, CMS, AI 번역, MCP 서버)를 원하는 경우. 모듈식 코드베이스나 대규모 디자인 시스템에 특히 유용합니다.
-- **`@intlayer/next-intl` 선택**: 이미 `next-intl`을 사용 중이며 코드 재작성 없이 번들 최적화 이점을 얻고 싶은 경우.
+<AccordionGroup>
+<Accordion header="next-intl 선택">
+
+Next.js의 생태계 표준을 원하고, ICU MessageFormat에 의존하며, 앱이 중소 규모이거나 중앙 집중식 JSON을 요구하는 번역 플랫폼(Crowdin, Phrase, Lokalise...)과 연동하는 경우. 성능이 중요하다면 카탈로그를 네임스페이스로 나누고 페이지별로 `pick()`을 통해 메시지를 선별하는 시간을 고려해야 합니다.
+
+</Accordion>
+<Accordion header="Intlayer 선택">
+
+**컴포넌트 스코프 콘텐츠**, **엄격한 TypeScript**, **빌드 타임 누락 키 에러**, **노력 없는 트리 쉐이킹 및 지연 로딩**, 동기식 서버 컴포넌트, 내장 편집 툴([비주얼 에디터](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/next-intl 선택">
+
+이미 `next-intl`을 사용 중이며 코드 재작성 없이 번들 크기를 줄이고자 하는 경우. [호환 어댑터](https://intlayer.org/ko/doc/compatibility/next-intl)는 기존 import 구문과 `messages/{locale}.json` 파일을 단일 진실 공급원으로 유지합니다. [next-intl vs @intlayer/next-intl](https://intlayer.org/ko/blog/next-intl-vs-intlayer-next-intl)에서 나란히 측정되었습니다.
+
+</Accordion>
+</AccordionGroup>
+
+## 자주 묻는 질문 (FAQ)
+
+<FAQ>
+
+<Question title="next-intl은 Intlayer보다 느린가요?">
+
+렌더링 시점에는 그렇지 않습니다. 차이점은 클라이언트에 전달되는 번들 크기에 있습니다. `next-intl`은 각 페이지마다 **+12.6 KB gzip**의 런타임 비용이 발생하며, 일반적인 설정에서는 다른 페이지의 문자열 중 약 90%를 함께 전송합니다. 언어 전환 및 하이드레이션 시간은 Next.js에서 유사합니다(15-18 ms). TanStack Start에서는 `use-intl`이 7-21 ms 걸리는 반면 Intlayer는 3-4 ms에 불과합니다.
+
+</Question>
+
+<Question title="next-intl로 누출률 0%를 달성할 수 있나요?">
+
+네, `scoped-dynamic` 설정을 통해 가능합니다. `messages/{locale}.json`을 라우트당 하나의 네임스페이스로 분할한 다음 각 페이지에서 `pick(messages, [...])`을 사용하고 컴포넌트 변경 시 이 매핑을 정확하게 유지해야 합니다. 벤치마크의 `scoped-*` 행이 바로 이러한 작업의 결과입니다. Intlayer는 컴파일러가 컴포넌트별로 콘텐츠 범위를 지정하므로 별도 작업 없이 기본적으로 0%에 도달합니다. [번들 최적화](https://intlayer.org/ko/doc/concept/bundle-optimization)를 참조하세요.
+
+</Question>
+
+<Question title="마이그레이션하려면 컴포넌트를 다시 작성해야 하나요?">
+
+아닙니다. `@intlayer/next-intl`은 `useTranslations`, `getTranslations`, `useFormatter`, `t.rich()`, ICU 복수형 및 네비게이션 헬퍼를 유지하며, 컴파일된 딕셔너리에서 이를 제공합니다. `next.config.ts`에 플러그인 한 줄만 추가하면 됩니다. 단계별 안내는 [next-intl 마이그레이션 가이드](https://intlayer.org/ko/doc/migration/next-intl)를 참조하세요.
+
+</Question>
+
+<Question title="Intlayer는 ICU MessageFormat을 지원하나요?">
+
+네이티브 API에서 ICU 지원은 지속적으로 확장 중입니다. 호환 어댑터(`@intlayer/next-intl`, `@intlayer/use-intl`)는 이미 ICU를 지원합니다: 복수형, `select`, `selectordinal`, `#`, `{ts, date, long}`은 Intlayer의 ICU 리졸버를 통해 처리됩니다. 자세한 내용은 [ICU 메시지 포맷 설명](https://intlayer.org/ko/blog/icu-message-format)을 참조하세요.
+
+</Question>
+
+<Question title="messages/{locale}.json 파일을 그대로 유지할 수 있나요?">
+
+네. [JSON 동기화 플러그인](https://intlayer.org/ko/doc/compatibility/next-intl)이 해당 파일을 읽어 최상위 키를 딕셔너리로 분할하고, CLI나 CMS가 번역을 업데이트할 때 동일한 파일에 다시 기록합니다. 번역 팀의 워크플로는 변경되지 않습니다.
+
+</Question>
+
+</FAQ>
 
 ## 관련 비교
 
-- [i18next vs Intlayer](https://intlayer.org/ko/blog/i18next-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) (동일 벤치마크)
+동일한 벤치마크, 다른 라이브러리:
+
+- [i18next vs Intlayer](https://intlayer.org/ko/blog/i18next-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)
-- [next-intl은 구식인가요?](https://intlayer.org/ko/blog/is-next-intl-outdated)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/ko/blog/react-i18next-vs-react-intl-vs-intlayer)
+
+next-intl 심층 분석:
+
+- [next-intl vs @intlayer/next-intl](https://intlayer.org/ko/blog/next-intl-vs-intlayer-next-intl), 동일한 앱에서 측정된 어댑터
+- [Is next-intl outdated?](https://intlayer.org/ko/blog/is-next-intl-outdated)
+- [Using Intlayer with next-intl](https://intlayer.org/ko/blog/intlayer-with-next-intl)
+- [How to internationalize a Next.js app with next-intl](https://intlayer.org/ko/blog/nextjs-internationalization-using-next-intl)
+
+참고 문서:
+
+- [Next.js 벤치마크 보고서](https://intlayer.org/ko/doc/benchmark/nextjs) 및 [TanStack Start 벤치마크 보고서](https://intlayer.org/ko/doc/benchmark/tanstack)
+- [호환 어댑터: next-intl](https://intlayer.org/ko/doc/compatibility/next-intl) 및 [마이그레이션 가이드](https://intlayer.org/ko/doc/migration/next-intl)
+- [번들 최적화](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 STARS
 

package/blog/ko/transform_existing_vite_react_app_using_compiler.md

@@ -284,7 +284,9 @@ const pathList = [
   { path: "/about", changefreq: "monthly", priority: 0.7 },
 ];
 
-const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });
+const sitemapXml = generateSitemap(pathList, {
+  siteUrl: "https://example.com",
+});
 fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);
 
 const getAllMultilingualUrls = (urls) =>
@@ -297,7 +299,7 @@ const robotsTxt = [
   "Allow: /",
   ...disallowedPaths.map((path) => `Disallow: ${path}`),
   "",
-  `Sitemap: ${SITE_URL}/sitemap.xml`,
+  `Sitemap: https://example.com/sitemap.xml`,
 ].join("\n");
 
 fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);