@intlayer/docs 9.4.4 → 9.5.0

package/docs/ko/intlayer_with_vite+react_compiler.md

@@ -1,637 +0,0 @@
----
-createdAt: 2024-03-07
-updatedAt: 2026-08-30
-title: "Vite + React i18n - 앱을 번역하는 완전 가이드"
-description: "i18next는 이제 그만. 2026년 다국어 (i18n) Vite + React 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
-keywords:
-  - 국제화
-  - 문서
-  - Intlayer
-  - Vite
-  - React
-  - 컴파일러
-  - AI
-slugs:
-  - doc
-  - environment
-  - vite-and-react
-  - compiler
-applicationTemplate: https://github.com/aymericzip/intlayer-vite-react-template
-applicationShowcase: https://intlayer-vite-react-template.vercel.app
-youtubeVideo: https://www.youtube.com/watch?v=dS9L7uJeak4
-history:
-  - version: 8.9.0
-    date: 2026-05-04
-    changes: "Solid useIntlayer API 사용법을 직접 속성 액세스로 업데이트"
-  - version: 8.2.0
-    date: 2026-03-09
-    changes: "Update compiler options, add FilePathPattern support"
-  - version: 8.1.6
-    date: 2026-02-23
-    changes: "초기 릴리스"
-author: aymericzip
----
-
-# 기존 Vite 및 React 애플리케이션을 나중에 다국어(i18n)로 만드는 방법 (i18n 가이드 2026)
-
-<Tabs defaultTab="video">
-  <Tab label="비디오" value="video">
-
-<iframe title="Vite와 React를 위한 최고의 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/dS9L7uJeak4?si=VaKmrYMmXjo3xpk2"/>
-
-  </Tab>
-  <Tab label="코드" value="code">
-
-<iframe
-  src="https://ide.intlayer.org/aymericzip/intlayer-vite-react-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-vite-react-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-vite-react-template"
-  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
-  loading="lazy"
-/>
-
-  </Tab>
-</Tabs>
-
-GitHub에서 [애플리케이션 템플릿](https://github.com/aymericzip/intlayer-vite-react-template)을 확인하세요.
-
-## 목차
-
-<TOC/>
-
-## 왜 기존 애플리케이션을 국제화하는 것이 어려울까요?
-
-단 하나의 언어만 고려하여 빌드된 앱에 여러 언어를 추가하려고 시도해 본 적이 있다면 그 고통을 아실 것입니다. 단순히 "어려운" 것이 아니라 지루합니다. 모든 파일을 샅샅이 뒤져 모든 텍스트 문자열을 찾아내고 이를 별도의 사전 파일로 옮겨야 합니다.
-
-그다음 위험한 단계가 옵니다. 레이아웃이나 로직을 깨뜨리지 않고 모든 텍스트를 코드 훅으로 교체하는 것입니다. 이는 몇 주 동안 새로운 기능 개발을 중단시키고 끝없는 리팩토링처럼 느껴지는 작업입니다.
-
-## Intlayer 컴파일러란 무엇인가요?
-
-**Intlayer 컴파일러**는 이러한 수동 작업을 건너뛰기 위해 만들어졌습니다. 사용자가 직접 문자열을 추출하는 대신 컴파일러가 대신 해줍니다. 코드를 스캔하고 텍스트를 찾아 AI를 사용하여 백그라운드에서 사전을 생성합니다.
-그런 다음 빌드 중에 코드를 수정하여 필요한 i18n 훅을 주입합니다. 기본적으로 앱을 단일 언어인 것처럼 계속 작성하면 컴파일러가 다국어 변환을 자동으로 처리합니다.
-
-> 컴파일러 문서: [https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compiler.md](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compiler.md)
-
-### 제한 사항
-
-컴파일러는 **컴파일 타임**에 코드 분석 및 변환(훅 삽입 및 사전 생성)을 수행하므로 애플리케이션의 **빌드 프로세스가 느려질 수 있습니다**.
-
-개발 중 이러한 영향을 완화하기 위해 컴파일러를 [`'build-only'`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md) 모드로 실행하도록 구성하거나 필요하지 않을 때 비활성화할 수 있습니다.
-
----
-
-## Vite 및 React 애플리케이션에서 Intlayer를 설정하기 위한 단계별 가이드
-
-<Steps>
-
-<Step number={1} title="종속성 설치">
-
-npm을 사용하여 필요한 패키지를 설치합니다:
-
-```bash packageManager="npm"
-npx intlayer init --interactive
-```
-
-```bash packageManager="pnpm"
-pnpm dlx intlayer init --interactive
-```
-
-```bash packageManager="yarn"
-yarn dlx intlayer init --interactive
-```
-
-```bash packageManager="bun"
-bunx intlayer init --interactive
-```
-
-> `--interactive` 플래그는 선택 사항입니다. AI 에이전트인 경우 `intlayer-cli init`를 사용하세요.
-
-> 이 명령은 환경을 감지하고 필요한 패키지를 설치합니다. 예를 들어:
-
-```bash packageManager="npm"
-npm install intlayer react-intlayer
-npm install vite-intlayer --save-dev
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer react-intlayer
-pnpm add vite-intlayer --save-dev
-```
-
-```bash packageManager="yarn"
-yarn add intlayer react-intlayer
-yarn add vite-intlayer --save-dev
-```
-
-```bash packageManager="bun"
-bun add intlayer react-intlayer
-bun add vite-intlayer --dev
-```
-
-- **intlayer**
-  구성 관리, 번역, [콘텐츠 선언](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/content_file.md), 트랜스파일 및 [CLI 명령](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/index.md)을 위한 국제화 도구를 제공하는 핵심 패키지입니다.
-
-- **react-intlayer**
-  Intlayer를 React 애플리케이션과 통합하는 패키지입니다. React 국제화를 위한 컨텍스트 프로바이더와 훅을 제공합니다.
-
-- **vite-intlayer**
-  Intlayer를 [Vite 번들러](https://vite.dev/guide/why.html#why-bundle-for-production)와 통합하기 위한 Vite 플러그인과 사용자의 선호 로케일 감지, 쿠키 관리 및 URL 리디렉션 처리를 위한 미들웨어를 포함합니다.
-
-</Step>
-
-<Step number={2} title="프로젝트 구성">
-
-애플리케이션의 언어를 구성하기 위한 설정 파일을 생성합니다:
-
-```typescript fileName="intlayer.config.ts"
-import { Locales, type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, Locales.KOREAN],
-    defaultLocale: Locales.ENGLISH,
-  },
-  compiler: {
-    /**
-     * 개발 중에 컴파일러를 건너뛰고 시작 시간을 단축하려면 'build-only'로 설정하십시오.
-     */
-    enabled: true,
-
-    /**
-     * 최적화된 사전의 출력 디렉터리.
-     */
-    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,
-
-    /**
-     * 키 없이 생성된 파일에 콘텐츠만 삽입합니다.
-     */
-    noMetadata: false,
-
-    /**
-     * 사전 키 접두사
-     */
-    dictionaryKeyPrefix: "", // Remove base prefix
-  },
-  ai: {
-    provider: "openai",
-    model: "gpt-5-mini",
-    apiKey: process.env.OPEN_AI_API_KEY,
-    applicationContext: "이 앱은 지도 앱입니다", // 참고: 앱 설명을 사용자 정의할 수 있습니다.
-  },
-};
-
-export default config;
-```
-
-> **참고**: 환경 변수에 `OPEN_AI_API_KEY`가 설정되어 있는지 확인하세요.
-
-> 이 구성 파일을 통해 로컬라이즈된 URL, 미들웨어 리디렉션, 쿠키 이름, 콘텐츠 선언의 위치 및 확장자 설정, 콘솔의 Intlayer 로그 비활성화 등을 설정할 수 있습니다. 사용 가능한 매개변수의 전체 목록은 [구성 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)를 참조하세요.
-
-</Step>
-
-<Step number={3} title="Vite 구성에 Intlayer 통합">
-
-구성 파일에 intlayer 플러그인을 추가합니다.
-
-```typescript fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react-swc";
-import { intlayer } from "vite-intlayer";
-
-// https://vitejs.dev/config/
-export default defineConfig({
-  plugins: [
-    react(),
-    intlayer({
-      proxy: {
-        ignore: (req) => req.url?.startsWith("/api"),
-      },
-    }),
-  ],
-});
-```
-
-> `intlayer()` Vite 플러그인은 Intlayer를 Vite와 통합하는 데 사용됩니다. 콘텐츠 선언 파일의 빌드를 보장하고 개발 모드에서 이를 모니터링합니다. Vite 애플리케이션 내에서 Intlayer 환경 변수를 정의합니다. 또한 성능 최적화를 위한 별칭(alias)을 제공합니다.
-
-> `intlayerCompiler()` Vite 플러그인은 컴포넌트에서 콘텐츠를 추출하고 `.content` 파일을 작성하는 데 사용됩니다.
-
-> Intlayer v9부터 컴파일러는 `intlayer()` 플러그인에 직접 번들되어 있으며, `compiler.enabled`이 `compiler.output` 경로로 설정되면 자동으로 활성화됩니다. 아래와 같이 `intlayerCompiler()`를 별도로 등록하는 것은 이제 선택 사항입니다. 추가되면 자동으로 중복 제거됩니다. [v9 릴리스 노트](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/releases/v9.md)를 참조하세요.
-
-</Step>
-
-<Step number={4} title="코드 컴파일">
-
-기본 로케일로 하드코딩된 문자열을 사용하여 컴포넌트를 작성하기만 하면 됩니다. 나머지는 컴파일러가 처리합니다.
-
-페이지의 예시는 다음과 같습니다:
-
-```tsx fileName="src/App.tsx"
-import { useState, type FC } from "react";
-import reactLogo from "./assets/react.svg";
-import viteLogo from "/vite.svg";
-import "./App.css";
-import { IntlayerProvider } from "react-intlayer";
-
-const AppContent: FC = () => {
-  const [count, setCount] = useState(0);
-
-  return (
-    <>
-      <div>
-        <a href="https://vitejs.dev" target="_blank">
-          <img src={viteLogo} className="logo" alt="Vite logo" />
-        </a>
-        <a href="https://react.dev" target="_blank">
-          <img src={reactLogo} className="logo react" alt="React logo" />
-        </a>
-      </div>
-      <h1>Vite + React</h1>
-      <div className="card">
-        <button onClick={() => setCount((count) => count + 1)}>
-          count is {count}
-        </button>
-        <p>
-          Edit <code>src/App.tsx</code> and save to test HMR
-        </p>
-      </div>
-      <p className="read-the-docs">
-        Click on the Vite and React logos to learn more
-      </p>
-    </>
-  );
-};
-
-const App: FC = () => (
-  <IntlayerProvider>
-    <AppContent />
-  </IntlayerProvider>
-);
-
-export default App;
-```
-
-```ts fileName="i18n/app-content.content.json"
-{
-  key: "app-content",
-  content: {
-    nodeType: "translation",
-    translation: {
-      en: {
-        viteLogo: "Vite logo",
-        reactLogo: "React logo",
-        title: "Vite + React",
-        countButton: "count is",
-        editMessage: "Edit",
-        hmrMessage: "and save to test HMR",
-        readTheDocs: "Click on the Vite and React logos to learn more",
-      },
-      ko: {
-        viteLogo: "Vite 로고",
-        reactLogo: "React 로고",
-        title: "Vite + React",
-        countButton: "현재 카운트:",
-        editMessage: "수정",
-        hmrMessage: "후 저장하여 HMR을 테스트하세요",
-        readTheDocs: "자세한 내용은 Vite 및 React 로고를 클릭하세요",
-      },
-    }
-  }
-}
-```
-
-```tsx fileName="src/App.tsx"
-import { useState, type FC } from "react";
-import reactLogo from "./assets/react.svg";
-import viteLogo from "/vite.svg";
-import "./App.css";
-import { IntlayerProvider, useIntlayer } from "react-intlayer";
-
-const AppContent: FC = () => {
-  const [count, setCount] = useState(0);
-  const content = useIntlayer("app-content");
-
-  return (
-    <>
-      <div>
-        <a href="https://vitejs.dev" target="_blank">
-          <img src={viteLogo} className="logo" alt={content.viteLogo.value} />
-        </a>
-        <a href="https://react.dev" target="_blank">
-          <img
-            src={reactLogo}
-            className="logo react"
-            alt={content.reactLogo.value}
-          />
-        </a>
-      </div>
-      <h1>{content.title}</h1>
-      <div className="card">
-        <button onClick={() => setCount((count) => count + 1)}>
-          {content.countButton} {count}
-        </button>
-        <p>
-          {content.editMessage} <code>src/App.tsx</code> {content.hmrMessage}
-        </p>
-      </div>
-      <p className="read-the-docs">{content.readTheDocs}</p>
-    </>
-  );
-};
-
-const App: FC = () => (
-  <IntlayerProvider>
-    <AppContent />
-  </IntlayerProvider>
-);
-
-export default App;
-```
-
-- **`IntlayerProvider`**는 중첩된 컴포넌트에 로케일을 제공하는 데 사용됩니다.
-
-</Step>
-
-<Step number={6} title="콘텐츠 언어 변경" isOptional={true}>
-
-콘텐츠 언어를 변경하려면 `useLocale` 훅에서 제공하는 `setLocale` 함수를 사용할 수 있습니다. 이 함수를 사용하면 애플리케이션의 로케일을 설정하고 그에 따라 콘텐츠를 업데이트할 수 있습니다.
-
-```tsx fileName="src/components/LocaleSwitcher.tsx"
-import type { FC } from "react";
-import { Locales } from "intlayer";
-import { useLocale } from "react-intlayer";
-
-const LocaleSwitcher: FC = () => {
-  const { setLocale } = useLocale();
-
-  return (
-    <button onClick={() => setLocale(Locales.KOREAN)}>
-      언어를 한국어로 변경
-    </button>
-  );
-};
-```
-
-> `useLocale` 훅에 대해 자세히 알아보려면 [문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/react-intlayer/useLocale.md)를 참조하세요.
-
-</Step>
-
-<Step number={7} title="누락된 번역 채우기" isOptional={true}>
-
-Intlayer는 누락된 번역을 채울 수 있도록 돕는 CLI 도구를 제공합니다. `intlayer` 명령어를 사용하여 코드에서 누락된 번역을 테스트하고 채울 수 있습니다.
-
-```bash packageManager="npm"
-npx intlayer test         # 누락된 번역이 있는지 테스트
-```
-
-```bash packageManager="yarn"
-yarn intlayer test         # 누락된 번역이 있는지 테스트
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer test         # 누락된 번역이 있는지 테스트
-```
-
-```bash packageManager="bun"
-bun x intlayer test         # 누락된 번역이 있는지 테스트
-```
-
-```bash packageManager="npm"
-npx intlayer fill         # 누락된 번역 채우기
-```
-
-```bash packageManager="yarn"
-yarn intlayer fill         # 누락된 번역 채우기
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer fill         # 누락된 번역 채우기
-```
-
-```bash packageManager="bun"
-bun x intlayer fill         # 누락된 번역 채우기
-```
-
-> 자세한 내용은 [CLI 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/ci.md)를 참조하세요.
-
-</Step>
-
-</Steps>
-
-### (선택) 사이트맵과 robots.txt(빌드 시 생성)
-
-Intlayer는 `generateSitemap`과 `getMultilingualUrls`로 크롤러용 다국어 `sitemap.xml`과 `robots.txt`를 만들어 `public/`에 자동으로 쓸 수 있습니다. 보통 Vite 실행 **전에** 작은 Node 스크립트를 돌립니다(예: npm `predev` / `prebuild`).
-
-#### 사이트맵
-
-Intlayer 사이트맵 생성기는 로케일 설정을 반영하고 크롤러용 메타데이터를 포함합니다.
-
-> 생성된 사이트맵은 `xhtml:link`(hreflang)를 지원합니다. 단순 URL 나열이 아니라 각 페이지의 모든 언어 버전을 양방향으로 연결합니다(예: `/about`, `/fr/about`, `/about?lang=fr` - 라우팅 모드에 따름).
-
-#### Robots.txt
-
-`getMultilingualUrls`로 `Disallow`가 민감 경로의 모든 현지화 변형에 적용되도록 하세요.
-
-#### 1. 프로젝트 루트에 `generate-seo.mjs` 추가
-
-```javascript fileName="generate-seo.mjs"
-import fs from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
-import { generateSitemap, getMultilingualUrls } from "intlayer";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(
-  /\/$/,
-  ""
-);
-
-const pathList = [
-  { path: "/", changefreq: "daily", priority: 1.0 },
-  { path: "/about", changefreq: "monthly", priority: 0.7 },
-];
-
-const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });
-fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);
-
-const getAllMultilingualUrls = (urls) =>
-  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));
-
-const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);
-
-const robotsTxt = [
-  "User-agent: *",
-  "Allow: /",
-  ...disallowedPaths.map((path) => `Disallow: ${path}`),
-  "",
-  `Sitemap: ${SITE_URL}/sitemap.xml`,
-].join("\n");
-
-fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);
-
-console.log("SEO files generated successfully.");
-```
-
-스크립트가 `intlayer`를 import하려면 패키지가 설치되어 있어야 합니다. 프로덕션에서는 환경 변수 `SITE_URL`을 설정하세요(CI 등).
-
-> Node ESM에는 `generate-seo.mjs` 사용을 권장합니다. `generate-seo.js`를 쓰면 `package.json`의 `"type": "module"` 등으로 ESM을 켜세요.
-
-#### 2. Vite 전에 스크립트 실행
-
-```json fileName="package.json"
-{
-  "scripts": {
-    "dev": "vite",
-    "prebuild": "node generate-seo.mjs",
-    "build": "vite build",
-    "preview": "vite preview"
-  }
-}
-```
-
-pnpm이나 yarn을 쓰면 명령을 맞게 바꾸세요. CI에서 호출해도 됩니다.
-
-### Git 구성
-
-Intlayer에서 생성된 파일은 무시하는 것이 좋습니다. 이렇게 하면 Git 저장소에 커밋되는 것을 방지할 수 있습니다.
-
-이를 위해 `.gitignore` 파일에 다음 지침을 추가할 수 있습니다:
-
-```plaintext fileName=".gitignore"
-# Intlayer에서 생성된 파일 무시
-.intlayer
-```
-
-### VS Code 확장 프로그램
-
-Intlayer 개발 경험을 향상시키기 위해 공식 **Intlayer VS Code 확장 프로그램**을 설치할 수 있습니다.
-
-[VS Code Marketplace에서 설치](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
-
-이 확장 프로그램은 다음을 제공합니다:
-
-- 번역 키에 대한 **자동 완성**.
-- 누락된 번역에 대한 **실시간 오류 감지**.
-- 번역된 콘텐츠의 **인라인 미리보기**.
-- 번역을 쉽게 생성하고 업데이트할 수 있는 **빠른 작업**.
-
-확장 프로그램 사용 방법에 대한 자세한 내용은 [Intlayer VS Code 확장 프로그램 문서](https://intlayer.org/doc/vs-code-extension)를 참조하세요.
-
-### 더 알아보기
-
-더 나아가 [비주얼 에디터](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)를 사용하여 콘텐츠를 외부화할 수 있습니다.
-
-## 자주 묻는 질문
-
-<FAQ>
-
-<Question title="Vite 및 React 앱을 국제화하는 데 사용할 수 있는 다양한 솔루션은 무엇인가요?">
-
-- **`react-i18next` / `i18next`**: 런타임에 JSON 네임스페이스를 로드하며, 모든 호출 위치에서 키를 수동으로 작성합니다.
-- **`react-intl`** 및 **`Lingui`**: 직접 실행해야 하는 추출 단계를 거치는 ICU 메시지 포맷 기반입니다.
-- **`Intlayer`**: 빌드 타임에 컴포넌트에서 직접 콘텐츠를 컴파일하여 추출하며, 완전한 타입 안전성을 제공하고 AI 번역, 비주얼 에디터 및 CMS를 지원합니다.
-
-본 가이드는 컴파일러 설정을 사용하므로 컴포넌트에 일반 문자열을 그대로 작성하면 사전이 자동으로 생성됩니다. [왜 Intlayer인가](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/interest_of_intlayer.md)와 [벤치마크](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/benchmark/index.md)를 참조하세요.
-
-</Question>
-
-<Question title="i18n이 Vite 번들 크기에 얼마나 영향을 미치나요?">
-
-네임스페이스 기반 설정보다 훨씬 적습니다. 페이지는 렌더링하지 않는 언어의 카탈로그를 절대 다운로드하지 않기 때문입니다. 빌드 타임 컴파일러는 `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/index.md)를 참조하세요.
-
-</Question>
-
-<Question title="컴포넌트를 다시 작성하지 않고 react-i18next나 react-intl에서 마이그레이션할 수 있나요?">
-
-네, 두 가지 방법이 있습니다. [react-i18next 마이그레이션 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/migration_from_react-i18next_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)는 `react-i18next`, `react-intl`, `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="콘텐츠를 키 단위로 하나씩 옮겨야 하나요?">
-
-아닙니다. 이것이 바로 이 가이드에서 구성한 내용입니다. 기본 로케일의 일반 문자열로 컴포넌트를 작성하기만 하면 [Intlayer 컴파일러](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compiler.md)가 빌드할 때마다 소스를 스캔하고 사용자 대면 텍스트를 추출하여 사전을 생성하므로 수동으로 키를 생성하거나 유지 관리할 필요가 없습니다.
-
-두 가지 제한 사항을 알아두면 좋습니다. 컴파일러는 정적 분석으로 작동하므로 API 오류 코드나 CMS 필드와 같이 런타임에만 존재하는 문자열은 감지할 수 없으므로 여전히 명시적인 사전 선언이 필요합니다. 또한 대규모 코드베이스에서는 `className="active"`나 상태 코드와 같은 애플리케이션 로직과 사용자 텍스트를 구분하기 위해 몇 가지 주석이 필요할 수 있습니다.
-
-수동으로 제어하기를 선호한다면 `npx intlayer extract`를 실행하여 원하는 파일에 대해 추출을 한 번 수행하고 각 컴포넌트 옆에 생성된 `.content` 파일의 diff를 검토할 수도 있습니다. [extract 명령](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/extract.md)을 참조하세요.
-
-</Question>
-
-<Question title="사용 가능한 에디터 및 AI 에이전트 도구는 무엇이 있나요?">
-
-5가지 도구가 모두 선택 사항으로 제공됩니다:
-
-- **[VS Code 확장 프로그램](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/vs_code_extension.md)**: `useIntlayer` 키에서 이를 선언한 콘텐츠 파일로 바로 이동하고, 컴포넌트에서 콘텐츠를 추출하며, 명령 팔레트나 전용 Intlayer 탭에서 build, fill, test, push, pull을 실행할 수 있습니다.
-- **[LSP 서버](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/lsp.md)**: LSP를 지원하는 모든 에디터에서 정의로 이동, 모든 참조 찾기, 번역 값 마우스 오버 미리보기, 키 및 필드 자동 완성, 선언되지 않은 키에 대한 경고 등 동일한 기능을 제공합니다. 또한 `i18next`, `react-i18next`, `next-intl`, `use-intl` 호출도 해석하므로 마이그레이션 시 유용합니다.
-- **[MCP 서버](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/mcp_server.md)**: Cursor, VS Code, Claude Desktop, Claude Code, ChatGPT에 Intlayer 문서와 CLI를 노출하여 AI 어시스턴트가 최신 문서를 기반으로 정확히 답변하고 `intlayer fill` 등의 명령을 직접 실행할 수 있게 합니다.
-- **[Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/agent_skills.md)**: `intlayer-config`, `intlayer-cli`, `intlayer-content` 및 각 프레임워크 전용 스킬을 통해 AI 에이전트에게 라우팅 설정과 콘텐츠 노드 타입을 학습시킵니다.
-- **[ESLint 플러그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/eslint.md)**: `no-raw-text` 규칙으로 하드코딩된 문자열을 표시하고, 정적 사전 키 및 사용되지 않는 콘텐츠에 대한 추가 규칙을 제공합니다.
-
-</Question>
-
-<Question title="컴파일러를 사용해야 할까요, 아니면 콘텐츠를 직접 선언해야 할까요?">
-
-기존 코드베이스에 최소한의 코드 변경으로 i18n을 도입하고 싶을 때는 컴파일러를 사용하세요: 컴포넌트는 그대로 두고 사전이 자동으로 생성됩니다. 키, 구조 및 컴포넌트 간 재사용을 명시적으로 제어하고 싶다면 [표준 Vite 및 React 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_with_vite+react.md)처럼 콘텐츠를 직접 선언하세요. 두 방식은 공존할 수 있습니다: 컴파일된 콘텐츠와 수동으로 선언된 콘텐츠는 동일한 사전 계층에 함께 존재합니다.
-
-</Question>
-
-<Question title="컴파일러가 감지할 수 없는 문자열은 어떻게 되나요?">
-
-컴파일러는 정적 분석으로 작동하므로 이러한 문자열은 번역되지 않은 상태로 유지됩니다. API 오류 메시지, CMS 필드 또는 문자열 연결로 런타임에 조립되는 모든 것은 일반적인 방식으로 콘텐츠 파일에 명시적으로 선언해야 합니다. 누락된 항목을 찾으려면 `npx intlayer test`를 실행하세요.
-
-</Question>
-
-<Question title="컴파일러는 사용자 대면 텍스트를 어떻게 판별하나요?">
-
-JSX에 대한 휴리스틱을 통해 판단하므로 양방향 모두에서 오류가 발생할 수 있습니다: `className` 값이나 상태 코드가 텍스트처럼 보일 수 있고, 특이한 패턴은 누락될 수 있습니다. 대규모 코드베이스에서는 주석을 통해 이러한 예외 사례를 보정합니다. 이러한 트레이드오프가 맞지 않는다면 `npx intlayer extract`를 통해 1회성 추출을 실행하고 diff를 직접 검토할 수 있습니다. [extract 명령](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/extract.md)을 참조하세요.
-
-</Question>
-
-<Question title="누락된 번역은 어떻게 채우나요?">
-
-7단계에서 다룹니다. `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="런타임에 언어를 어떻게 변경하나요?">
-
-6단계에서 다룹니다. `useLocale`은 활성 로케일, 선언된 로케일 목록 및 선택 사항을 유지하는 setter를 노출하며, 컴파일된 콘텐츠를 읽는 컴포넌트는 페이지 새로고침 없이 새 언어로 다시 렌더링됩니다.
-
-</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)도 가능합니다.
-
-</Question>
-
-</FAQ>