@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/docs/ko/intlayer_with_vite+svelte.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-04-18
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Vite + Svelte i18n - 앱을 번역하는 완전 가이드"
 description: "i18next는 이제 그만. 2026년 다국어 (i18n) Vite + Svelte 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
 keywords:
@@ -126,32 +126,50 @@ Intlayer는 단순한 i18n 솔루션 그 이상으로 관리에 도움이 되는
 
 GitHub에서 [애플리케이션 템플릿](https://github.com/aymericzip/intlayer-vite-svelte-template)을 확인하세요.
 
-### 1단계: 의존성 설치
+<Steps>
+
+<Step number={1} title="의존성 설치">
 
 npm을 사용하여 필요한 패키지를 설치하세요:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` 플래그는 선택 사항입니다. AI 에이전트인 경우 `intlayer-cli init`를 사용하세요.
+
+> 이 명령은 환경을 감지하고 필요한 패키지를 설치합니다. 예를 들어:
+
 ```bash packageManager="npm"
 npm install intlayer svelte-intlayer
 npm install vite-intlayer --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer svelte-intlayer
 pnpm add vite-intlayer --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer svelte-intlayer
 yarn add vite-intlayer --save-dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer svelte-intlayer
 bun add vite-intlayer --save-dev
-bun x intlayer init
 ```
 
 - **intlayer**
@@ -164,7 +182,9 @@ bun x intlayer init
 - **vite-intlayer**
   Intlayer를 [Vite 번들러](https://vite.dev/guide/why.html#why-bundle-for-production)와 통합하기 위한 Vite 플러그인과, 사용자의 선호 로케일 감지, 쿠키 관리, URL 리디렉션 처리를 위한 미들웨어를 포함합니다.
 
-### 2단계: 프로젝트 구성
+</Step>
+
+<Step number={2} title="프로젝트 구성">
 
 애플리케이션의 언어를 구성하기 위한 설정 파일을 생성합니다:
 
@@ -188,6 +208,10 @@ export default config;
 
 > 이 구성 파일을 통해 로컬라이즈된 URL, 미들웨어 리디렉션, 쿠키 이름, 콘텐츠 선언의 위치 및 확장자 설정, 콘솔에서 Intlayer 로그 비활성화 등 다양한 설정을 할 수 있습니다. 사용 가능한 모든 매개변수 목록은 [구성 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)를 참조하세요.
 
+</Step>
+
+</Steps>
+
 <Steps>
 
 <Step number={3} title="Vite 구성에 Intlayer 통합하기">
@@ -271,6 +295,8 @@ 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.
+
 `vite.config.ts`를 업데이트하여 `intlayerCompiler` 플러그인을 포함합니다.
 
 ```ts fileName="vite.config.ts"
@@ -280,7 +306,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 컴파일러 플러그인을 추가합니다
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```
@@ -305,9 +331,7 @@ bun run build # Or bun run dev
 </Tabs>
 </Step>
 
-</Steps>
-
-### 4단계: 콘텐츠 선언하기
+<Step number={4} title="콘텐츠 선언하기">
 
 번역을 저장하기 위해 콘텐츠 선언을 생성하고 관리하세요:
 
@@ -349,7 +373,9 @@ export default appContent;
 
 > 자세한 내용은 [콘텐츠 선언 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/content_file.md)를 참조하세요.
 
-### 5단계: 코드에서 Intlayer 사용하기
+</Step>
+
+<Step number={5} title="코드에서 Intlayer 사용하기">
 
 ```svelte fileName="src/App.svelte"
 <script>
@@ -371,7 +397,9 @@ export default appContent;
 <div aria-label={String($content.title)}></div>
 ```
 
-### (선택 사항) 6단계: 콘텐츠 언어 변경하기
+</Step>
+
+<Step number={6} title="콘텐츠 언어 변경하기" isOptional={true}>
 
 ```svelte fileName="src/App.svelte"
 <script lang="ts">
@@ -400,7 +428,9 @@ const changeLocale = (event: Event) => {
 </div>
 ```
 
-### (선택 사항) 7단계: 마크다운 렌더링
+</Step>
+
+<Step number={7} title="마크다운 렌더링" isOptional={true}>
 
 Intlayer는 Svelte 애플리케이션에서 마크다운 콘텐츠를 직접 렌더링하는 것을 지원합니다. 기본적으로 마크다운은 일반 텍스트로 처리됩니다. 마크다운을 풍부한 HTML로 변환하려면 `@humanspeak/svelte-markdown` 또는 다른 마크다운 파서를 통합할 수 있습니다.
 
@@ -421,13 +451,17 @@ Intlayer는 Svelte 애플리케이션에서 마크다운 콘텐츠를 직접 렌
 
 > `content.markdownContent.metadata.xxx` 속성을 사용하여 마크다운 프론트매터 데이터에도 접근할 수 있습니다.
 
-### (선택 사항) 8단계: intlayer 에디터 / CMS 설정하기
+</Step>
+
+<Step number={8} title="intlayer 에디터 / CMS 설정하기" isOptional={true}>
 
 intlayer 에디터를 설정하려면 [intlayer 에디터 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_visual_editor.md)를 따라야 합니다.
 
 intlayer CMS를 설정하려면 [intlayer CMS 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_CMS.md)를 따라야 합니다.
 
-### (선택 사항) 7단계: 애플리케이션에 지역화된 라우팅 추가하기
+</Step>
+
+<Step number={7} title="애플리케이션에 지역화된 라우팅 추가하기" isOptional={true}>
 
 Svelte 애플리케이션에서 지역화된 라우팅을 처리하려면, `svelte-spa-router`와 Intlayer의 `localeFlatMap`을 함께 사용하여 각 로케일에 대한 라우트를 생성할 수 있습니다.
 
@@ -525,12 +559,12 @@ $: content = useIntlayer('app', locale);
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
 import { svelte } from "@sveltejs/vite-plugin-svelte";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 typescript {3,7} fileName="vite.config.ts" codeFormat="typescript"
 import { defineConfig } from "vite";
 import { svelte } from "@sveltejs/vite-plugin-svelte";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
@@ -539,7 +573,9 @@ export default defineConfig({
 });
 ```
 
-### (선택 사항) 8단계: 로케일이 변경될 때 URL 변경하기
+</Step>
+
+<Step number={8} title="로케일이 변경될 때 URL 변경하기" isOptional={true}>
 
 사용자가 언어를 전환하고 URL을 그에 맞게 업데이트할 수 있도록 `LocaleSwitcher` 컴포넌트를 만들 수 있습니다. 이 컴포넌트는 `intlayer`의 `getLocalizedUrl`과 `svelte-spa-router`의 `push`를 사용합니다.
 
@@ -575,33 +611,9 @@ const changeLocale = (event: Event) => {
 </div>
 ```
 
-### Git 구성
-
-Intlayer가 생성하는 파일은 Git 저장소에 커밋하지 않도록 무시하는 것이 좋습니다.
-
-이를 위해 `.gitignore` 파일에 다음 지침을 추가할 수 있습니다:
-
-```bash
-#  Intlayer가 생성하는 파일 무시
-.intlayer
-```
-
-### VS Code 확장 프로그램
-
-Intlayer 개발 경험을 향상시키기 위해 공식 **Intlayer VS Code 확장 프로그램**을 설치할 수 있습니다.
-
-[VS Code 마켓플레이스에서 설치하기](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
-
-이 확장 프로그램은 다음을 제공합니다:
-
-- 번역 키에 대한 **자동 완성** 기능.
-- 누락된 번역에 대한 **실시간 오류 감지**.
-- 번역된 콘텐츠의 **인라인 미리보기**.
-- 번역을 쉽게 생성하고 업데이트할 수 있는 **빠른 작업**.
-
-확장 프로그램 사용 방법에 대한 자세한 내용은 [Intlayer VS Code 확장 프로그램 문서](https://intlayer.org/doc/vs-code-extension)를 참조하세요.
+</Step>
 
----
+</Steps>
 
 ### (선택) 사이트맵과 robots.txt(빌드 시 생성)
 
@@ -677,6 +689,32 @@ console.log("SEO files generated successfully.");
 
 pnpm이나 yarn을 쓰면 명령을 맞게 바꾸세요. CI에서 호출해도 됩니다.
 
+### Git 구성
+
+Intlayer가 생성하는 파일은 Git 저장소에 커밋하지 않도록 무시하는 것이 좋습니다.
+
+이를 위해 `.gitignore` 파일에 다음 지침을 추가할 수 있습니다:
+
+```bash
+#  Intlayer가 생성하는 파일 무시
+.intlayer
+```
+
+### VS Code 확장 프로그램
+
+Intlayer 개발 경험을 향상시키기 위해 공식 **Intlayer VS Code 확장 프로그램**을 설치할 수 있습니다.
+
+[VS Code 마켓플레이스에서 설치하기](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)를 사용하여 콘텐츠를 외부화할 수 있습니다.

package/docs/ko/intlayer_with_vite+vanilla.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-03-23
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Vite + Vanilla JS i18n - 앱을 번역하는 완전 가이드"
 description: "i18next는 이제 그만. 2026년 다국어 (i18n) Vite + Vanilla JS 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
 keywords:
@@ -112,32 +112,50 @@ Intlayer는 단순한 i18n 솔루션 그 이상으로 관리에 도움이 되는
 
 ## Vite 및 Vanilla JS 애플리케이션에서 Intlayer를 설정하는 단계별 가이드
 
-### 1단계: 종속성 설치
+<Steps>
+
+<Step number={1} title="종속성 설치">
 
 npm을 사용하여 필요한 패키지를 설치합니다:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` 플래그는 선택 사항입니다. AI 에이전트인 경우 `intlayer-cli init`를 사용하세요.
+
+> 이 명령은 환경을 감지하고 필요한 패키지를 설치합니다. 예를 들어:
+
 ```bash packageManager="npm"
 npm install intlayer vanilla-intlayer
 npm install vite-intlayer --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer vanilla-intlayer
 pnpm add vite-intlayer --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer vanilla-intlayer
 yarn add vite-intlayer --save-dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer vanilla-intlayer
 bun add vite-intlayer --dev
-bun x intlayer init
 ```
 
 - **intlayer**
@@ -149,7 +167,9 @@ bun x intlayer init
 - **vite-intlayer**
   Intlayer를 [Vite 번들러](https://vite.dev/guide/why.html#why-bundle-for-production)와 통합하기 위한 Vite 플러그인과 사용자의 선호 로케일 감지, 쿠키 관리 및 URL 리디렉션 처리를 위한 미들웨어를 포함합니다.
 
-### 2단계: 프로젝트 구성
+</Step>
+
+<Step number={2} title="프로젝트 구성">
 
 애플리케이션의 언어를 구성하기 위해 설정 파일을 생성합니다:
 
@@ -173,7 +193,9 @@ export default config;
 
 > 이 구성 파일을 통해 로컬라이즈된 URL, 미들웨어 리디렉션, 쿠키 이름, 콘텐츠 선언의 위치 및 확장자, 콘솔에서 Intlayer 로그 비활성화 등을 설정할 수 있습니다. 사용 가능한 파라미터의 전체 목록은 [구성 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)를 참조하세요.
 
-### 3단계: Vite 구성에 Intlayer 통합
+</Step>
+
+<Step number={3} title="Vite 구성에 Intlayer 통합">
 
 구성 파일에 intlayer 플러그인을 추가합니다.
 
@@ -183,13 +205,21 @@ import { intlayer } from "vite-intlayer";
 
 // https://vitejs.dev/config/
 export default defineConfig({
-  plugins: [intlayer()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 
 > `intlayer()` Vite 플러그인은 Intlayer를 Vite와 통합하는 데 사용됩니다. 콘텐츠 선언 파일의 빌드를 보장하고 개발 모드에서 이를 모니터링합니다. Vite 애플리케이션 내에서 Intlayer 환경 변수를 정의합니다. 또한 성능 최적화를 위한 별칭을 제공합니다.
 
-### 4단계: 엔트리 포인트에서 Intlayer 부트스트랩
+</Step>
+
+<Step number={4} title="엔트리 포인트에서 Intlayer 부트스트랩">
 
 글로벌 로케일 싱글톤이 준비되도록 콘텐츠가 렌더링되기 **전**에 `installIntlayer()`를 호출합니다.
 
@@ -214,7 +244,9 @@ installIntlayerMarkdown();
 import "./app.js";
 ```
 
-### 5단계: 콘텐츠 선언하기
+</Step>
+
+<Step number={5} title="콘텐츠 선언하기">
 
 번역을 저장하기 위해 콘텐츠 선언을 생성하고 관리합니다:
 
@@ -292,7 +324,9 @@ export default appContent;
 >
 > 자세한 내용은 [콘텐츠 선언 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/content_file.md)를 참조하세요.
 
-### 6단계: JavaScript에서 Intlayer 사용하기
+</Step>
+
+<Step number={6} title="JavaScript에서 Intlayer 사용하기">
 
 `vanilla-intlayer`는 `react-intlayer` 서비스 API를 따릅니다: `useIntlayer(key, locale?)`는 번역된 콘텐츠를 직접 반환합니다. 결과에 `.onChange()`를 체이닝하여 로케일 변경을 구독할 수 있으며, 이는 React 리렌더링과 명시적으로 동일한 효과를 냅니다.
 
@@ -328,7 +362,9 @@ document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =
 > img.alt = content.viteLogoLabel.value;
 > ```
 
-### (선택 사항) 7단계: 콘텐츠의 언어 변경하기
+</Step>
+
+<Step number={7} title="콘텐츠의 언어 변경하기" isOptional={true}>
 
 콘텐츠의 언어를 변경하려면 `useLocale`에서 노출된 `setLocale` 함수를 사용하세요.
 
@@ -363,7 +399,9 @@ export function setupLocaleSwitcher(container: HTMLElement): () => void {
 }
 ```
 
-### (선택 사항) 8단계: 마크다운 및 HTML 콘텐츠 렌더링하기
+</Step>
+
+<Step number={8} title="마크다운 및 HTML 콘텐츠 렌더링하기" isOptional={true}>
 
 Intlayer는 `md()` 및 `html()` 콘텐츠 선언을 지원합니다. Vanilla JS에서 컴파일된 출력은 `innerHTML`을 통해 원시 HTML로 삽입됩니다.
 
@@ -422,7 +460,9 @@ document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =
 > });
 > ```
 
-### (선택 사항) 9단계: 애플리케이션에 로컬라이즈된 라우팅 추가하기
+</Step>
+
+<Step number={9} title="애플리케이션에 로컬라이즈된 라우팅 추가하기" isOptional={true}>
 
 각 언어에 대해 고유한 라우트를 만들려면(SEO에 유용함) Vite 구성에서 서버 측 로케일 감지를 위해 `intlayerProxy`를 사용할 수 있습니다.
 
@@ -432,17 +472,22 @@ document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =
 
 ```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // 가장 먼저 위치해야 합니다
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```
 
-### (선택 사항) 10단계: 로케일 변경 시 URL 변경하기
+</Step>
+
+<Step number={10} title="로케일 변경 시 URL 변경하기" isOptional={true}>
 
 로케일이 변경될 때 브라우저 URL을 업데이트하려면 Intlayer를 설치한 후 `useRewriteURL()`을 호출하세요:
 
@@ -456,7 +501,9 @@ installIntlayer();
 const stopRewriteURL = useRewriteURL();
 ```
 
-### (선택 사항) 11단계: HTML 언어 및 방향 속성 전환하기
+</Step>
+
+<Step number={11} title="HTML 언어 및 방향 속성 전환하기" isOptional={true}>
 
 접근성 및 SEO를 위해 `<html>` 태그의 `lang` 및 `dir` 속성을 현재 로케일에 맞게 업데이트하세요.
 
@@ -474,7 +521,9 @@ useLocale({
 });
 ```
 
-### (선택 사항) 12단계: 로케일별 딕셔너리 레이지 로딩 (Lazy-load)
+</Step>
+
+<Step number={12} title="로케일별 딕셔너리 레이지 로딩 (Lazy-load)" isOptional={true}>
 
 대규모 앱의 경우 각 로케일의 딕셔너리를 자체 청크로 나누고 싶을 수 있습니다. Vite의 동적 `import()`와 함께 `useDictionaryDynamic`을 사용하세요:
 
@@ -497,7 +546,9 @@ const unsubscribe = useDictionaryDynamic(
 
 > 각 로케일의 번들은 해당 로케일이 활성화될 때만 가져오고 결과는 캐시됩니다. 동일한 로케일로의 후속 전환은 즉시 이루어집니다.
 
-### (선택 사항) 13단계: 컴포넌트의 콘텐츠 추출하기
+</Step>
+
+<Step number={13} title="컴포넌트의 콘텐츠 추출하기" isOptional={true}>
 
 기존 코드베이스가 있는 경우 수천 개의 파일을 변환하는 데 시간이 많이 걸릴 수 있습니다.
 
@@ -561,6 +612,8 @@ 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.
+
 `intlayerCompiler` 플러그인을 포함하도록 `vite.config.ts`를 업데이트합니다:
 
 ```ts fileName="vite.config.ts"
@@ -570,7 +623,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 컴파일러 플러그인 추가
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```
@@ -594,6 +647,10 @@ bun run build # 또는 bun run dev
  </Tab>
 </Tabs>
 
+</Step>
+
+</Steps>
+
 ### (선택) 사이트맵과 robots.txt(빌드 시 생성)
 
 Intlayer는 `generateSitemap`과 `getMultilingualUrls`로 크롤러용 다국어 `sitemap.xml`과 `robots.txt`를 만들어 `public/`에 자동으로 쓸 수 있습니다. 보통 Vite 실행 **전에** 작은 Node 스크립트를 돌립니다(예: npm `predev` / `prebuild`).