@intlayer/docs 9.4.4 → 9.5.0

package/docs/ko/intlayer_with_nextjs_16.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-12-06
-updatedAt: 2026-08-30
+updatedAt: 2026-09-08
 title: "Next.js 16 i18n - 앱을 번역하는 완전 가이드"
 description: "i18next는 이제 그만. 2026년 다국어 (i18n) Next.js 16 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
 keywords:
@@ -41,7 +41,7 @@ author: aymericzip
 <iframe title="Next.js를 위한 최고의 i18n 솔루션? Intlayer를 발견하세요" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/e_PPG7PTqGU?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
 
   </Tab>
-  <Tab label="코드" value="code">
+  <Tab label="코드 (로케일 경로 있음)" value="code-locale-path">
 
 <iframe
   src="https://ide.intlayer.org/aymericzip/intlayer-next-16-template?file=intlayer.config.ts"
@@ -52,12 +52,23 @@ author: aymericzip
 />
 
   </Tab>
-  <Tab label="데모" value="demo">
+  <Tab label="코드 (로케일 경로 없음)" value="code-no-locale-path">
+
+<iframe
+  src="https://ide.intlayer.org/aymericzip/intlayer-next-16-no-locale-path-template?file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="데모 CodeSandbox - Intlayer를 사용하여 애플리케이션을 국제화하는 방법"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+  <Tab label="데모 (로케일 경로 있음)" value="demo">
 
 <iframe
   src="https://intlayer-next-16-template.vercel.app"
   className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="데모 - intlayer-next-16-template"
+  title="데모 Intlayer Next.js 16 Template"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
   loading="lazy"
 />
@@ -65,7 +76,7 @@ author: aymericzip
   </Tab>
 </Tabs>
 
