@intlayer/docs 9.0.0-canary.2 → 9.0.0-canary.21

package/docs/ko/intlayer_with_storybook.md

@@ -98,7 +98,9 @@ Storybook은 UI 컴포넌트를 독립적으로 개발하고 문서화하기 위
 <Tabs>
 <Tab value="Vite Setup">
 
-### 1단계: 종속성 설치
+<Steps>
+
+<Step number={1} title="종속성 설치">
 
 ```bash packageManager="npm"
 npm install intlayer react-intlayer
@@ -128,7 +130,9 @@ bun add vite-intlayer --dev
 
 ---
 
-### 2단계: Intlayer 구성 생성
+</Step>
+
+<Step number={2} title="Intlayer 구성 생성">
 
 프로젝트 루트(또는 디자인 시스템 패키지 내부)에 `intlayer.config.ts`를 생성합니다:
 
@@ -157,7 +161,9 @@ export default config;
 
 ---
 
-### 3단계: Storybook에 Vite 플러그인 추가
+</Step>
+
+<Step number={3} title="Storybook에 Vite 플러그인 추가">
 
 Storybook의 `viteFinal` 훅을 사용하면 내부 Vite 구성을 확장할 수 있습니다. 여기에 `intlayer()` 플러그인을 가져와서 추가합니다:
 
@@ -184,7 +190,13 @@ const config: StorybookConfig = {
     } as const;
 
     const viteConfig = defineConfig(() => ({
-      plugins: [intlayer()],
+      plugins: [
+        intlayer({
+          proxy: {
+            ignore: (req) => req.url?.startsWith("/api"),
+          },
+        }),
+      ],
     }));
 
     return mergeConfig(baseConfig, viteConfig(env));
@@ -198,7 +210,9 @@ export default config;
 
 ---
 
-### 4단계: `IntlayerProvider` 데코레이터 및 로케일 도구 모음 추가
+</Step>
+
+<Step number={4} title="`IntlayerProvider` 데코레이터 및 로케일 도구 모음 추가">
 
 Storybook의 `preview` 파일은 모든 스토리를 `IntlayerProvider`로 감싸고 도구 모음에 로케일 스위처를 노출하기에 적합한 장소입니다:
 
@@ -255,7 +269,9 @@ export default preview;
 </Tab>
 <Tab value="Webpack Setup">
 
-### 1단계: 종속성 설치
+</Step>
+
+<Step number={1} title="종속성 설치">
 
 ```bash packageManager="npm"
 npm install intlayer react-intlayer
@@ -279,7 +295,9 @@ bun add @intlayer/webpack --dev
 
 ---
 
-### 2단계: Intlayer 구성 생성
+</Step>
+
+<Step number={2} title="Intlayer 구성 생성">
 
 프로젝트 루트에 `intlayer.config.ts`를 생성합니다:
 
@@ -301,7 +319,9 @@ export default config;
 
 ---
 
-### 3단계: Storybook의 Webpack 구성
+</Step>
+
+<Step number={3} title="Storybook의 Webpack 구성">
 
 Webpack 기반 Storybook 설정(예: `@storybook/react-webpack5`)의 경우, `webpackFinal`을 통해 webpack 구성을 확장하여 Intlayer 별칭(alias) 및 로더를 추가합니다:
 
@@ -328,7 +348,9 @@ export default config;
 
 ---
 
-### 4단계: `IntlayerProvider` 데코레이터 및 로케일 도구 모음 추가
+</Step>
+
+<Step number={4} title="`IntlayerProvider` 데코레이터 및 로케일 도구 모음 추가">
 
 Vite 설정과 동일하게 `.storybook/preview.tsx`에 데코레이터와 전역 로케일 유형을 추가합니다:
 
@@ -374,6 +396,10 @@ export default preview;
 
 ---
 
+</Step>
+
+</Steps>
+
 ## 콘텐츠 선언
 
 각 컴포넌트 옆에 `*.content.ts` 파일을 생성합니다. Intlayer는 컴파일 중에 이를 자동으로 감지합니다.

package/docs/ko/intlayer_with_svelte_kit.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-20
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "SvelteKit i18n - 앱을 번역하는 완전 가이드"
 description: "i18next는 이제 그만. 2026년 다국어 (i18n) SvelteKit 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
 keywords:
