@intlayer/docs 9.4.0 → 9.4.2

package/docs/ko/analytics.md

@@ -103,6 +103,21 @@ export default config;
 
 직접 Intlayer를 호스팅(self-host)하는 경우, `editor.backendURL`을 공유하므로 분석은 자동으로 사용자 자체 인스턴스를 가리킵니다.
 
+### 브라우저에서 API 호출하기
+
+동일한 토큰이 자격 증명이 필요 없는 작은 클라이언트를 지원하므로, 정적 사이트나 SPA는 서버, 서버 액션, 번들 내 시크릿 없이도 런타임에 CMS 콘텐츠를 읽을 수 있습니다:
+
+```ts fileName="content.ts"
+import { createPublicClient } from "@intlayer/api/public";
+
+const client = createPublicClient();
+
+const keys = await client.getDictionaryKeys();
+const [navbar] = await client.getDictionaries(["navbar"]);
+```
+
+이 클라이언트는 `editor.clientId`를 기반으로 자체 인증하며, 토큰 교환·캐싱·갱신은 내부적으로 처리됩니다. 스코프는 접근할 수 있는 범위를 제한합니다: 게시된 사전 콘텐츠와 애널리틱스 수집입니다. 그 외의 작업(사전 푸시, 프로젝트 읽기, AI 크레딧 사용)에는 실제 자격 증명, 즉 서버 또는 로그인한 사용자가 필요합니다.
+
 ### 옵트아웃하기
 
 선택적 `analytics` 블록으로 수집을 조정하거나 완전히 끌 수 있습니다:
@@ -134,6 +149,126 @@ export default config;
 - 로케일 변경 시마다 `page_view`를 기록,
 - 약 20초의 플러시 루프(flush loop)를 시작하고, 언마운트 / 탭 닫기 시 남은 이벤트를 플러시합니다 (`navigator.sendBeacon`을 사용하며, `fetch(..., { keepalive: true })`로 폴백).
 
+진입점은 프레임워크마다 다르지만, 어떤 경우든 이미 Intlayer를 설정할 때 사용한 것과 동일한 지점이므로 추가로 할 일은 없습니다:
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
+
+    `IntlayerProvider`는 내부적으로 애널리틱스 프로바이더를 마운트합니다.
+
+    ```tsx fileName="App.tsx"
+    import { IntlayerProvider } from "react-intlayer";
+
+    const App = () => (
+      <IntlayerProvider>
+        <Router />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+
+    `next-intlayer`는 React의 `IntlayerProvider`를 재내보내므로, 애널리틱스도 동일한 방식으로 연결됩니다.
+
+    ```tsx fileName="app/[locale]/layout.tsx"
+    import { IntlayerProvider } from "next-intlayer";
+
+    const LocaleLayout = ({ children }) => (
+      <IntlayerProvider>{children}</IntlayerProvider>
+    );
+
+    export default LocaleLayout;
+    ```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+
+    `intlayer` 플러그인은 루트 컴포넌트의 라이프사이클에 애널리틱스 훅을 등록합니다.
+
+    ```javascript fileName="main.js"
+    import { createApp } from "vue";
+    import { intlayer } from "vue-intlayer";
+    import App from "./App.vue";
+
+    const app = createApp(App);
+
+    app.use(intlayer);
+
+    app.mount("#app");
+    ```
+
+    > Nuxt에서는 `nuxt-intlayer`가 대신 플러그인을 설치해 주므로 별도로 할 일이 없습니다.
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+
+    `setupIntlayer()`는 Intlayer를 설정하는 컴포넌트에서 애널리틱스를 시작합니다.
+
+    ```svelte fileName="src/routes/[[locale=locale]]/+layout.svelte"
+    <script lang="ts">
+      import { setupIntlayer } from "svelte-intlayer";
+      import type { Snippet } from "svelte";
+
+      let { children, data }: { children: Snippet, data: LayoutData } = $props();
+
+      $effect(() => {
+        setupIntlayer(data.locale);
+      });
+    </script>
+
+    {@render children()}
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+
+    `IntlayerProvider`는 내부적으로 애널리틱스 프로바이더를 마운트합니다.
+
+    ```tsx fileName="app.tsx"
+    import { IntlayerProvider } from "preact-intlayer";
+
+    const App = () => (
+      <IntlayerProvider>
+        <Router />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+
+    `IntlayerProvider`는 애널리틱스 프로바이더를 지연(lazy) 마운트하므로, 해당 청크는 크리티컬 패스에서 벗어나 있습니다.
+
+    ```tsx fileName="App.tsx"
+    import { IntlayerProvider } from "solid-intlayer";
+
+    const App = () => (
+      <IntlayerProvider>
+        <Router />
+      </IntlayerProvider>
+    );
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+    `provideIntlayer()`에는 이미 `provideIntlayerAnalytics()`가 포함되어 있습니다.
+
+    ```ts fileName="app.config.ts"
+    import { provideIntlayer } from "angular-intlayer";
+    import type { ApplicationConfig } from "@angular/core";
+
+    export const appConfig: ApplicationConfig = {
+      providers: [provideIntlayer()],
+    };
+    ```
+
+    > 프로바이더를 개별적으로 관리하는 경우에만 `provideIntlayerAnalytics()`를 단독으로 사용하세요.
+
+  </Tab>
+</Tabs>
+
 ### 자동 노드 레벨 추적
 
 `useIntlayer`가 표시할 콘텐츠 조각을 해석할 때마다, 해석기(interpreter)는 해당 정확한 `dictionaryKey` + 키 경로 + 로케일에 대해 `content_exposure` 이벤트를 보고합니다 — 이 역시 코드를 변경할 필요가 없습니다. 플러시 창(flush window) 내에 같은 노드가 반복해서 노출되면 이벤트는 `count` 속성을 포함한 단일 이벤트로 병합(coalesced)되므로, 리스트가 50번 리렌더링된다고 해서 50개의 이벤트가 전송되지 않습니다.
