@intlayer/docs 9.4.4 → 9.5.0

package/docs/ko/intlayer_with_nestjs.md

@@ -279,25 +279,21 @@ NestJS에는 요청 범위(request-scoped) 서비스와 함께 JSON 또는 YAML
 [왜 Intlayer인가](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/interest_of_intlayer.md)를 참조하세요.
 
 </Question>
-
 <Question title="i18n이 NestJS 서버 번들 크기에 얼마나 영향을 미치나요?">
 
 매우 적습니다. 사전은 사전에 컴파일되며 선언한 로케일만 포함되므로 부팅 시 카탈로그 로딩이나 요청 경로에서의 파일 읽기가 발생하지 않습니다. 이는 번들 크기가 콜드 스타트 시간을 좌우하는 서버리스 및 엣지 배포 환경에서 특히 중요합니다. [번들 최적화](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/bundle_optimization.md)를 참조하세요.
 
 </Question>
-
 <Question title="핸들러를 다시 작성하지 않고 i18next에서 마이그레이션할 수 있나요?">
 
 네, 두 가지 방법이 있습니다. [i18next 마이그레이션 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/migration_from_i18next_to_intlayer.md)를 따라 점진적으로 이전할 수 있습니다. 또는 현재 API를 완전히 유지할 수도 있습니다: [호환 어댑터(compat adapters)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compat/index.md)는 `i18next`와 완전히 동일한 API를 노출하면서 Intlayer 사전에서 데이터를 제공하므로, import 구문만 변경하고 핸들러 코드는 그대로 유지할 수 있습니다.
 
 </Question>
-
 <Question title="기존 JSON 번역 파일을 유지할 수 있나요?">
 
 네. [sync JSON 플러그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/plugins/sync-json.md)은 `/messages/{locale}/{namespace}.json` 파일을 단일 진실 공급원(source of truth)으로 유지하면서 양방향으로 Intlayer 사전을 생성합니다. [sync PO 플러그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/plugins/sync-po.md)은 gettext 카탈로그에 대해 동일한 작업을 수행하며, [로케일별 파일](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/per_locale_file.md)을 통해 로케일을 한 파일에 모으는 대신 언어별로 콘텐츠를 분할할 수도 있습니다.
 
 </Question>
-
 <Question title="콘텐츠를 키 단위로 하나씩 옮겨야 하나요?">
 
 아닙니다. `npx intlayer extract`를 실행하면 Intlayer가 소스 파일을 읽고 사용자 대면 문자열을 추출하여 각 컴포넌트 옆에 `.content` 파일을 생성하므로 카탈로그에 일일이 복사할 필요 없이 diff만 검토하면 됩니다. [extract 명령](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/extract.md)을 참조하세요.
@@ -305,7 +301,6 @@ NestJS에는 요청 범위(request-scoped) 서비스와 함께 JSON 또는 YAML
 동일한 프로젝트의 프론트엔드 측에서는 [Intlayer 컴파일러](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compiler.md)가 빌드 타임에 JSX, TSX, Vue 또는 Svelte 소스에서 사전을 생성하므로 앱의 두 영역이 수동 키 관리 없이 단일 콘텐츠 레이어를 공유할 수 있습니다.
 
 </Question>
-
 <Question title="사용 가능한 에디터 및 AI 에이전트 도구는 무엇이 있나요?">
 
 5가지 도구가 모두 선택 사항으로 제공됩니다:
@@ -317,61 +312,51 @@ NestJS에는 요청 범위(request-scoped) 서비스와 함께 JSON 또는 YAML
 - **[ESLint 플러그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/eslint.md)**: `no-raw-text` 규칙으로 하드코딩된 문자열을 표시하고, 정적 사전 키 및 사용되지 않는 콘텐츠에 대한 추가 규칙을 제공합니다.
 
 </Question>
-
 <Question title="Intlayer는 응답할 언어를 어떻게 파악하나요?">
 
 기본적으로 `express-intlayer`는 들어오는 요청의 `Accept-Language` 헤더를 읽고 선언된 가장 가까운 로케일을 선택하며, 기본 로케일로 폴백합니다. `routing.storage`를 통해 소스를 사용자 지정 헤더나 프론트엔드가 설정한 쿠키 등으로 변경할 수 있으므로 브라우저 광고 언어가 아닌 사용자가 실제로 선택한 언어로 API가 응답하도록 만들 수 있습니다. [설정 참조](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)를 참조하세요.
 
 </Question>