@@ -155,215 +155,63 @@ Intlayer는 단순한 i18n 솔루션 그 이상으로 관리에 도움이 되는
 └── vite.config.ts
 ```
 
-### 1단계: 의존성 설치
+<Steps>
+
+<Step number={1} title="의존성 설치">
 
 npm을 사용하여 필요한 패키지를 설치합니다:
 
 ```bash packageManager="npm"
-npm install intlayer svelte-intlayer
-npm install vite-intlayer --save-dev
-npx intlayer init
+npx intlayer@canary init --interactive    # v9
+# npx intlayer init                       # v8
 ```
 
 ```bash packageManager="pnpm"
-pnpm add intlayer svelte-intlayer
-pnpm add vite-intlayer --save-dev
-pnpm intlayer init
+pnpm dlx intlayer@canary init --interactive   # v9
+# pnpm dlx intlayer init                      # v8
 ```
 
 ```bash packageManager="yarn"
-yarn add intlayer svelte-intlayer
-yarn add vite-intlayer --save-dev
-yarn intlayer init
+yarn dlx intlayer@canary init --interactive   # v9
+# yarn dlx intlayer init                      # v8
 ```
 
 ```bash packageManager="bun"
-bun add intlayer svelte-intlayer
-bun add vite-intlayer --save-dev
-bun x intlayer init
-```
-
-- **intlayer**: 핵심 i18n 패키지입니다.
-- **svelte-intlayer**: Svelte/SvelteKit용 컨텍스트 제공자와 스토어를 제공합니다.
-- **vite-intlayer**: 콘텐츠 선언을 빌드 프로세스와 통합하는 Vite 플러그인입니다.
-
-### 2단계: 프로젝트 구성
-
-프로젝트 루트에 구성 파일을 생성합니다:
-
-```typescript fileName="intlayer.config.ts"
-import { Locales, type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-};
-
-export default config;
-```
-
-### 3단계: Vite 구성에 Intlayer 통합하기
-
-`vite.config.ts` 파일을 업데이트하여 Intlayer 플러그인을 포함하세요. 이 플러그인은 콘텐츠 파일의 트랜스파일을 처리합니다.
-
-```typescript fileName="vite.config.ts"
-import { sveltekit } from "@sveltejs/kit/vite";
-import { defineConfig } from "vite";
-import { intlayer } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [intlayer(), sveltekit()], // 순서가 중요하며, Intlayer는 SvelteKit보다 먼저 위치해야 합니다.
-});
-```
-
-### 4단계: 콘텐츠 선언하기
-
-`src` 폴더 내 어디에서든 콘텐츠 선언 파일을 생성하세요 (예: `src/lib/content` 또는 컴포넌트와 함께). 이 파일들은 각 로케일별로 `t()` 함수를 사용하여 애플리케이션의 번역 가능한 콘텐츠를 정의합니다.
-
-```ts fileName="src/features/hero/hero.content.ts" contentDeclarationFormat=["typescript", "esm", "cjs"]
-import { t, type Dictionary } from "intlayer";
-
-const heroContent = {
-  key: "hero-section",
-  content: {
-    title: t({
-      en: "Welcome to SvelteKit",
-      fr: "Bienvenue sur SvelteKit",
-      es: "Bienvenido a SvelteKit",
-    }),
-  },
-} satisfies Dictionary;
-
-export default heroContent;
+bunx intlayer@canary init --interactive   # v9
+# bunx intlayer init                      # v8
 ```
 
-### 5단계: 컴포넌트에서 Intlayer 사용하기
-
-이제 어떤 Svelte 컴포넌트에서든 `useIntlayer` 함수를 사용할 수 있습니다. 이 함수는 locale이 변경될 때 자동으로 업데이트되는 반응형 스토어를 반환합니다. 이 함수는 SSR과 클라이언트 사이드 내비게이션 모두에서 현재 locale을 자동으로 인식합니다.
-
-> **참고:** `useIntlayer`는 Svelte 스토어를 반환하므로, 반응형 값을 접근하려면 `---
-> createdAt: 2025-11-20
-> updatedAt: 2026-05-31
-> title: SvelteKit 앱 번역 방법 – i18n 가이드 2026
-> description: SvelteKit 웹사이트를 다국어로 만드는 방법을 알아보세요. 서버 사이드 렌더링(SSR)을 사용하여 국제화(i18n) 및 번역하는 문서를 따라가세요.
-> keywords:
-
-- 국제화
-- 문서
-- Intlayer
-- SvelteKit
-- 자바스크립트
-- SSR
-  slugs:
-- doc
-- environment
-- sveltekit
-  applicationTemplate: https://github.com/aymericzip/intlayer-sveltekit-template
-  history:
-- version: 7.1.10
-  date: 2025-11-20
-  changes: 초기 기록
-
----
-
-# Intlayer를 사용하여 SvelteKit 웹사이트 번역하기 | 국제화(i18n)
+> `--interactive` 플래그는 선택 사항입니다. AI 에이전트인 경우 `intlayer-cli init`를 사용하세요.
 
