@intlayer/docs 9.4.1 → 9.4.3

package/docs/ko/how_works_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-12
-updatedAt: 2025-06-29
+updatedAt: 2026-08-30
 title: Intlayer 작동 방식
 description: Intlayer가 내부적으로 어떻게 작동하는지 알아보세요. Intlayer를 강력하게 만드는 아키텍처와 구성 요소를 이해하십시오.
 keywords:
@@ -259,3 +259,95 @@ Express를 기반으로 한 서버는 시각적 편집기 요청을 수신하고
 ## 스마트 문서와 채팅하기
 
 - [스마트 문서에 질문하기](https://intlayer.org/doc/chat)
+
+## 자주 묻는 질문
+
+<FAQ>
+
+<Question title="사전은 빌드 타임에 빌드되나요, 아니면 런타임에 빌드되나요?">
+
+빌드 타임에 빌드됩니다. 번들러 플러그인 또는 `npx intlayer build`가 `.content.ts` 파일을 스캔하여 `.intlayer` 폴더에 사전으로 컴파일하고 해당하는 TypeScript 타입을 생성합니다. 런타임 시 컴포넌트는 결과물만 읽으므로 요청 경로에서 파싱이나 파일 로딩이 전혀 발생하지 않습니다.
+
+</Question>
+
+<Question title="i18n이 번들 크기에 얼마나 영향을 미치나요?">
+
+네임스페이스 기반 설정보다 훨씬 적습니다. 페이지는 렌더링하지 않는 언어의 카탈로그를 절대 다운로드하지 않기 때문입니다. 서버 렌더링 마크업은 서버에서 콘텐츠를 확인하고, 빌드 타임 컴파일러는 `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="컴포넌트를 다시 작성하지 않고 i18next, next-intl 또는 react-i18next에서 마이그레이션할 수 있나요?">
+
+네, 두 가지 방법이 있습니다. [i18next 마이그레이션 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/migration_from_i18next_to_intlayer.md) 또는 [next-intl 마이그레이션 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/migration_from_next-intl_to_intlayer.md)를 따라 점진적으로 이전할 수 있습니다. 또는 현재 API를 완전히 유지할 수도 있습니다: [호환 어댑터(compat adapters)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compat/index.md)는 `i18next`, `react-i18next`, `next-intl`, `next-i18next`, `react-intl`, `use-intl`, `vue-i18n` 및 `Lingui`와 완전히 동일한 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)을 참조하세요.
+
+완전 자동화된 파이프라인을 위해 [Intlayer 컴파일러](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compiler.md)는 빌드 타임에 JSX, TSX, Vue 및 Svelte 소스에서 동일한 작업을 수행하여 변경될 때마다 사전을 생성하고 HMR을 통해 동기화하므로 수동으로 키를 관리할 필요가 없습니다. 정적 분석으로 작동하므로 런타임에만 존재하는 문자열은 제외되며, 사용자 텍스트와 애플리케이션 로직을 구분하기 위해 몇 가지 주석이 필요합니다.
+
+</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=".intlayer 폴더는 무엇이며 Git에 커밋해야 하나요?">
+
+컴파일된 사전과 생성된 타입이 포함된 생성 출력 디렉토리입니다. 콘텐츠 파일로부터 유도되므로 `dist` 폴더와 마찬가지로 `.gitignore`에 등록하고 빌드 단계에서 다시 생성해야 합니다.
+
+</Question>
+
+<Question title="활성 로케일은 어떻게 결정되나요?">
+
+`routing.storage`에 나열된 순서대로 소스를 읽어 결정됩니다: `routing.mode`에서 접두사를 사용하는 경우의 URL 접두사, 쿠키, `Accept-Language` 헤더, 기본 로케일 순입니다. 사용자가 명시적으로 선택한 로케일은 저장되어 다음 방문 시에도 유지됩니다. [설정 참조](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)를 참조하세요.
+
+</Question>
+
+<Question title="로컬 사전과 원격 사전의 차이점은 무엇인가요?">
+
+로컬 사전은 코드베이스에 선언되어 애플리케이션과 함께 컴파일됩니다. 원격 사전은 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_CMS.md)에서 관리되고 런타임에 확인되므로 배포 없이도 변경될 수 있습니다. 둘 다 동일한 훅을 통해 읽히며, 원격 콘텐츠를 사용할 수 없는 경우 로컬 선언으로 원활하게 폴백됩니다.
+
+</Question>
+
+<Question title="Intlayer는 TypeScript 없이도 작동하나요?">
+
+네. 콘텐츠 파일은 TypeScript, JavaScript, ESM, CommonJS 또는 JSON으로 작성할 수 있습니다. TypeScript는 생성된 타입과 자동 완성을 활성화하므로 권장되지만 필수는 아닙니다.
+
+</Question>
+
+<Question title="서버 렌더링과 클라이언트 렌더링이 동일한 콘텐츠를 어떻게 공유하나요?">
+
+서버는 서버 렌더링된 컴포넌트의 콘텐츠를 직접 확인하므로 해당 마크업에 대해 클라이언트로 사전이 전송되지 않습니다. 클라이언트 컴포넌트는 서버에서 확인된 로케일을 수신하는 프로바이더를 통해 동일한 사전을 읽으므로, 첫 번째 클라이언트 렌더링이 서버 HTML과 일치하여 다른 언어로 깜빡이는 현상(flash)이 발생하지 않습니다.
+
+</Question>
+
+<Question title="Intlayer는 로케일로 인한 하이드레이션 불일치(hydration mismatch)를 어떻게 방지하나요?">
+
+로케일은 브라우저에서 다시 감지되는 대신 서버에서 한 번 확인되어 프로바이더로 전달됩니다. 클라이언트는 서버가 렌더링한 것과 동일한 로케일에서 시작하므로 마크업이 정확히 일치하여 클라이언트 측 로케일 감지에서 흔히 발생하는 문제가 해결됩니다.
+
+</Question>
+
+<Question title="번역을 추가할 때 다시 빌드해야 하나요?">
+
+개발 환경에서는 필요하지 않습니다. 플러그인이 콘텐츠 파일을 감시하고 저장 시 영향을 받는 사전을 자동으로 다시 빌드합니다. 프로덕션 환경에서는 사전이 빌드의 일부가 되지만, 원격 콘텐츠인 경우 [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>
+
+</FAQ>

package/docs/ko/interest_of_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-14
-updatedAt: 2026-05-31
+updatedAt: 2026-08-30
 title: Intlayer의 장점
 description: 프로젝트에서 Intlayer를 사용할 때의 이점과 장점을 알아보세요. 다른 프레임워크 중에서 Intlayer가 왜 뛰어난지 이해해보세요.
 keywords:
@@ -39,7 +39,6 @@ author: aymericzip
 `next-intl`이나 `i18next`와 같은 주요 솔루션과 비교할 때, Intlayer는 다음과 같은 통합된 최적화를 제공합니다:
 
 <AccordionGroup>
-
 <Accordion header="번들 크기">
 
 페이지에 대용량 JSON 파일을 로드하는 대신, 꼭 필요한 콘텐츠만 로드합니다. Intlayer는 **번들 및 페이지 크기를 최대 50%까지 줄이는 데** 기여합니다.
@@ -291,4 +290,100 @@ GitHub Star 수는 프로젝트의 인지도, 커뮤니티의 신뢰도 및 장
 
 `intlayer` 문법 형태로 다국어를 간편히 선언만 해두면, intlayer가 번거롭고 복잡한 기존 프레임워크 규격(예: `/messages/{{locale}}/{{namespace}}.json`)에 맞춰 빌드 타임에 자동으로 사전 파일을 추출 및 변환해 줍니다.
 
-현재 사용 중인 i18n 라이브러리의 API를 그대로 유지하고 싶다면, `intlayer`는 **호환 어댑터(compat adapters)** 도 제공합니다. `react-i18next`, `next-intl`, `react-intl`, `vue-i18n` 등과 완전히 동일한 API를 노출하지만, 실제 콘텐츠는 Intlayer 사전에서 제공되는 패키지입니다. 덕분에 코드를 다시 작성하지 않고 점진적으로 마이그레이션할 수 있습니다. [호환 어댑터 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md)를 참고하세요.
+현재 사용 중인 i18n 라이브러리의 API를 그대로 유지하고 싶다면, `intlayer`는 **호환 어댑터(compat adapters)** 도 제공합니다. `react-i18next`, `next-intl`, `react-intl`, `vue-i18n` 등과 완전히 동일한 API를 노출하지만, 실제 콘텐츠는 Intlayer 사전에서 제공되는 패키지입니다. 덕분에 코드를 다시 작성하지 않고 점진적으로 마이그레이션할 수 있습니다. [호환 어댑터 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compat/index.md)를 참고하세요.
+
+## 자주 묻는 질문
+
+<FAQ>
+
+<Question title="JavaScript 앱을 국제화하는 데 사용할 수 있는 다양한 솔루션은 무엇인가요?">
+
+이 분야는 크게 세 세대로 공존하고 있습니다:
+
+- **런타임 카탈로그 라이브러리**: `i18next`, `react-i18next`, `next-i18next`, `vue-i18n`, `ngx-translate`, `svelte-i18n`. 메시지가 런타임에 로드되는 JSON 네임스페이스에 존재합니다. 성숙하고 프레임워크에 구애받지 않지만 타입이 없고 번들 전체가 페이지에 전달됩니다.
+- **컴파일 타임 메시지 라이브러리**: `Lingui`, `Paraglide`, 그리고 추출 단계를 거치는 `react-intl`, `next-intl`. 더 나은 번들 동작과 일부 타입 검사를 제공하지만 여전히 중앙 집중식 카탈로그에 의존합니다.
+- **콘텐츠 레이어 라이브러리**: `Intlayer`. 컴포넌트별로 콘텐츠를 선언하고 컴파일하므로 타입 안전성, 트리 쉐이킹(tree-shaking), 편집 도구 및 AI 번역이 모두 동일한 선언에서 제공됩니다.
+
+</Question>
+
+<Question title="i18n이 번들 크기에 얼마나 영향을 미치나요?">
+
+네임스페이스 기반 설정보다 훨씬 적습니다. 페이지는 렌더링하지 않는 언어의 카탈로그를 절대 다운로드하지 않기 때문입니다. 서버 렌더링 마크업은 서버에서 콘텐츠를 확인하고, 빌드 타임 컴파일러는 `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="컴포넌트를 다시 작성하지 않고 i18next, next-intl 또는 react-i18next에서 마이그레이션할 수 있나요?">
+
+네, 두 가지 방법이 있습니다. [i18next 마이그레이션 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/migration_from_i18next_to_intlayer.md) 또는 [next-intl 마이그레이션 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/migration_from_next-intl_to_intlayer.md)를 따라 점진적으로 이전할 수 있습니다. 또는 현재 API를 완전히 유지할 수도 있습니다: [호환 어댑터(compat adapters)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compat/index.md)는 `i18next`, `react-i18next`, `next-intl`, `next-i18next`, `react-intl`, `use-intl`, `vue-i18n` 및 `Lingui`와 완전히 동일한 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)을 참조하세요.
+
+완전 자동화된 파이프라인을 위해 [Intlayer 컴파일러](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compiler.md)는 빌드 타임에 JSX, TSX, Vue 및 Svelte 소스에서 동일한 작업을 수행하여 변경될 때마다 사전을 생성하고 HMR을 통해 동기화하므로 수동으로 키를 관리할 필요가 없습니다. 정적 분석으로 작동하므로 런타임에만 존재하는 문자열은 제외되며, 사용자 텍스트와 애플리케이션 로직을 구분하기 위해 몇 가지 주석이 필요합니다.
+
+</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="Intlayer는 next-intl과 어떻게 다른가요?">
+
+`next-intl`은 Next.js를 위한 메시지 계층입니다: 로케일별로 JSON 메시지 파일을 유지하고 `useTranslations`를 통해 읽습니다. Intlayer는 콘텐츠 계층입니다: 선언이 컴포넌트 바로 옆에 위치하며, 선언 자체에서 타입이 지정되고, 컴포넌트별로 컴파일되므로 페이지는 렌더링하는 데 필요한 것만 전달합니다. 또한 Intlayer는 `next-intl`이 다루지 않는 AI 번역, 비주얼 에디터, CMS 및 CI에서의 누락 번역 검사를 모두 기본 제공합니다. `next-intl` API를 그대로 유지하고 싶다면 [호환 어댑터(compat adapter)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compat/index.md)를 통해 Intlayer 사전에서 이를 제공받을 수 있습니다.
+
+</Question>
+
+<Question title="Intlayer는 i18next 및 react-i18next와 어떻게 다른가요?">
+
+`i18next`는 런타임에 네임스페이스에 대해 문자열 키를 확인하므로 키 이름이 변경되거나 오타가 발생하면 조용히 실패하며 페이지가 접근하는 모든 네임스페이스가 통째로 다운로드됩니다. Intlayer는 빌드 타임에 생성된 타입에 대해 콘텐츠를 확인하므로 잘못된 키는 컴파일 오류가 되며 컴포넌트가 렌더링하는 항목만 번들에 포함됩니다. `i18next`는 더 큰 플러그인 생태계와 오랜 역사를 가지고 있지만, Intlayer는 정밀한 타입 검사, 번들 최적화, 그리고 비주얼 편집 및 자동화 도구에서 압도적인 장점을 제공합니다. [i18next 마이그레이션 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/migration_from_i18next_to_intlayer.md) 또는 [호환 어댑터](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compat/index.md)를 참조하세요.
+
+</Question>
+
+<Question title="Intlayer는 다른 대안들보다 더 빠르고 가볍나요?">
+
+번들 및 페이지 크기 측면에서 확실히 그렇습니다. 페이지에서 렌더링하지 않는 카탈로그를 로드하지 않음으로써 네임스페이스 기반 설정 대비 번들 및 페이지 크기를 최대 50%까지 줄여줍니다. [벤치마크](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/benchmark/index.md)에서는 [Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/benchmark/nextjs.md), [TanStack Start](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/benchmark/tanstack.md), [Vue](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/benchmark/vue.md), [Svelte](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/benchmark/svelte.md) 등 각 프레임워크별 측정 방법과 수치를 투명하게 공개하고 있어 직접 재현해 볼 수 있습니다.
+
+</Question>
+
+<Question title="기존 앱을 마이그레이션할 가치가 있나요?">
+
+현재 프로젝트가 겪고 있는 병목에 따라 다릅니다. 번들 크기 증가, 조용히 누락되는 번역 오류, 또는 개발자의 도움 없이는 작업할 수 없는 번역팀과의 협업이 고민이라면 마이그레이션은 충분한 가치가 있습니다. 카탈로그가 작고 안정적이라면 체감 효과는 상대적으로 적을 수 있습니다. 어떤 경우든 전면 재작성 없이 이전할 수 있습니다: [호환 어댑터(compat adapters)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compat/index.md)는 현재 API를 그대로 유지해 주며, [sync JSON 플러그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/plugins/sync-json.md)은 두 계층이 공존하는 동안 기존 JSON 파일을 단일 진실 공급원으로 유지해 줍니다.
+
+</Question>
+
+<Question title="다른 i18n 라이브러리에는 없는 Intlayer만의 특별한 기능은 무엇인가요?">
+
+[Markdown 콘텐츠](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/markdown.md), [외부 소스에서 가져온 콘텐츠](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/content_file.md), 파일 콘텐츠 로딩, [실시간 콘텐츠 업데이트](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/live.md), [비주얼 에디터](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/compiler.md), A/B 테스트를 위한 [콘텐츠 변형(content variants)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/variants.md), 콘텐츠 노출 [애널리틱스](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/analytics.md), [MCP 서버](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/mcp_server.md), [LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/lsp.md) 및 [에이전트 스킬](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/agent_skills.md)을 제공합니다.
+
+</Question>
+
+<Question title="현재 사용 중인 라이브러리를 유지하면서 Intlayer를 번역 관리 도구로만 사용할 수 있나요?">
+
+네. Intlayer는 현재 라이브러리가 요구하는 형식과 위치(예: `/messages/{locale}/{namespace}.json`)로 네임스페이스를 생성할 수 있으므로, 애플리케이션 코드는 기존 i18n 라이브러리를 그대로 사용하면서 AI 번역, 비주얼 에디터 및 CI 검사 기능의 혜택을 누릴 수 있습니다.
+
+</Question>
+
+<Question title="Intlayer는 무료이며 오픈 소스인가요?">
+
+네, 상업적 사용을 포함하여 Apache 2.0 라이선스에 따라 제공됩니다. 호스팅형 CMS는 선택적 유료 서비스이며 [자체 호스팅](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/self_hosting.md)도 가능합니다.
+
+</Question>
+
+</FAQ>

