@intlayer/docs 9.5.4-canary.0 → 9.5.5

package/docs/ja/packages/remix-intlayer/useDictionary.md

@@ -0,0 +1,95 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: useDictionary フックのドキュメント | remix-intlayer
+description: Remix 3 アプリケーションで useDictionary フックを使用して、現在のリクエストロケールに対応する辞書オブジェクトを解決する方法を説明します。
+keywords:
+  - useDictionary
+  - dictionary
+  - remix
+  - remix-3
+  - Intlayer
+  - intlayer
+  - 国際化
+  - ドキュメント
+slugs:
+  - doc
+  - packages
+  - remix-intlayer
+  - useDictionary
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "useDictionary フックの初期ドキュメント"
+author: aymericzip
+---
+
+# useDictionary フックのドキュメント
+
+`useDictionary` フックは、インポートされた、またはインラインの辞書オブジェクトを変換し、Remix 3 アプリケーションで現在のリクエストロケールに対応するコンテンツを返します。
+
+グローバル辞書レジストリから文字列キーによって辞書を解決する `useIntlayer` とは異なり、`useDictionary` は辞書オブジェクトを直接受け入れます。
+
+## 使用方法
+
+```ts fileName="src/views/home.ts"
+import { useDictionary } from "remix-intlayer";
+import homeContent from "./home.content";
+
+export const HomeView = () => {
+  const content = useDictionary(homeContent);
+
+  return `
+    <div>
+      <h1>${content.title}</h1>
+      <p>${content.subtitle}</p>
+    </div>
+  `;
+};
+```
+
+`t()` を使用して定義されたインライン辞書を渡すこともできます。
+
+```ts
+import { useDictionary } from "remix-intlayer";
+import { t } from "intlayer";
+
+export const FooterView = () => {
+  const content = useDictionary({
+    key: "footer",
+    content: {
+      copyright: t({
+        ja: "無断転載を禁じます。",
+        en: "All rights reserved.",
+        fr: "Tous droits réservés.",
+        es: "Todos los derechos reservados.",
+      }),
+    },
+  });
+
+  return `<footer>${content.copyright}</footer>`;
+};
+```
+
+## パラメーター
+
+```ts
+useDictionary(dictionary, localeOrSelector?)
+```
+
+1. **`dictionary`**: 辞書オブジェクト、または修飾された辞書グループ。
+2. **`localeOrSelector`**（オプション）: 特定のロケールまたはセレクターオブジェクト（`{ item }`、`{ variant }`、必要に応じて `locale`）。指定された場合、リクエストロケールよりも優先されます。
+
+## 説明
+
+このフックは以下の処理を実行します。
+
+1. **ロケール検出**: `intlayer()` ミドルウェアによって作成された `AsyncLocalStorage` ストアからアクティブなリクエストロケールを読み取ります。
+2. **コンテンツ解決**: 解決されたロケールに従って、翻訳（`t()`）、列挙、条件、およびネストされた構造を評価します。
+3. **セレクター処理**: 引数で指定されたアイテムまたはバリアントセレクターを適用します。
+
+## 関連ドキュメント
+
+- [`intlayer` ミドルウェア](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/remix-intlayer/intlayerMiddleware.md)
+- [`useIntlayer` フック](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/remix-intlayer/useIntlayer.md)
+- [`useLocale` フック](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/remix-intlayer/useLocale.md)

package/docs/ja/packages/remix-intlayer/useIntlayer.md