-GitHub에서 [애플리케이션 템플릿](https://github.com/aymericzip/intlayer-next-16-template)을 확인하세요.
+GitHub에서 [애플리케이션 템플릿](https://github.com/aymericzip/intlayer-next-16-template) 및 [로케일 경로 없는 애플리케이션 템플릿](https://github.com/aymericzip/intlayer-next-no-lolale-path-template)을 확인하세요.
 
 ## 목차
 
@@ -81,41 +92,35 @@ GitHub에서 [애플리케이션 템플릿](https://github.com/aymericzip/intlay
 Intlayer는 효율적인 렌더링을 위해 **서버 구성요소**와 작동하도록 최적화되어 있으며 [**Turbopack**](https://nextjs.org/docs/architecture/turbopack)과 완벽하게 호환됩니다. 정적 렌더링을 차단하지 않으며 미들웨어는 물론 국제화 확장(i18n)에 필요한 모든 기능을 제공합니다.
 
 > Intlayer는 Next.js 12, 13, 14, 15, 16과 호환됩니다. Next.js Pages Router를 사용하는 경우 이 [가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_page_router.md)를 참조하세요.
-> 로케일 라우팅은 SEO, 번들 크기 및 성능에 유용합니다. 필요하지 않은 경우에는 이 [가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_no_locale_path.md)를 참고하시면 됩니다.
+> 로케일 라우팅은 SEO, 번들 크기 및 성능에 유용합니다. 로케일 경로가 있는 설정과 없는 설정 모두 지원되며 이 가이드에서 다룹니다.
 > 앱 라우터가 포함된 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)**를 제공합니다. 다국어 콘텐츠를 **실시간**으로 제공하여 번역가, 카피라이터, 기타 팀원과 원활하게 협업할 수 있습니다. 콘텐츠는 로컬 및/또는 원격으로 저장될 수 있습니다.
@@ -123,12 +128,9 @@ Intlayer는 단순한 i18n 솔루션 그 이상으로 관리에 도움이 되는
 </Accordion>
 </AccordionGroup>
 
----
-
 ## Next.js 애플리케이션에서 Intlayer 설정 단계별 가이드
 
 <Steps>
-
 <Step number={1} title="의존성 설치">
 
 npm을 사용하여 필요한 패키지를 설치하세요:
@@ -178,10 +180,16 @@ bun 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="프로젝트 구성">
 
-최종적으로 만들어질 구조는 다음과 같습니다:
+애플리케이션이 지역화된 URL 경로(예: `/ko/about`, `/en/about`)를 사용할지, 아니면 경로에 로케일 세그먼트 없이 콘텐츠를 제공할지(예: `/about`, 쿠키, 헤더 또는 쿼리 파라미터를 통해 감지) 선택하세요.
+
+<Tabs group="routing-mode">
+<Tab label="로케일 경로 있음" value="with-locale-path">
+
+### 아키텍처
+
+이 아키텍처에서는 지역화된 모든 페이지가 `[locale]` 동적 라우트 세그먼트 아래에 중첩됩니다. 각 언어마다 고유한 전용 URL이 제공되므로 SEO 및 정적 렌더링에 권장됩니다:
 
 ```bash
 .
@@ -207,9 +215,9 @@ bun add intlayer next-intlayer
 └── tsconfig.json
 ```
 
-> 로케일 라우팅을 원하지 않는 경우, intlayer를 단순한 프로바이더 / 훅으로 사용할 수 있습니다. 자세한 내용은 [이 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_nextjs_no_locale_path.md)를 참조하세요.
+### 설정
 
-애플리케이션의 언어를 구성하기 위해 설정 파일을 만드세요:
+애플리케이션에서 지원하는 언어를 선언하기 위해 `intlayer.config.ts` 설정 파일을 생성합니다:
 
 ```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { Locales, type IntlayerConfig } from "intlayer";
@@ -224,15 +232,76 @@ const config: IntlayerConfig = {
     ],
     defaultLocale: Locales.ENGLISH,
   },
+  routing: {
+    mode: "prefix-no-default", // 또는 `prefix-all`
+  },
 };
 
 export default config;
 ```
 
+</Tab>
+<Tab label="로케일 경로 없음" value="without-locale-path">
+
+### 아키텍처
+
+이 아키텍처에서는 라우트의 URL 경로에 `[locale]` 동적 세그먼트가 포함되지 않습니다. 모든 페이지는 `src/app/` 바로 아래에 위치하며 쿠키, 헤더 또는 쿼리 매개변수를 통해 로케일이 결정됩니다. 대시보드, 사내 도구 또는 인증된 앱에 적합합니다:
+
+```bash
+.
+├── src
+│   ├── app
+│   │   ├── layout.tsx
+│   │   ├── page.content.ts
+│   │   └── page.tsx
+│   ├── components
+│   │   ├── clientComponentExample
+│   │   │   ├── client-component-example.content.ts
+│   │   │   └── ClientComponentExample.tsx
+│   │   ├── localeSwitcher
+│   │   │   ├── localeSwitcher.content.ts
+│   │   │   └── LocaleSwitcher.tsx
+│   │   └── serverComponentExample
+│   │       ├── server-component-example.content.ts
+│   │       └── ServerComponentExample.tsx
+│   └── proxy.ts
+├── intlayer.config.ts
+├── next.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+### 설정
+
+경로 접두사 없이 콘텐츠를 제공하려면 `routing.mode` 속성을 `"search-params"`(예: `/about?locale=ko`) 또는 `"no-prefix"`로 설정하세요:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // 다른 로케일들
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+  routing: {
+    mode: "search-params", // 또는 `no-prefix` - 미들웨어 감지에 유용함
+  },
+};
+
+export default config;
+```
+
+</Tab>
+</Tabs>
+
 > 이 구성 파일을 통해 지역화된 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와 함께 사용하도록 구성합니다:
@@ -275,9 +344,11 @@ export default withIntlayer(nextConfig);
 > ```
 
 </Step>
-
 <Step number={4} title="동적 로케일 경로 정의">
 
+<Tabs group="routing-mode">
+<Tab label="로케일 경로 있음" value="with-locale-path">
+
 `RootLayout`의 모든 내용을 제거하고 다음 코드로 교체하세요:
 
 ```tsx {3} fileName="src/app/layout.tsx" codeFormat={["typescript", "esm"]}
@@ -372,8 +443,102 @@ export default LocaleLayout;
 
 > Intlayer는 `export const dynamic = 'force-static';`와 함께 작동하여 모든 로케일에 대해 페이지가 사전 빌드되도록 보장합니다.
 
-</Step>
+</Tab>
+<Tab label="로케일 경로 없음" value="without-locale-path">
+
+로케일 경로가 없는 아키텍처에서는 `[locale]` 디렉터리가 없습니다. 요청 컨텍스트에서 로케일을 읽고 애플리케이션을 `IntlayerProvider`로 래핑하도록 `src/app/layout.tsx`를 직접 구성하세요:
+
+<Tabs>
+ <Tab label='Intlayer >=9.4' value='>=9.4'>
+
+```tsx {5} fileName="src/app/layout.tsx" codeFormat={["typescript", "esm"]}
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+import "./globals.css";
+import { getHTMLTextDir, getIntlayer } from "intlayer";
+import { getLocale, IntlayerProvider } from "next-intlayer/server";
+export { generateStaticParams } from "next-intlayer";
+
+export const generateMetadata = async (): Promise<Metadata> => {
+  const locale = await getLocale();
+  const { title, description, keywords } = getIntlayer("metadata", locale);
+
+  return {
+    title,
+    description,
+    keywords,
+  };
+};
+
+const RootLayout = async ({
+  children,
+}: Readonly<{
+  children: ReactNode;
+}>) => {
+  const locale = await getLocale();
+
+  return (
+    <html lang={locale} dir={getHTMLTextDir(locale)}>
+      <body>
+        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
+      </body>
+    </html>
+  );
+};
+
+export default RootLayout;
+```
+
+> 단일 `IntlayerProvider`는 트리의 두 부분을 모두 커버합니다: 서버 훅에서 읽는 request-scoped 서버 컨텍스트를 제공하고, 클라이언트 컴포넌트가 동일한 로케일을 받도록 클라이언트 provider를 마운트합니다.
+
+RootLayout에서 모든 내용을 제거하고 다음 코드로 교체하세요:
+
+```tsx {3} fileName="src/app/layout.tsx" codeFormat={["typescript", "esm"]}
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+import "./globals.css";
+import { IntlayerProvider, LocalPromiseParams } from "next-intlayer";
+import { getHTMLTextDir, getIntlayer } from "intlayer";
+import { getLocale } from "next-intlayer/server";
+export { generateStaticParams } from "next-intlayer";
+
+export const generateMetadata = async (): Promise<Metadata> => {
+  const locale = await getLocale();
+  const { title, description, keywords } = getIntlayer("metadata", locale);
+
+  return {
+    title,
+    description,
+    keywords,
+  };
+};
+
+const RootLayout = async ({
+  children,
+}: Readonly<{
+  children: ReactNode;
+}>) => {
+  const locale = await getLocale();
+
+  return (
+    <html lang={locale} dir={getHTMLTextDir(locale)}>
+      <body>
+        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
+      </body>
+    </html>
+  );
+};
 
+export default RootLayout;
+```
+
+ </Tab>
+</Tabs>
+
+</Tab>
+</Tabs>
+
+</Step>
 <Step number={5} title="콘텐츠 선언하기">
 
 번역을 저장하기 위해 콘텐츠 선언을 생성하고 관리하세요:
@@ -421,7 +586,6 @@ export default pageContent;
 > 자세한 내용은 [콘텐츠 선언 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/content_file.md)를 참조하세요.
 
 </Step>
-
 <Step number={6} title="코드에서 콘텐츠 활용하기">
 
 애플리케이션 전반에서 콘텐츠 사전을 접근하세요:
@@ -569,10 +733,10 @@ export 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)를 참조하세요.
@@ -580,7 +744,6 @@ export const ServerComponentExample: FC = () => {
 > 기존 앱이 있다면, [Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compiler.md)와 [extract 명령어](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/extract.md)를 사용하여 수천 개의 컴포넌트를 몇 초 만에 변환할 수 있습니다.
 
 </Step>
-
 <Step number={7} title="로케일 감지를 위한 프록시 구성" isOptional={true}>
 
 사용자의 선호 로케일을 감지하기 위해 프록시를 설정합니다:
@@ -608,7 +771,6 @@ export const proxy = multipleProxies([intlayerProxy, customProxy]);
 ```
 
 </Step>
-
 <Step number={8} title="메타데이터의 국제화" isOptional={true}>
 
 페이지 제목과 같은 메타데이터를 국제화하려는 경우, Next.js에서 제공하는 `generateMetadata` 함수를 사용할 수 있습니다. 내부에서 `getIntlayer` 함수로부터 콘텐츠를 가져와 메타데이터를 번역할 수 있습니다.
@@ -711,7 +873,6 @@ export const generateMetadata = async ({
 > 메타데이터 최적화에 대해 더 알아보기 [공식 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을 생성할 수 있게 해줍니다.
@@ -776,7 +937,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` 컴포넌트는 페이지의 사전 로딩(prefetching)을 가능하게 하여 전체 페이지 새로고침을 방지하는 데 도움이 됩니다.
@@ -865,7 +1025,6 @@ return (
 > - [`aria-current` attribute](https://developer.mozilla.org/ko/docs/Web/Accessibility/ARIA/Attributes/aria-current)
 
 </Step>
-
 <Step number={11} title="지역화된 링크 컴포넌트 생성하기" isOptional={true}>
 
 애플리케이션의 내비게이션이 현재 로케일을 준수하도록 하려면, 커스텀 `Link` 컴포넌트를 만들 수 있습니다. 이 컴포넌트는 내부 URL에 현재 언어를 자동으로 접두사로 붙여줍니다. 예를 들어, 프랑스어 사용자가 "About" 페이지로 가는 링크를 클릭하면 `/about` 대신 `/fr/about`로 리디렉션됩니다.
@@ -935,7 +1094,6 @@ export const Link: FC<PropsWithChildren<NextLinkProps>> = ({
 이 `Link` 컴포넌트를 애플리케이션 전반에 통합함으로써, 일관성 있고 언어를 인식하는 사용자 경험을 유지하는 동시에 향상된 SEO 및 사용성 이점을 누릴 수 있습니다.
 
 </Step>
-
 <Step number={12} title="Server Actions에서 현재 로케일 가져오기" isOptional={true}>
 
 Server Action 내부에서 활성 로케일이 필요한 경우(예: 이메일 현지화 또는 로케일 인식 로직 실행), `next-intlayer/server`에서 `getLocale`을 호출하십시오:
@@ -962,7 +1120,6 @@ export const myServerAction = async () => {
 > 이는 사용 가능한 컨텍스트를 기반으로 가장 적절한 로케일이 선택되도록 합니다.
 
 </Step>
-
 <Step number={13} title="번들 크기 최적화" isOptional={true}>
 
 `next-intlayer`를 사용할 때, 사전(dictionary)은 기본적으로 모든 페이지의 번들에 포함됩니다. 번들 크기를 최적화하기 위해 Intlayer는 매크로를 사용하여 `useIntlayer` 호출을 지능적으로 대체하는 선택적 SWC 플러그인을 제공합니다. 이를 통해 사전은 실제로 사용하는 페이지의 번들에만 포함됩니다.
@@ -992,7 +1149,6 @@ bun add @intlayer/swc --dev
 > 참고: `dictionary` 설정에서 옵션을 `importMode: 'dynamic'` 또는 `importMode: 'fetch'`로 설정하면 Suspense에 의존하게 되므로, `useIntlayer` 호출을 `Suspense` 경계로 감싸야 합니다. 즉, Page / Layout 컴포넌트의 최상위 레벨에서 `useIntlayer`를 직접 사용할 수 없습니다.
 
 </Step>
-
 <Step number={14} title="컴포넌트 콘텐츠 추출" isOptional={true}>
 
 기존 코드베이스가 있는 경우 수천 개의 파일을 변환하는 데 시간이 많이 걸릴 수 있습니다.
@@ -1056,8 +1212,6 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 컴파일러'>
 
-> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
-
 ```bash packageManager="npm"
 npm install @intlayer/babel --save-dev
 ```
@@ -1113,6 +1267,14 @@ bun run build # Or bun run dev
 
 ### Turbopack에서 사전 변경 사항 감시
 
+<Tabs>
+ <Tab label='Intlayer >=9.5' value='intlayer>=9.5'>
+
+Intlayer v9.5부터 `withIntlayer`가 content watcher를 자체적으로 시작하므로 추가 설정이 필요하지 않습니다.
+
+ </Tab>
+ <Tab label='Intlayer <9.5' value='intlayer<9.5'>
+
 `next dev --turbopack` 명령을 사용하여 개발 서버로 Turbopack을 사용할 때, 기본적으로 사전 변경 사항이 자동으로 감지되지 않습니다.
 
 이 제한은 Turbopack이 콘텐츠 파일의 변경 사항을 모니터링하기 위해 webpack 플러그인을 병렬로 실행할 수 없기 때문에 발생합니다. 이 문제를 해결하려면 `intlayer watch` 명령을 사용하여 개발 서버와 Intlayer 빌드 감시자를 동시에 실행해야 합니다.
@@ -1129,6 +1291,8 @@ bun run build # Or bun run dev
 
 > next-intlayer@<=6.x.x를 사용하는 경우, Next.js 16 애플리케이션이 Turbopack에서 올바르게 작동하도록 `--turbopack` 플래그를 유지해야 합니다. 이 제한을 피하기 위해 next-intlayer@>=7.x.x를 사용하는 것을 권장합니다.
 
+ </Tab>
+</Tabs>
 ### TypeScript 구성
 
 Intlayer는 모듈 증강(module augmentation)을 사용하여 TypeScript의 이점을 활용하고 코드베이스를 더욱 견고하게 만듭니다.
@@ -1194,25 +1358,21 @@ Next.js는 `next.config.js`의 `i18n` 필드가 App Router에 더 이상 적용
 실제적인 차이는 브라우저에 도달하는 데이터입니다. 네임스페이스 기반 라이브러리는 페이지에 전체 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만 검토하면 됩니다. 이 가이드의 14단계를 확인하세요.
@@ -1222,7 +1382,6 @@ Next.js는 `next.config.js`의 `i18n` 필드가 App Router에 더 이상 적용
 컴파일러를 켜기 전에 알아두어야 할 두 가지 제한 사항이 있습니다. 정적 분석으로 작동하므로 API 오류 코드나 CMS 필드와 같이 런타임에만 존재하는 문자열은 처리할 수 없습니다. 또한 큰 코드베이스에서 몇 가지 어노테이션이 필요한 `className="active"` 또는 상태 코드와 같은 애플리케이션 로직과 사용자 대면 텍스트를 구분해야 합니다. [extract 명령](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/extract.md)은 사용자가 직접 제어할 수 있도록 하여 두 가지 문제를 모두 방지합니다.
 
 </Question>
-
 <Question title="사용 가능한 에디터 및 AI 에이전트 도구는 무엇이 있나요?">
 
 5가지 도구가 모두 선택 사항으로 제공됩니다:
@@ -1234,19 +1393,16 @@ Next.js는 `next.config.js`의 `i18n` 필드가 App Router에 더 이상 적용
 - **[ESLint 플러그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/eslint.md)**: `no-raw-text` 규칙으로 하드코딩된 문자열을 표시하고, 정적 사전 키 및 사용되지 않는 콘텐츠에 대한 추가 규칙을 제공합니다.
 
 </Question>
-
 <Question title="Intlayer는 Next.js App Router 및 React Server Components와 호환되나요?">
 
 네. `next-intlayer`는 App Router 전용으로 설계되었습니다: Server Components 내부의 서버에서 콘텐츠가 직접 확인되므로 서버 렌더링된 텍스트에 대해 클라이언트로 사전이 전송되지 않습니다. Client Components는 프로바이더를 통해 동일한 `useIntlayer` 훅을 사용합니다. Intlayer는 정적 렌더링을 차단하지 않으며 Turbopack과 완벽히 호환됩니다.
 
 </Question>
-
 <Question title="Intlayer는 어떤 Next.js 버전을 지원하나요?">
 
 Intlayer는 Next.js 12, 13, 14, 15 및 16을 지원합니다. 본 가이드는 Next.js 16을 다룹니다. 이전 설정의 경우 [Next.js 15 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_nextjs_15.md), [Next.js 14 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_nextjs_14.md) 또는 [Pages Router 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_nextjs_page_router.md)를 따르세요.
 
 </Question>
-
 <Question title="/fr/about처럼 URL에 로케일을 반드시 포함해야 하나요?">
 
 아닙니다. URL 체계는 설정 옵션일 뿐 제약 사항이 아닙니다. `routing.mode`는 다음을 지원합니다:
@@ -1256,40 +1412,34 @@ Intlayer는 Next.js 12, 13, 14, 15 및 16을 지원합니다. 본 가이드는 N
 - `"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)를 참조하세요.
+또한 `routing.domains`를 사용하여 각 로케일을 자체 도메인에 매핑할 수도 있습니다. [설정 참조](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md) 및 라우팅 모드 옵션에 대한 [2단계](#step-2-configure-your-project)를 참조하세요..
 
 </Question>
-
 <Question title="SEO를 위한 hreflang 태그 및 현지화된 메타데이터는 어떻게 추가하나요?">
 
 Next.js의 `generateMetadata` 함수를 Intlayer의 `getMultilingualUrls`와 함께 사용하세요. `x-default` 항목을 포함하여 선언된 모든 로케일에 대해 `alternates.languages` 맵을 구축하므로 검색 엔진이 올바른 언어 버전을 제공할 수 있습니다. 동일한 헬퍼를 통해 `sitemap.ts`와 `robots.ts`도 현지화할 수 있습니다. 본 가이드의 8단계와 9단계에서 전체 코드를 확인할 수 있습니다.
 
 </Question>
-
 <Question title="AI를 사용하여 Next.js 앱을 자동으로 번역하려면 어떻게 하나요?">
 
 `npx intlayer fill`을 실행하세요. CLI가 콘텐츠 파일 전반의 누락된 번역을 감지하고 자체 제공업체 및 API 키를 사용하여 원하는 LLM으로 채워주므로, 제공업체에 직접 비용을 지불하고 제3자를 거치지 않습니다. [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)는 콘텐츠를 외부화하여 배포 없이도 업데이트할 수 있게 하며, [라이브 동기화](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/live.md)를 통해 런타임에 변경 사항을 즉시 반영합니다.
 
 </Question>
-
 <Question title="배포 전에 누락된 번역을 어떻게 감지하나요?">
 
 CI에서 `npx intlayer test`를 실행하세요. 선언된 로케일에 콘텐츠가 누락된 경우 빌드를 실패시켜 번역되지 않은 문자열이 프로덕션에 배포되는 것을 방지합니다. [VS Code 확장 프로그램](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/vs_code_extension.md)은 코드를 작성하는 동안 동일한 오류를 화면에 표시하며, [ESLint 플러그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/eslint.md)과 `no-raw-text` 규칙은 하드코딩된 문자열을 감지합니다. [콘텐츠 테스트](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/testing.md)를 참조하세요.
 
 </Question>
-
 <Question title="Intlayer는 무료이며 오픈 소스인가요?">
 
 네. Intlayer는 Apache 2.0 라이선스에 따른 오픈 소스이며, 라이브러리 전체, CLI, 비주얼 에디터 및 컴파일러는 상업적 사용을 포함하여 무료로 사용할 수 있습니다. 호스팅형 CMS는 선택적 유료 서비스이며 [자체 호스팅](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/self_hosting.md)도 가능합니다.