-## 목차
-
-<TOC/>
-
-## Intlayer란 무엇인가?
-
-**Intlayer**는 현대 웹 애플리케이션에서 다국어 지원을 간소화하기 위해 설계된 혁신적인 오픈 소스 국제화(i18n) 라이브러리입니다. **SvelteKit**의 서버 사이드 렌더링(SSR) 기능과 원활하게 작동합니다.
-
-Intlayer를 사용하면 다음을 할 수 있습니다:
-
-- **컴포넌트 수준에서 선언적 사전을 사용하여 번역을 쉽게 관리**할 수 있습니다.
-- **메타데이터, 라우트 및 콘텐츠를 동적으로 현지화**할 수 있습니다.
-- **자동 생성된 타입으로 TypeScript 지원을 보장**할 수 있습니다.
-- **SvelteKit의 SSR을 활용하여 SEO 친화적인 국제화**를 구현할 수 있습니다.
-
----
-
-## SvelteKit 애플리케이션에서 Intlayer 설정 단계별 가이드
-
-시작하려면 새 SvelteKit 프로젝트를 생성하세요. 다음은 우리가 만들 최종 구조입니다:
-
-```bash
-.
-├── intlayer.config.ts
-├── package.json
-├── src
-│   ├── app.d.ts
-│   ├── app.html
-│   ├── hooks.server.ts
-│   ├── lib
-│   │   ├── getLocale.ts
-│   │   ├── LocaleSwitcher.svelte
-│   │   └── LocalizedLink.svelte
-│   ├── params
-│   │   └── locale.ts
-│   └── routes
-│       ├── [[locale=locale]]
-│       │   ├── +layout.svelte
-│       │   ├── +layout.ts
-│       │   ├── +page.svelte
-│       │   ├── +page.ts
-│       │   ├── about
-│       │   │   ├── +page.svelte
-│       │   │   ├── +page.ts
-│       │   │   └── page.content.ts
-│       │   ├── Counter.content.ts
-│       │   ├── Counter.svelte
-│       │   ├── Header.content.ts
-│       │   ├── Header.svelte
-│       │   ├── home.content.ts
-│       │   └── layout.content.ts
-│       ├── +layout.svelte
-│       └── layout.css
-├── static
-│   ├── favicon.svg
-│   └── robots.txt
-├── svelte.config.js
-├── tsconfig.json
-└── vite.config.ts
-```
-
-### 1단계: 의존성 설치
-
-npm을 사용하여 필요한 패키지를 설치합니다:
+> 이 명령은 환경을 감지하고 필요한 패키지를 설치합니다. 예를 들어:
 
 ```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**: 핵심 i18n 패키지입니다.
 - **svelte-intlayer**: Svelte/SvelteKit용 컨텍스트 제공자와 스토어를 제공합니다.
 - **vite-intlayer**: 콘텐츠 선언을 빌드 프로세스와 통합하는 Vite 플러그인입니다.
 
-### 2단계: 프로젝트 구성
+</Step>
+
+<Step number={2} title="프로젝트 구성">
 
 프로젝트 루트에 구성 파일을 생성합니다:
 
@@ -380,7 +228,9 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-### 3단계: Vite 구성에 Intlayer 통합하기
+</Step>
+
+<Step number={3} title="Vite 구성에 Intlayer 통합하기">
 
 `vite.config.ts` 파일을 업데이트하여 Intlayer 플러그인을 포함하세요. 이 플러그인은 콘텐츠 파일의 트랜스파일을 처리합니다.
 
@@ -394,7 +244,9 @@ export default defineConfig({
 });
 ```
 
-### 4단계: 콘텐츠 선언하기
+</Step>
+
+<Step number={4} title="콘텐츠 선언하기">
 
 `src` 폴더 내 어디에서든 콘텐츠 선언 파일을 생성하세요 (예: `src/lib/content` 또는 컴포넌트와 함께). 이 파일들은 각 로케일별로 `t()` 함수를 사용하여 애플리케이션의 번역 가능한 콘텐츠를 정의합니다.
 