@@ -0,0 +1,94 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: useIntlayer フックのドキュメント | remix-intlayer
+description: Remix 3 アプリケーションで useIntlayer フックを使用して、キーによってローカライズされたコンテンツにアクセスする方法を説明します。
+keywords:
+  - useIntlayer
+  - dictionary
+  - remix
+  - remix-3
+  - Intlayer
+  - intlayer
+  - 国際化
+  - ドキュメント
+slugs:
+  - doc
+  - packages
+  - remix-intlayer
+  - useIntlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "useIntlayer フックの初期ドキュメント"
+author: aymericzip
+---
+
+# useIntlayer フックのドキュメント
+
+`useIntlayer` フックを使用すると、Remix 3 アプリケーションでキーを指定して Intlayer 辞書からローカライズされたコンテンツを取得できます。
+
+現在のリクエストコンテキスト（`AsyncLocalStorage` 経由）からアクティブなロケールを自動的に読み取るため、ルートハンドラー、ビューテンプレート、またはコンポーネント間でロケールを受け渡す必要はありません。
+
+## 使用方法
+
+### ルートハンドラー内での使用
+
+```ts fileName="src/server.ts"
+import { createRouter } from "remix/router";
+import { intlayer, useIntlayer } from "remix-intlayer";
+
+const router = createRouter({
+  middleware: [intlayer()],
+});
+
+router.get("/api/welcome", () => {
+  const content = useIntlayer("home");
+
+  return Response.json({
+    title: content.title,
+    subtitle: content.subtitle,
+  });
+});
+```
+
+### ビューテンプレートおよびコンポーネント内での使用
+
+```tsx fileName="src/views/home.ts"
+import { useIntlayer } from "remix-intlayer";
+
+export const HomeView = () => {
+  const content = useIntlayer("home");
+
+  return `
+    <main>
+      <h1>${content.title}</h1>
+      <p>${content.subtitle}</p>
+    </main>
+  `;
+};
+```
+
+## パラメーター
+
+```ts
+useIntlayer(key, localeOrSelector?)
+```
+
+1. **`key`**: 辞書の一意のキー（`.content.ts` 宣言ファイルで定義されたもの）。
+2. **`localeOrSelector`**（オプション）: 特定のロケールまたはセレクターオブジェクト（`{ item }`、`{ variant }`、必要に応じて `locale`）。指定された場合、リクエストコンテキストから検出されたロケールを上書きします。
+
+## 説明
+
+このフックは以下の処理を実行します。
+
+1. **コンテキストロケールの取得**: `intlayer()` ミドルウェアによって設定されたリクエストスコープの `AsyncLocalStorage` から現在のロケールを検出します。
+2. **辞書の取得**: 指定されたキーに対応する事前コンパイル済み辞書を取得します。
+3. **翻訳処理**: 解決されたロケールに基づいて、翻訳、列挙、マークダウン、および条件付きコンテンツを解決します。
+4. **フォールバック処理**: アクティブな HTTP リクエストコンテキスト外（ミドルウェアのないバックグラウンドタスクや単体テストなど）で呼び出された場合、設定された `defaultLocale` に安全にフォールバックします。
+
+## 関連ドキュメント
+
+- [`intlayer` ミドルウェア](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/remix-intlayer/intlayerMiddleware.md)
+- [`useDictionary` フック](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/remix-intlayer/useDictionary.md)
+- [`useLocale` フック](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/remix-intlayer/useLocale.md)

package/docs/ja/packages/remix-intlayer/useLocale.md

