@intlayer/docs 9.3.3 → 9.4.0

package/docs/ko/intlayer_with_svelte_kit.md

@@ -86,7 +86,7 @@ Intlayer는 **다국어 라우팅**, **SSR 지원** 및 국제화 확장(i18n)
 
 <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)와 같은 도구 모음도 함께 제공됩니다. 기술](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**, AI 에이전트를 위한 개발자 경험(DX)을 더욱 원활하게 만듭니다.
+콘텐츠를 같은 위치에 배치하면 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>
 
@@ -113,6 +113,8 @@ Intlayer는 단순한 i18n 솔루션 그 이상으로 관리에 도움이 되는
 
 ## SvelteKit 애플리케이션에서 Intlayer 설정 단계별 가이드
 
+GitHub에서 [Application Template](https://github.com/aymericzip/intlayer-sveltekit-template)을 참조하세요.
+
 시작하려면 새 SvelteKit 프로젝트를 생성하세요. 다음은 우리가 만들 최종 구조입니다:
 
 ```bash
@@ -267,6 +269,8 @@ export default heroContent;
 
 <Step number={5} title="컴포넌트에서 Intlayer 사용하기">
 
+이제 모든 Svelte 컴포넌트에서 `useIntlayer` 함수를 사용할 수 있습니다. 이 함수는 로케일이 변경될 때 자동으로 업데이트되는 반응형 스토어를 반환합니다. 이 함수는 현재 로케일을 자동으로 존중합니다 (SSR 및 클라이언트 측 네비게이션 모두).
+
 접두사를 사용해야 합니다 (예: `$content.title`).
 
 ```svelte fileName="src/lib/components/Component.svelte"
@@ -612,6 +616,8 @@ goto(localizedPath); // 로케일에 따라 /en/about 또는 /fr/about로 이동
 
 SvelteKit 애플리케이션에 백엔드 프록시를 추가하려면 `vite-intlayer` 플러그인이 제공하는 `intlayerProxy` 함수를 사용할 수 있습니다. 이 플러그인은 URL, 쿠키 및 브라우저 언어 설정을 기반으로 사용자에게 가장 적합한 로케일을 자동으로 감지합니다.
 
+> Intlayer v9부터 `intlayerProxy()`는 `intlayer()` 플러그인에 직접 번들되어 있으며 `routing.enableProxy` 옵션(`true`가 기본값)을 통해 기본적으로 활성화됩니다. 아래와 같이 별도로 등록하는 것은 이제 선택 사항이며, 역호환성 및 플러그인 순서를 제어해야 하는 설정을 위해 유지됩니다. `routing.enableProxy: false`로 설정하여 옵트아웃할 수 있습니다. [v9 릴리스 노트](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/releases/v9.md)를 참조하세요.
+
 ```ts fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { intlayer } from "vite-intlayer";
@@ -659,52 +665,41 @@ intlayer 에디터 선택기를 시각화하려면 intlayer 콘텐츠에서 컴
 
 </Step>
 
-</Steps>
-
-### Git 구성
-
-Intlayer가 생성한 파일은 무시하는 것이 권장됩니다.
-
-```plaintext fileName=".gitignore"
-# Intlayer가 생성한 파일 무시
-.intlayer
-```
-
----
-
-<Steps>
-
-<Step number={1} title="컴포넌트 콘텐츠 추출" isOptional={true}>
+<Step number={12} title="Extract the content of your components" isOptional={true}>
 
-기존 코드베이스가 있는 경우 수천 개의 파일을 변환하는 데 시간이 많이 걸릴 수 있습니다.
+기존 codebase가 있다면 수천 개의 파일을 변환하는 것은 시간이 많이 걸릴 수 있습니다.
 
-이 프로세스를 용이하게 하기 위해 Intlayer는 컴포넌트를 변환하고 콘텐츠를 추출하기 위한 [컴파일러](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compiler.md) / [추출기](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/extract.md)를 제안합니다.
+이 프로세스를 간편하게 하기 위해 Intlayer는 컴포넌트를 변환하고 콘텐츠를 추출하는 [compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/compiler.md) / [extractor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/extract.md)를 제공합니다.
 
-설정하려면 `intlayer.config.ts` 파일에 `compiler` 섹션을 추가할 수 있습니다.
+이를 설정하려면 `intlayer.config.ts` 파일에 `compiler` 섹션을 추가할 수 있습니다:
 
 ```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { type IntlayerConfig } from "intlayer";
 
 const config: IntlayerConfig = {
-  // ... 나머지 구성
+  // ... 나머지 config
   compiler: {
     /**
-     * 컴파일러 활성화 여부를 나타냅니다.
+     * 컴파일러가 활성화되어야 하는지 여부를 나타냅니다.
      */
     enabled: true,
 
     /**
-     * 출력 파일 경로를 정의합니다.
+     * 출력 파일 경로를 정의합니다
      */
     output: ({ fileName, extension }) => `./${fileName}${extension}`,
 
     /**
-     * 변환 후 컴포넌트를 저장할지 여부를 나타냅니다. 그렇게 하면 컴파일러를 한 번만 실행하여 앱을 변환한 다음 제거할 수 있습니다.
+     * 변환 후 컴포넌트를 저장할지 여부를 나타냅니다.
+     *
+     * - `true`인 경우, 컴파일러는 디스크의 컴포넌트 파일을 다시 작성합니다. 따라서 변환은 영구적이며, 컴파일러는 다음 프로세스에서 변환을 건너뜁니다. 이런 방식으로 컴파일러는 앱을 변환한 후 제거할 수 있습니다.
+     *
+     * - `false`인 경우, 컴파일러는 `useIntlayer()` 함수 호출을 빌드 출력의 코드에만 주입하고 기본 codebase를 손상되지 않은 상태로 유지합니다. 변환은 메모리에서만 수행됩니다.
      */
     saveComponents: false,
 
     /**
-     * 사전 키 접두사
+     * 딕셔너리 키 접두사
      */
     dictionaryKeyPrefix: "",
   },
@@ -714,9 +709,9 @@ export default config;
 ```
 
 <Tabs>
- <Tab value='추출 명령'>
+ <Tab value='Extract command'>
 
-컴포넌트를 변환하고 콘텐츠를 추출하기 위해 추출기를 실행합니다
+extractor를 실행하여 컴포넌트를 변환하고 콘텐츠를 추출합니다
 
 ```bash packageManager="npm"
 npx intlayer extract
@@ -735,11 +730,11 @@ bun x intlayer extract
 ```
 
  </Tab>
- <Tab value='Babel 컴파일러'>
+ <Tab value='Babel compiler'>
 
-> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+> v9부터 `intlayerCompiler`는 `intlayer` 플러그인에 포함되어 있습니다. 따라서 수동으로 추가할 필요가 없습니다.
 
-`vite.config.ts`를 업데이트하여 `intlayerCompiler` 플러그인을 포함합니다.
+`vite.config.ts`를 업데이트하여 `intlayerCompiler` 플러그인을 포함시킵니다:
 
 ```ts fileName="vite.config.ts"
 import { defineConfig } from "vite";
@@ -748,7 +743,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Adds the compiler plugin
+    intlayerCompiler(), // compiler plugin을 추가합니다
   ],
 });
 ```
@@ -766,15 +761,26 @@ yarn build # 또는 yarn dev
 ```
 
 ```bash packageManager="bun"
-bun run build # Or bun run dev
+bun run build # 또는 bun run dev
 ```
 