@@ -415,7 +267,9 @@ const heroContent = {
 export default heroContent;
 ```
 
-### 5단계: 컴포넌트에서 Intlayer 사용하기
+</Step>
+
+<Step number={5} title="컴포넌트에서 Intlayer 사용하기">
 
 접두사를 사용해야 합니다 (예: `$content.title`).
 
@@ -437,7 +291,9 @@ export default heroContent;
 <div aria-label={String($content.title)}></div>
 ```
 
-### (선택 사항) 6단계: 라우팅 설정하기
+</Step>
+
+<Step number={6} title="라우팅 설정하기" isOptional={true}>
 
 다음 단계에서는 SvelteKit에서 로케일 기반 라우팅을 설정하는 방법을 보여줍니다. 이를 통해 URL에 로케일 접두사(e.g., `/en/about`, `/fr/about`)를 포함시켜 SEO 및 사용자 경험을 향상시킬 수 있습니다.
 
@@ -462,7 +318,9 @@ export default heroContent;
         └── +layout.svelte         # 폰트 및 전역 스타일을 위한 루트 레이아웃
 ```
 
-### 7단계: 서버 사이드 로케일 감지 처리 (Hooks)
+</Step>
+
+<Step number={7} title="서버 사이드 로케일 감지 처리 (Hooks)">
 
 SvelteKit에서는 SSR 중에 올바른 콘텐츠를 렌더링하기 위해 서버가 사용자의 로케일을 알아야 합니다. 우리는 URL이나 쿠키에서 로케일을 감지하기 위해 `hooks.server.ts`를 사용합니다.
 
@@ -674,7 +532,9 @@ export const prerender = true;
 </style>
 ```
 
-### (선택 사항) 8단계: 국제화된 링크
+</Step>
+
+<Step number={8} title="국제화된 링크" isOptional={true}>
 
 SEO를 위해 경로에 로케일 접두사를 붙이는 것이 권장됩니다(예: `/en/about`, `/fr/about`). 이 컴포넌트는 현재 로케일로 모든 링크에 자동으로 접두사를 붙입니다.
 
@@ -707,7 +567,9 @@ const localizedPath = getLocalizedUrl("/about", $locale);
 goto(localizedPath); // 로케일에 따라 /en/about 또는 /fr/about로 이동합니다.
 ```
 
-### (선택 사항) 9단계: 언어 전환기
+</Step>
+
+<Step number={9} title="언어 전환기" isOptional={true}>
 
 사용자가 언어를 전환할 수 있도록 URL을 업데이트합니다.
 
@@ -748,26 +610,33 @@ goto(localizedPath); // 로케일에 따라 /en/about 또는 /fr/about로 이동
 </style>
 ```
 
-### (선택 사항) 10단계: 백엔드 프록시 추가
+</Step>
+
+<Step number={10} title="백엔드 프록시 추가" isOptional={true}>
 
 SvelteKit 애플리케이션에 백엔드 프록시를 추가하려면 `vite-intlayer` 플러그인이 제공하는 `intlayerProxy` 함수를 사용할 수 있습니다. 이 플러그인은 URL, 쿠키 및 브라우저 언어 설정을 기반으로 사용자에게 가장 적합한 로케일을 자동으로 감지합니다.
 
 ```ts fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 import { sveltekit } from "@sveltejs/kit/vite";
 
 // https://vitejs.dev/config/
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
     sveltekit(),
   ],],
 });
 ```
 
-### (선택 사항) 11단계: intlayer 에디터 / CMS 설정하기
+</Step>
+
+<Step number={11} title="intlayer 에디터 / CMS 설정하기" isOptional={true}>
 
 intlayer 에디터를 설정하려면 [intlayer 에디터 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_visual_editor.md)를 따라야 합니다.
 
@@ -792,6 +661,10 @@ intlayer 에디터 선택기를 시각화하려면 intlayer 콘텐츠에서 컴
 </div>
 ```
 
+</Step>
+
+</Steps>
+
 ### Git 구성
 
 Intlayer가 생성한 파일은 무시하는 것이 권장됩니다.
@@ -868,6 +741,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"
@@ -877,7 +752,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 컴파일러 플러그인을 추가합니다
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```