@@ -0,0 +1,104 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: useLocale フックのドキュメント | remix-intlayer
+description: Remix 3 アプリケーションで useLocale フックを使用して、現在のリクエストロケール、デフォルトロケール、および利用可能なロケールを取得する方法を説明します。
+keywords:
+  - useLocale
+  - locale
+  - remix
+  - remix-3
+  - Intlayer
+  - intlayer
+  - 国際化
+  - ドキュメント
+slugs:
+  - doc
+  - packages
+  - remix-intlayer
+  - useLocale
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "useLocale フックの初期ドキュメント"
+author: aymericzip
+---
+
+# useLocale フックのドキュメント
+
+`remix-intlayer` の `useLocale` フックは、現在処理中の HTTP リクエストのロケールと、プロジェクトで設定されたデフォルトロケールおよび利用可能なロケールへのアクセスを提供します。
+
+## 使用方法
+
+Remixコンポーネント内（例：言語スイッチャー）：
+
+```tsx fileName="src/components/LocaleSwitcher.tsx"
+import { type FC } from "react";
+import { Link } from "@remix-run/react";
+import { useLocale } from "remix-intlayer";
+import { getLocalizedUrl, getPathWithoutLocale } from "intlayer";
+
+export const LocaleSwitcher: FC = () => {
+  const { locale, availableLocales } = useLocale();
+  const pathWithoutLocale = getPathWithoutLocale();
+
+  return (
+    <nav>
+      <ul>
+        {availableLocales.map((localeItem) => (
+          <li key={localeItem} className="p-1">
+            <Link
+              href={getLocalizedUrl(pathWithoutLocale, localeItem)}
+              aria-current={localeItem === locale ? "page" : undefined}
+            >
+              {localeItem.toUpperCase()}
+            </Link>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+};
+```
+
+ルートハンドラー内での使用:
+
+```ts fileName="src/server.ts"
+import { createRouter } from "remix/router";
+import { intlayer, useLocale } from "remix-intlayer";
+
+const router = createRouter({
+  middleware: [intlayer()],
+});
+
+router.get("/api/locale-info", () => {
+  const { locale, defaultLocale, availableLocales } = useLocale();
+
+  return Response.json({
+    locale,
+    defaultLocale,
+    availableLocales,
+  });
+});
+```
+
+## 戻り値
+
+このフックは `UseLocaleResult` 型のオブジェクトを返します。
+
+| プロパティ         | タイプ              | 説明                                                                  |
+| ------------------ | ------------------- | --------------------------------------------------------------------- |
+| `locale`           | `DeclaredLocales`   | 現在のリクエストに対して解決されたロケール。                          |
+| `defaultLocale`    | `DeclaredLocales`   | `intlayer.config.ts` で設定されたデフォルトのフォールバックロケール。 |
+| `availableLocales` | `DeclaredLocales[]` | `intlayer.config.ts` で設定されたすべての利用可能なロケールの配列。   |
+
+## 説明
+
+1. **リクエストスコープの解決**: `intlayer()` ミドルウェアによって処理されるアクティブなリクエスト内で、`useLocale` はリクエストストレージから解決されたロケールを読み取ります。
+2. **安全なフォールバック**: 初期化スクリプトやテストスイートなど、リクエストコンテキスト外で呼び出された場合、設定された `defaultLocale` にフォールバックします。
+
+## 関連ドキュメント
+
+- [`intlayer` ミドルウェア](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/remix-intlayer/intlayerMiddleware.md)
+- [`useIntlayer` フック](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/remix-intlayer/useIntlayer.md)
+- [`useDictionary` フック](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/remix-intlayer/useDictionary.md)

package/docs/ja/readme.md

@@ -199,7 +199,8 @@ Intlayer の包括的なドキュメントを探索し、Intlayer の使い始
   <li><a href="https://intlayer.org/doc/environment/create-react-app" rel=''>React CRA</a></li>
   <li><a href="https://intlayer.org/doc/environment/vite-and-react" rel=''>Vite + React</a></li>
   <li><a href="https://intlayer.org/doc/environment/vite-and-react" rel=''>コンパイラを使用した Vite + React</a></li>
-  <li><a href="https://intlayer.org/doc/environment/vite-and-react/compiler" rel=''>React-router-v7</a></li>
+  <li><a href="https://intlayer.org/doc/environment/vite-and-react/react-router-v7" rel=''>React-router-v7</a></li>
+  <li><a href="https://intlayer.org/doc/environment/remix-3" rel=''>Remix 3</a></li>
   <li><a href="https://intlayer.org/doc/environment/tanstack-start" rel=''>Tanstack start</a>
     <ul>
       <li><a href="https://intlayer.org/doc/environment/tanstack-start/solid" rel=''>Solid</a></li>

package/docs/ko/how_works_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-12
-updatedAt: 2026-08-30
+updatedAt: 2026-09-19
 title: Intlayer 작동 방식
 description: Intlayer가 내부적으로 어떻게 작동하는지 알아보세요. Intlayer를 강력하게 만드는 아키텍처와 구성 요소를 이해하십시오.
 keywords:
