@intlayer/docs 9.0.0-canary.3 → 9.0.0-canary.5

package/docs/ko/intlayer_with_vite+preact.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-04-18
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Vite + Preact i18n - 앱을 번역하는 완전 가이드"
 description: "i18next는 이제 그만. 2026년 다국어 (i18n) Vite + Preact 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
 keywords:
@@ -120,32 +120,50 @@ Intlayer는 단순한 i18n 솔루션 그 이상으로 관리에 도움이 되는
 
 GitHub에서 [애플리케이션 템플릿](https://github.com/aymericzip/intlayer-vite-preact-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 preact-intlayer
 npm install vite-intlayer --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer preact-intlayer
 pnpm add vite-intlayer --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer preact-intlayer
 yarn add vite-intlayer --save-dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer preact-intlayer
 bun add vite-intlayer --dev
-bun x intlayer init
 ```
 
 - **intlayer**
@@ -160,7 +178,9 @@ bun x intlayer init
 
   Intlayer를 [Vite 번들러](https://vite.dev/guide/why.html#why-bundle-for-production)와 통합하기 위한 Vite 플러그인과, 사용자의 선호 로케일 감지, 쿠키 관리, URL 리디렉션 처리를 위한 미들웨어를 포함합니다.
 
-### 2단계: 프로젝트 구성
+</Step>
+
+<Step number={2} title="프로젝트 구성">
 
 애플리케이션의 언어를 구성하기 위해 설정 파일을 만드세요:
 
@@ -188,7 +208,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 플러그인을 구성에 추가하세요.
 
@@ -205,7 +227,9 @@ export default defineConfig({
 
 > `intlayer()` Vite 플러그인은 Intlayer를 Vite와 통합하기 위해 사용됩니다. 이 플러그인은 콘텐츠 선언 파일의 빌드를 보장하고 개발 모드에서 이를 모니터링합니다. 또한 Vite 애플리케이션 내에서 Intlayer 환경 변수를 정의하며, 성능 최적화를 위해 별칭(alias)도 제공합니다.
 
-### 4단계: 콘텐츠 선언하기
+</Step>
+
+<Step number={4} title="콘텐츠 선언하기">
 
 번역을 저장하기 위해 콘텐츠 선언을 생성하고 관리하세요:
 
@@ -327,7 +351,9 @@ export default appContent;
 
 > 콘텐츠 파일에 TSX 코드가 포함된 경우, `import { h } from "preact";`를 임포트하거나 JSX 프래그마가 Preact에 맞게 올바르게 설정되어 있는지 확인해야 할 수 있습니다.
 
-### 5단계: 코드에서 Intlayer 사용하기
+</Step>
+
+<Step number={5} title="코드에서 Intlayer 사용하기">
 
 애플리케이션 전반에서 콘텐츠 사전을 접근하세요:
 
@@ -397,7 +423,9 @@ export default App;
 
 > `useIntlayer` 훅에 대해 더 알아보려면 [문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/react-intlayer/useIntlayer.md)를 참고하세요 (`preact-intlayer`도 API가 유사합니다).
 
-### (선택 사항) 6단계: 콘텐츠의 언어 변경하기
+</Step>
+
+<Step number={6} title="콘텐츠의 언어 변경하기" isOptional={true}>
 
 콘텐츠의 언어를 변경하려면 `useLocale` 훅에서 제공하는 `setLocale` 함수를 사용할 수 있습니다. 이 함수는 애플리케이션의 로케일을 설정하고 그에 따라 콘텐츠를 업데이트할 수 있게 해줍니다.
 
@@ -421,7 +449,9 @@ export default LocaleSwitcher;
 
 > `useLocale` 훅에 대해 더 알아보려면 [문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/react-intlayer/useLocale.md)를 참조하세요 (`preact-intlayer`와 API가 유사합니다).
 
-### (선택 사항) 7단계: 애플리케이션에 로컬라이즈된 라우팅 추가
+</Step>
+
+<Step number={7} title="애플리케이션에 로컬라이즈된 라우팅 추가" isOptional={true}>
 
 이 단계의 목적은 각 언어별로 고유한 경로를 만드는 것입니다. 이는 SEO 및 SEO 친화적인 URL에 유용합니다.
 예시:
@@ -484,7 +514,9 @@ const App: FunctionalComponent = () => (
 export default App;
 ```
 
-### (선택 사항) 8단계: 로캘이 변경될 때 URL 변경
+</Step>
+
+<Step number={8} title="로캘이 변경될 때 URL 변경" isOptional={true}>
 
 로캘이 변경될 때 URL을 변경하려면 `useLocale` 훅에서 제공하는 `onLocaleChange` 속성을 사용할 수 있습니다. 이와 동시에 `preact-iso`의 `useLocation`에서 제공하는 `route` 메서드를 사용하여 URL 경로를 업데이트할 수 있습니다.
 
@@ -558,7 +590,9 @@ export default LocaleSwitcher;
 >
 > > - [`useLocale` 훅](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/react-intlayer/useLocale.md) (API는 `preact-intlayer`와 유사합니다)> - [`getLocaleName` 훅](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getLocaleName.md)> - [`getLocalizedUrl` 훅](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getLocalizedUrl.md)> - [`getHTMLTextDir` 훅](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/intlayer/getHTMLTextDir.md)> - [`hreflang` 속성](https://developers.google.com/search/docs/specialty/international/localized-versions?hl=ko)> - [`lang` 속성](https://developer.mozilla.org/ko/docs/Web/HTML/Global_attributes/lang)> - [`dir` 속성](https://developer.mozilla.org/ko/docs/Web/HTML/Global_attributes/dir)> - [`aria-current` 속성](https://developer.mozilla.org/ko/docs/Web/Accessibility/ARIA/Attributes/aria-current)> - [Popover API](https://developer.mozilla.org/ko/docs/Web/API/Popover_API)
 
-### (선택 사항) 9단계: HTML 언어 및 방향 속성 전환
+</Step>
+
+<Step number={9} title="HTML 언어 및 방향 속성 전환" isOptional={true}>
 
 애플리케이션이 다국어를 지원할 때, 현재 로케일에 맞춰 `<html>` 태그의 `lang` 및 `dir` 속성을 업데이트하는 것이 중요합니다. 이를 통해 다음을 보장할 수 있습니다:
 
@@ -625,7 +659,9 @@ const App: FunctionalComponent = () => (
 export default App;
 ```
 
-### (선택 사항) 10단계: 로컬라이즈된 링크 컴포넌트 만들기
+</Step>
+
+<Step number={10} title="로컬라이즈된 링크 컴포넌트 만들기" isOptional={true}>
 
 애플리케이션의 내비게이션이 현재 로케일을 존중하도록 하려면, 커스텀 `Link` 컴포넌트를 만들 수 있습니다. 이 컴포넌트는 내부 URL에 자동으로 현재 언어 접두사를 붙입니다.
 
@@ -679,90 +715,6 @@ export const Link = forwardRef<HTMLAnchorElement, LinkProps>(
 Link.displayName = "Link";
 ```
 
-#### 작동 방식
-
-- **외부 링크 감지**:  
-  헬퍼 함수 `checkIsExternalLink`는 URL이 외부 링크인지 확인합니다. 외부 링크는 로컬라이제이션이 필요하지 않으므로 변경되지 않은 상태로 유지됩니다.
-- **현재 로케일 검색**:  
-  `useLocale` 훅은 현재 로케일(예: 프랑스어의 경우 `fr`)을 제공합니다.
-- **URL 로컬라이즈**:  
-  내부 링크(즉, 비외부 링크)의 경우, `getLocalizedUrl`을 사용하여 URL에 현재 로케일을 자동으로 접두사로 붙입니다. 즉, 사용자가 프랑스어 환경에 있을 때 `/about`을 `href`로 전달하면 `/fr/about`으로 변환됩니다.
-- **링크 반환**:  
-  컴포넌트는 로컬라이즈된 URL이 포함된 `<a>` 요소를 반환하여 내비게이션이 로케일과 일치하도록 보장합니다.
-
-### (선택 사항) 11단계: Markdown 및 HTML 렌더링
-
-Intlayer는 Preact에서 Markdown 및 HTML 콘텐츠의 렌더링을 지원합니다.
-
-`.use()` 메서드를 사용하여 Markdown 및 HTML 콘텐츠의 렌더링을 커스터마이징할 수 있습니다. 이 메서드를 사용하면 특정 태그의 기본 렌더링을 오버라이드할 수 있습니다.
-
-```tsx
-import { useIntlayer } from "preact-intlayer";
-
-const { myMarkdownContent, myHtmlContent } = useIntlayer("my-component");
-
-// ...
-
-return (
-  <div>
-    {/* 기본 렌더링 */}
-    {myMarkdownContent}
-
-    {/* Markdown을 위한 커스텀 렌더링 */}
-    {myMarkdownContent.use({
-      h1: (props) => <h1 style={{ color: "red" }} {...props} />,
-    })}
-
-    {/* HTML을 위한 기본 렌더링 */}
-    {myHtmlContent}
-
-    {/* HTML을 위한 커스텀 렌더링 */}
-    {myHtmlContent.use({
-      b: (props) => <strong style={{ color: "blue" }} {...props} />,
-    })}
-  </div>
-);
-```
-
-### TypeScript 구성
-
-Intlayer는 모듈 확장을 사용하여 TypeScript의 이점을 활용하고 코드베이스를 더 견고하게 만듭니다.
-
-![Autocompletion](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
-
-![Translation error](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
-
-TypeScript 구성에 자동 생성된 타입이 포함되어 있는지 확인하세요.
-
-```json5 fileName="tsconfig.json"
-{
-  // ... 기존 TypeScript 구성
-  "compilerOptions": {
-    // ...
-    "jsx": "react-jsx",
-    "jsxImportSource": "preact", // Preact 10 이상에서 권장됨
-    // ...
-  },
-  "include": [
-    // ... 기존 TypeScript 구성
-    ".intlayer/**/*.ts", // 자동 생성된 타입 포함
-  ],
-}
-```
-
-> `tsconfig.json`이 Preact에 맞게 설정되었는지 확인하세요. 특히 `jsx`와 `jsxImportSource`를 확인하고, `preset-vite`의 기본값을 사용하지 않는 구버전 Preact의 경우 `jsxFactory`/`jsxFragmentFactory`를 확인하세요.
-
-### Git 구성
-
-Intlayer에서 생성된 파일은 무시하는 것이 좋습니다. 이를 통해 Git 저장소에 커밋되는 것을 방지할 수 있습니다.
-
-이렇게 하려면 `.gitignore` 파일에 다음 지침을 추가할 수 있습니다:
-
-```bash
-#  Intlayer에서 생성된 파일 무시
-.intlayer
-```
-
 ### VS Code 확장 프로그램
 
 Intlayer 개발 경험을 향상시키기 위해 공식 **Intlayer VS Code 확장 프로그램**을 설치할 수 있습니다.
@@ -955,6 +907,62 @@ console.log("SEO files generated successfully.");
 
 pnpm이나 yarn을 쓰면 명령을 맞게 바꾸세요. CI에서 호출해도 됩니다.
 
+### TypeScript 구성
+
+Intlayer는 모듈 augmentation을 사용하여 TypeScript의 이점을 활용하고 codebase를 더욱 강화합니다.
+
+![자동완성](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
+
+![번역 오류](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
+
+TypeScript 설정에 자동 생성된 타입이 포함되어 있는지 확인하세요.
+
+```json5 fileName="tsconfig.json"
+{
+  // ... 기존 TypeScript 설정
+  "compilerOptions": {
+    // ...
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact", // Preact 10+ 권장
+    // ...
+  },
+  "include": [
+    // ... 기존 TypeScript 설정
+    ".intlayer/**/*.ts", // 자동 생성된 타입 포함
+  ],
+}
+```
+
+> `preset-vite`의 기본값을 사용하지 않는 경우, 특히 이전 Preact 버전의 `jsxFactory`/`jsxFragmentFactory`에 대해 `tsconfig.json`이 Preact에 맞게 설정되어 있는지 확인하세요.
+
+### Git 구성
+
+Intlayer에서 생성된 파일을 무시하는 것이 좋습니다. 이를 통해 Git 저장소에 커밋하는 것을 피할 수 있습니다.
+
+이를 위해 `.gitignore` 파일에 다음 지침을 추가할 수 있습니다:
+
+```bash
+# Intlayer에서 생성된 파일 무시
+.intlayer
+```
+
+### VS Code Extension
+
+Intlayer를 사용한 개발 경험을 개선하기 위해 공식 **Intlayer VS Code Extension**을 설치할 수 있습니다.
+
+[VS Code Marketplace에서 설치](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+이 extension은 다음을 제공합니다:
+
+- 번역 키에 대한 **자동완성**.
+- 누락된 번역에 대한 **실시간 오류 감지**.
+- 번역된 콘텐츠의 **인라인 미리보기**.
+- 번역을 쉽게 만들고 업데이트하기 위한 **빠른 작업**.
+
+extension 사용 방법에 대한 자세한 내용은 [Intlayer VS Code Extension 문서](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+react.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-03-07
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Vite + React i18n - 앱을 번역하는 완전 가이드"
 description: "i18next는 이제 그만. 2026년 다국어 (i18n) Vite + React 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
 keywords:
@@ -37,6 +37,57 @@ author: aymericzip
 
 <TOC/>
 
+## 왜 다른 대안들 대신 Intlayer를 선택해야 하나요?
+
+react-i18next나 i18next와 같은 주요 솔루션과 비교했을 때, Intlayer는 다음과 같은 통합된 최적화 기능을 제공하는 솔루션입니다:
+
+<AccordionGroup>
+
+<Accordion header="완벽한 Vite 및 React 지원">
+
+Intlayer는 **컴포넌트 수준의 콘텐츠 스코핑**, **지연 로드(lazy-loaded) 번역**, 그리고 국제화(i18n) 확장에 필요한 모든 기능을 제공하여 Vite 및 React와 완벽하게 작동하도록 최적화되어 있습니다.
+
+</Accordion>
+
+<Accordion header="번들 크기">
+
+페이지에 방대한 JSON 파일을 로드하는 대신, 필요한 콘텐츠만 로드하세요. Intlayer는 **번들 및 페이지 크기를 최대 50%까지 줄이는 데** 도움을 줍니다.
+
+</Accordion>
+
+<Accordion header="유지보수성">
+
+애플리케이션의 콘텐츠를 스코핑하면 대규모 애플리케이션의 **유지보수가 용이해집니다**. 전체 콘텐츠 codebase를 검토해야 한다는 심리적 부담 없이 단일 기능 폴더를 복제하거나 삭제할 수 있습니다. 또한, Intlayer는 콘텐츠의 정확성을 보장하기 위해 **완벽한 타입 지정(fully typed)**을 지원합니다.
+
+</Accordion>
+
+<Accordion header="AI 에이전트">
+
+콘텐츠를 같은 위치에 배치(Co-locating)하면 대규모 언어 모델(LLM)에 필요한 문맥이 줄어듭니다. Intlayer는 또한 누락된 번역을 테스트하기 위한 **CLI**, **[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/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/ko/intlayer_CMS.md)을 제공합니다.
+
+</Accordion>
+
+<Accordion header="성능">
+
+방대한 JSON 파일을 컴포넌트에 연결하면 성능 및 반응성 문제가 발생할 수 있습니다. Intlayer는 빌드 타임에 콘텐츠 로딩을 최적화합니다.
+
+</Accordion>
+
+<Accordion header="비개발자와의 확장성">
+
+단순한 i18n 솔루션 그 이상으로, Intlayer는 **자체 호스팅 가능한 [시각적 편집기(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)**를 제공하여 다국어 콘텐츠를 **실시간**으로 관리할 수 있게 도와주며, 번역가, 카피라이터 및 기타 팀원과의 협업을 원활하게 만듭니다. 콘텐츠는 로컬 및/또는 원격으로 저장할 수 있습니다.
+
+</Accordion>
+</AccordionGroup>
+
+---
+
 ## 대안보다 Intlayer를 선택해야 하는 이유는 무엇입니까?
 
 'react-i18next' 또는 'i18next'와 같은 주요 솔루션과 비교할 때 Intlayer는 다음과 같은 통합 최적화가 제공되는 솔루션입니다.
@@ -88,7 +139,9 @@ Intlayer는 단순한 i18n 솔루션 그 이상으로 관리에 도움이 되는
 
 ---
 
-### (선택 사항) 8단계: 로케일이 변경될 때 URL 변경하기
+<Steps>
+
+<Step number={8} title="로케일이 변경될 때 URL 변경하기" isOptional={true}>
 
 로케일이 변경될 때 URL을 변경하려면, `useLocale` 훅에서 제공하는 `onLocaleChange` 속성을 사용할 수 있습니다. 동시에, `react-router-dom`의 `useLocation`과 `useNavigate` 훅을 사용하여 URL 경로를 업데이트할 수 있습니다.
 
@@ -172,6 +225,35 @@ const LocaleSwitcher: FC = () => {
 
 ---
 
+#### Hook 구현하기
+
+HTML 속성을 관리하기 위한 커스텀 hook을 생성합니다. 이 hook은 로케일 변경을 감지하고 그에 따라 속성을 업데이트합니다:
+
+```tsx fileName="src/hooks/useI18nHTMLAttributes.tsx" codeFormat={["typescript", "esm"]}
+import { useEffect } from "react";
+import { useLocale } from "react-intlayer";
+import { getHTMLTextDir } from "intlayer";
+
+/**
+ * 현재 로케일을 기반으로 HTML <html> 요소의 `lang` 및 `dir` 속성을 업데이트합니다.
+ * - `lang`: 브라우저와 검색 엔진에 페이지의 언어를 알립니다.
+ * - `dir`: 올바른 읽기 순서를 보장합니다 (예: 영어의 경우 'ltr', 아랍어의 경우 'rtl').
+ *
+ * 이 동적 업데이트는 올바른 텍스트 렌더링, 접근성 및 SEO에 필수적입니다.
+ */
+export const useI18nHTMLAttributes = () => {
+  const { locale } = useLocale();
+
+  useEffect(() => {
+    // 언어 속성을 현재 로케일로 업데이트합니다.
+    document.documentElement.lang = locale;
+
+    // 현재 로케일을 기반으로 텍스트 방향을 설정합니다.
+    document.documentElement.dir = getHTMLTextDir(locale);
+  }, [locale]);
+};
+```
+
 #### 훅 구현하기
 
 HTML 속성을 관리하는 커스텀 훅을 만듭니다. 이 훅은 로케일 변경을 감지하여 속성을 적절히 업데이트합니다:
@@ -201,7 +283,9 @@ export const useI18nHTMLAttributes = () => {
 };
 ```
 
-### (선택 사항) 10단계: 지역화된 링크 컴포넌트 만들기
+</Step>
+
+<Step number={10} title="지역화된 링크 컴포넌트 만들기" isOptional={true}>
 
 애플리케이션의 내비게이션이 현재 로케일을 준수하도록 하려면, 커스텀 `Link` 컴포넌트를 만들 수 있습니다. 이 컴포넌트는 내부 URL에 자동으로 현재 언어 접두사를 붙여줍니다. 예를 들어, 프랑스어 사용자가 "About" 페이지로 가는 링크를 클릭하면 `/about` 대신 `/fr/about`로 리디렉션됩니다.
 
@@ -259,26 +343,25 @@ export const Link = forwardRef<HTMLAnchorElement, LinkProps>(
 Link.displayName = "Link";
 ```
 
-### VS Code 확장 프로그램
+#### 작동 방식
 
-Intlayer와 함께 개발 경험을 향상시키기 위해 공식 **Intlayer VS Code 확장 프로그램**을 설치할 수 있습니다.
+- **외부 링크 감지**:  
+  헬퍼 함수 `checkIsExternalLink`는 지정된 URL이 외부 링크인지 여부를 판단합니다. 외부 링크는 현지화할 필요가 없으므로 변경되지 않은 상태로 유지됩니다.
 
-[VS Code 마켓플레이스에서 설치하기](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+- **현재 로케일 가져오기**:  
+  `useLocale` 훅은 현재 로케일(예: 프랑스어의 경우 `fr`)을 제공합니다.
 
-이 확장 프로그램은 다음 기능을 제공합니다:
+- **URL 현지화**:  
+  내부 링크(즉, 외부 링크가 아닌 링크)의 경우, `getLocalizedUrl`을 사용하여 현재 로케일로 URL 접두사를 자동으로 붙입니다. 즉, 사용자가 프랑스어 환경인 경우 `/about`을 `href`로 전달하면 `/fr/about`으로 변환됩니다.
 
-- 번역 키에 대한 **자동 완성**.
-- 누락된 번역에 대한 **실시간 오류 감지**.
-- 번역된 내용의 **인라인 미리보기**.
-- 번역을 쉽게 생성하고 업데이트할 수 있는 **빠른 작업**.
+- **링크 반환**:  
+  이 컴포넌트는 로컬라이즈된 URL이 적용된 `<a>` 요소를 반환하여 내비게이션이 로케일과 일치하도록 보장합니다.
 
-확장 기능 사용 방법에 대한 자세한 내용은 [Intlayer VS Code 확장 문서](https://intlayer.org/doc/vs-code-extension)를 참조하세요.
+애플리케이션 전반에 이 `Link` 컴포넌트를 통합함으로써, 일관되고 언어를 인식하는 사용자 경험을 유지하는 동시에 개선된 SEO 및 사용성 이점을 누릴 수 있습니다.
 
----
-
-<Steps>
+</Step>
 
-<Step number={1} title="컴포넌트 콘텐츠 추출" isOptional={true}>
+<Step number={11} title="컴포넌트 콘텐츠 추출" isOptional={true}>
 
 기존 코드베이스가 있는 경우 수천 개의 파일을 변환하는 데 시간이 많이 걸릴 수 있습니다.
 

package/docs/ko/intlayer_with_vite+react_compiler.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-03-07
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Vite + React i18n - 앱을 번역하는 완전 가이드"
 description: "i18next는 이제 그만. 2026년 다국어 (i18n) Vite + React 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
 keywords:
@@ -93,32 +93,50 @@ GitHub에서 [애플리케이션 템플릿](https://github.com/aymericzip/intlay
 
 ## Vite 및 React 애플리케이션에서 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 react-intlayer
 npm install vite-intlayer --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer react-intlayer
 pnpm add vite-intlayer --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer react-intlayer
 yarn add vite-intlayer --save-dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer react-intlayer
 bun add vite-intlayer --dev
-bun x intlayer init
 ```
 
 - **intlayer**
@@ -130,7 +148,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="프로젝트 구성">
 
 애플리케이션의 언어를 구성하기 위한 설정 파일을 생성합니다:
 
@@ -178,7 +198,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 플러그인을 추가합니다.
 
@@ -197,7 +219,9 @@ export default defineConfig({
 
 > `intlayerCompiler()` Vite 플러그인은 컴포넌트에서 콘텐츠를 추출하고 `.content` 파일을 작성하는 데 사용됩니다.
 
-### 4단계: 코드 컴파일
+</Step>
+
+<Step number={4} title="코드 컴파일">
 
 기본 로케일로 하드코딩된 문자열을 사용하여 컴포넌트를 작성하기만 하면 됩니다. 나머지는 컴파일러가 처리합니다.
 
@@ -336,7 +360,9 @@ export default App;
 
 - **`IntlayerProvider`**는 중첩된 컴포넌트에 로케일을 제공하는 데 사용됩니다.
 
-### (선택 사항) 6단계: 콘텐츠 언어 변경
+</Step>
+
+<Step number={6} title="콘텐츠 언어 변경" isOptional={true}>
 
 콘텐츠 언어를 변경하려면 `useLocale` 훅에서 제공하는 `setLocale` 함수를 사용할 수 있습니다. 이 함수를 사용하면 애플리케이션의 로케일을 설정하고 그에 따라 콘텐츠를 업데이트할 수 있습니다.
 
@@ -358,7 +384,9 @@ const LocaleSwitcher: FC = () => {
 
 > `useLocale` 훅에 대해 자세히 알아보려면 [문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/packages/react-intlayer/useLocale.md)를 참조하세요.
 
-### (선택 사항) 7단계: 누락된 번역 채우기
+</Step>
+
+<Step number={7} title="누락된 번역 채우기" isOptional={true}>
 
 Intlayer는 누락된 번역을 채울 수 있도록 돕는 CLI 도구를 제공합니다. `intlayer` 명령어를 사용하여 코드에서 누락된 번역을 테스트하고 채울 수 있습니다.
 
@@ -396,6 +424,10 @@ 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`).