@@ -142,30 +277,341 @@ export default config;
 
 `useConversion()`을 사용하여 세션이 본 변형에 목표를 연결(attribute)하세요:
 
-```tsx fileName="CTAButton.tsx" codeFormat="tsx"
-import { useConversion } from "react-intlayer";
+<Tabs group="framework">
+  <Tab label="React" value="react">
+
+    ```tsx fileName="CTAButton.tsx"
+    import { useConversion } from "react-intlayer";
+
+    const CTAButton = () => {
+      const trackConversion = useConversion();
+
+      return (
+        <button
+          onClick={() =>
+            trackConversion({
+              experimentKey: "homepage-hero",
+              variant: "black_friday",
+              goal: "cta_click",
+            })
+          }
+        >
+          시작하기
+        </button>
+      );
+    };
+    ```
 
-const CTAButton = () => {
-  const trackConversion = useConversion();
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+
+    ```tsx fileName="CTAButton.tsx"
+    "use client";
+
+    import { useConversion } from "next-intlayer";
+
+    const CTAButton = () => {
+      const trackConversion = useConversion();
+
+      return (
+        <button
+          onClick={() =>
+            trackConversion({
+              experimentKey: "homepage-hero",
+              variant: "black_friday",
+              goal: "cta_click",
+            })
+          }
+        >
+          시작하기
+        </button>
+      );
+    };
+    ```
+
+    > `useConversion`은 클라이언트 훅입니다: 컴포넌트에 `"use client"`를 지정하세요.
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+
+    ```vue fileName="CTAButton.vue"
+    <script setup lang="ts">
+    import { useConversion } from "vue-intlayer";
+
+    const trackConversion = useConversion();
+    </script>
+
+    <template>
+      <button
+        @click="
+          trackConversion({
+            experimentKey: 'homepage-hero',
+            variant: 'black_friday',
+            goal: 'cta_click',
+          })
+        "
+      >
+        시작하기
+      </button>
+    </template>
+    ```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+
+    ```svelte fileName="CTAButton.svelte"
+    <script lang="ts">
+      import { useConversion } from "svelte-intlayer";
+
+      const trackConversion = useConversion();
+    </script>
 
-  return (
     <button
-      onClick={() =>
+      onclick={() =>
         trackConversion({
           experimentKey: "homepage-hero",
           variant: "black_friday",
           goal: "cta_click",
-        })
-      }
+        })}
     >
       시작하기
     </button>