@@ -135,49 +135,105 @@ Intlayer는 번역 프로세스에서 특정 역할을 하는 여러 패키지
 
 `intlayer` 패키지는 애플리케이션에서 콘텐츠 파일 내의 콘텐츠를 선언하는 데 사용됩니다.
 
-### react-intlayer
+### 프론트엔드 프레임워크
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
 
 `react-intlayer` 패키지는 Intlayer 사전을 해석하여 React 애플리케이션에서 사용할 수 있도록 합니다.
 
-### next-intlayer
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
 
 `next-intlayer` 패키지는 `react-intlayer` 위에 레이어로 작동하여 Intlayer 사전을 Next.js 애플리케이션에서 사용할 수 있도록 합니다. 번역 미들웨어, 라우팅, 또는 `next.config.js` 파일 구성과 같은 Next.js 환경에서 Intlayer가 작동하도록 필수 기능을 통합합니다.
 
-### vue-intlayer
+  </Tab>
+  <Tab label="Vue" value="vue">
 
 `vue-intlayer` 패키지는 Intlayer 사전을 해석하여 Vue 애플리케이션에서 사용할 수 있도록 합니다.
 
-### nuxt-intlayer
+  </Tab>
+  <Tab label="Nuxt" value="nuxt">
 
 `nuxt-intlayer` 패키지는 Nuxt 모듈로서 Intlayer 사전을 Nuxt 애플리케이션에서 사용할 수 있도록 합니다. 이 패키지는 번역 미들웨어, 라우팅, `nuxt.config.js` 파일 구성 등 Nuxt 환경에서 Intlayer가 작동하는 데 필요한 필수 기능을 통합합니다.
 
-### svelte-intlayer (작업 중)
+  </Tab>
+  <Tab label="Svelte" value="svelte">
 
 `svelte-intlayer` 패키지는 Intlayer 사전을 해석하여 Svelte 애플리케이션에서 사용할 수 있도록 합니다.
 
-### solid-intlayer (작업 중)
+  </Tab>
+  <Tab label="Solid" value="solid">
 
 `solid-intlayer` 패키지는 Intlayer 사전을 해석하여 Solid.js 애플리케이션에서 사용할 수 있도록 합니다.
 
-### preact-intlayer
+  </Tab>
+  <Tab label="Preact" value="preact">
 
 `preact-intlayer` 패키지는 Intlayer 사전을 해석하여 Preact 애플리케이션에서 사용할 수 있도록 합니다.
 
-### angular-intlayer (작업 중)
+  </Tab>
+  <Tab label="Angular" value="angular">
 
 `angular-intlayer` 패키지는 Intlayer 사전을 해석하여 Angular 애플리케이션에서 사용할 수 있도록 합니다.
 
-### express-intlayer
+  </Tab>
+  <Tab label="Astro" value="astro">
 
-`express-intlayer` 패키지는 Express.js 백엔드에서 Intlayer를 사용할 수 있도록 합니다.
+`astro-intlayer` 패키지는 Intlayer를 Astro 애플리케이션에 통합하기 위한 필수 도구를 제공합니다. 로케일 기반 라우팅 및 사전 관리(딕셔너리 관리를) 구성합니다.
+
+  </Tab>
+  <Tab label="Remix" value="remix">
+
+`remix-intlayer` 패키지는 Intlayer를 Remix 애플리케이션에 통합하기 위한 필수 도구를 제공합니다. 로케일 기반 라우팅, 서버 측 컨텍스트 및 사전 관리를 구성합니다.
 
-### react-native-intlayer
+  </Tab>
+  <Tab label="React Native" value="react-native">
 
 `react-native-intlayer` 패키지는 Metro 번들러와 함께 작동하도록 Intlayer 플러그인을 통합하는 도구를 제공합니다.
 