-
 <Question title="로케일은 요청별로 격리되나요?">
 
 네. 미들웨어는 활성 로케일의 범위를 요청으로 한정하므로 서로 다른 언어로 실행 중인 두 개의 동시 요청이 상대방의 로케일을 읽지 않습니다. 덕분에 모든 함수에 로케일 인수를 전달하지 않고도 서비스 내에서 `t()` 및 `getIntlayer()`를 안전하게 호출할 수 있습니다.
 
 </Question>
-
 <Question title="수신자의 언어로 트랜잭션 이메일을 보내려면 어떻게 하나요?">
 
 다른 콘텐츠와 마찬가지로 콘텐츠 파일에 이메일 내용을 선언한 다음 요청 로케일 대신 수신자의 저장된 로케일로 `getIntlayer`를 호출하여 확인합니다. 이는 언어가 사용자 레코드에 속해 있고 헤더를 읽을 수 있는 인바운드 요청이 없는 백그라운드 작업 및 큐에서 특히 유용합니다.
 
 </Question>
-
 <Question title="API 오류 메시지를 어떻게 지역화하나요?">
 
 오류가 생성되는 지점에서 메시지를 `t()`로 래핑하세요. 활성 요청 로케일이 이를 확인하므로 클라이언트는 직접 표시할 수 있는 메시지를 수신하게 되며 프론트엔드에서 오류 코드 카탈로그를 별도로 유지할 필요가 없습니다.
 
 </Question>
-
 <Question title="NestJS 서비스나 컨트롤러에 번역을 주입할 수 있나요?">
 
 네. 위 예제처럼 서비스나 컨트롤러 내부에서 `getIntlayer("app")`을 호출하면 됩니다. 활성 로케일은 미들웨어가 설정한 요청 컨텍스트에서 가져오므로 기능별로 모듈을 등록하거나 토큰을 주입할 필요가 없습니다.
 
 </Question>
-
 <Question title="AI를 사용하여 백엔드 콘텐츠를 자동으로 번역하려면 어떻게 하나요?">
 
 `npx intlayer fill`을 실행하면 자체 제공업체 및 API 키를 사용하여 원하는 LLM으로 누락된 번역을 채워줍니다. 브랜치에서 변경된 콘텐츠만 번역하려면 `--git-diff`를 추가하세요. [fill 명령](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/fill.md) 및 [CI/CD 통합](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/CI_CD.md)을 참조하세요.
 
 </Question>
-
 <Question title="Intlayer는 서버에서 복수형, 성별 및 보간된 값을 지원하나요?">
 
 네: [복수형(plural forms)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/plurial.md), [성별 기반 콘텐츠](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/gender.md), 조건문, 보간 값을 위한 [삽입(insertions)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/insertion.md), 이메일 본문을 위한 [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/markdown.md), 그리고 숫자, 날짜, 통화를 위한 [포맷터](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/formatters.md)를 지원합니다.
 
 </Question>
-
 <Question title="서버에서 TypeScript 자동 완성이 지원되나요?">
 
 네. Intlayer는 사전의 타입을 `./types/intlayer.d.ts`에 생성하므로 존재하지 않는 키는 런타임 빈 문자열이 아니라 컴파일 오류가 됩니다. CI에서 `npx intlayer test`를 실행하면 선언된 로케일에 콘텐츠가 누락된 경우 빌드가 실패합니다.
 
 </Question>
-
 <Question title="프론트엔드와 백엔드가 동일한 콘텐츠를 공유할 수 있나요?">
 
 네, 실제로 권장되는 설정입니다. `express-intlayer`는 동일한 선언 콘텐츠에 대해 `react-intlayer`, `next-intlayer`, `vite-intlayer`와 함께 작동하므로 API 응답과 웹 페이지 모두에서 사용되는 레이블을 한 번만 선언하면 됩니다. [Intlayer 작동 방식](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/how_works_intlayer.md)을 참조하세요.
 
 </Question>
-
 <Question title="Intlayer는 무료이며 오픈 소스인가요?">
 
 네, 상업적 사용을 포함하여 Apache 2.0 라이선스에 따라 제공됩니다. 호스팅형 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_CMS.md)는 선택적 유료 서비스이며 [자체 호스팅](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/self_hosting.md)도 가능합니다.

package/docs/ko/intlayer_with_next-i18next.md

@@ -40,8 +40,6 @@ author: aymericzip
 > 참고: next-i18next는 i18next 위에 구축되었습니다. 이 가이드는 App Router에서 next-i18next와 호환되는 i18next 기본 기능을 사용하며, 아키텍처를 간단하고 프로덕션 준비 상태로 유지합니다.
 > 더 넓은 비교는 [next-i18next vs next-intl vs Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ko/next-i18next_vs_next-intl_vs_intlayer.md)를 참조하세요.
 