- </Tab>
+</Tab>
 </Tabs>
 </Step>
 
 </Steps>
 
+### Git 구성
+
+Intlayer가 생성한 파일은 무시하는 것이 권장됩니다.
+
+```plaintext fileName=".gitignore"
+# Intlayer가 생성한 파일 무시
+.intlayer
+```
+
+---
+
 ### 더 나아가기
 
 - **비주얼 에디터**: UI에서 직접 번역을 편집할 수 있도록 [Intlayer 비주얼 에디터](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_visual_editor.md)를 통합하세요.

package/docs/ko/intlayer_with_tanstack+solid.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-25
-updatedAt: 2026-06-23
+updatedAt: 2026-08-25
 title: "TanStack Start + Solid i18n - 앱을 번역하는 완전 가이드"
 description: "i18next는 이제 그만. 2026년 다국어 (i18n) TanStack Start + Solid 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
 keywords:
@@ -22,6 +22,9 @@ applicationTemplate: https://github.com/aymericzip/intlayer-tanstack-start-solid
 applicationShowcase: https://intlayer-tanstack-start-solid.vercel.app
 youtubeVideo: https://www.youtube.com/watch?v=_XTdKVWaeqg
 history:
+  - version: 9.4.0
+    date: 2026-08-25
+    changes: "라우트 head 함수에서 메타데이터 사전의 정적·동적·캐시된 동적 해석 비교"
   - version: 8.9.0
     date: 2026-05-04
     changes: "Solid useIntlayer API 사용법을 직접 속성 액세스로 업데이트"