-### lynx-intlayer
+  </Tab>
+  <Tab label="Lit" value="lit">
+
+`lit-intlayer` 패키지는 Lit 애플리케이션에서 Intlayer 사전을 해석하고 사용하기 위한 도구와 컴포넌트를 제공합니다.
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+
+`vanilla-intlayer` 패키지는 Intlayer를 바닐라 JavaScript, HTML 또는 PHP 애플리케이션에 통합하기 위한 도구를 제공합니다.
+
+  </Tab>
+</Tabs>
+
+### 백엔드 프레임워크
+
+<Tabs group="backend">
+  <Tab label="Express" value="express">
+
+`express-intlayer` 패키지는 Express.js 백엔드에서 Intlayer를 사용할 수 있도록 합니다.
+
+  </Tab>
+  <Tab label="Fastify" value="fastify">
+
+`fastify-intlayer` 패키지는 Fastify 애플리케이션에서 국제화를 처리하기 위한 플러그인을 제공합니다. 사용자 로케일을 감지하고 요청(request) 객체에 데코레이터를 추가합니다.
 
-`lynx-intlayer` 패키지는 Lynx 번들러와 함께 작동하도록 Intlayer 플러그인을 통합하는 도구를 제공합니다.
+  </Tab>
+  <Tab label="Hono" value="hono">
+
+`hono-intlayer` 패키지는 국제화를 처리하기 위한 Hono 애플리케이션용 미들웨어를 제공합니다. 사용자의 로케일을 감지하고 컨텍스트 객체를 채웁니다.
+
+  </Tab>
+  <Tab label="Elysia" value="elysia">
+
+`elysia-intlayer` 패키지는 Elysia 애플리케이션에서 국제화를 처리하기 위한 플러그인을 제공합니다. 사용자 로케일을 감지하고 라우트 컨텍스트에 `intlayer` 객체를 주입합니다.
+
+  </Tab>
+  <Tab label="AdonisJS" value="adonis">
+
+`adonis-intlayer` 패키지는 AdonisJS 애플리케이션이 국제화를 처리할 수 있도록 미들웨어를 제공합니다. 사용자의 로케일을 감지하고 번역 기능을 제공합니다.
+
+  </Tab>
+</Tabs>
 
 ### vite-intlayer
 
@@ -187,6 +243,10 @@ Intlayer는 번역 프로세스에서 특정 역할을 하는 여러 패키지
 
 `react-scripts-intlayer` 명령어와 플러그인을 포함하며, Create React App 기반 애플리케이션과 Intlayer를 통합하는 데 사용됩니다. 이 플러그인들은 [craco](https://craco.js.org/)를 기반으로 하며, [Webpack](https://webpack.js.org/) 번들러에 대한 추가 구성을 포함합니다.
 
+### eslint-plugin-intlayer
+
+`eslint-plugin-intlayer` 패키지는 번역되지 않은 문자열을 감지하고 사전 정의를 검증하며 i18n 모범 사례를 적용하기 위한 ESLint 및 oxlint 규칙을 제공합니다.
+
 ### intlayer-editor
 
 `intlayer-editor` 패키지는 시각적 편집기를 사용할 수 있도록 하는 데 사용됩니다. 이 패키지는 선택 사항으로, 애플리케이션에 설치할 수 있으며 `react-intlayer` 패키지에서 사용됩니다.  
@@ -220,6 +280,18 @@ Express를 기반으로 한 서버는 시각적 편집기 요청을 수신하고
 
 `@intlayer/mcp` 패키지는 Intlayer 생태계에 맞춘 AI 기반 IDE 지원을 제공하는 MCP(Model Context Protocol) 서버를 제공합니다. 이 서버는 문서를 자동으로 로드하며 Intlayer CLI와 통합됩니다.
 
+### @intlayer/lsp
+
+`@intlayer/lsp` 패키지는 Intlayer에 맞춘 Language Server Protocol (LSP) 서버를 제공합니다. 정의로 이동, 모든 참조 찾기, 호버 미리보기, 사전 키 자동 완성 및 진단 경고와 같은 IDE 기능을 지원합니다.
+
+### @intlayer/ai
+
+`@intlayer/ai` 패키지는 Intlayer 애플리케이션을 위한 SDK 기능을 제공하여 자동 번역 및 AI 기반 콘텐츠 생성을 지원합니다.
+
+### @intlayer/analytics
+
+`@intlayer/analytics` 패키지는 콘텐츠 노출 지표, 페이지/로케일 및 노드 수준 분석을 수집하고 콘텐츠 A/B 테스트를 지원하는 도구를 제공합니다.
+
 ### @intlayer/dictionaries-entry
 
 `@intlayer/dictionaries-entry` 패키지는 Intlayer 사전의 진입 경로를 반환합니다. 루트의 병합된 사전과 `/unmerged`, `/remote`, `/dynamic`, `/fetch` 하위 경로의 미병합, 원격, 동적 및 fetch 사전입니다. 브라우저에서 파일 시스템을 검색하는 것이 불가능하기 때문에, Webpack이나 Rollup과 같은 번들러를 사용하여 사전의 진입 경로를 가져오는 것은 불가능합니다. 이 패키지와 해당 하위 경로는 별칭(alias)으로 설계되어 Vite, Webpack, Turbopack 등 다양한 번들러에서 번들링 최적화를 가능하게 합니다.

package/docs/ko/intlayer_visual_editor.md

@@ -278,6 +278,13 @@ pnpm intlayer-editor start -e development
 
 비주얼 에디터는 편집 후 재빌드가 허용되는 개발 및 스테이징 환경용으로 설계되었습니다. 배포 없이 실시간 사이트의 콘텐츠를 편집하려면 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_CMS.md)와 원격 사전을 사용하는 것이 좋습니다.
 