-  );
-};
-```
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+
+    ```tsx fileName="CTAButton.tsx"
+    import { useConversion } from "preact-intlayer";
+
+    const CTAButton = () => {
+      const trackConversion = useConversion();
+
+      return (
+        <button
+          onClick={() =>
+            trackConversion({
+              experimentKey: "homepage-hero",
+              variant: "black_friday",
+              goal: "cta_click",
+            })
+          }
+        >
+          시작하기
+        </button>
+      );
+    };
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+
+    ```tsx fileName="CTAButton.tsx"
+    import { useConversion } from "solid-intlayer";
+
+    const CTAButton = () => {
+      const trackConversion = useConversion();
+
+      return (
+        <button
+          onClick={() =>
+            trackConversion({
+              experimentKey: "homepage-hero",
+              variant: "black_friday",
+              goal: "cta_click",
+            })
+          }
+        >
+          시작하기
+        </button>
+      );
+    };
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+    ```typescript fileName="cta-button.component.ts"
+    import { Component } from "@angular/core";
+    import { useConversion } from "angular-intlayer";
+
+    @Component({
+      selector: "app-cta-button",
+      template: `<button (click)="onClick()">시작하기</button>`,
+    })
+    export class CtaButtonComponent {
+      private trackConversion = useConversion();
+
+      onClick() {
+        this.trackConversion({
+          experimentKey: "homepage-hero",
+          variant: "black_friday",
+          goal: "cta_click",
+        });
+      }
+    }
+    ```
+
+  </Tab>
+</Tabs>
 
 ### 클라이언트 측에서 변형 해결(Resolving a variant)
 
+`useExperiment()`는 세션을 변형에 할당하고, 전환율의 분모가 되는 노출(exposure)을 기록합니다. 할당이 확정되기 전에 방문자가 컨트롤이 잠깐 보이는 현상을 겪지 않도록, 변형에 의존하는 서브트리는 `isAssigned`로 게이팅하세요:
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
+
+    `variant`는 일반 문자열입니다.
+
+    ```tsx fileName="Hero.tsx"
+    import { useExperiment } from "react-intlayer";
+    import { HeroBanner } from "./HeroBanner";
+
+    export const Hero = () => {
+      const { variant, isAssigned } = useExperiment("homepage-hero", [
+        "default",
+        "black_friday",
+      ]);
+
+      if (!isAssigned) return null;
+
+      return <HeroBanner variant={variant} />;
+    };
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+
+    `variant`는 일반 문자열입니다. 할당은 브라우저에서 이루어지므로 컴포넌트는 클라이언트 컴포넌트여야 합니다.
+
+    ```tsx fileName="Hero.tsx"
+    "use client";
+
+    import { useExperiment } from "next-intlayer";
+    import { HeroBanner } from "./HeroBanner";
+
+    export const Hero = () => {
+      const { variant, isAssigned } = useExperiment("homepage-hero", [
+        "default",
+        "black_friday",
+      ]);
+
+      if (!isAssigned) return null;
+
+      return <HeroBanner variant={variant} />;
+    };
+    ```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+
+    `variant`와 `isAssigned`는 `Ref`입니다.
+
+    ```vue fileName="Hero.vue"
+    <script setup lang="ts">
+    import { useExperiment } from "vue-intlayer";
+    import HeroBanner from "./HeroBanner.vue";
+
+    const { variant, isAssigned } = useExperiment("homepage-hero", [
+      "default",
+      "black_friday",
+    ]);
+    </script>
+
+    <template>
+      <HeroBanner v-if="isAssigned" :variant="variant" />
+    </template>
+    ```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+
+    `variant`와 `isAssigned`는 스토어(store)입니다. `$` 접두사로 읽으세요.
+
+    ```svelte fileName="Hero.svelte"
+    <script lang="ts">
+      import { useExperiment } from "svelte-intlayer";
+      import HeroBanner from "./HeroBanner.svelte";
+
+      const { variant, isAssigned } = useExperiment("homepage-hero", [
+        "default",
+        "black_friday",
+      ]);
+    </script>
+
+    {#if $isAssigned}
+      <HeroBanner variant={$variant} />
+    {/if}
+    ```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+
+    `variant`는 일반 문자열입니다.
+
+    ```tsx fileName="Hero.tsx"
+    import { useExperiment } from "preact-intlayer";
+    import { HeroBanner } from "./HeroBanner";
+
+    export const Hero = () => {
+      const { variant, isAssigned } = useExperiment("homepage-hero", [
+        "default",
+        "black_friday",
+      ]);
+
+      if (!isAssigned) return null;
+
+      return <HeroBanner variant={variant} />;
+    };
+    ```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+
+    `variant`와 `isAssigned`는 `Accessor`입니다. 값을 읽으려면 호출하세요.
+
+    ```tsx fileName="Hero.tsx"
+    import { useExperiment } from "solid-intlayer";
+    import { Show } from "solid-js";
+    import { HeroBanner } from "./HeroBanner";
+
+    export const Hero = () => {
+      const { variant, isAssigned } = useExperiment("homepage-hero", [
+        "default",
+        "black_friday",
+      ]);
+
+      return (
+        <Show when={isAssigned()}>
+          <HeroBanner variant={variant()} />
+        </Show>
+      );
+    };
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+    `variant`와 `isAssigned`는 `Signal`입니다. 값을 읽으려면 호출하세요.
+
+    ```typescript fileName="hero.component.ts"
+    import { Component } from "@angular/core";
+    import { useExperiment } from "angular-intlayer";
+    import { HeroBannerComponent } from "./hero-banner.component";
+
+    @Component({
+      selector: "app-hero",
+      imports: [HeroBannerComponent],
+      template: `@if (experiment.isAssigned()) {
+        <app-hero-banner [variant]="experiment.variant()" />
+      }`,
+    })
+    export class HeroComponent {
+      experiment = useExperiment("homepage-hero", ["default", "black_friday"]);
+    }
+    ```
+
   </Tab>
 </Tabs>
 

package/docs/ko/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-08-22
+updatedAt: 2026-08-30
 title: 구성 (Configuration)
 description: 애플리케이션에 Intlayer를 구성하는 방법을 알아보세요. 필요에 따라 Intlayer를 맞춤설정하는 데 사용할 수 있는 다양한 설정과 옵션을 이해하세요.
 keywords:
@@ -1118,3 +1118,101 @@ Intlayer가 애플리케이션의 국제화를 최적화하고 컴파일하는
 | 필드      | 설명                                 | 타입               |
 | --------- | ------------------------------------ | ------------------ |
 | `plugins` | 포함할 Intlayer 플러그인 목록입니다. | `IntlayerPlugin[]` |
+
+## 자주 묻는 질문
+
+<FAQ>
+
+<Question title="intlayer.config.ts 파일은 어디에 위치해야 하나요?">
+
+프로젝트 루트의 `package.json` 바로 옆에 위치해야 합니다. Intlayer는 `intlayer.config.js`, `intlayer.config.mjs`, `intlayer.config.cjs` 및 JSON도 허용하므로 프로젝트에서 사용하는 모듈 시스템에 맞춰 자유롭게 선택할 수 있습니다.
+
+</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="앱에 새로운 언어를 어떻게 추가하나요?">
+
+`internationalization.locales`에 새 로케일을 추가한 다음 `npx intlayer fill`을 실행하여 기존 콘텐츠를 번역하세요. 생성된 타입이 동시에 업데이트되므로 새 로케일이 누락된 콘텐츠 파일은 조용한 폴백 대신 컴파일 타입 오류가 되어 즉시 감지할 수 있습니다.
+
+</Question>
+
+<Question title="URL에서 로케일 접두사를 어떻게 제거하나요?">
+
+`routing.mode`를 설정하세요. 기본값 `"prefix-no-default"`는 기본 로케일에 대해 `/about`을, 다른 로케일에 대해 `/ko/about`을 제공합니다. `"prefix-all"`은 모든 로케일에 접두사를 붙입니다. `"no-prefix"`는 경로에서 로케일을 완전히 제거하고 쿠키, 헤더 또는 도메인에서 로케일을 확인합니다. `"search-params"`는 쿼리 문자열에 `/about?locale=ko`와 같이 추가합니다.
+
+</Question>
+
+<Question title="각 언어를 자체 도메인에서 제공할 수 있나요?">
+
+네. `routing.domains`를 통해 로케일을 호스트 이름에 매핑할 수 있습니다(예: `{ ko: 'example.co.kr', en: 'example.com' }`). 도메인이 로케일을 식별하므로 경로에 접두사가 추가되지 않으며, `getLocalizedUrl`은 올바른 도메인의 절대 URL을 반환합니다.
+
+</Question>
+
+<Question title="사용자의 언어는 어떻게 감지되나요?">
+
+`routing.storage`를 통해 확인하며, 일반적으로 URL, 쿠키, `Accept-Language` 헤더 순으로 읽을 소스 목록을 지정합니다. 사용자가 명시적으로 선택한 언어는 저장되므로 다음 방문 시 우선 적용됩니다.
+
+</Question>
+
+<Question title="routing.enableProxy는 어떤 역할을 하나요?">
+
+접두사를 확인하고 리디렉션하는 미들웨어인 로케일 라우팅 프록시를 제어합니다. 설정하지 않은 경우 프록시가 실행되지만 개발 및 미리보기 서버는 리디렉션 소스로서 저장된 로케일을 무시하여 테스트하지 않는 언어로 튕겨 나가는 현상을 방지합니다. 프로덕션 환경은 `true`인 것처럼 작동합니다. 로케일 라우팅을 직접 처리하려면 `false`로 설정하세요.
+
+</Question>
+
+<Question title="importMode static, dynamic, fetch의 차이점은 무엇인가요?">
+
+기본값인 `"static"`은 사전을 정적으로 가져와 함께 번들링되고 동기식으로 읽힙니다. `"dynamic"`은 Suspense를 통해 가져오므로 컴포넌트가 렌더링할 때만 해당 로케일이 다운로드되어 대용량 콘텐츠에 이상적입니다. `"fetch"`는 실시간 동기화 API에서 사전을 검색하고 실패 시 `"dynamic"`으로 폴백합니다. [번들 최적화](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)을 참조하세요.
+
+</Question>
+
+<Question title="자동 번역을 위한 AI 제공업체 및 API 키는 어디에 설정하나요?">
+
+구성 파일 내에서 설정하거나 커맨드라인에서 `--provider`, `--model`, `--api-key` 플래그로 지정할 수 있습니다. 키는 완전히 사용자 소유로 유지됩니다. 번역 호출은 로컬 머신 또는 CI 러너에서 선택한 제공업체로 직접 전송되므로 어떠한 제3자도 거치지 않습니다. [fill 명령](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/fill.md)을 참조하세요.
+
+</Question>
+
+<Question title="구성을 변경한 후 개발 서버를 다시 시작해야 하나요?">
+
+대부분의 경우 필요하지 않습니다. Intlayer 감시자(watcher)는 `intlayer.config.ts` 자체를 감시합니다: 저장 시 구성을 다시 로드하고 사전을 다시 준비하므로 로케일을 추가하거나 라우팅 모드를 변경하는 것도 콘텐츠 변경처럼 자동으로 반영됩니다. 단, 시스템 환경에 따라 캐시될 수 있으므로 변경 사항이 보이지 않을 경우 앱을 다시 시작하는 것이 좋습니다.
+
+</Question>
+
+</FAQ>

package/docs/ko/dictionary/content_file.md

@@ -364,15 +364,15 @@ content: { /* ... */ }
 
 **예시:**
 
-```json
+```jsonc
 // 로케일별 사전
 {
   "key": "about-page",
   "locale": "en",
   "content": {
     "title": "About Us", // 'en'에 대한 번역 노드가 됩니다.
-    "description": "Learn more about our company"
-  }
+    "description": "Learn more about our company",
+  },
 }
 ```
 