@@ -65,7 +68,7 @@ Intlayer는 **다국어 라우팅**, **사이트맵** 및 국제화 확장(i18n)
 
 <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)와 같은 도구 모음도 함께 제공됩니다. 기술](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**, AI 에이전트를 위한 개발자 경험(DX)을 더욱 원활하게 만듭니다.
+콘텐츠를 같은 위치에 배치하면 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>
 
@@ -458,6 +461,8 @@ export const useLocalizedNavigate = () => {
 
 <Step number={9} title="페이지에서 Intlayer 사용">
 
+> 컴포넌트 안에서는 기본적으로 **`useIntlayer`** 를 사용하세요. 컴파일러가 렌더링되는 로케일로 해석해 주므로 이것이 권장 방식입니다. `getIntlayer` / `getIntlayerAsync` 는 Solid 트리 바깥(라우트 `head`, 로더, 서버 함수)에서만 사용하세요.
+
 애플리케이션 전체에서 콘텐츠 딕셔너리에 접근하세요.
 
 #### 로컬라이즈된 홈 페이지
@@ -487,8 +492,6 @@ 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()}" />
@@ -574,6 +577,8 @@ const RootComponent: ParentComponent = (props) => {
 
 > 프로덕션에서 `intlayerProxy`를 사용하려면 `vite-intlayer` 패키지를 `devDependencies`에서 `dependencies`로 변경해야 합니다.
 
+> Intlayer v9부터 `intlayerProxy()`는 `intlayer()` 플러그인에 직접 번들되어 있으며 `routing.enableProxy` 옵션(`기본값: true`)을 통해 기본적으로 활성화됩니다. 아래와 같이 별도로 등록하는 것은 이제 선택 사항입니다. 이전 버전과의 호환성과 플러그인 순서를 제어해야 하는 설정을 위해 유지됩니다. `routing.enableProxy: false`로 설정하여 옵트아웃할 수 있습니다. [v9 release notes](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/releases/v9.md)를 참조하세요.
+
 ```typescript fileName="vite.config.ts"
 import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
 import solid from "vite-plugin-solid";
@@ -606,16 +611,25 @@ export default defineConfig({
 
 <Step number={12} title="메타데이터 국제화 (선택 사항)" isOptional={true}>
 
-로케일 인식 메타데이터를 위해 `head` 로더 내에서 `getIntlayer` 함수를 사용하여 콘텐츠 딕셔너리에 접근할 수도 있습니다.
+<Tabs>
+
+<Tab label="정적 해석" value="static">
+
+`getIntlayer` 는 선언된 모든 로케일을 담은 **병합** 사전을 대상으로 동기적으로 해석됩니다. `head` 는 동기 상태로 남고 아무것도 대기하지 않지만, 다국어 사전 전체가 브라우저로 전송되는 라우트 청크에 포함됩니다.
 
 ```tsx fileName="src/routes/{-$locale}/index.tsx"
 import { createFileRoute } from "@tanstack/solid-router";
-import { getIntlayer } from "intlayer";
+import {
+  defaultLocale,
+  getIntlayer,
+  getLocalizedUrl,
+  localeMap,
+} from "intlayer";
 
 export const Route = createFileRoute("/{-$locale}/")({
   component: RouteComponent,
   head: ({ params }) => {
-    const { locale } = params;
+    const { locale = defaultLocale } = params;
     const path = "/"; // The path for this route
 
     const metaContent = getIntlayer("app", locale);
@@ -649,6 +663,143 @@ export const Route = createFileRoute("/{-$locale}/")({
 });
 ```
 
+작은 메타데이터 사전, 소수의 로케일, 또는 프로토타이핑 단계에 적합합니다.
+
+</Tab>
+
+<Tab label="동적 해석" value="dynamic">
+
+`getIntlayerAsync`(**v9.4** 부터 제공)는 `getIntlayer` 와 동일하게 동작하지만, 빌드 플러그인이 병합 사전 대신 `.intlayer/dynamic_dictionaries/` 의 로케일별 청크를 가리키게 합니다. 따라서 페이지는 렌더링하는 로케일만 전송합니다. 해당 청크는 필요할 때 로드되므로 `head` 는 `async` 가 됩니다:
+
+```tsx fileName="src/routes/{-$locale}/index.tsx"
+import { createFileRoute } from "@tanstack/solid-router";
+import {
+  defaultLocale,
+  getIntlayerAsync,
+  getLocalizedUrl,
+  localeMap,
+} from "intlayer";
+
+export const Route = createFileRoute("/{-$locale}/")({
+  component: RouteComponent,
+  head: async ({ params }) => {
+    const { locale = defaultLocale } = params;
+    const path = "/"; // The path for this route
+
+    const metaContent = await getIntlayerAsync("app", locale);
+
+    return {
+      links: [
+        // Canonical link: Points to the current localized page
+        { rel: "canonical", href: getLocalizedUrl(path, locale) },
+
+        // Hreflang: Tell Google about all localized versions
+        ...localeMap(({ locale: mapLocale }) => ({
+          rel: "alternate",
+          hrefLang: mapLocale,
+          href: getLocalizedUrl(path, mapLocale),
+        })),
+
+        // x-default: For users in unmatched languages
+        // Define the default fallback locale (usually your primary language)
+        {
+          rel: "alternate",
+          hrefLang: "x-default",
+          href: getLocalizedUrl(path, defaultLocale),
+        },
+      ],
+      meta: [
+        { title: metaContent.title },
+        { name: "description", content: metaContent.meta.description },
+      ],
+    };
+  },
+});
+```
+
+> 하나의 `head` 에서 여러 사전을 읽는다면 `Promise.all` 로 함께 해석하세요. `getIntlayerAsync` 를 한 줄씩 await 하면 요청이 병렬이 아니라 순차적으로 연결됩니다.
+
+절충점: 동적 import 는 문서 렌더링의 임계 경로에서 `head` 가 실행되는 동안 해석됩니다. 콜드 라우트에서는 `head` 가 몇 밀리초 지연되어 **LCP** 가 약간 나빠질 수 있습니다.
+
+</Tab>
+
+<Tab label="캐시된 동적 해석" value="cached">
+
+사전을 라우트 `loader` 에서 해석하고, `head` 에서는 `loaderData` 로 다시 읽어 오세요. 매칭된 라우트의 로더는 병렬로 실행되며, `staleTime: Infinity` 는 결과가 절대 만료되지 않음을 TanStack Router 에 알립니다. 즉 로케일별 청크는 한 번만 해석되고 이후에는 라우터 캐시에서 제공되므로 `head` 는 동기로 유지됩니다.
+
+```tsx fileName="src/routes/{-$locale}/index.tsx"
+import { createFileRoute } from "@tanstack/solid-router";
+import {
+  defaultLocale,
+  getIntlayerAsync,
+  getLocalizedUrl,
+  localeMap,
+} from "intlayer";
+
+export const Route = createFileRoute("/{-$locale}/")({
+  component: RouteComponent,
+  // Resolved in parallel with the other matched routes, off the head critical path
+  loader: async ({ params }) => {
+    const { locale = defaultLocale } = params;
+
+    return { metaContent: await getIntlayerAsync("app", locale) };
+  },
+  // The dictionary never changes for a given locale: resolve the chunk once
+  staleTime: Infinity,
+  head: ({ params, loaderData }) => {
+    const { locale = defaultLocale } = params;
+    const path = "/"; // The path for this route
+
+    return {
+      links: [
+        // Canonical link: Points to the current localized page
+        { rel: "canonical", href: getLocalizedUrl(path, locale) },
+
+        // Hreflang: Tell Google about all localized versions
+        ...localeMap(({ locale: mapLocale }) => ({
+          rel: "alternate",
+          hrefLang: mapLocale,
+          href: getLocalizedUrl(path, mapLocale),
+        })),
+
+        // x-default: For users in unmatched languages
+        // Define the default fallback locale (usually your primary language)
+        {
+          rel: "alternate",
+          hrefLang: "x-default",
+          href: getLocalizedUrl(path, defaultLocale),
+        },
+      ],
+      meta: [
+        { title: loaderData?.metaContent.title },
+        {
+          name: "description",
+          content: loaderData?.metaContent.meta.description,
+        },
+      ],
+    };
+  },
+});
+```
+
+> `head` 는 로더가 완료되기 전에 호출될 수 있어 `loaderData` 는 `undefined` 가능 타입입니다. 옵셔널 체이닝을 유지하거나 대체 제목을 반환하세요.
+
+로케일별 청크의 이점을 유지하면서 그 비용을 `head` 임계 경로에서 지불하지 않습니다. 대가는 DX 입니다. 콘텐츠를 로더에서 `head` 로 `loaderData` 를 통해 명시적으로 전달해야 합니다.
+
+</Tab>
+
+</Tabs>
+
+### 어떤 해석 방식을 선택해야 할까요?
+
+|                       | 정적 해석          | 동적 해석                  | 캐시된 동적 해석                         |
+| --------------------- | ------------------ | -------------------------- | ---------------------------------------- |
+| API                   | `getIntlayer`      | `getIntlayerAsync` (v9.4+) | `loader` 안의 `getIntlayerAsync` (v9.4+) |
+| `head` 시그니처       | 동기               | `async`                    | 동기, `loaderData` 를 읽음               |
+| 전송되는 로케일       | 선언된 모든 로케일 | 요청된 로케일만            | 요청된 로케일만                          |
+| 클라이언트 내비게이션 | 해석할 것 없음     | 매칭될 때마다 다시 실행    | 라우터 캐시에서 제공                     |
+| DX                    | 가장 단순함        | `await` 하나               | 콘텐츠를 `loaderData` 로 전달            |
+
 ---
 
 </Step>
@@ -962,10 +1113,10 @@ export const Route = createFileRoute("/sitemap.xml")({
 
 <Step number={17} title="TypeScript 구성 (선택 사항)" isOptional={true}>
 
-Intlayer는 모듈 보강(module augmentation)을 사용하여 TypeScript의 이점을 얻고 코드베이스를 더 강력하게 만듭니다.
-
 TypeScript 구성에 자동 생성된 타입이 포함되어 있는지 확인하세요.
 
+TypeScript 설정에 자동 생성된 타입이 포함되어 있는지 확인하세요:
+
 ```json5 fileName="tsconfig.json"
 {
   // ... 기존 구성