+</Question>
+<Question title="비주얼 에디터의 비용은 얼마인가요? 필요하지 않은 경우 과도한가요?">
+
+Intlayer 비주얼 에디터는 설정되지 않은 경우 애플리케이션에 **비용이 전혀 들지 않습니다**. 추가 로직은 명시적으로 활성화되고 필요할 때만 로드됩니다.
+
+활성화하더라도 대부분의 로직은 [app.intlayer.org](https://app.intlayer.org)의 서버 에디터나 `intlayer-editor` 패키지를 통해 처리되므로 영향은 극히 미미합니다(활성화 시 동적으로 로드되는 +5 kB에 불과함). 비주얼 편집 없이 간단한 번역 솔루션만 필요한 경우 Intlayer는 앱에 어떠한 오버헤드도 추가하지 않습니다.
+
 </Question>
 <Question title="비주얼 에디터는 무료인가요?">
 

package/docs/ko/intlayer_with_astro.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-03-07
-updatedAt: 2026-08-30
+updatedAt: 2026-09-19
 title: "Astro i18n - 앱을 번역하는 완전 가이드"
 description: "i18next는 이제 그만. 2026년 다국어 (i18n) Astro 앱 구축 가이드. AI 에이전트로 번역하고 번들 크기, SEO, 성능을 최적화하세요."
 keywords:
@@ -18,6 +18,9 @@ slugs:
 applicationTemplate: https://github.com/aymericzip/intlayer-astro-template
 applicationShowcase: https://intlayer-astro-template.vercel.app
 history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "astro-intlayer에 useIntlayer / useLocale 훅 및 Astro.locals 미들웨어 추가"
   - version: 8.9.0
     date: 2026-05-04
     changes: "Solid useIntlayer API 사용법을 직접 속성 액세스로 업데이트"
@@ -152,7 +155,7 @@ bun add intlayer astro-intlayer
   설정 관리, 번역, [콘텐츠 선언](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/content_file.md), 트랜스파일 및 [CLI 명령어](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/index.md)를 위한 국제화 도구를 제공하는 핵심 패키지입니다.
 
 - **astro-intlayer**
-  Intlayer를 [Vite 번들러](https://vite.dev/guide/why.html#why-bundle-for-production)와 통합하기 위한 Astro 통합 플러그인과 사용자의 선호 로케일을 감지하고 쿠키를 관리하며 URL 리디렉션을 처리하는 미들웨어가 포함되어 있습니다.
+  Intlayer를 [Vite 번들러](https://vite.dev/guide/why.html#why-bundle-for-production)와 통합하기 위한 Astro 통합 플러그인, 모든 요청의 로케일을 `Astro.locals.intlayer`로 확인하는 미들웨어, `useIntlayer` / `useDictionary` / `useLocale` 훅이 포함되어 있습니다. 동일한 import 경로가 `.astro` 프론트매터에서는 서버 구현체로, `<script>` 블록에서는 클라이언트 구현체(`vanilla-intlayer` 기반)로 확인됩니다.
 
 </Step>
 <Step number={2} title="프로젝트 설정">
@@ -229,26 +232,28 @@ export default appContent;
 </Step>
 <Step number={5} title="Astro에서 콘텐츠 사용">
 
-`intlayer`에서 내보낸 핵심 헬퍼를 사용하여 `.astro` 파일에서 직접 사전을 소비할 수 있습니다.
+`astro-intlayer`에서 내보낸 훅을 사용하여 `.astro` 파일에서 사전을 사용하세요. 이 훅들은 `react-intlayer`와 동일한 시그니처를 공유합니다. `useIntlayer("key")`는 사전의 내용을 반환하고 `useLocale()`은 인수를 전달할 필요 없이 현재 로케일을 반환합니다.
+
+로케일은 통합 플러그인이 자체 `src/middleware.ts`보다 먼저 등록하는 `astro-intlayer` 미들웨어에서 제공됩니다. URL 접두사, 클라이언트가 저장한 로케일(쿠키 또는 헤더), `Accept-Language` 순으로 모든 요청에 대해 로케일을 확인하고 이를 `Astro.locals.intlayer`에 저장합니다. 사전 렌더링된 페이지는 방문자마다 한 번만 렌더링되므로 URL만 사용합니다.
+
+또한 각 페이지에 hreflang 및 정식(canonical) 링크와 같은 SEO 메타데이터를 추가하고 사용자가 언어를 변경할 수 있도록 언어 전환기를 포함해야 합니다.
 
 ```astro fileName="src/pages/index.astro"
 ---
+import { useIntlayer, useLocale } from "astro-intlayer";
 import {
-  getIntlayer,
-  getLocaleFromPath,
   getLocalizedUrl,
   defaultLocale,
   localeMap,
   getHTMLTextDir,
-  type LocalesValues,
 } from "intlayer";
 import LocaleSwitcher from "../components/LocaleSwitcher.astro";
 
-// Get the current locale from the URL (e.g. /es/about -> 'es')
-const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
+// 미들웨어에 의해 확인된 로케일 (예: /ko/about -> 'ko')
+const { locale } = useLocale();
 
-// Get the content for the 'app' dictionary
-const { title } = getIntlayer("app", locale);
+// 해당 로케일의 'app' 사전 내용
+const { title } = useIntlayer("app");
 ---
 
 <!doctype html>
@@ -300,6 +305,8 @@ const { title } = getIntlayer("app", locale);
 </html>
 ```
 
+> `Astro.locals.intlayer`는 자체 미들웨어 및 엔드포인트에 `locale`, `defaultLocale`, `availableLocales`도 노출합니다. 단일 호출에 대해 요청 로케일을 재정의하려면 로케일이나 선택기를 두 번째 인수로 전달하세요(`useIntlayer("app", "fr")`, `useIntlayer("faq", { item: 2 })`).
+
 </Step>
 <Step number={6} title="로컬라이즈된 라우팅">
 
@@ -325,44 +332,51 @@ Astro 통합은 개발 중에 언어 인식 라우팅 및 환경 정의를 돕
 
 ```astro fileName="src/components/LocaleSwitcher.astro"
 ---
-import {
-  locales,
-  getLocaleName,
-  getLocalizedUrl,
-  getLocaleFromPath,
-  getPathWithoutLocale,
-  type LocalesValues,
-} from "intlayer";
+import { useLocale } from "astro-intlayer";
+import { getLocaleName, getLocalizedUrl, getPathWithoutLocale } from "intlayer";
 
-const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
+const { locale, availableLocales } = useLocale();
 const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
 ---
 
-<nav>
-  {
-    locales.map((localeItem) => (
-      <a
-        href={getLocalizedUrl(pathWithoutLocale, localeItem)}
-        data-locale={localeItem}
-        aria-current={localeItem === locale ? "page" : undefined}
-      >
-        {getLocaleName(localeItem)}
-      </a>
-    ))
-  }
+<nav aria-label="Languages">
+  <ul>
+    {
+      availableLocales.map((localeItem) => (
+        <li key={localeItem} class="p-1">
+          <a
+            href={getLocalizedUrl(pathWithoutLocale, localeItem)}
+            data-locale={localeItem}
+            aria-current={localeItem === locale ? "page" : undefined}
+          >
+            {getLocaleName(localeItem)}
+          </a>
+        </li>
+      ))
+    }
+  </ul>
 </nav>
 
 <script>
-  import { setLocaleInStorageClient, getLocalizedUrl, type LocalesValues } from "intlayer";
+  // 브라우저에서는 동일한 import가 클라이언트 구현체로 확인됩니다
+  import { useLocale } from "astro-intlayer";
+  import { getLocalizedUrl, type LocalesValues } from "intlayer";
+
+  // 로케일 쿠키에 선택 사항을 저장한 다음 현지화된 URL로 이동합니다
+  const { setLocale } = useLocale({
+    onLocaleChange: (newLocale) => {
+      window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
+    },
+  });
 
   const localeLinks = document.querySelectorAll("[data-locale]");
 
   localeLinks.forEach((link) => {
-    link.addEventListener("click", (e) => {
+    link.addEventListener("click", (event) => {
       const locale = link.getAttribute("data-locale") as LocalesValues;
 
-      // Update the locale cookie
-      setLocaleInStorageClient(locale);
+      event.preventDefault();
+      setLocale(locale);
     });
   });
 </script>
@@ -372,6 +386,13 @@ const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
     display: flex;
     gap: 1rem;
   }
+  ul {
+    display: flex;
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    gap: 0.5rem;
+  }
   a[aria-current="page"] {
     font-weight: bold;
     text-decoration: underline;
@@ -379,8 +400,11 @@ const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
 </style>
 ```
 
-> **지속성에 대한 참고 사항:**
-> 클라이언트 측 스크립트에서 `setLocaleInStorageClient`를 사용하면 사용자의 언어 선호도가 쿠키에 저장됩니다. 이를 통해 Intlayer 미들웨어는 선택을 기억하고 향후 방문 시 사용자가 선호하는 언어로 자동으로 리다이렉트할 수 있습니다.
+> **영속성에 대한 참고 사항:**
+> 클라이언트 측 `useLocale`의 `setLocale`은 사용자의 언어 설정을 쿠키에 저장합니다. 이를 통해 Intlayer 미들웨어는 선택 항목을 기억하고 향후 방문 시 사용자를 선호하는 언어로 자동 리디렉션할 수 있습니다.
+>
+> **서버 / 클라이언트 상호 호환성:**
+> `astro-intlayer`는 프론트매터에서는 서버 훅(`Astro.locals` 읽기)으로 확인되고, `<script>` 블록과 아일랜드에서는 `vanilla-intlayer`의 클라이언트 훅으로 확인되며 동일한 이름과 데이터 구조를 가집니다. `setLocale`과 `onChange`는 클라이언트에서만 동작하므로, 클라이언트 스토어를 초기화하려면 클라이언트에서 `installIntlayer()`를 한 번 호출하세요. `astro-intlayer/client`는 클라이언트 엔트리를 명시적으로 노출합니다.
 
 </Step>
 <Step number={8} title="Sitemap 및 Robots.txt">