package/docs/ko/intlayer_CMS.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-08-23
-updatedAt: 2026-07-08
+updatedAt: 2026-08-30
 title: Intlayer CMS | Intlayer CMS에 콘텐츠 외부화하기
 description: 콘텐츠 관리를 팀에 위임하기 위해 Intlayer CMS에 콘텐츠를 외부화하세요.
 keywords:
@@ -434,3 +434,95 @@ CMS에서 문제가 발생하면 다음을 확인하세요:
 - 프로젝트 구성이 Intlayer CMS에 푸시되었는지 확인하세요.
 
 - 비주얼 에디터는 iframe을 사용하여 웹사이트를 표시합니다. 웹사이트의 콘텐츠 보안 정책(CSP)이 CMS URL을 `frame-ancestors`로 허용하는지 확인하세요(기본값은 'https://app.intlayer.org'). 에디터 콘솔에서 오류가 있는지 확인하세요.
+
+## 자주 묻는 질문
+
+<FAQ>
+
+<Question title="Intlayer CMS와 비주얼 에디터의 차이점은 무엇인가요?">
+
+[비주얼 에디터](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_visual_editor.md)는 로컬 사전을 편집하고 변경 사항을 코드베이스에 다시 기록하므로, 앱이 다시 빌드되고 정상적인 코드 리뷰 및 배포 과정을 거칩니다. CMS는 원격 사전을 편집합니다: 변경 사항이 코드베이스를 건드리지 않으며 실행 중인 웹사이트가 배포 없이 즉시 업데이트를 반영합니다. 팀에서는 두 가지를 함께 사용하는 경우가 많습니다. 즉, 개발자가 소유하는 UI 콘텐츠에는 에디터를 사용하고 마케팅 팀이 매주 변경하는 콘텐츠에는 CMS를 사용합니다.
+
+</Question>
+
+<Question title="i18n이 번들 크기에 얼마나 영향을 미치나요?">
+
+네임스페이스 기반 설정보다 훨씬 적습니다. 페이지는 렌더링하지 않는 언어의 카탈로그를 절대 다운로드하지 않기 때문입니다. 서버 렌더링 마크업은 서버에서 콘텐츠를 확인하고, 빌드 타임 컴파일러는 `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="컴포넌트를 다시 작성하지 않고 i18next, next-intl 또는 react-i18next에서 마이그레이션할 수 있나요?">
+
+네, 두 가지 방법이 있습니다. [i18next 마이그레이션 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/migration_from_i18next_to_intlayer.md) 또는 [next-intl 마이그레이션 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/migration_from_next-intl_to_intlayer.md)를 따라 점진적으로 이전할 수 있습니다. 또는 현재 API를 완전히 유지할 수도 있습니다: [호환 어댑터(compat adapters)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compat/index.md)는 `i18next`, `react-i18next`, `next-intl`, `next-i18next`, `react-intl`, `use-intl`, `vue-i18n` 및 `Lingui`와 완전히 동일한 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)을 참조하세요.
+
+완전 자동화된 파이프라인을 위해 [Intlayer 컴파일러](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compiler.md)는 빌드 타임에 JSX, TSX, Vue 및 Svelte 소스에서 동일한 작업을 수행하여 변경될 때마다 사전을 생성하고 HMR을 통해 동기화하므로 수동으로 키를 관리할 필요가 없습니다. 정적 분석으로 작동하므로 런타임에만 존재하는 문자열은 제외되며, 사용자 텍스트와 애플리케이션 로직을 구분하기 위해 몇 가지 주석이 필요합니다.
+
+</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="어떤 콘텐츠를 CMS로 이동해야 하나요?">
+
+릴리스 주기와 무관하게 자주 변경되는 콘텐츠가 적합합니다: 랜딩 페이지 문구, 요금제 설명, 공지사항 등 마케팅 팀이 직접 관리하는 모든 항목이 여기에 해당합니다. 버튼 레이블이나 폼 오류 메시지와 같이 사용자 인터페이스의 필수적인 부분인 콘텐츠는 이를 사용하는 코드와 함께 검토될 수 있도록 로컬 사전으로 유지하는 것이 좋습니다.
+
+</Question>
+
+<Question title="CMS에 연결할 수 없으면 어떻게 되나요?">
+
+애플리케이션은 사전의 로컬 선언으로 자동 폴백되므로 네트워크 장애나 서비스 중단이 발생하더라도 빈 페이지가 표시되지 않고 빌드 시 포함된 콘텐츠가 안전하게 렌더링됩니다. 이것이 모든 원격 사전에 대해 로컬 선언을 함께 유지해야 하는 이유입니다.
+
+</Question>
+
+<Question title="CMS를 자체 호스팅(self-host)할 수 있나요?">
+
+네. CMS를 자체 인프라에서 실행할 수 있으며, 콘텐츠가 내부 네트워크 외부로 유출되어서는 안 되는 환경에서 주로 사용됩니다. [Intlayer 자체 호스팅](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/self_hosting.md)을 참조하세요.
+
+</Question>
+
+<Question title="콘텐츠 편집자가 변경 사항을 게시하기 위해 개발자의 도움이 필요한가요?">
+
+아닙니다. 그것이 원격 사전의 핵심 목적입니다: 편집자가 CMS에서 텍스트를 변경하면 사이트에 즉시 반영되며, [실시간 동기화(live sync)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/live.md)를 통해 빌드를 기다리지 않고 런타임에 업데이트가 적용됩니다.
+
+</Question>
+
+<Question title="인터페이스를 사용하는 대신 CMS 작업을 자동화할 수 있나요?">
+
+네. `@intlayer/api` SDK는 UI와 동일한 엔드포인트를 노출하므로 스크립트나 CI 파이프라인에서 프로젝트를 조회하고 사전을 읽으며 업데이트를 푸시할 수 있습니다. 위 섹션에서 인증 방식과 엔드포인트를 확인할 수 있습니다.
+
+</Question>
+
+<Question title="CMS에서 번역 A/B 테스트를 지원하나요?">
+
+네. 원격 사전은 [콘텐츠 변형(content variants)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/variants.md)을 지원하며, [애널리틱스](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/analytics.md)를 통해 각 변형이 어떻게 노출되었는지 보고하므로 주관적인 토론 대신 데이터에 기반하여 문구 변경 효과를 측정할 수 있습니다.
+
+</Question>
+
+<Question title="CMS는 무료인가요?">
+
+Intlayer 라이브러리, CLI, 컴파일러 및 비주얼 에디터는 Apache 2.0 라이선스에 따라 무료 오픈 소스로 제공됩니다. 호스팅형 CMS는 선택적 유료 서비스이며 대안으로 [자체 호스팅](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/self_hosting.md)할 수도 있습니다.
+
+</Question>
+
+</FAQ>

package/docs/ko/intlayer_visual_editor.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-11
-updatedAt: 2025-06-29
+updatedAt: 2026-08-30
 title: Intlayer 비주얼 편집기 | 비주얼 편집기를 사용하여 콘텐츠를 편집합니다
 description: Intlayer 편집기를 사용하여 다국어 웹사이트를 관리하는 방법을 알아보세요. 이 온라인 문서의 단계를 따라 몇 분 만에 프로젝트를 설정하세요.
 keywords:
@@ -210,4 +210,90 @@ pnpm intlayer-editor start -e development
   - 필수 필드:
     - 애플리케이션 URL은 편집기 구성(`applicationURL`)에 설정한 URL과 일치해야 합니다.
 
-- 비주얼 에디터는 iframe을 사용하여 웹사이트를 표시합니다. 웹사이트의 콘텐츠 보안 정책(CSP)이 CMS URL을 `frame-ancestors`로 허용하는지 확인하세요(기본값은 'http://localhost:8000'입니다). 에디터 콘솔에서 오류가 있는지 확인하세요.
+- 비주얼 에디터는 iframe을 사용하여 웹사이트를 표시합니다. 웹사이트의 콘텐츠 보안 정책(CSP)이 CMS URL을 `frame-ancestors`로 허용하는지 확인하세요(기본값은 `http://localhost:8000`입니다). 에디터 콘솔에서 오류가 있는지 확인하세요.
+
+## 자주 묻는 질문
+
+<FAQ>
+
+<Question title="비주얼 에디터와 CMS의 차이점은 무엇인가요?">
+
+비주얼 에디터는 로컬 사전을 편집하고 변경 사항을 코드베이스에 다시 기록하므로 일반적인 코드 리뷰 및 배포 과정을 거칩니다. [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_CMS.md)는 원격 사전을 편집하여 배포 없이 실행 중인 웹사이트에서 콘텐츠를 변경합니다. 에디터는 개발자가 소유하는 콘텐츠에 적합하며, CMS는 마케팅 팀이 소유하는 콘텐츠에 적합합니다.
+
+</Question>
+
+<Question title="i18n이 번들 크기에 얼마나 영향을 미치나요?">
+
+네임스페이스 기반 설정보다 훨씬 적습니다. 페이지는 렌더링하지 않는 언어의 카탈로그를 절대 다운로드하지 않기 때문입니다. 서버 렌더링 마크업은 서버에서 콘텐츠를 확인하고, 빌드 타임 컴파일러는 `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="컴포넌트를 다시 작성하지 않고 i18next, next-intl 또는 react-i18next에서 마이그레이션할 수 있나요?">
+
+네, 두 가지 방법이 있습니다. [i18next 마이그레이션 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/migration_from_i18next_to_intlayer.md) 또는 [next-intl 마이그레이션 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/migration_from_next-intl_to_intlayer.md)를 따라 점진적으로 이전할 수 있습니다. 또는 현재 API를 완전히 유지할 수도 있습니다: [호환 어댑터(compat adapters)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compat/index.md)는 `i18next`, `react-i18next`, `next-intl`, `next-i18next`, `react-intl`, `use-intl`, `vue-i18n` 및 `Lingui`와 완전히 동일한 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)을 참조하세요.
+
+완전 자동화된 파이프라인을 위해 [Intlayer 컴파일러](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compiler.md)는 빌드 타임에 JSX, TSX, Vue 및 Svelte 소스에서 동일한 작업을 수행하여 변경될 때마다 사전을 생성하고 HMR을 통해 동기화하므로 수동으로 키를 관리할 필요가 없습니다. 정적 분석으로 작동하므로 런타임에만 존재하는 문자열은 제외되며, 사용자 텍스트와 애플리케이션 로직을 구분하기 위해 몇 가지 주석이 필요합니다.
+
+</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="비주얼 에디터는 어디에서 실행되나요?">
+
+사용자의 자체 인프라에서 실행됩니다. iframe 내에 애플리케이션을 로드하고 로컬 에디터 서버와 통신하므로 콘텐츠가 내부 환경 외부로 절대 유출되지 않습니다. 따라서 외부 호스팅 서비스로 사본을 보낼 수 없는 민감한 프로젝트에서도 안전하게 사용할 수 있습니다.
+
+</Question>
+
+<Question title="편집자가 코딩 지식을 알아야 하나요?">
+
+아닙니다. 사이트를 열고 텍스트를 클릭하여 그 자리에서 직접 편집하면 됩니다. 에디터가 해당 텍스트를 지원하는 사전 항목을 확인하고 올바른 콘텐츠 파일에 변경 사항을 기록하므로 번역가가 파일을 직접 찾거나 키 이름을 알 필요가 없습니다.
+
+</Question>
+
+<Question title="비주얼 에디터를 통한 편집이 소스 파일을 변경하나요?">
+
+네, 바로 그것이 의도된 동작입니다. 변경 사항이 코드베이스의 콘텐츠 선언 파일에 직접 기록되므로 일반적인 Git diff 형태로 검토하고 커밋할 수 있으며 애플리케이션이 다시 빌드되어 변경 사항을 화면에 표시합니다.
+
+</Question>
+
+<Question title="에디터에 빈 페이지가 표시되거나 사이트 로드를 거부합니다. 무엇을 확인해야 하나요?">
+
+에디터는 iframe을 사용하여 애플리케이션을 표시하므로 콘텐츠 보안 정책(CSP)에서 에디터 출처를 `frame-ancestors`로 허용해야 합니다(기본값은 `http://localhost:8000`). 또한 에디터 구성의 `applicationURL`이 앱이 실제로 서비스되는 URL과 일치하는지 확인하세요. 에디터 콘솔에서 두 가지 실패 원인을 모두 확인할 수 있습니다.
+
+</Question>
+
+<Question title="프로덕션 환경에서 비주얼 에디터를 사용할 수 있나요?">
+
+비주얼 에디터는 편집 후 재빌드가 허용되는 개발 및 스테이징 환경용으로 설계되었습니다. 배포 없이 실시간 사이트의 콘텐츠를 편집하려면 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_CMS.md)와 원격 사전을 사용하는 것이 좋습니다.
+
+</Question>
+
+<Question title="비주얼 에디터는 무료인가요?">
+
+네. 비주얼 에디터는 상업적 사용을 포함하여 Apache 2.0 라이선스에 따라 오픈 소스 프로젝트의 일부로 제공됩니다. 호스팅형 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_CMS.md)만 유료 서비스이며, CMS 또한 [자체 호스팅](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/self_hosting.md)이 가능합니다.
+
+</Question>
+
+</FAQ>