@@ -441,7 +441,7 @@ export default aboutPageMetaContent;
 
 **예시:**
 
-```json
+```jsonc
 // 모든 로케일에 대해 활성화
 {
   "autoFill": true

package/docs/ko/dictionary/markdown.md

@@ -51,6 +51,7 @@ Intlayer는 Markdown 구문을 사용하여 정의된 서식 있는 텍스트
 
 <Tabs>
   <Tab label=".content.md" value=".content.md">
+
     버전 `8.10.0`부터 `.content.md` 파일에서 직접 Markdown 콘텐츠를 선언할 수 있습니다. Intlayer가 Markdown 콘텐츠를 자동으로 감지하고 구문 분석합니다.
 
     ```md fileName="markdown-file.en.content.md"
@@ -96,6 +97,7 @@ Intlayer는 Markdown 구문을 사용하여 정의된 서식 있는 텍스트
     ```
 
   </Tab>
+
   <Tab label="외부 파일" value="external-files">
     `file` 함수를 사용하여 `.md` 파일을 직접 가져옵니다.
 
@@ -129,6 +131,7 @@ Intlayer는 Markdown 구문을 사용하여 정의된 서식 있는 텍스트
     ```
 
   </Tab>
+
 </Tabs>
 
 ## Markdown 렌더링
@@ -957,7 +960,21 @@ Markdown 렌더링은 **MDX**를 지원합니다 — Markdown 내에서 이름
   </Tab>
   <Tab label="Angular" value="angular">
 
-> MDX가 지원됨 — Markdown 내에서 사용되는 모든 component 이름(예: `<MyCustomJSXComponent />`)은 `components` 맵에 대해 해석됩니다.
+    ```typescript fileName="app.config.ts"
+    import { createIntlayerMarkdownProvider } from "angular-intlayer/markdown";
+
+    export const appConfig: ApplicationConfig = {
+      providers: [
+        createIntlayerMarkdownProvider({
+          components: {
+            h1: { class: "text-2xl font-bold" },
+          },
+        }),
+      ],
+    };
+    ```
+
+    > MDX가 지원됨 — Markdown 내에서 사용되는 모든 component 이름(예: `<MyCustomJSXComponent />`)은 `components` 맵에 대해 해석됩니다.
 
 자신의 markdown renderer를 사용할 수도 있습니다: