@intlayer/docs 9.4.4 → 9.5.1

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

@@ -42,16 +42,12 @@ Next.js를 위한 세 가지 i18n 옵션인 next-i18next, next-intl, Intlayer의
 
 > 개발자들이 자주 혼동하는 점 중 하나는 `next-intl`이 `react-intl`의 Next.js 버전이라고 생각하는 것입니다. 그렇지 않습니다, `next-intl`은 [Amann](https://github.com/amannn)이 유지 관리하며, `react-intl`은 [FormatJS](https://github.com/formatjs/formatjs)가 유지 관리합니다.
 
----
-
 ## 요약
 
 - **next-intl** - 가볍고 직관적인 메시지 포맷팅을 제공하며, 견고한 Next.js 지원을 갖추고 있습니다. 중앙 집중식 카탈로그가 일반적이며, 개발자 경험(DX)은 간단하지만 안전성과 대규모 유지 관리는 주로 사용자 책임입니다.
 - **next-i18next** - Next.js 환경에 맞춘 i18next입니다. 성숙한 생태계와 플러그인(예: ICU)을 통한 기능을 제공하지만, 설정이 장황할 수 있으며 프로젝트가 커질수록 카탈로그가 중앙 집중화되는 경향이 있습니다.
 - **Intlayer** - Next.js를 위한 컴포넌트 중심 콘텐츠 모델, **엄격한 TS 타이핑**, **빌드 시 검사**, **트리 쉐이킹**, **내장 미들웨어 및 SEO 도우미**, 선택적 **비주얼 에디터/CMS**, 그리고 **AI 지원 번역**을 제공합니다.
 
----
-
 | Library                | GitHub Stars                                                                                                                                                                     | Total Commits                                                                                                                                                                        | Last Commit                                                                                                                                           | First Version | NPM Version                                                                                                         | NPM Downloads                                                                                                                  |
 | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | `aymericzip/intlayer`  | [![GitHub Repo stars](https://img.shields.io/github/stars/aymericzip/intlayer?style=for-the-badge&label=%E2%AD%90%20stars)](https://github.com/aymericzip/intlayer/stargazers)   | [![GitHub commit activity](https://img.shields.io/github/commit-activity/t/aymericzip/intlayer?style=for-the-badge&label=commits)](https://github.com/aymericzip/intlayer/commits)   | [![Last Commit](https://img.shields.io/github/last-commit/aymericzip/intlayer?style=for-the-badge)](https://github.com/aymericzip/intlayer/commits)   | April 2024    | [![npm](https://img.shields.io/npm/v/intlayer?style=for-the-badge)](https://www.npmjs.com/package/intlayer)         | [![npm downloads](https://img.shields.io/npm/dm/intlayer?style=for-the-badge)](https://www.npmjs.com/package/intlayer)         |
@@ -61,8 +57,6 @@ Next.js를 위한 세 가지 i18n 옵션인 next-i18next, next-intl, Intlayer의
 
 > 배지는 자동으로 업데이트됩니다. 스냅샷은 시간이 지남에 따라 달라질 수 있습니다.
 
----
-
 ## 나란히 기능 비교 (Next.js 중심)
 
 | 기능                                      | `next-intlayer` (Intlayer)                                                                                               | `next-intl`                                                                              | `next-i18next`                                                                           |
@@ -88,16 +82,12 @@ Next.js를 위한 세 가지 i18n 옵션인 next-i18next, next-intl, Intlayer의
 | **대규모 프로젝트 관리**                  | ✅ 모듈화 권장, 디자인 시스템에 적합                                                                                     | ✅ 설정과 함께 모듈화                                                                    | ✅ 설정과 함께 모듈화                                                                    |
 | **누락된 번역 테스트 (CLI/CI)**           | ✅ CLI: `npx intlayer content test` (CI 친화적 감사)                                                                     | ⚠️ 내장되어 있지 않음; 문서에서는 `npx @lingual/i18n-check` 사용 권장                    | ⚠️ 내장되어 있지 않음; i18next 도구 또는 런타임 `saveMissing`에 의존                     |
 
----
-
 ## 소개
 
 Next.js는 국제화된 라우팅(예: 로케일 세그먼트)을 기본적으로 지원합니다. 하지만 이 기능만으로는 번역을 수행하지 않습니다. 사용자에게 현지화된 콘텐츠를 렌더링하려면 여전히 라이브러리가 필요합니다.
 
 많은 i18n 라이브러리가 존재하지만, 현재 Next.js 환경에서는 next-i18next, next-intl, 그리고 Intlayer 세 가지가 주목받고 있습니다.
 
----
-
 ## 아키텍처 및 확장성
 
 - **next-intl / next-i18next**: 기본적으로 로케일별 **중앙 집중식 카탈로그**(그리고 i18next의 **네임스페이스**)를 사용합니다. 초기에는 잘 작동하지만, 점차 결합도가 높아지고 키 변경이 잦아지면서 큰 공유 영역이 되는 경우가 많습니다.
@@ -105,8 +95,6 @@ Next.js는 국제화된 라우팅(예: 로케일 세그먼트)을 기본적으
 
 **중요한 이유:** 대규모 코드베이스나 디자인 시스템 설정에서는 **모듈화된 콘텐츠**가 단일 카탈로그보다 더 잘 확장됩니다.
 
----
-
 ## 번들 크기 및 의존성
 
 애플리케이션을 빌드한 후, 번들은 브라우저가 페이지를 렌더링하기 위해 로드하는 자바스크립트입니다. 따라서 번들 크기는 애플리케이션 성능에 매우 중요합니다.
@@ -172,8 +160,6 @@ Next.js는 국제화된 라우팅(예: 로케일 세그먼트)을 기본적으
 | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
 | ![최적화된 번들](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle.png?raw=true) | ![최적화되지 않은 번들](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle_no_optimization.png?raw=true) |
 
----
-
 ## TypeScript 및 안전성
 
 <Columns>
@@ -198,12 +184,11 @@ Next.js는 국제화된 라우팅(예: 로케일 세그먼트)을 기본적으
 - **콘텐츠에서 엄격한 타입을 생성합니다.** **IDE 자동완성**과 **컴파일 타임 오류**가 배포 전에 오타와 누락된 키를 잡아냅니다.
 
   </Column>
+
 </Columns>
 
 **중요한 이유:** 강력한 타입 지정은 실패를 **오른쪽(런타임)**이 아닌 **왼쪽(CI/빌드)**으로 이동시킵니다.
 
----
-
 ## 라우팅, 미들웨어 및 URL 전략
 
 <Columns>
@@ -228,12 +213,11 @@ Next.js는 국제화된 라우팅(예: 로케일 세그먼트)을 기본적으
 - 위의 모든 기능에 더해, **i18n 미들웨어**(헤더/쿠키를 통한 로케일 감지)와 지역화된 URL 및 `<link rel="alternate" hreflang="…">` 태그 생성을 위한 **도우미**를 제공합니다.
 
   </Column>
+
 </Columns>
 
 **중요한 이유:** 커스텀 연결 계층이 줄어들고, **일관된 사용자 경험(UX)**과 **깔끔한 SEO**를 지역별로 유지할 수 있습니다.
 
----
-
 ## 서버 컴포넌트(RSC) 정렬
 
 <Columns>
@@ -258,12 +242,11 @@ Next.js는 국제화된 라우팅(예: 로케일 세그먼트)을 기본적으
 - Next.js 13+를 지원하며, 일관된 API와 RSC 지향 프로바이더를 통해 **서버/클라이언트 경계**를 원활하게 처리하여 포매터나 t-함수를 전달하는 것을 방지합니다.
 
   </Column>
+
 </Columns>
 
 **중요한 이유:** 더 깔끔한 정신 모델과 하이브리드 트리에서의 예외 상황 감소.
 
----
-
 ## 개발자 경험(DX), 도구 및 유지보수
 
 <Columns>
@@ -288,6 +271,7 @@ Next.js는 국제화된 라우팅(예: 로케일 세그먼트)을 기본적으
 - **무료 비주얼 에디터**와 **선택적 CMS**(Git 친화적이거나 외부화 가능)를 제공하며, **VSCode 확장**과 자체 제공자 키를 사용하는 **AI 지원 번역**도 포함됩니다.
 
   </Column>
+
 </Columns>
 
 **중요한 이유:** 운영 비용을 낮추고 개발자와 콘텐츠 작성자 간의 피드백 주기를 단축합니다.
@@ -798,8 +782,6 @@ const ClientComponentExample = () => {
   - **next-intl**는 유연하며, 설정에 따라 메시지 로드 가능.
   - **Intlayer**는 TS/JS 딕셔너리에 콘텐츠를 저장하고 키로 해석.
 
----
-
 ### 서버 컴포넌트에서의 사용
 
 UI 컴포넌트의 경우를 살펴보겠습니다. 이 컴포넌트는 서버 컴포넌트이며, 클라이언트 컴포넌트의 자식으로 삽입될 수 있어야 합니다. (페이지 (서버 컴포넌트) -> 클라이언트 컴포넌트 -> 서버 컴포넌트). 이 컴포넌트가 클라이언트 컴포넌트의 자식으로 삽입될 수 있으므로 비동기(async)일 수 없습니다.
@@ -897,7 +879,7 @@ const ServerComponent = ({ count }: { count: number }) => {
 개발자들은 종종 여러 로케일에 걸쳐 페이지를 올바르게 참조하는 것을 잊어버립니다.
 
 <Tabs defaultTab="next-intl" group='techno'>
- 
+
   <Tab label="next-i18next" value="next-i18next">
 
 ```ts fileName="i18n.config.ts"
@@ -1155,8 +1137,6 @@ export default robots;
 
 > Intlayer는 사이트맵을 위해 다국어 URL을 생성하는 `getMultilingualUrls` 함수를 제공합니다.
 
----
-
 ### 로케일 라우팅을 위한 Middleware
 
 <Tabs defaultTab="next-intl" group='techno'>
@@ -1274,9 +1254,8 @@ middleware의 설정은 `intlayer.config.ts` 파일에 중앙화되어 있습니
 - **통합 도구**: 기본 제공 라우팅, SEO 헬퍼 및 비주얼 에디터 지원을 활용합니다.
 
   </Tab>
-</Tabs>
 
----
+</Tabs>
 
 ## 그리고 승자는…
 
@@ -1304,6 +1283,7 @@ middleware의 설정은 `intlayer.config.ts` 파일에 중앙화되어 있습니
 - 모듈식 콘텐츠, 타입 안전성, 도구 지원, 그리고 보일러플레이트가 적은 현대적인 Next.js를 위해 설계되었습니다. 특히 **Next.js App Router**, 디자인 시스템, 그리고 **대규모 모듈식 코드베이스**에 대해 **컴포넌트 범위 콘텐츠**, **엄격한 TypeScript**, **빌드 타임 보장**, **트리 쉐이킹**, 그리고 **기본 제공** 라우팅/SEO/에디터 도구를 중요하게 생각한다면 적합합니다.
 
   </Column>
+
 </Columns>
 
 최소한의 설정을 선호하고 일부 수동 연결을 감수할 수 있다면 next-intl이 좋은 선택입니다. 모든 기능이 필요하고 복잡성을 감수할 수 있다면 next-i18next가 적합합니다. 하지만 현대적이고 확장 가능하며 모듈식 솔루션과 내장 도구를 원한다면 Intlayer가 바로 그 요구를 충족시키고자 합니다.
@@ -1318,8 +1298,6 @@ GitHub 스타는 프로젝트의 인기, 커뮤니티 신뢰도, 그리고 장
 
 [![스타 히스토리 차트](https://api.star-history.com/chart?repos=i18next/next-i18next%2Camannn/next-intl%2Caymericzip/intlayer&type=date&legend=top-left)](https://www.star-history.com/#i18next/next-i18next&amannn/next-intl&aymericzip/intlayer)
 
----
-
 ## 결론
 
 세 가지 라이브러리 모두 핵심 로컬라이제이션에서는 성공적입니다. 차이점은 **현대적인 Next.js에서 견고하고 확장 가능한 설정을 달성하기 위해 얼마나 많은 작업을 해야 하는가**에 있습니다:

package/blog/ko/nextjs-multilingual-seo-comparison.md

@@ -26,8 +26,6 @@ author: aymericzip
 
 이 블로그에서는 **왜 i18n이 SEO의 강력한 무기인지**와 `next-intl`, `next-i18next`, 그리고 `Intlayer`를 사용해 Next.js에서 이를 올바르게 구현하는 방법을 살펴보겠습니다.
 
----
-
 ## 왜 SEO와 i18n인가
 
 언어를 추가하는 것은 단순히 사용자 경험(UX)에 관한 것이 아닙니다. 이는 **유기적 가시성**을 위한 강력한 수단이기도 합니다. 이유는 다음과 같습니다:
@@ -37,8 +35,6 @@ author: aymericzip
 3. **더 나은 UX:** 방문자는 즉시 사이트의 올바른 버전에 도착합니다.
 4. **경쟁 우위:** 다국어 SEO를 잘 구현하는 사이트가 적기 때문에 돋보일 수 있습니다.
 
----
-
 ## Next.js에서 다국어 SEO를 위한 모범 사례
 
 모든 다국어 앱이 구현해야 할 체크리스트는 다음과 같습니다:
@@ -57,8 +53,6 @@ author: aymericzip
 
 이것들은 간단한 단계이지만, 건너뛰면 가시성에 큰 영향을 줄 수 있습니다.
 
----
-
 ## 구현 예제
 
 개발자들은 종종 여러 로케일에 걸쳐 페이지를 올바르게 참조하는 것을 잊어버리므로, 다양한 라이브러리에서 이것이 실제로 어떻게 작동하는지 살펴보겠습니다.
@@ -343,14 +337,10 @@ export default robots;
   </Tab>
 </Tabs>
 
----
-
 ## Intlayer SEO Scanner로 웹사이트 감사하기
 
 다국어 앱이 완벽하게 최적화되도록 하려면 [Intlayer SEO Scanner](https://intlayer.org/i18n-seo-scanner)를 사용하는 것이 좋습니다. 다국어 웹사이트 검사에 특화된 도구로, 모든 현지화된 페이지에서 누락된 hreflang 태그, 끊어진 링크 및 기타 SEO 문제를 식별하는 데 도움이 됩니다.
 
----
-
 ## 결론
 
 Next.js에서 i18n을 제대로 구현하는 것은 단순히 텍스트를 번역하는 것뿐만 아니라, 검색 엔진과 사용자가 정확히 어떤 버전의 콘텐츠를 제공받아야 하는지 아는 것이 중요합니다.

package/blog/ko/react-i18next_vs_react-intl_vs_intlayer.md

@@ -35,16 +35,12 @@ author: aymericzip
 
 > **요약**: 세 가지 모두 React 앱을 현지화할 수 있습니다. 만약 **컴포넌트 범위 콘텐츠**, **엄격한 TypeScript 타입**, **빌드 시 누락 키 검사**, **트리 쉐이킹된 사전**, 그리고 내장된 편집 도구(비주얼 에디터/CMS + 선택적 AI 번역)를 원한다면, **Intlayer**가 모듈형 React 코드베이스에 가장 완벽한 선택입니다.
 
----
-
 ## 상위 수준 포지셔닝
 
 - **react-intl** - ICU 우선, 표준에 맞는 포맷팅(날짜/숫자/복수형)과 성숙한 API를 제공. 카탈로그는 일반적으로 중앙 집중식이며, 키 안전성과 빌드 시 검증은 주로 사용자가 책임집니다.
 - **react-i18next** - 매우 인기 있고 유연함; 네임스페이스, 탐지기, 다양한 플러그인(ICU, 백엔드 등)을 지원. 강력하지만 프로젝트가 커질수록 설정이 복잡해질 수 있습니다.
 - **Intlayer** - React용 컴포넌트 중심 콘텐츠 모델, **엄격한 TS 타입 지정**, **빌드 시 검사**, **트리 쉐이킹**, 그리고 **비주얼 에디터/CMS** 및 **AI 지원 번역**을 포함. React Router, Vite, CRA 등과 호환됩니다.
 
----
-
 ## 기능 매트릭스 (React 중심)
 
 | 기능                                                 | `react-intlayer` (Intlayer)                                                                                                   | `react-i18next` (i18next)                                                           | `react-intl` (FormatJS)                                                     |
@@ -69,8 +65,6 @@ author: aymericzip
 | **사용하지 않는 콘텐츠 정리 (Purge unused content)** | ✅ 예, 빌드 시 사전별                                                                                                         | ❌ 아니요, 수동 네임스페이스 분할을 통해서만 가능                                   | ❌ 아니요, 선언된 모든 메시지가 번들에 포함됨                               |
 | **대규모 프로젝트 관리**                             | ✅ 모듈화를 장려하며 디자인 시스템에 적합                                                                                     | ⚠️ 체계적인 파일 관리 필요                                                          | ⚠️ 중앙 카탈로그가 커질 수 있음                                             |
 
----
-
 ## 심층 비교
 
 ### 1) 아키텍처 및 확장성
@@ -80,8 +74,6 @@ author: aymericzip
 
 **중요한 이유:** 모듈화된 콘텐츠는 모듈화된 UI를 반영합니다. 대규모 React 코드베이스는 번역이 해당 컴포넌트와 함께 있을 때 더 깔끔하게 유지됩니다.
 
----
-
 ### 2) TypeScript 및 안정성
 
 - **react-intl**: 견고한 타입 정의를 제공하지만, **자동 키 타입 지정은 없으며** 안전성 패턴을 직접 적용해야 합니다.
@@ -90,8 +82,6 @@ author: aymericzip
 
 **중요한 이유:** 실패를 **왼쪽으로 이동**(빌드/CI 단계로)시켜 프로덕션 문제를 줄이고 개발자 피드백 루프를 가속화합니다.
 
----
-
 ### 3) 누락된 번역 처리
 
 - **react-intl / react-i18next**: 기본적으로 **런타임 폴백**(키 에코 또는 기본 로케일)으로 처리합니다. 린팅/플러그인을 추가할 수 있지만 빌드 시 보장은 없습니다.
@@ -99,8 +89,6 @@ author: aymericzip
 
 **중요한 이유:** CI가 누락된 문자열을 실패 처리하여 비영어 UI에 “미스터리 영어”가 유출되는 것을 방지합니다.
 
----
-
 ### 4) 풍부한 콘텐츠 및 포맷팅
 
 - **react-intl**: 복수형, 선택형, 날짜/숫자, 메시지 구성에 대해 뛰어난 **ICU** 지원을 제공합니다. JSX를 사용할 수 있지만, 정신 모델은 메시지 중심으로 유지됩니다.
@@ -109,8 +97,6 @@ author: aymericzip
 
 **중요한 이유:** 복잡한 UI 텍스트(링크, 굵은 부분, 인라인 컴포넌트 등)는 라이브러리가 React 노드를 깔끔하게 수용할 때 더 쉽게 처리할 수 있습니다.
 
----
-
 ### 5) 성능 및 로딩 동작
 
 - **react-intl / react-i18next**: 일반적으로 **카탈로그 분할**과 **지연 로딩**을 수동으로 관리합니다(네임스페이스/동적 임포트). 효과적이지만 규율이 필요합니다.
@@ -118,8 +104,6 @@ author: aymericzip
 
 **중요한 이유:** 더 작은 번들과 사용하지 않는 문자열 감소는 시작 및 탐색 성능을 향상시킵니다.
 
----
-
 ### 6) 개발자 경험(DX), 도구 및 유지보수
 
 - **react-intl / react-i18next**: 광범위한 커뮤니티 생태계; 편집 워크플로우를 위해 일반적으로 외부 현지화 플랫폼을 채택합니다.
@@ -127,16 +111,12 @@ author: aymericzip
 
 **중요한 이유:** 내장된 도구는 개발자와 콘텐츠 작성자 간의 작업 흐름을 단축시켜 - 접착 코드가 줄고, 벤더 의존성이 감소합니다.
 
----
-
 ## 언제 어떤 것을 선택해야 할까요?
 
 - **react-intl**을 선택하세요, 만약 **ICU 우선** 메시지 포맷팅과 직관적이고 표준에 맞는 API를 원하며, 팀이 카탈로그와 안전성 검사를 수동으로 관리하는 데 익숙하다면.
 - **react-i18next**를 선택하세요, 만약 **i18next 생태계의 폭넓은 기능**(탐지기, 백엔드, ICU 플러그인, 통합 등)이 필요하고, 유연성을 얻기 위해 더 많은 설정을 감수할 수 있다면.
 - **Intlayer를 선택하세요** 만약 **컴포넌트 범위의 콘텐츠**, **엄격한 TypeScript**, **빌드 시 보장**, **트리 쉐이킹**, 그리고 **포함된 편집 도구**를 중요하게 생각한다면 - 특히 **크고 모듈화된** React 앱에 적합합니다.
 
----
-
 ## 실용적인 마이그레이션 노트 (react-intl / react-i18next → Intlayer)
 
 - **점진적으로 마이그레이션하세요**: 한 기능 또는 라우트부터 시작하고, 전환 기간 동안 기존 카탈로그를 병행 유지하세요.
@@ -144,8 +124,6 @@ author: aymericzip
 - **엄격한 검사 활성화**: 빌드 시 오류가 누락된 키/로케일을 CI 초기에 드러내도록 하세요.
 - **번들 크기 측정**: 사용하지 않는 문자열이 제거되면서 크기 감소를 기대하세요.
 
----
-
 ## GitHub STARs
 
 GitHub star는 프로젝트의 인기도, 커뮤니티 신뢰도, 장기적 관련성의 강력한 지표입니다. 기술적 품질의 직접적인 척도는 아니지만, 얼마나 많은 개발자가 프로젝트를 유용하다고 생각하는지, 진행 상황을 팔로우하는지, 그리고 이를 도입할 가능성이 있는지를 반영합니다. 프로젝트의 가치를 추정할 때, star는 대안들 간의 견인력을 비교하고 생태계 성장에 대한 통찰력을 제공하는 데 도움이 됩니다.

package/blog/ko/transform_existing_nextjs_app_using_compiler.md

@@ -0,0 +1,293 @@
+---
+createdAt: 2026-01-10
+updatedAt: 2026-09-06
+title: "기존 Next.js 애플리케이션을 사후에 다국어(i18n)화하는 방법 (2026 가이드)"
+description: "기존 Next.js 앱을 대대적인 리팩토링 없이 다국어(i18n)화하는 2026년 가이드. Intlayer를 활용한 자동 텍스트 추출, AI 번역 및 고성능 라우팅을 경험하세요."
+keywords:
+  - Next.js i18n
+  - 국제화
+  - 기존 Next.js 앱 번역
+  - Next.js 16
+  - Intlayer
+  - 다국어
+  - React i18n
+  - 컴파일러
+  - AI 번역
+  - SEO
+slugs:
+  - blog
+  - transform-existing-nextjs-app-into-multilingual-app
+applicationTemplate: https://github.com/aymericzip/intlayer-next-no-lolale-path-template
+youtubeVideo: https://www.youtube.com/watch?v=e_PPG7PTqGU
+history:
+  - version: 9.4.0
+    date: 2026-08-22
+    changes: "Update to Next.js >= 9.4.0 architecture"
+  - version: 8.9.0
+    date: 2026-05-04
+    changes: "Update Solid useIntlayer API usage to direct property access"
+  - version: 8.2.0
+    date: 2026-03-09
+    changes: "Update compiler options, add FilePathPattern support"
+  - version: 8.1.6
+    date: 2026-02-23
+    changes: "Initial release"
+author: aymericzip
+---
+
+# 기존 Next.js 애플리케이션을 사후에 다국어(i18n)화하는 방법 (2026 가이드)
+
+처음부터 Next.js 프로젝트에 국제화(i18n)를 적용하는 것은 비교적 간단합니다. 하지만 이미 단일 언어로 구축되어 배포 중인 Next.js 앱에 **사후에** 다국어를 적용해야 한다면 어떻게 해야 할까요?
+
+`next-intl`이나 `next-i18next` 같은 기존 라이브러리를 사용해 본 개발자라면 그 고통을 잘 알고 있습니다:
+
+- 수백 개의 JSX/TSX 파일에서 하드코딩된 문자열을 일일이 찾아내기.
+- 중첩된 JSON 딕셔너리를 수동 생성하고 번역 키(`pages.dashboard.header.title` 등)를 작명하기.
+- 텍스트를 복잡한 훅(`t('...')`)으로 교체하기.
+- `app/` 디렉터리 전체를 `app/[locale]/...`로 재구성하여 기존 URL과 검색 엔진 색인을 손상시키기.
+
+2026년에는 코드를 처음부터 다시 짤 필요가 없습니다. **Intlayer**를 사용하면 자동 텍스트 추출, AI 번역, 비침습적 라우팅을 통해 단 몇 분 만에 기존 Next.js 앱에 다국어를 도입할 수 있습니다.
+
+> Next.js 16 App Router에 대한 단계별 전체 기술 가이드를 찾고 계신가요? 전용 문서를 확인하세요: [Intlayer로 Next.js 16 번역하기](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_nextjs_16.md).
+
+## 목차
+
+<TOC/>
+
+## 사후 적용의 딜레마: 기존 앱에 다국어를 추가하기 힘든 이유
+
+기존 Next.js 애플리케이션에 국제화를 적용할 때 개발자는 세 가지 큰 문제에 직면합니다:
+
+1. **코드베이스 오염**: 문자열을 수동 추출하면 거의 모든 컴포넌트 파일을 수정해야 하므로 회귀 버그 위험이 급증합니다.
+2. **라우팅 구조 강제**: 기존 i18n 라이브러리는 레이아웃과 페이지를 `[locale]` 동적 세그먼트로 이동하도록 강제합니다.
+3. **지루한 번역 작업**: 추출 후 수십 개 언어로 번역하기 위해 끝없는 복사-붙여넣기 작업이 필요합니다.
+
+Intlayer는 **컴파일러 기반 자동 추출**, **선언적 딕셔너리**, **유연한 라우팅**으로 이러한 문제를 아키텍처 수준에서 해결합니다.
+
+## 자동 콘텐츠 추출 (수동 텍스트 검색 불필요)
+
+### 옵션 A: CLI 추출 도구 (`npx intlayer extract`)
+
+프로젝트에서 Intlayer의 추출 CLI를 바로 실행하세요:
+
+```bash packageManager="npm"
+npx intlayer extract
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer extract
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer extract
+```
+
+```bash packageManager="bun"
+bunx intlayer extract
+```
+
+React 컴포넌트를 정적 분석하여 사용자 텍스트를 추출하고 컴포넌트 바로 옆에 선언형 파일(`.content.ts`)을 자동 생성합니다.
+
+### 옵션 B: Intlayer 컴파일러 (빌드 타임 자동 추출)
+
+컴파일러를 활성화하면 기본 언어로 일반 텍스트를 컴포넌트에 그대로 작성하면 됩니다. 빌드 시 컴파일러가 텍스트를 추출하고 번역 콘텐츠를 자동으로 주입합니다:
+
+```tsx fileName="src/app/page.tsx"
+// Write normal React code. The compiler extracts the text automatically
+export default function HomePage() {
+  return (
+    <section>
+      <h1>Welcome to our platform</h1>
+      <p>Start exploring our modern features today.</p>
+    </section>
+  );
+}
+```
+
+백그라운드에서 Intlayer가 딕셔너리를 빌드하고 컴포넌트를 현지화된 콘텐츠에 연결하므로 수동 리팩토링 과정이 완전히 사라집니다.
+
+이 경우 다음과 같은 내용으로 `src/app/page.content.ts` 파일이 생성됩니다:
+
+```typescript fileName="src/app/page.content.ts"
+import { Dictionary } from "intlayer";
+
+const content = {
+  key: "home-page",
+  content: {
+    welcomeToOurPlatform: t({ en: "Welcome to our platform" }),
+    startExploringOurModernFeaturesToday: t({
+      en: "Start exploring our modern features today.",
+    }),
+  },
+};
+
+export default content;
+```
+
+## 선호하는 LLM을 활용한 AI 자동 번역
+
+콘텐츠가 추출되면 내장된 AI CLI를 통해 OpenAI, Anthropic, DeepSeek, Mistral을 사용하여 몇 초 만에 다국어로 번역할 수 있습니다:
+
+```bash packageManager="npm"
+npx intlayer fill
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer fill
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer fill
+```
+
+```bash packageManager="bun"
+bunx intlayer fill
+```
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, Locales.GERMAN],
+    defaultLocale: Locales.ENGLISH,
+  },
+  ai: {
+    provider: "openai",
+    model: "gpt-4o-mini",
+    apiKey: process.env.OPENAI_API_KEY,
+    applicationContext: "생산성 및 팀 협업을 위한 SaaS 대시보드",
+  },
+};
+
+export default config;
+```
+
+`npx intlayer fill`을 실행하면 설정된 모든 로케일에 대한 번역이 `.content.ts` 선언 파일에 자동으로 채워집니다:
+
+```typescript fileName="src/app/page.content.ts"
+import { Dictionary } from "intlayer";
+
+const content = {
+  key: "home-page",
+  content: {
+    welcomeToOurPlatform: t({
+      en: "Welcome to our platform",
+      fr: "Bienvenue sur notre plateforme",
+      es: "Bienvenido a nuestra plataforma",
+      ko: "플랫폼에 오신 것을 환영합니다",
+    }),
+    startExploringOurModernFeaturesToday: t({
+      en: "Start exploring our modern features today.",
+      fr: "Découvrez nos fonctionnalités modernes dès aujourd'hui.",
+      es: "Comience a explorar nuestras funciones modernas hoy.",
+      ko: "지금 바로 모던한 기능을 탐색해 보세요.",
+    }),
+  },
+};
+
+export default content;
+```
+
+Intlayer는 LLM에 상위 수준의 `applicationContext`를 제공하므로 생성된 번역이 기존 자동 번역 도구보다 기술적 뉘앙스, 브랜드 톤, 문법적 맥락을 훨씬 잘 유지합니다.
+
+프로덕션 배포 전 누락된 텍스트가 없는지 확인하려면:
+
+```bash
+npx intlayer test
+```
+
+## 기존 URL을 손상시키지 않고 다국어 라우팅 추가
+
+Intlayer는 다양한 라우팅 모드를 기본 지원합니다:
+
+- **쿼리 파라미터 / 쿠키 모드 (`search-params`)**: `[locale]` 폴더로 이동하지 않고 기존 `/app/page.tsx` 구조를 그대로 유지합니다.
+- **접두사 모드 (`prefix` / `prefix-all-locales`)**: SEO 친화적인 URL(`/ko/dashboard`)이 필요할 때 Next.js 프록시를 통해 간편하게 처리할 수 있습니다.
+
+단 몇 초 만에 Next.js 연동 설정을 완료하세요:
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { withIntlayer } from "next-intlayer/server";
+
+const nextConfig: NextConfig = {/* Your existing Next.js config */};
+
+export default withIntlayer(nextConfig);
+```
+
+루트 레이아웃을 `IntlayerProvider`로 감싸세요:
+
+```tsx fileName="src/app/layout.tsx"
+import type { ReactNode } from "react";
+import { IntlayerProvider } from "next-intlayer";
+import { getLocale } from "next-intlayer/server";
+import { getHTMLTextDir } from "intlayer";
+
+export default async function RootLayout({
+  children,
+}: {
+  children: ReactNode;
+}) {
+  const locale = await getLocale();
+
+  return (
+    <html lang={locale} dir={getHTMLTextDir(locale)}>
+      <body>
+        <IntlayerProvider defaultLocale={locale}>{children}</IntlayerProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## 다국어 SEO
+
+다국어 메타데이터 및 `hreflang` 태그를 자동 생성하여 글로벌 검색 엔진 노출을 최적화합니다:
+
+```tsx fileName="src/app/page.tsx"
+import type { Metadata } from "next";
+import { getLocale } from "next-intlayer/server";
+import { getIntlayer } from "intlayer";
+
+export const generateMetadata = async (): Promise<Metadata> => {
+  const locale = await getLocale();
+  const content = getIntlayer("home-page-metadata", locale);
+
+  return {
+    title: content.title,
+    description: content.description,
+  };
+};
+```
+
+## 더 알아보기: 단계별 구현 가이드가 준비되어 있습니다
+
+이 글은 기존 Next.js 앱을 사후에 다국어화하는 아키텍처 개요를 설명했습니다. 미들웨어 설정, 정적 생성 (`generateStaticParams`), 서버 컴포넌트 통합을 포함한 전체 가이드는 공식 문서를 참조하세요:
+
+👉 **[Intlayer로 Next.js 16 번역하기 전체 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_nextjs_16.md)**
+
+## 자주 묻는 질문 (FAQ)
+
+<FAQ>
+
+<Question title="app/[locale]로 파일을 옮기지 않고도 Next.js 앱을 다국어화할 수 있나요?">
+
+네. Intlayer는 `routing.mode: "search-params"`와 쿠키/헤더 감지를 지원하여 기존 폴더 구조를 완전히 유지할 수 있습니다.
+
+</Question>
+<Question title="기존 코드의 모든 문자열을 수동으로 바꿔야 하나요?">
+
+아닙니다. `npx intlayer extract` 또는 Intlayer 컴파일러를 통해 자동으로 추출 및 선언할 수 있습니다.
+
+</Question>
+<Question title="next-intl 대비 Intlayer는 어떻게 번들 크기를 줄이나요?">
+
+컴포넌트 단위 선언과 빌드 타임 매크로를 통해 실제 페이지에서 사용되는 번역 필드만 클라이언트에 번들링합니다.
+
+</Question>
+<Question title="AI를 사용해 컴포넌트를 여러 언어로 자동 번역할 수 있나요?">
+
+네. `npx intlayer fill` 명령을 통해 OpenAI, Claude 등 다양한 LLM으로 문맥을 고려한 고품질 번역을 자동 생성합니다.
+
+</Question>
+</FAQ>