package/docs/ko/intlayer_with_adonisjs.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-08-23
-updatedAt: 2026-05-31
+updatedAt: 2026-08-30
 title: "AdonisJS i18n - 앱을 번역하는 완전 가이드"
 description: "i18next는 이제 그만. 2026년 다국어 (i18n) AdonisJS 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
 keywords:
@@ -64,15 +64,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > `--interactive` 플래그는 선택 사항입니다. AI 에이전트인 경우 `intlayer-cli init`를 사용하세요.
@@ -318,3 +318,123 @@ Intlayer에서 생성된 파일을 무시하는 것이 좋습니다. 이를 통
 # Intlayer에서 생성된 파일 무시
 .intlayer
 ```
+
+## 자주 묻는 질문
+
+<FAQ>
+
+<Question title="AdonisJS 백엔드를 국제화하는 데 사용할 수 있는 다양한 솔루션은 무엇인가요?">
+
+AdonisJS는 요청 범위(request-scoped) 서비스와 함께 `resources/lang` 파일의 ICU 메시지를 지원하는 `@adonisjs/i18n`을 제공합니다. 대안은 `adonis-intlayer`를 통한 `Intlayer`로, 프론트엔드와 공유되는 타입 정의 파일에 콘텐츠를 선언하고 요청별로 로케일을 확인하며 AI 번역, 누락된 번역 검사 및 CMS를 추가합니다.
+
+백엔드를 국제화해야 하는 이유는 사용자가 읽는 텍스트의 상당 부분이 프론트엔드를 거치지 않기 때문입니다: API 오류 메시지, 트랜잭션 이메일, 푸시 알림, SMS 및 PDF 내보내기 등이 여기에 해당합니다. 이러한 텍스트는 세션이 아닌 요청별로 수신자의 언어가 확인되어야 합니다.
+
+[왜 Intlayer인가](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/interest_of_intlayer.md)를 참조하세요.
+
+</Question>
+
+<Question title="i18n이 AdonisJS 서버 번들 크기에 얼마나 영향을 미치나요?">
+
+매우 적습니다. 사전은 사전에 컴파일되며 선언한 로케일만 포함되므로 부팅 시 카탈로그 로딩이나 요청 경로에서의 파일 읽기가 발생하지 않습니다. 이는 번들 크기가 콜드 스타트 시간을 좌우하는 서버리스 및 엣지 배포 환경에서 특히 중요합니다. [번들 최적화](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)을 참조하세요.
+
+동일한 프로젝트의 프론트엔드 측에서는 [Intlayer 컴파일러](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compiler.md)가 빌드 타임에 JSX, TSX, Vue 또는 Svelte 소스에서 사전을 생성하므로 앱의 두 영역이 수동 키 관리 없이 단일 콘텐츠 레이어를 공유할 수 있습니다.
+
+</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="Intlayer는 응답할 언어를 어떻게 파악하나요?">
+
+기본적으로 `adonis-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="컨트롤러나 서비스 내부에서 번역을 어떻게 사용하나요?">
+
+사전 키로 `getIntlayer`를 호출하거나 메시지를 `t()`로 래핑하세요. 활성 로케일은 미들웨어가 설정한 요청 컨텍스트에서 가져오므로 주입할 서비스나 전달할 로케일 인수가 없습니다.
+
+</Question>
+
+<Question title="Edge 템플릿과 호환되나요?">
+
+네. 컨트롤러에서 콘텐츠를 확인하여 뷰에 전달하면 템플릿이 키를 자체적으로 확인하는 대신 이미 번역된 값을 렌더링합니다.
+
+</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="프론트엔드와 백엔드가 동일한 콘텐츠를 공유할 수 있나요?">
+
+네, 실제로 권장되는 설정입니다. `adonis-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)도 가능합니다.
+
+</Question>
+
+</FAQ>