----
-
 ## 1) 프로젝트 구조
 
 next-i18next 의존성을 설치하세요:
@@ -93,8 +91,6 @@ bun add next-i18next i18next react-i18next i18next-resources-to-backend
 - 메시지를 과도하게 중앙집중화하지 마세요; 작은 페이지/기능 범위의 namespace를 사용하세요
 - 모든 locale을 한 번에 임포트하지 마세요; 필요한 것만 로드하세요
 
----
-
 ## 2) 의존성 설치
 
 ```bash
@@ -107,8 +103,6 @@ next-i18next API 또는 설정 연동을 사용할 계획이라면, 다음도
 pnpm add next-i18next
 ```
 
----
-
 ## 3) 핵심 i18n 설정
 
 로케일, 기본 로케일, RTL, 그리고 지역화된 경로/URL을 위한 헬퍼를 정의합니다.
@@ -135,8 +129,6 @@ export function abs(locale: string, path: string) {
 
 시니어 노트: `next-i18next.config.js`를 사용하는 경우, `i18n.config.ts`와 일치하도록 유지하여 불일치를 방지하세요.
 
----
-
 ## 4) 서버 사이드 i18n 초기화
 
 필요한 locale/namespace JSON만 동적으로 가져오는 백엔드를 사용하여 서버에서 i18next를 초기화합니다.
@@ -175,8 +167,6 @@ export async function initI18next(
 
 중간 노트: 페이로드를 제한하기 위해 페이지별 네임스페이스 목록을 짧게 유지하세요. 전역 “catch-all” 번들은 피하세요.
 
----
-
 ## 5) React 컴포넌트를 위한 클라이언트 프로바이더
 
 서버 설정을 반영하고 요청된 네임스페이스만 로드하는 프로바이더로 클라이언트 컴포넌트를 감싸세요.
@@ -233,8 +223,6 @@ export default function I18nProvider({
 
 초급 팁: 모든 메시지를 클라이언트에 전달할 필요가 없습니다. 페이지의 네임스페이스만 전달하는 것으로 시작하세요.
 
----
-
 ## 6) 지역화된 레이아웃과 라우트
 
 언어와 방향을 설정하고, 정적 렌더링을 우선시하기 위해 로케일별 라우트를 미리 생성합니다.
@@ -270,8 +258,6 @@ export default function LocaleLayout({
 }
 ```
 
----
-
 ## 7) 서버 + 클라이언트 사용 예제 페이지
 
 ```tsx fileName="src/app/[locale]/about.tsx"
@@ -387,8 +373,6 @@ const ServerComponent = ({ t, locale, count }: ServerComponentProps) => {
 export default ServerComponent;
 ```
 
----
-
 ## 8) SEO: 메타데이터, Hreflang, 사이트맵, 로봇
 
 콘텐츠 번역은 도달 범위를 확장하는 수단입니다. 다국어 SEO를 철저히 구성하세요.
@@ -482,8 +466,6 @@ export default function robots(): MetadataRoute.Robots {
 }
 ```
 
----
-
 ## 9) 로케일 라우팅을 위한 미들웨어
 
 로케일을 감지하고 누락된 경우 로컬라이즈된 경로로 리디렉션합니다.
@@ -526,8 +508,6 @@ export const config = {
 };
 ```
 
----
-
 ## 10) 성능 및 개발자 경험(DX) 모범 사례
 
 - **html `lang` 및 `dir` 설정**: `src/app/[locale]/layout.tsx`에서 완료됨.
@@ -538,8 +518,6 @@ export const config = {
 - **무거운 연산 메모이제이션**: 특히 구버전 React 클라이언트 코드에서 중요.
 - **캐시 및 헤더**: 가능하면 동적 렌더링보다 정적 또는 `revalidate` 사용 선호.
 
----
-
 ## 11) 테스트 및 CI
 
 - `t`를 사용하는 컴포넌트에 대해 키 존재 여부를 확인하는 단위 테스트 추가.
@@ -548,8 +526,6 @@ export const config = {
 
 Intlayer가 이 작업의 대부분을 자동화해줍니다 (다음 섹션 참조).
 
----
-
 ## 12) Intlayer 추가하기 (자동화)
 
 Intlayer는 JSON 번역을 동기화 상태로 유지하고, 누락된 키를 테스트하며, 필요 시 AI로 채워주는 기능을 제공합니다.
@@ -635,8 +611,6 @@ export default config;
 
 > CLI 인수를 제공할 수 있습니다; 자세한 내용은 [Intlayer CLI 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/index.md)를 참조하세요.
 
----
-
 ## 13) 문제 해결
 
 - **키를 찾을 수 없음**: 페이지/프로바이더가 올바른 네임스페이스를 나열하고 JSON 파일이 `src/locales/<locale>/<namespace>.json` 경로에 존재하는지 확인하세요.
@@ -645,8 +619,6 @@ export default config;
 - **SEO 대체 언어 누락**: `alternates.languages`에 모든 로케일과 `x-default`가 포함되어 있는지 확인하세요.
 - **번들 크기 과다**: 네임스페이스를 더 세분화하고 클라이언트에서 전체 `locales` 트리를 임포트하지 않도록 하세요.
 
----
-
 ## 14) 다음 단계
 
 - 기능이 확장됨에 따라 더 많은 로케일과 네임스페이스 추가

package/docs/ko/intlayer_with_nextjs_14.md

@@ -50,37 +50,31 @@ Intlayer는 효율적인 렌더링을 위해 **서버 구성요소**와 작동
 > 앱 라우터가 포함된 Next.js 12, 13, 14, 15의 경우 이 [가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_14.md)를 참조하세요.
 
 </Accordion>
-
 <Accordion header="번들 크기">
 
 대용량 JSON 파일을 페이지에 로드하는 대신 필요한 콘텐츠만 로드하세요. Intlayer는 **번들 및 페이지 크기를 최대 50%** 줄이는 데 도움이 됩니다.
 
 </Accordion>
-
 <Accordion header="유지관리성">
 
 애플리케이션 콘텐츠의 범위를 지정하면 대규모 애플리케이션의 **유지 관리가 용이해집니다**. 전체 콘텐츠 코드베이스를 검토해야 하는 정신적 부담 없이 단일 기능 폴더를 복제하거나 삭제할 수 있습니다. 또한 Intlayer는 **완전히 유형**되어 콘텐츠의 정확성을 보장합니다.
 
 </Accordion>
-
 <Accordion header="AI 에이전트">
 
 콘텐츠를 같은 위치에 배치하면 LLM(대형 언어 모델)에 **필요한 컨텍스트가 줄어듭니다**. Intlayer에는 누락된 번역을 테스트하기 위한 **CLI**, **[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)** 및 **[agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/agent_skills.md)**, AI 에이전트를 위한 개발자 경험(DX)을 더욱 원활하게 만듭니다.
 
 </Accordion>
-
 <Accordion header="오토메이션">
 
 AI 공급자의 비용으로 선택한 LLM을 사용하여 CI/CD 파이프라인을 번역하려면 자동화를 사용하세요. Intlayer는 또한 콘텐츠 추출을 자동화하는 **컴파일러**와 **백그라운드에서 번역**을 돕는 [웹 플랫폼](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)을 제공합니다.
 
 </Accordion>
-
 <Accordion header="성능">
 
 대규모 JSON 파일을 구성 요소에 연결하면 성능 및 반응성 문제가 발생할 수 있습니다. Intlayer는 빌드 시 콘텐츠 로딩을 최적화합니다.
 
 </Accordion>
-
 <Accordion header="개발자가 없는 경우 확장">
 
 Intlayer는 단순한 i18n 솔루션 그 이상으로 관리에 도움이 되는 **자체 호스팅 [비주얼 편집기](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** 및 **[전체 CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)**를 제공합니다. 다국어 콘텐츠를 **실시간**으로 제공하여 번역가, 카피라이터, 기타 팀원과 원활하게 협업할 수 있습니다. 콘텐츠는 로컬 및/또는 원격으로 저장될 수 있습니다.
@@ -88,8 +82,6 @@ Intlayer는 단순한 i18n 솔루션 그 이상으로 관리에 도움이 되는
 </Accordion>
 </AccordionGroup>
 
----
-
 ## Next.js 애플리케이션에서 Intlayer 설정 단계별 가이드
 
 <Tabs defaultTab="code">
@@ -120,7 +112,6 @@ Intlayer는 단순한 i18n 솔루션 그 이상으로 관리에 도움이 되는
 [Application Template](https://github.com/aymericzip/intlayer-next-14-template)을 GitHub에서 확인하세요.
 
 <Steps>
-
 <Step number={1} title="의존성 설치">
 
 npm을 사용하여 필요한 패키지를 설치합니다:
@@ -171,7 +162,6 @@ yarn add intlayer next-intlayer
 Intlayer를 Next.js와 통합하는 패키지입니다. Next.js 국제화를 위한 컨텍스트 프로바이더와 훅을 제공합니다. 또한, Intlayer를 [Webpack](https://webpack.js.org/) 또는 [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack)과 통합하기 위한 Next.js 플러그인과 사용자의 선호 로케일 감지, 쿠키 관리, URL 리디렉션 처리를 위한 미들웨어도 포함하고 있습니다.
 
 </Step>
-
 <Step number={2} title="프로젝트 구성">
 
 Here is the final structure that we will make:
@@ -225,7 +215,6 @@ export default config;
 > 이 구성 파일을 통해 지역화된 URL, 미들웨어 리디렉션, 쿠키 이름, 콘텐츠 선언의 위치 및 확장자 설정, 콘솔에서 Intlayer 로그 비활성화 등 다양한 설정을 할 수 있습니다. 사용 가능한 모든 매개변수 목록은 [구성 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)를 참조하세요.
 
 </Step>
-
 <Step number={3} title="Next.js 구성에 Intlayer 통합하기">
 
 Next.js 설정에서 Intlayer를 사용하도록 구성합니다:
@@ -251,7 +240,6 @@ export default withIntlayer(nextConfig);
 > ```
 
 </Step>
-
 <Step number={4} title="로케일 감지를 위한 미들웨어 구성">
 
 사용자의 선호 로케일을 감지하기 위해 미들웨어를 설정합니다:
@@ -287,7 +275,6 @@ export const middleware = multipleMiddlewares([
 ```
 
 </Step>
-
 <Step number={5} title="동적 로케일 라우트 정의">
 
 `RootLayout`의 모든 내용을 제거하고 다음 코드로 교체하세요:
@@ -381,7 +368,6 @@ export default LocaleLayout;
 > `generateStaticParams`는 애플리케이션이 모든 로케일에 대해 필요한 페이지를 사전 빌드하도록 하여 런타임 계산을 줄이고 사용자 경험을 향상시킵니다. 자세한 내용은 [Next.js 문서의 generateStaticParams](https://nextjs.org/docs/app/building-your-application/rendering/static-and-dynamic-rendering#generate-static-params)를 참조하세요.
 
 </Step>
-
 <Step number={6} title="콘텐츠 선언하기">
 
 번역을 저장하기 위해 콘텐츠 선언을 생성하고 관리하세요:
@@ -436,7 +422,6 @@ export default pageContent;
 > 자세한 내용은 [콘텐츠 선언 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/content_file.md)를 참조하세요.
 
 </Step>
-
 <Step number={7} title="코드에서 콘텐츠 활용하기">
 
 애플리케이션 전반에서 콘텐츠 사전을 접근하세요:
@@ -573,16 +558,15 @@ const ServerComponentExample: FC = () => {
 
 > 콘텐츠를 `alt`, `title`, `href`, `aria-label` 등과 같은 `string` 속성에서 사용하려면, 함수의 값을 호출해야 합니다. 예를 들어:
 
-> ```html
-> <img src="{content.image.src.value}" alt="{content.image.value}" />
-> <img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
-> <img src="{String(content.image.src)}" alt="{String(content.image)}" />
+> ```tsx
+> <img src={content.image.src.value} alt={content.image.value} />
+> <img src={content.image.src.toString()} alt={content.image.toString()} />
+> <img src={String(content.image.src)} alt={String(content.image)} />
 > ```
 
 > `useIntlayer` 훅에 대해 더 알아보려면 [문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/next-intlayer/useIntlayer.md)를 참조하세요.
 
 </Step>
-
 <Step number={8} title="메타데이터의 국제화" isOptional={true}>
 
 페이지 제목과 같은 메타데이터를 국제화하려는 경우, Next.js에서 제공하는 `generateMetadata` 함수를 사용할 수 있습니다. 이 함수 내부에서 `getIntlayer` 함수를 통해 콘텐츠를 가져와 메타데이터를 번역할 수 있습니다.
@@ -722,7 +706,6 @@ export const generateMetadata = ({ params: { locale } }) => {
 > 메타데이터 최적화에 대해 더 알아보려면 [공식 Next.js 문서](https://nextjs.org/docs/app/building-your-application/optimizing/metadata)를 참고하세요.
 
 </Step>
-
 <Step number={9} title="sitemap.xml 및 robots.txt의 다국어 지원" isOptional={true}>
 
 `sitemap.xml`과 `robots.txt`를 다국어로 지원하려면 Intlayer에서 제공하는 `getMultilingualUrls` 함수를 사용할 수 있습니다. 이 함수는 사이트맵에 다국어 URL을 생성할 수 있게 해줍니다.
@@ -780,7 +763,6 @@ export default robots;
 > 사이트맵 최적화에 대해 더 알아보려면 [공식 Next.js 문서](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap)를 참고하세요. robots.txt 최적화에 대해서는 [공식 Next.js 문서](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/robots)를 참고하세요.
 
 </Step>
-
 <Step number={10} title="콘텐츠 언어 변경하기" isOptional={true}>
 
 Next.js에서 콘텐츠의 언어를 변경하려면 권장되는 방법은 `Link` 컴포넌트를 사용하여 사용자를 적절한 현지화된 페이지로 리디렉션하는 것입니다. `Link` 컴포넌트는 페이지를 미리 가져오는(prefetch) 기능을 제공하여 전체 페이지 리로드를 방지하는 데 도움이 됩니다.
@@ -869,7 +851,6 @@ return (
 > - [`aria-current` 속성](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current)
 
 </Step>
-
 <Step number={11} title="지역화된 링크 컴포넌트 생성하기" isOptional={true}>
 
 애플리케이션의 내비게이션이 현재 로케일을 준수하도록 하려면, 커스텀 `Link` 컴포넌트를 만들 수 있습니다. 이 컴포넌트는 내부 URL에 현재 언어를 자동으로 접두사로 붙여줍니다. 예를 들어, 프랑스어 사용자가 "About" 페이지로 가는 링크를 클릭하면 `/about` 대신 `/fr/about`로 리디렉션됩니다.
@@ -941,7 +922,6 @@ Link.displayName = "Link";
 이 `Link` 컴포넌트를 애플리케이션 전반에 통합하면 일관되고 언어에 민감한 사용자 경험을 유지할 수 있으며, SEO 및 사용성 향상에도 도움이 됩니다.
 
 </Step>
-
 <Step number={12} title="번들 크기 최적화" isOptional={true}>
 
 Server Action 내에서 활성 locale이 필요한 경우(예: 이메일 로컬라이제이션 또는 locale 인식 로직 실행), `next-intlayer/server`에서 `getLocale`을 호출하세요:
@@ -968,7 +948,6 @@ export const myServerAction = async () => {
 > 이는 사용 가능한 컨텍스트를 기반으로 가장 적절한 로케일이 선택되도록 보장합니다.
 
 </Step>
-
 <Step number={13} title="번들 크기 최적화" isOptional={true}>
 
 `next-intlayer`를 사용할 때, 기본적으로 모든 페이지 번들에 사전이 포함됩니다. 번들 크기를 최적화하기 위해 Intlayer는 매크로를 사용하여 `useIntlayer` 호출을 지능적으로 대체하는 선택적 SWC 플러그인을 제공합니다. 이를 통해 실제로 사전을 사용하는 페이지의 번들에만 사전이 포함되도록 보장합니다.
@@ -995,6 +974,8 @@ bun add @intlayer/swc --dev
 
 > 참고: 이 패키지는 SWC 플러그인이 Next.js에서 아직 실험 단계이기 때문에 기본적으로 설치되지 않습니다. 향후 변경될 수 있습니다.
 
+> 참고: `dictionary` 설정에서 옵션을 `importMode: 'dynamic'` 또는 `importMode: 'fetch'`로 설정하면 Suspense에 의존하게 되므로, `useIntlayer` 호출을 `Suspense` 경계로 감싸야 합니다. 즉, Page / Layout 컴포넌트의 최상위 레벨에서 `useIntlayer`를 직접 사용할 수 없습니다.
+
 </Step>
 
 </Steps>
@@ -1064,25 +1045,21 @@ Intlayer와 함께 개발 경험을 향상시키기 위해 공식 **Intlayer VS
 실제적인 차이는 브라우저에 전송되는 데이터 양입니다. 네임스페이스 기반 라이브러리는 페이지에 전체 JSON 카탈로그를 전송하지만, Intlayer는 렌더링된 컴포넌트가 사용하는 콘텐츠만 전송하므로 번들 및 페이지 크기를 최대 50% 줄여줍니다. [왜 Intlayer인가](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/interest_of_intlayer.md)와 [Next.js i18n 벤치마크](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/benchmark/nextjs.md)를 참조하세요.
 
 </Question>
-
 <Question title="i18n이 Next.js 번들 크기에 얼마나 영향을 미치나요?">
 
 네임스페이스 기반 설정보다 훨씬 적습니다. 페이지는 렌더링하지 않는 언어의 카탈로그를 절대 다운로드하지 않기 때문입니다. Server Components는 서버에서 직접 콘텐츠를 확인하며, 빌드 타임 컴파일러는 `useIntlayer` 호출을 컴포넌트가 사용하는 정확한 사전 항목으로 대체하므로 사용되지 않는 키와 언어는 제거되며, [동적 사전](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/index.md)을 통해 로케일별로 분할됩니다. 일반적인 대안들과 비교했을 때 Intlayer는 번들 및 페이지 크기를 최대 50%까지 줄여줍니다. [번들 최적화](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/bundle_optimization.md)와 [벤치마크](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/benchmark/nextjs.md)를 참조하세요.
 
 </Question>
-
 <Question title="컴포넌트를 다시 작성하지 않고 next-intl, next-i18next 또는 i18next에서 마이그레이션할 수 있나요?">
 
 네, 두 가지 방법이 있습니다. [next-intl 마이그레이션 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/migration_from_next-intl_to_intlayer.md) 또는 [i18next 마이그레이션 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/migration_from_i18next_to_intlayer.md)를 통해 콘텐츠를 점진적으로 마이그레이션할 수 있습니다. 또는 현재 API를 완전히 유지할 수도 있습니다. [호환 어댑터(compat adapters)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compat/index.md)는 `next-intl`, `react-i18next`, `react-intl`과 완전히 동일한 API를 노출하면서 Intlayer 사전에서 데이터를 제공하므로, import 구문만 변경하고 컴포넌트 코드는 그대로 유지할 수 있습니다.
 
 </Question>
-
 <Question title="기존 JSON 번역 파일을 유지할 수 있나요?">
 
 네. [sync JSON 플러그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/plugins/sync-json.md)은 `/messages/{locale}/{namespace}.json` 파일을 단일 진실 공급원(source of truth)으로 유지하면서 양방향으로 Intlayer 사전을 생성합니다. [sync PO 플러그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/plugins/sync-po.md)은 gettext 카탈로그에 대해 동일한 작업을 수행하며, [로케일별 파일](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/per_locale_file.md)을 통해 로케일을 한 파일에 모으는 대신 언어별로 콘텐츠를 분할할 수도 있습니다.
 
 </Question>
-
 <Question title="콘텐츠를 키 단위로 하나씩 옮겨야 하나요?">
 
 아닙니다. `npx intlayer extract`를 실행하면 Intlayer가 소스 파일을 읽고 사용자 대면 문자열을 추출하여 각 컴포넌트 옆에 `.content` 파일을 생성하므로 카탈로그에 일일이 복사할 필요 없이 diff만 검토하면 됩니다. [extract 명령](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/extract.md)을 참조하세요.
@@ -1090,7 +1067,6 @@ Intlayer와 함께 개발 경험을 향상시키기 위해 공식 **Intlayer VS
 완전 자동화된 파이프라인을 위해 [Intlayer 컴파일러](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compiler.md)는 빌드 타임에 JSX, TSX, Vue 및 Svelte 소스에서 동일한 작업을 수행하여 변경될 때마다 사전을 생성하므로 수동으로 키를 관리할 필요가 없습니다. 정적 분석으로 작동하므로 런타임에만 존재하는 문자열은 제외되며, 사용자 텍스트와 애플리케이션 로직을 구분하기 위해 몇 가지 주석이 필요합니다.
 
 </Question>
-
 <Question title="사용 가능한 에디터 및 AI 에이전트 도구는 무엇이 있나요?">
 
 5가지 도구가 모두 선택 사항으로 제공됩니다:
@@ -1102,61 +1078,51 @@ Intlayer와 함께 개발 경험을 향상시키기 위해 공식 **Intlayer VS
 - **[ESLint 플러그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/eslint.md)**: `no-raw-text` 규칙으로 하드코딩된 문자열을 표시하고, 정적 사전 키 및 사용되지 않는 콘텐츠에 대한 추가 규칙을 제공합니다.
 
 </Question>
-
 <Question title="Intlayer는 어떤 Next.js 버전을 지원하나요?">
 
 Next.js 12, 13, 14, 15 및 16을 지원합니다. 본 가이드는 Next.js 14를 다룹니다. Next.js 16의 경우 [Next.js 16 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_nextjs_16.md)를, Next.js 15의 경우 [Next.js 15 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_nextjs_15.md)를, Pages Router의 경우 [Pages Router 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_nextjs_page_router.md)를 따르세요.
 
 </Question>
-
 <Question title="Intlayer는 React Server Components와 호환되나요?">
 
 네. Next.js 14에서는 App Router의 `params`가 여전히 동기식이므로 라우트 세그먼트에서 직접 로케일을 읽어 프로바이더에 전달합니다. Server Components 내부의 서버에서 콘텐츠가 직접 확인되므로 서버 렌더링된 텍스트에 대해 클라이언트로 사전이 전송되지 않으며, Client Components는 동일한 사전을 프로바이더를 통해 읽습니다.
 
 </Question>
-
 <Question title="/fr/about처럼 URL에 로케일을 반드시 포함해야 하나요?">
 
 아닙니다. `routing.mode`는 `"prefix-no-default"`(기본값: 기본 로케일은 `/about`, 나머지는 `/ko/about`), `"prefix-all"`, `"no-prefix"`(쿠키, 헤더 또는 도메인에서 확인), `"search-params"`(`/about?locale=ko`)를 허용합니다. `routing.domains`를 사용하면 각 로케일을 자체 도메인에 매핑할 수도 있습니다. [설정 참조](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md) 및 [로케일 경로 없는 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_nextjs_no_locale_path.md)를 참조하세요.
 
 </Question>
-
 <Question title="SEO를 위한 hreflang 태그 및 현지화된 메타데이터는 어떻게 추가하나요?">
 
 8단계에서 `generateMetadata`를 다루고, 9단계에서 `sitemap.xml` 및 `robots.txt`를 다룹니다. `getMultilingualUrls`는 `x-default` 항목을 포함하여 선언된 모든 로케일에 대해 `alternates.languages` 맵을 구축하므로 검색 엔진이 올바른 언어 버전을 제공할 수 있습니다.
 
 </Question>
-
 <Question title="미들웨어가 반드시 필요한가요?">
 
 방문자의 로케일을 감지하고 일치하는 접두사로 리디렉션하는 역할을 하므로 로케일 라우팅을 직접 처리하지 않는 한 미들웨어를 사용하는 것이 좋습니다. 4단계에서는 API 라우트, 정적 에셋 및 `_next`를 제외하는 matcher를 포함한 설정을 보여줍니다.
 
 </Question>
-
 <Question title="현지화된 Link 컴포넌트는 어떻게 구축하나요?">
 
 11단계에서 보여줍니다. 컴포넌트는 Next.js `Link`를 감싸고 `getLocalizedUrl`을 통해 href를 전달하므로, `/about`으로 작성된 내부 링크가 모든 호출 위치에서 로케일을 반복하지 않고도 한국어 방문자에게 자동으로 `/ko/about`이 됩니다.
 
 </Question>
-
 <Question title="AI를 사용하여 앱을 자동으로 번역하려면 어떻게 하나요?">
 
 `npx intlayer fill`을 실행하세요. 자체 제공업체 및 API 키를 사용하여 원하는 LLM으로 누락된 번역을 채워주며, `--git-diff`를 사용하면 브랜치에서 변경된 콘텐츠로 번역 범위를 제한할 수 있습니다. [fill 명령](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/fill.md) 및 [CI/CD 통합](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/CI_CD.md)을 참조하세요.
 
 </Question>
-
 <Question title="Intlayer는 복수형, 성별 및 서식 있는 텍스트(Rich Text)를 지원하나요?">
 
 네: [복수형(plural forms)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/plurial.md), [성별 기반 콘텐츠](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/gender.md), 조건문, [삽입(insertions)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/insertion.md), 긴 텍스트를 위한 [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/markdown.md), 그리고 숫자, 날짜, 통화를 위한 [포맷터](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/formatters.md)를 지원합니다.
 
 </Question>
-
 <Question title="번역가가 코드를 건드리지 않고 콘텐츠를 수정할 수 있나요?">
 
 자체 호스팅되는 [비주얼 에디터](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_visual_editor.md)를 통해 누구나 실행 중인 앱에서 직접 텍스트를 수정할 수 있으며, 배포 없이 콘텐츠를 변경해야 하는 경우에는 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_CMS.md)를 활용할 수 있습니다.
 
 </Question>
-
 <Question title="Intlayer는 무료이며 오픈 소스인가요?">
 
 네, 상업적 사용을 포함하여 Apache 2.0 라이선스에 따라 제공됩니다. 호스팅형 CMS는 선택적 유료 서비스이며 [자체 호스팅](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/self_hosting.md)도 가능합니다.