@intlayer/docs 9.4.4 → 9.5.1

package/docs/ko/intlayer_with_tanstack.md

@@ -69,37 +69,31 @@ author: aymericzip
 Intlayer는 TanStack Start에 완전히 최적화되어 **다국어 라우팅**, **쿠키 관리**, **사이트맵 생성**, **동적 콘텐츠 로딩** 및 국제화(i18n) 노력을 확장하는 데 필요한 모든 기능을 제공합니다.
 
 </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)**를 제공합니다. 다국어 콘텐츠를 **실시간**으로 제공하여 번역가, 카피라이터, 기타 팀원과 원활하게 협업할 수 있습니다. 콘텐츠는 로컬 및/또는 원격으로 저장될 수 있습니다.
@@ -107,8 +101,6 @@ Intlayer는 단순한 i18n 솔루션 그 이상으로 관리에 도움이 되는
 </Accordion>
 </AccordionGroup>
 
----
-
 ## TanStack Start 애플리케이션에서 Intlayer를 설정하기 위한 단계별 가이드
 
 <Tabs defaultTab="video">
@@ -144,13 +136,11 @@ Intlayer는 단순한 i18n 솔루션 그 이상으로 관리에 도움이 되는
 GitHub에서 [애플리케이션 템플릿](https://github.com/aymericzip/intlayer-tanstack-start-template)을 참조하세요.
 
 <Steps>
-
 <Step number={1} title="프로젝트 생성">
 
 먼저 TanStack Start 웹사이트의 [새 프로젝트 시작하기](https://tanstack.com/start/latest/docs/framework/react/quick-start) 가이드에 따라 새 TanStack Start 프로젝트를 생성합니다.
 
 </Step>
-
 <Step number={2} title="Intlayer 패키지 설치">
 
 선호하는 패키지 관리자를 사용하여 필요한 패키지를 설치합니다:
@@ -206,9 +196,44 @@ bun add vite-intlayer --dev
   Intlayer를 [Vite 번들러](https://vite.dev/guide/why.html#why-bundle-for-production)와 통합하기 위한 Vite 플러그인과 사용자의 기본 로케일 감지, 쿠키 관리 및 URL 리디렉션 처리를 위한 미들웨어를 포함합니다.
 
 </Step>
-
 <Step number={3} title="프로젝트 구성">
 
+### 아키텍처
+
+이 아키텍처에서는 모든 지역화된 라우트가 `{-$locale}` 라우트 세그먼트 아래에 중첩됩니다. 이 접근 방식은 각 언어에 고유한 전용 URL을 보장하며 자동 로케일 접두사 지정, 유효성 검사 및 SEO 최적화를 가능하게 합니다.
+
+```bash
+.
+├── src
+│   ├── components
+│   │   ├── Header.tsx
+│   │   ├── locale-switcher.content.ts
+│   │   ├── locale-switcher.tsx
+│   │   └── localized-link.tsx
+│   ├── hooks
+│   │   ├── useI18nHTMLAttributes.tsx
+│   │   └── useLocalizedNavigate.ts
+│   ├── routes
+│   │   ├── {-$locale}
+│   │   │   ├── 404.content.ts
+│   │   │   ├── 404.tsx
+│   │   │   ├── about.content.ts
+│   │   │   ├── about.tsx
+│   │   │   ├── index.content.tsx
+│   │   │   ├── index.tsx
+│   │   │   └── route.tsx             # Locale layout & prefix validation
+│   │   ├── __root.tsx                # Root route with IntlayerProvider
+│   │   └── sitemap[.]xml.ts
+│   ├── router.tsx
+│   └── styles.css
+├── intlayer.config.ts
+├── package.json
+├── tsconfig.json
+└── vite.config.ts
+```
+
+### 설정
+
 애플리케이션의 언어를 구성하기 위한 설정 파일을 생성합니다:
 
 ```typescript fileName="intlayer.config.ts"
@@ -229,7 +254,6 @@ export default config;
 > 이 구성 파일을 통해 지역화된 URL, 미들웨어 리디렉션, 쿠키 이름, 콘텐츠 선언의 위치 및 확장자 설정, 콘솔에서 Intlayer 로그 비활성화 등을 수행할 수 있습니다. 사용 가능한 매개변수의 전체 목록은 [구성 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)를 참조하세요.
 
 </Step>
-
 <Step number={4} title="Vite 구성에 Intlayer 통합">
 
 구성에 intlayer 플러그인을 추가합니다:
@@ -265,7 +289,6 @@ export default config;
 > `intlayer()` Vite 플러그인은 Intlayer를 Vite와 통합하는 데 사용됩니다. 콘텐츠 선언 파일의 빌드를 보장하고 개발 모드에서 이를 감시합니다. Vite 애플리케이션 내에서 Intlayer 환경 변수를 정의합니다. 또한 성능 최적화를 위한 별칭을 제공합니다.
 
 </Step>
-
 <Step number={5} title="루트 레이아웃 생성">
 
 `useParams`를 사용하여 현재 로케일을 감지하고 `html` 태그에 `lang` 및 `dir` 속성을 설정하여 국제화를 지원하도록 루트 레이아웃을 구성합니다.
@@ -321,7 +344,6 @@ function RootDocument({ children }: { children: ReactNode }) {
 ```
 
 </Step>
-
 <Step number={6} title="로케일 레이아웃 생성">
 
 로케일 접두사를 처리하고 유효성 검사를 수행하는 레이아웃을 생성합니다.
@@ -355,7 +377,6 @@ export const Route = createFileRoute("/{-$locale}")({
 > `'no-prefix'` 또는 `'search-params'` 모드의 경우 슬롯을 완전히 제거할 수 있습니다.
 
 </Step>
-
 <Step number={7} title="콘텐츠 선언">
 
 번역을 저장하기 위해 콘텐츠 선언을 생성하고 관리합니다:
@@ -403,7 +424,6 @@ export default appContent;
 > 자세한 내용은 [콘텐츠 선언 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/content_file.md)를 참조하세요.
 
 </Step>
-
 <Step number={8} title="로케일 인식 컴포넌트 및 훅 생성">
 
 로케일 인식 내비게이션을 위한 `LocalizedLink` 컴포넌트를 생성합니다:
@@ -508,7 +528,6 @@ export const useLocalizedNavigate = () => {
 ```
 
 </Step>
-
 <Step number={9} title="페이지에서 Intlayer 활용하기">
 
 > 컴포넌트 안에서는 기본적으로 **`useIntlayer`** 를 사용하세요. 컴파일러가 렌더링되는 로케일로 해석해 주므로 이것이 권장 방식입니다. `getIntlayer` / `getIntlayerAsync` 는 React 트리 바깥(라우트 `head`, 로더, 서버 함수)에서만 사용하세요.
@@ -558,16 +577,15 @@ function RouteComponent() {
 
 > 콘텐츠를 `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` hook에 대해 자세히 알아보려면 [문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/react-intlayer/useIntlayer.md)를 참조하세요.
 
 </Step>
-
 <Step number={9} title="로케일 전환 컴포넌트 만들기">
 
 사용자가 언어를 변경할 수 있는 컴포넌트를 만듭니다:
@@ -630,7 +648,6 @@ export const LocaleSwitcher: FC = () => {
 > `useLocale` hook에 대해 자세히 알아보려면 [문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/react-intlayer/useLocale.md)를 참조하세요.
 
 </Step>
-
 <Step number={10} title="HTML 속성 관리">
 
 Step 5에서 본 것처럼 루트 컴포넌트에서 `useParams`를 사용하여 `html` 태그의 `lang`과 `dir` 속성을 관리할 수 있습니다. 이렇게 하면 서버와 클라이언트에서 올바른 속성이 설정됩니다.
@@ -651,7 +668,6 @@ function RootDocument({ children }: { children: ReactNode }) {
 ```
 
 </Step>
-
 <Step number={11} title="미들웨어 추가">
 
 또한 `intlayerProxy`를 사용하여 애플리케이션에 서버 측 라우팅을 추가할 수 있습니다. 이 플러그인은 URL을 기반으로 현재 로케일을 자동으로 감지하고 적절한 로케일 쿠키를 설정합니다. 로케일이 지정되지 않으면 플러그인이 사용자의 브라우저 언어 설정을 기반으로 가장 적절한 로케일을 결정합니다. 로케일이 감지되지 않으면 기본 로케일로 리다이렉트됩니다.
@@ -687,7 +703,6 @@ export default defineConfig({
 ```
 
 </Step>
-
 <Step number={12} title="메타데이터 국제화">
 
 <Tabs>
@@ -880,7 +895,6 @@ export const Route = createFileRoute("/{-$locale}/")({
 | Developer experience | simplest              | one `await`                | content threaded through `loaderData`  |
 
 </Step>
-
 <Step number={13} title="서버 액션에서 로케일 검색">
 
 서버 액션이나 API 엔드포인트 내에서 현재 로케일에 액세스하고 싶을 수 있습니다.
@@ -917,7 +931,6 @@ export const getLocaleServer = createServerFn().handler(async () => {
 ```
 
 </Step>
-
 <Step number={14} title="찾을 수 없는 페이지 관리(선택 사항)" isOptional={true}>
 
 사용자가 존재하지 않는 페이지를 방문할 때 맞춤형 찾을 수 없음 페이지를 표시할 수 있으며, 로케일 접두사가 찾을 수 없음 페이지가 트리거되는 방식에 영향을 줄 수 있습니다.
@@ -993,7 +1006,6 @@ export const Route = createFileRoute("/{-$locale}/$")({
 ```
 
 </Step>
-
 <Step number={15} title="컴포넌트에서 콘텐츠 추출(선택 사항)" isOptional={true}> isOptional={true}>
 
 기존 코드베이스가 있는 경우 수천 개의 파일을 변환하는 데 시간이 많이 걸릴 수 있습니다.
@@ -1093,7 +1105,6 @@ bun run build # 또는 bun run dev
 </Tabs>
 
 </Step>
-
 <Step number={16} title="사이트맵 생성(선택 사항)" isOptional={true}>
 
 Intlayer는 애플리케이션의 사이트맵을 쉽게 만들 수 있는 내장 사이트맵 생성기를 제공합니다. 로컬라이즈된 경로를 처리하고 검색 엔진에 필요한 메타데이터를 추가합니다.
@@ -1168,7 +1179,6 @@ export const Route = createFileRoute("/sitemap.xml")({
 ```
 
 </Step>
-
 <Step number={17} title="TypeScript 구성(선택 사항)" isOptional={true}>
 
 Intlayer는 모듈 확장을 사용하여 TypeScript의 이점을 얻고 코드베이스를 더욱 견고하게 만듭니다.
@@ -1200,8 +1210,6 @@ Intlayer에서 생성된 파일은 무시하는 것이 좋습니다. 이를 통
 .intlayer
 ```
 
----
-
 ## VS Code 확장 프로그램
 
 Intlayer로 개발 경험을 개선하기 위해 공식 **Intlayer VS Code 확장 프로그램**을 설치할 수 있습니다.
@@ -1217,14 +1225,10 @@ Intlayer로 개발 경험을 개선하기 위해 공식 **Intlayer VS Code 확
 
 확장 프로그램 사용 방법에 대한 자세한 내용은 [Intlayer VS Code 확장 프로그램 문서](https://intlayer.org/doc/vs-code-extension)를 참조하세요.
 
----
-
 ## 더 나아가기
 
 더 나아가려면 [visual editor](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)를 사용하여 콘텐츠를 외부화할 수 있습니다.
 
----
-
 ## 문서 참고
 
 - [Intlayer 문서](https://intlayer.org)
@@ -1250,25 +1254,21 @@ TanStack Start는 자체 i18n 레이어를 제공하지 않으므로 라이브
 TanStack Start에서 중요한 차이점은 라우팅과 서버 렌더링입니다. Intlayer는 프로바이더, 로케일 감지기, 사이트맵을 수동으로 조립할 필요 없이 파일 기반 라우터, `head` 함수 및 사전 렌더링 패스와 완벽히 통합됩니다. [왜 Intlayer인가](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/interest_of_intlayer.md)와 [TanStack Start i18n 벤치마크](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/benchmark/tanstack.md)를 참조하세요.
 
 </Question>
-
 <Question title="i18n이 TanStack Start 번들 크기에 얼마나 영향을 미치나요?">
 
 네임스페이스 기반 설정보다 훨씬 적습니다. 페이지는 렌더링하지 않는 언어의 카탈로그를 절대 다운로드하지 않기 때문입니다. 서버 렌더링된 마크업은 서버에서 직접 콘텐츠를 확인하며, 빌드 타임 컴파일러는 `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/tanstack.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="콘텐츠를 키 단위로 하나씩 옮겨야 하나요?">
 
 아닙니다. `npx intlayer extract`를 실행하면 Intlayer가 컴포넌트를 읽고 사용자 대면 문자열을 추출하여 각 컴포넌트 옆에 `.content` 파일을 생성하므로 카탈로그에 일일이 복사할 필요 없이 diff만 검토하면 됩니다. 이 가이드의 15단계를 확인하세요.
@@ -1278,7 +1278,6 @@ TanStack Start에서 중요한 차이점은 라우팅과 서버 렌더링입니
 컴파일러를 켜기 전에 알아두어야 할 두 가지 제한 사항이 있습니다. 정적 분석으로 작동하므로 API 오류 코드나 CMS 필드와 같이 런타임에만 존재하는 문자열은 처리할 수 없습니다. 또한 큰 코드베이스에서 몇 가지 어노테이션이 필요한 `className="active"` 또는 상태 코드와 같은 애플리케이션 로직과 사용자 대면 텍스트를 구분해야 합니다. [extract 명령](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/extract.md)은 사용자가 직접 제어할 수 있도록 하여 두 가지 문제를 모두 방지합니다.
 
 </Question>
-
 <Question title="사용 가능한 에디터 및 AI 에이전트 도구는 무엇이 있나요?">
 
 5가지 도구가 모두 선택 사항으로 제공됩니다:
@@ -1290,55 +1289,46 @@ TanStack Start에서 중요한 차이점은 라우팅과 서버 렌더링입니
 - **[ESLint 플러그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/eslint.md)**: `no-raw-text` 규칙으로 하드코딩된 문자열을 표시하고, 정적 사전 키 및 사용되지 않는 콘텐츠에 대한 추가 규칙을 제공합니다.
 
 </Question>
-
 <Question title="Intlayer는 TanStack Start에서 서버 사이드 렌더링 및 사전 렌더링(pre-rendering)을 지원하나요?">
 
 네. SSR 중에 콘텐츠가 확인되며, 가이드에서는 지역화된 라우트당 하나의 정적 문서를 내보내는 사전 렌더링 구성을 다룹니다. 16단계에서는 `vite.config.ts`에서 `prerender`를 활성화하고 동일한 라우트 테이블에서 지역화된 사이트맵을 생성하는 방법을 보여줍니다.
 
 </Question>
-
 <Question title="hreflang 태그 및 지역화된 사이트맵은 어떻게 추가하나요?">
 
 `src/routes/sitemap[.]xml.ts` 라우트에서 내장 `generateSitemap` 함수를 사용하세요. 일반 URL 목록과 달리 `xhtml:link` 네임스페이스를 내보내므로 페이지의 모든 언어 버전이 서로 양방향으로 연결되어 검색 엔진이 각 대상에게 적합한 버전을 인덱싱할 수 있습니다. 현지화된 `head` 메타데이터는 12단계에서 다룹니다.
 
 </Question>
-
 <Question title="URL에 로케일을 반드시 포함해야 하나요?">
 
 아닙니다. `routing.mode`는 URL 체계를 제어합니다: `"prefix-no-default"`(기본값: `/about`, `/ko/about`), `"prefix-all"`(`/en/about`), `"no-prefix"`(쿠키, 헤더 또는 도메인에서 확인) 또는 `"search-params"`(`/about?locale=ko`). `routing.domains`를 통해 로케일을 별도의 도메인에 매핑할 수도 있습니다. [설정 참조](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)를 참조하세요.
 
 </Question>
-
 <Question title="현재 라우트를 유지하는 로케일 전환기는 어떻게 만드나요?">
 
 9단계에 설명된 지역화된 링크 컴포넌트와 함께 `useLocale`을 사용하세요. `useLocale`은 활성 로케일, 사용 가능한 로케일 목록 및 선택 사항을 유지하는 setter를 노출하며, `getLocalizedUrl`은 현재 경로를 대상 언어로 다시 작성하므로 사용자가 홈 페이지로 튕겨 나가지 않고 동일한 페이지에 머무를 수 있습니다.
 
 </Question>
-
 <Question title="지역화된 라우트에서 404 페이지는 어떻게 처리하나요?">
 
 14단계에서 다룹니다. `validatePrefix`는 URL의 로케일 세그먼트가 선언된 로케일인지 여부를 확인하여 `/xx/about`이 일반 경로로 처리되지 않고 실제 404를 반환하도록 합니다. 이 작업이 없으면 알 수 없는 접두사가 조용히 해석되어 검색 엔진이 중복 페이지를 인덱싱하게 됩니다.
 
 </Question>
-
 <Question title="AI를 사용하여 TanStack Start 앱을 자동으로 번역하려면 어떻게 하나요?">
 
 `npx intlayer fill`을 실행하세요. CLI가 누락된 번역을 찾아 자체 제공업체 및 API 키를 사용하여 원하는 LLM으로 채워줍니다. `--git-diff`를 추가하면 현재 브랜치에서 변경된 콘텐츠만 번역하므로 CI 실행 비용을 절감할 수 있습니다. [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)도 가능합니다.

package/docs/ko/intlayer_with_vanilla.md

@@ -68,37 +68,31 @@ author: aymericzip
 Intlayer는 **프레임워크에 구애받지 않는 콘텐츠 관리**, **TypeScript 지원** 및 국제화 확장(i18n)에 필요한 모든 기능을 제공하여 Vanilla JavaScript와 완벽하게 작동하도록 최적화되었습니다.
 
 </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)**를 제공합니다. 다국어 콘텐츠를 **실시간**으로 제공하여 번역가, 카피라이터, 기타 팀원과 원활하게 협업할 수 있습니다. 콘텐츠는 로컬 및/또는 원격으로 저장될 수 있습니다.
@@ -106,12 +100,9 @@ Intlayer는 단순한 i18n 솔루션 그 이상으로 관리에 도움이 되는
 </Accordion>
 </AccordionGroup>
 
----
-
 ## Vanilla JS 애플리케이션에 Intlayer를 설정하는 단계별 가이드
 
 <Steps>
-
 <Step number={1} title="종속성 설치">
 
 npm을 사용하여 필요한 패키지를 설치합니다:
@@ -173,9 +164,24 @@ bun x intlayer build
 > `intlayer standalone` CLI의 번들링 내보내기는 설정에 특화된 미사용 패키지, 로케일 및 비필수 로직(리디렉션 또는 접두사 등)을 트리 쉐이킹(tree-shaking)하여 최적화된 빌드를 생성합니다.
 
 </Step>
-
 <Step number={2} title="프로젝트 구성">
 
+### 아키텍처
+
+이 아키텍처에서는 코어 `intlayer`가 프론트엔드 프레임워크 없는 표준 JavaScript 또는 TypeScript 환경에서 사전을 선언하고 사용할 수 있는 JavaScript API를 제공합니다.
+
+```bash
+.
+├── src
+│   ├── app.content.mjs
+│   └── main.js
+├── index.html
+├── intlayer.config.mjs
+└── package.json
+```
+
+### 설정
+
 애플리케이션의 언어를 구성하기 위한 설정 파일을 생성합니다:
 
 ```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
@@ -199,7 +205,6 @@ export default config;
 > 이 설정 파일을 통해 로컬라이즈된 URL, 미들웨어 리디렉션, 쿠키 이름, 콘텐츠 선언 위치 및 확장자, 콘솔 내 Intlayer 로그 비활성화 등을 구성할 수 있습니다. 사용 가능한 전체 매개변수 목록은 [구성 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)를 참조하세요.
 
 </Step>
-
 <Step number={3} title="HTML에 번들 가져오기">
 
 `intlayer.js` 번들을 생성한 후, HTML 파일에서 가져올 수 있습니다:
@@ -225,7 +230,6 @@ export default config;
 번들은 `window` 객체에 `Intlayer`와 `VanillaIntlayer`를 글로벌 객체로 노출합니다.
 
 </Step>
-
 <Step number={4} title="진입점에서 Intlayer 부트스트랩">
 
 `src/main.js`에서 콘텐츠가 렌더링되기 **전**에 `installIntlayer()`를 호출하여 글로벌 로케일 싱글톤이 준비되도록 합니다.
@@ -247,7 +251,6 @@ installIntlayerMarkdown();
 ```
 
 </Step>
-
 <Step number={5} title="콘텐츠 선언하기">
 
 번역을 저장하기 위해 콘텐츠 선언을 생성하고 관리합니다:
@@ -327,7 +330,6 @@ export default appContent;
 > 자세한 내용은 [콘텐츠 선언 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/content_file.md)를 참조하세요.
 
 </Step>
-
 <Step number={6} title="JavaScript에서 Intlayer 사용하기">
 
 `window.VanillaIntlayer` 객체는 API 헬퍼를 제공합니다. `useIntlayer(key, locale?)`는 주어진 키에 대한 번역된 콘텐츠를 반환합니다.
@@ -363,7 +365,6 @@ document.querySelector(".read-the-docs").textContent = String(
 > ```
 
 </Step>
-
 <Step number={7} title="콘텐츠 언어 변경하기" isOptional={true}>
 
 콘텐츠의 언어를 변경하려면 `useLocale`에서 노출된 `setLocale` 함수를 사용하세요.
@@ -400,7 +401,6 @@ export function setupLocaleSwitcher(container) {
 ```
 
 </Step>
-
 <Step number={8} title="HTML 언어 및 방향 속성 전환" isOptional={true}>
 
 접근성 및 SEO를 위해 `<html>` 태그의 `lang` 및 `dir` 속성을 현재 로케일에 맞게 업데이트합니다.
@@ -420,7 +420,6 @@ useLocale({
 ```
 
 </Step>
-
 <Step number={9} title="로케일별 딕셔너리 지연 로드 (Lazy-load)" isOptional={true}>
 
 로케일별로 딕셔너리를 지연 로드하려면 `useDictionaryDynamic`을 사용할 수 있습니다. 이는 초기 `intlayer.js` 파일에 모든 번역을 포함하고 싶지 않을 때 유용합니다.
@@ -476,8 +475,6 @@ Intlayer 개발 경험을 향상시키려면 공식 **Intlayer VS Code 확장
 
 확장 프로그램 사용법에 대한 자세한 내용은 [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)를 사용하여 콘텐츠를 외부화할 수 있습니다.
@@ -491,25 +488,21 @@ Intlayer 개발 경험을 향상시키려면 공식 **Intlayer VS Code 확장
 네. 바로 그것이 이 가이드에서 다루는 내용입니다. 3단계에 표시된 대로 HTML에서 직접 `vanilla-intlayer` 번들을 가져오고, 엔트리 포인트에서 부트스트랩한 다음 `useIntlayer`로 콘텐츠를 읽으면 됩니다. Vite, webpack 또는 별도의 빌드 파이프라인이 필요하지 않습니다.
 
 </Question>
-
 <Question title="i18n이 페이지 용량에 얼마나 영향을 미치나요?">
 
 런타임 카탈로그보다 훨씬 적습니다. 페이지는 렌더링하지 않는 언어를 절대 다운로드하지 않기 때문입니다. 콘텐츠는 미리 컴파일된 사전에서 확인되며, 로케일별 지연 로딩을 통해 방문자가 언어를 전환할 때까지 다른 언어가 초기 페이로드에 포함되지 않습니다. 일반적인 대안들과 비교했을 때 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/dynamic_dictionaries/index.md) 및 [벤치마크](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/benchmark/index.md)를 참조하세요.
 
 </Question>
-
 <Question title="스크립트를 다시 작성하지 않고 i18next에서 마이그레이션할 수 있나요?">
 
 대부분 가능합니다. 콘텐츠를 이전하려면 [i18next 마이그레이션 가이드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/migration_from_i18next_to_intlayer.md)를 따르세요. 점진적으로 마이그레이션할 수도 있습니다: [sync JSON 플러그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/plugins/sync-json.md)은 기존 JSON 카탈로그를 단일 진실 공급원(source of truth)으로 유지하면서 Intlayer 사전을 생성하므로 스크립트를 하나씩 이전하는 동안 두 계층의 동기화가 유지됩니다.
 
 </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)을 참조하세요.
@@ -517,7 +510,6 @@ Intlayer 개발 경험을 향상시키려면 공식 **Intlayer VS Code 확장
 완전 자동화된 파이프라인을 위해 [Intlayer 컴파일러](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compiler.md)는 빌드 타임에 JSX, TSX, Vue 및 Svelte 소스에서 동일한 작업을 수행하여 변경될 때마다 사전을 생성하고 HMR을 통해 동기화하므로 수동으로 키를 관리할 필요가 없습니다. 정적 분석으로 작동하므로 런타임에만 존재하는 문자열은 제외되며, 사용자 텍스트와 애플리케이션 로직을 구분하기 위해 몇 가지 주석이 필요합니다.
 
 </Question>
-
 <Question title="사용 가능한 에디터 및 AI 에이전트 도구는 무엇이 있나요?">
 
 5가지 도구가 모두 선택 사항으로 제공됩니다:
@@ -529,7 +521,6 @@ Intlayer 개발 경험을 향상시키려면 공식 **Intlayer VS Code 확장
 - **[ESLint 플러그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/eslint.md)**: `no-raw-text` 규칙으로 하드코딩된 문자열을 표시하고, 정적 사전 키 및 사용되지 않는 콘텐츠에 대한 추가 규칙을 제공합니다.
 
 </Question>
-
 <Question title="순수 JavaScript 사이트를 국제화하는 데 사용할 수 있는 다양한 솔루션은 무엇인가요?">
 
 - **직접 작성한 사전 객체**, 일반적으로 `fetch`로 로드되는 언어당 하나의 JSON 파일: 의존성은 없지만 타입 안전성, 복수형 규칙이 없으며 번역 누락을 알려주는 도구가 없습니다.
@@ -539,49 +530,41 @@ Intlayer 개발 경험을 향상시키려면 공식 **Intlayer VS Code 확장
 [왜 Intlayer인가](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/interest_of_intlayer.md)를 참조하세요.
 
 </Question>
-
 <Question title="번역을 읽고 DOM에 어떻게 적용하나요?">
 
 6단계에 나와 있듯이 사전 키로 `useIntlayer`를 호출하고 반환된 값을 노드에 직접 작성합니다. 프레임워크가 없기 때문에 스스로 다시 렌더링되지 않으며, 7단계에서 다루는 것처럼 로케일이 변경될 때 노드를 수동으로 업데이트합니다.
 
 </Question>
-
 <Question title="방문자의 언어는 어떻게 감지하나요?">
 
 `routing.storage`에 나열된 소스(일반적으로 쿠키 우선, 그 다음 `Accept-Language` 헤더 순)에서 감지하며, 기본 로케일로 폴백됩니다. 방문자가 명시적으로 선택한 언어는 저장되어 다음 방문 시에도 유지됩니다. [설정 참조](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)를 참조하세요.
 
 </Question>
-
 <Question title="아랍어나 히브리어와 같은 RTL(우에서 좌로 쓰는) 언어는 어떻게 지원하나요?">
 
 8단계에서 다룹니다. `getHTMLTextDir`은 로케일에 대해 `ltr`, `rtl` 또는 `auto`를 반환하므로 활성 로케일에 따라 `html` 요소에 `lang` 및 `dir`을 설정하고 나머지는 CSS 논리적 속성에 맡기면 됩니다.
 
 </Question>
-
 <Question title="방문자가 모든 언어를 한 번에 다운로드하나요?">
 
 원하지 않는다면 그렇지 않습니다. 9단계에서 로케일별 사전 지연 로딩을 다루므로 페이지는 한 언어만 로드하고 방문자가 전환할 때만 다른 언어를 가져옵니다. [동적 사전](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/index.md)을 참조하세요.
 
 </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)도 가능합니다.