@intlayer/docs 9.5.4-canary.0 → 9.5.5

package/docs/zh/packages/astro-intlayer/intlayer.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2026-01-21
+updatedAt: 2026-09-19
+title: intlayer 集成文档 | astro-intlayer
+description: 了解如何在 astro.config.mjs 中配置和使用 intlayer Astro 集成。
+keywords:
+  - intlayer
+  - astro
+  - astro-intlayer
+  - 集成
+  - i18n
+  - 国际化
+  - 文档
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - intlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "更新了包含中间件和钩子细节的集成文档"
+  - version: 8.0.0
+    date: 2026-01-21
+    changes: "初始文档"
+author: aymericzip
+---
+
+# intlayer Astro 集成文档
+
+Astro 的 `intlayer` 集成为多语言国际化 (i18n) 配置您的项目。它处理构建时字典准备、Vite 插件注入、请求中间件自动注册以及在重写的本地化路径输出预渲染页面。
+
+## 使用方法
+
+将 `intlayer()` 添加到您的 `astro.config.mjs` 中：
+
+```ts fileName="astro.config.mjs"
+import { defineConfig } from "astro/config";
+import { intlayer } from "astro-intlayer";
+
+export default defineConfig({
+  integrations: [intlayer()],
+});
+```
+
+Astro CLI 的 codemod（`astro add astro-intlayer`）也会生成一个支持的默认导入：
+
+```ts
+import intlayer from "astro-intlayer";
+```
+
+## 说明
+
+该集成接入 Astro 的构建和运行时生命周期：
+
+1. **配置设置 (`astro:config:setup`)**：
+   - **字典准备**：在构建运行之前准备 Intlayer 字典和生成的类型。
+   - **Vite 插件**：注入 Vite 别名插件（实现无缝字典导入）、语言环境路由代理和构建剪裁。
+   - **中间件注册**：自动将 `astro-intlayer/middleware` 注入到项目的中间件链中，在每个传入请求上填充 `Astro.locals.intlayer`。
+2. **构建完成 (`astro:build:done`)**：
+   - **页面重写**：检查本地化 URL 重写规则，并在其对应的本地化路径输出预渲染的 HTML 页面。
+
+## 开箱即用功能
+
+配置完成后，您的 Astro 应用程序可以立即使用：
+
+- `.astro` 组件 frontmatter 中的 `useIntlayer`、`useDictionary` 和 `useLocale` 钩子。
+- Astro 端点和页面中的 `Astro.locals.intlayer` 对象。
+- `<script>` 块中的客户端导入，以响应式更新镜像相同的 API。
+- `astro-intlayer/format` 下的内置格式化程序（`useDate`、`useNumber`、`useCurrency` 等）。
+
+## 相关文档
+
+- [`useIntlayer` 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/astro-intlayer/useIntlayer.md)
+- [`useLocale` 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/astro-intlayer/useLocale.md)
+- [`onRequest` 中间件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/astro-intlayer/onRequest.md)

package/docs/zh/packages/astro-intlayer/onRequest.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: onRequest 中间件文档 | astro-intlayer
+description: 了解如何在 Astro 应用程序中使用 onRequest 中间件解析请求语言环境并填充 Astro.locals.intlayer。
+keywords:
+  - onRequest
+  - middleware
+  - astro
+  - astro-intlayer
+  - Astro.locals
+  - 国际化
+  - 文档
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - onRequest
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "初始文档"
+author: aymericzip
+---
+
+# onRequest Astro 中间件文档
+
+`astro-intlayer/middleware` 中的 `onRequest` 中间件解析每个传入 HTTP 请求的语言环境，并填充 `Astro.locals.intlayer`。
+
+当你在 `astro.config.mjs` 中注册 `intlayer()` 集成时，会自动注入此中间件。只有在使用 `sequence(...)` 手动组合 Astro 中间件时，才需要直接导入它。
+
+## 使用方法
+
+```ts fileName="src/middleware.ts"
+import { onRequest as intlayer } from "astro-intlayer/middleware";
+import { sequence } from "astro:middleware";
+
+export const onRequest = sequence(intlayer, async (context, next) => {
+  // 在自定义中间件中访问解析出的语言环境
+  const { locale } = context.locals.intlayer;
+  console.log(`处理语言环境请求: ${locale}`);
+
+  return next();
+});
+```
+
+## 说明
+
+该中间件执行以下任务：
+
+1. **语言环境检测**：
+   - **URL**：分析 URL 路径前缀或 `?locale=` 查询参数（除非 `routing.mode` 设置为 `no-prefix`）。
+   - **Cookie / 请求头**：检查持久化的语言环境 Cookie 或自定义标头值。
+   - **Accept-Language**：回退到浏览器的首选语言协商。
+   - 对于预渲染页面（`context.isPrerendered`），严格从 URL 中提取语言环境，以防止 Astro 构建警告。
+2. **上下文填充**：使用以下内容填充 `Astro.locals.intlayer`：
+   - `locale`：解析出的语言环境。
+   - `defaultLocale`：默认回退语言环境。
+   - `availableLocales`：配置的语言环境数组。
+3. **AsyncLocalStorage 作用域**：将下游请求处理包装在 `AsyncLocalStorage` 作用域内，允许 `useIntlayer()`、`useDictionary()` 和 `useLocale()` 无需显式传递参数即可访问请求状态。
+
+## `IntlayerLocals` 类型
+
+```ts
+export type IntlayerLocals = {
+  locale: DeclaredLocales;
+  defaultLocale: DeclaredLocales;
+  availableLocales: DeclaredLocales[];
+};
+```
+
+## 相关文档
+
+- [`intlayer` 集成](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/astro-intlayer/intlayer.md)
+- [`useIntlayer` 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/astro-intlayer/useIntlayer.md)
+- [`useLocale` 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/astro-intlayer/useLocale.md)

package/docs/zh/packages/astro-intlayer/useDictionary.md

@@ -0,0 +1,95 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: useDictionary 钩子文档 | astro-intlayer
+description: 了解如何在 Astro 组件和脚本中使用 useDictionary 钩子解析字典对象。
+keywords:
+  - useDictionary
+  - dictionary
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - 国际化
+  - 文档
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useDictionary
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "初始文档"
+author: aymericzip
+---
+
+# useDictionary 钩子文档
+
+`useDictionary` 钩子解析导入的或内联的字典对象，并在 Astro 应用程序中返回当前语言环境的内容。
+
+与通过键从全局字典注册表检索字典的 `useIntlayer` 不同，`useDictionary` 直接操作字典对象。
+
+## 使用方法
+
+```astro fileName="src/pages/index.astro"
+---
+import { useDictionary } from "astro-intlayer";
+import homeContent from "../content/home.content";
+
+const content = useDictionary(homeContent);
+---
+
+<main>
+  <h1>{content.title}</h1>
+  <p>{content.description}</p>
+</main>
+```
+
+您也可以传入使用 `t()` 定义的内联字典：
+
+```astro fileName="src/components/Footer.astro"
+---
+import { useDictionary } from "astro-intlayer";
+import { t } from "intlayer";
+
+const footer = useDictionary({
+  key: "footer",
+  content: {
+    copyright: t({
+      zh: "版权所有。",
+      en: "All rights reserved.",
+      fr: "Tous droits réservés.",
+      es: "Todos los derechos reservados.",
+    }),
+  },
+});
+---
+
+<footer>
+  <p>{footer.copyright}</p>
+</footer>
+```
+
+## 参数
+
+```ts
+useDictionary(dictionary, localeOrSelector?)
+```
+
+1. **`dictionary`**：字典对象或限定字典组。
+2. **`localeOrSelector`**（可选）：特定语言环境或选择器对象（`{ item }`、`{ variant }`，可包含 `locale`）。
+
+## 说明
+
+该钩子执行以下任务：
+
+1. **语言环境检测**：在服务端，它从 `Astro.locals.intlayer` 获取语言环境。在浏览器中，它使用客户端 store 语言环境。
+2. **内容处理**：根据解析出的语言环境评估翻译 (`t()`)、枚举、条件和嵌套结构。
+3. **选择器**：应用参数中提供的任何项或变体选择器。
+
+## 相关文档
+
+- [`intlayer` 集成](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/astro-intlayer/intlayer.md)
+- [`useIntlayer` 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/astro-intlayer/useIntlayer.md)
+- [`useLocale` 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/astro-intlayer/useLocale.md)

package/docs/zh/packages/astro-intlayer/useIntlayer.md

@@ -0,0 +1,98 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: useIntlayer 钩子文档 | astro-intlayer
+description: 了解如何在 Astro 组件和客户端脚本中使用 useIntlayer 钩子访问本地化内容。
+keywords:
+  - useIntlayer
+  - dictionary
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - 国际化
+  - 文档
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useIntlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "初始文档"
+author: aymericzip
+---
+
+# useIntlayer 钩子文档
+
+`useIntlayer` 钩子允许您在 Astro 应用程序中按键检索本地化的字典内容。
+
+可以使用相同的导入路径在两个不同的上下文中调用它：
+
+1. **服务端 / Frontmatter**：在 `.astro` 文件内部，它会自动使用存储在 `Astro.locals.intlayer` 中的请求语言环境来解析内容。
+2. **浏览器 / 客户端 `<script>`**：在客户端脚本或 UI 框架组件内部，它解析为客户端 store 实现 (`vanilla-intlayer`)。
+
+## 使用方法
+
+### 在 Astro 组件 Frontmatter 中
+
+```astro fileName="src/pages/index.astro"
+---
+import { useIntlayer } from "astro-intlayer";
+
+const content = useIntlayer("home");
+---
+
+<main>
+  <h1>{content.title}</h1>
+  <p>{content.description}</p>
+</main>
+```
+
+### 在客户端 `<script>` 块中
+
+```astro fileName="src/components/InteractiveWidget.astro"
+---
+import { useIntlayer } from "astro-intlayer";
+
+const content = useIntlayer("home");
+---
+
+<button id="alert-btn">{content.buttonText}</button>
+
+<script>
+  import { useIntlayer } from "astro-intlayer";
+
+  const content = useIntlayer("home");
+
+  document.getElementById("alert-btn")?.addEventListener("click", () => {
+    alert(content.buttonText);
+  });
+</script>
+```
+
+## 参数
+
+```ts
+useIntlayer(key, localeOrSelector?)
+```
+
+1. **`key`**：字典的唯一键（在 `.content.ts` 声明文件中定义）。
+2. **`localeOrSelector`**（可选）：特定语言环境或选择器对象（`{ item }`、`{ variant }`，可包含 `locale`）。提供时，它会覆盖从请求上下文或客户端 store 检测到的语言环境。
+
+## 说明
+
+该钩子执行以下任务：
+
+1. **语言环境解析**：
+   - 在服务端，通过由 `astro-intlayer/middleware` 初始化的 `AsyncLocalStorage` 作用域从 `Astro.locals.intlayer` 读取活动语言环境。
+   - 在浏览器中，从客户端存储/store 读取活动语言环境。
+2. **字典获取**：注入与指定键匹配的字典内容。
+3. **翻译处理**：将翻译 (`t()`)、枚举、条件和 markdown 解析为可渲染的内容。
+
+## 相关文档
+
+- [`intlayer` 集成](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/astro-intlayer/intlayer.md)
+- [`useDictionary` 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/astro-intlayer/useDictionary.md)
+- [`useLocale` 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/astro-intlayer/useLocale.md)

package/docs/zh/packages/astro-intlayer/useLocale.md

@@ -0,0 +1,126 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: useLocale 钩子文档 | astro-intlayer
+description: 了解如何在 Astro 应用程序中使用 useLocale 钩子访问和管理当前语言环境。
+keywords:
+  - useLocale
+  - locale
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - 国际化
+  - 文档
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useLocale
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "初始文档"
+author: aymericzip
+---
+
+# useLocale 钩子文档
+
+`astro-intlayer` 的 `useLocale` 钩子提供对 Astro 应用程序中当前请求语言环境、配置的默认语言环境以及所有可用语言环境的访问权限。
+
+它在服务器渲染的 `.astro` frontmatter 和客户端 `<script>` 块中表现一致。
+
+## 使用方法
+
+### 在组件 Frontmatter 中（服务端渲染）
+
+```astro fileName="src/layouts/Layout.astro"
+---
+import { useLocale } from "astro-intlayer";
+import { getLocalizedUrl, getPathWithoutLocale } from "intlayer";
+
+const { locale, defaultLocale, availableLocales } = useLocale();
+const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
+---
+
+<!DOCTYPE html>
+<html lang={locale}>
+  <head>
+    <meta charset="utf-8" />
+    <title>Astro + Intlayer</title>
+  </head>
+  <body>
+    <header>
+      <span>当前语言环境：{locale}</span>
+      <span>默认语言环境：{defaultLocale}</span>
+      <nav>
+        <ul>
+          {availableLocales.map((localeItem) => (
+            <li key={localeItem} className="p-1">
+              <a
+                href={getLocalizedUrl(pathWithoutLocale, localeItem)}
+                aria-current={localeItem === locale ? "page" : undefined}
+              >
+                {localeItem.toUpperCase()}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </nav>
+    </header>
+    <slot />
+  </body>
+</html>
+```
+
+### 在客户端 `<script>` 中（交互式）
+
+```astro fileName="src/components/LocaleSwitcher.astro"
+---
+import { useLocale } from "astro-intlayer";
+
+const { locale, availableLocales } = useLocale();
+---
+
+<select id="locale-select">
+  {availableLocales.map((loc) => (
+    <option value={loc} selected={loc === locale}>
+      {loc.toUpperCase()}
+    </option>
+  ))}
+</select>
+
+<script>
+  import { useLocale, setLocaleInStorage } from "astro-intlayer";
+
+  const { setLocale } = useLocale();
+
+  document.getElementById("locale-select")?.addEventListener("change", (e) => {
+    const target = e.target as HTMLSelectElement;
+    setLocale(target.value);
+  });
+</script>
+```
+
+## 返回值
+
+该钩子返回一个 `UseLocaleResult` 类型的对象：
+
+| 属性               | 类型                                   | 描述                                                                        |
+| ------------------ | -------------------------------------- | --------------------------------------------------------------------------- |
+| `locale`           | `DeclaredLocales`                      | 活动语言环境。                                                              |
+| `defaultLocale`    | `DeclaredLocales`                      | 在 `intlayer.config.ts` 中配置的默认回退语言环境。                          |
+| `availableLocales` | `DeclaredLocales[]`                    | 为项目配置的所有受支持语言环境的数组。                                      |
+| `setLocale`        | `(locale: LocalesValues) => void`      | 更新语言环境的函数。（在客户端 `<script>` 中可交互，在 SSR 期间发出警告）。 |
+| `subscribe`        | `(callback: () => void) => () => void` | 订阅客户端语言环境更改。                                                    |
+
+## 服务端与客户端行为
+
+- **在 SSR / 服务端渲染期间**：请求使用固定参数渲染一次。在服务端渲染期间调用 `setLocale()` 没有效果并会发出警告；语言环境切换应在客户端执行或通过导航到目标语言环境 URL 执行。
+- **在客户端脚本中**：`setLocale` 更新客户端 store 并根据您的 Intlayer 配置更新持久化的 Cookie 或本地存储。
+
+## 相关文档
+
+- [`intlayer` 集成](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/astro-intlayer/intlayer.md)
+- [`useIntlayer` 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/astro-intlayer/useIntlayer.md)
+- [`useDictionary` 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/astro-intlayer/useDictionary.md)

package/docs/zh/packages/remix-intlayer/Intlayer.md

@@ -0,0 +1,55 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Intlayer 上下文文档 | remix-intlayer
+description: Remix 3 应用程序中 Intlayer 请求上下文存储键的文档。
+keywords:
+  - Intlayer
+  - remix
+  - remix-3
+  - 请求上下文
+  - 国际化
+  - i18n
+slugs:
+  - doc
+  - packages
+  - remix-intlayer
+  - Intlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Intlayer 上下文键初始文档"
+author: aymericzip
+---
+
+# Intlayer 请求上下文键
+
+`Intlayer` 导出项用作 Remix 3 中的请求上下文存储标识符。它允许在路由处理程序或自定义中间件内直接从 Remix 上下文对象中检索 Intlayer 状态。
+
+## 使用方法
+
+```ts fileName="src/server.ts"
+import { createRouter } from "remix/router";
+import { intlayer, Intlayer } from "remix-intlayer";
+
+const router = createRouter({
+  middleware: [intlayer()],
+});
+
+router.get("/api/current-locale", (context) => {
+  const intlayerState = context.get(Intlayer);
+
+  return Response.json({
+    locale: intlayerState?.locale,
+  });
+});
+```
+
+## 说明
+
+`Intlayer` 由 `intlayer()` 中间件用于将当前会话状态绑定到 Remix 的请求上下文 (`RequestContext`)。通常推荐使用 `useLocale()` 或 `useIntlayer()` 等钩子。通过 `context.get(Intlayer)` 进行直接访问在底层中间件处理程序或显式传递上下文实例的 API 路由中非常有用。
+
+## 相关文档
+
+- [`intlayer` 中间件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/remix-intlayer/intlayerMiddleware.md)
+- [`useLocale` 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/remix-intlayer/useLocale.md)

package/docs/zh/packages/remix-intlayer/exports.md

@@ -0,0 +1,80 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: remix-intlayer 包文档
+description: remix-intlayer 包的导出项文档，为 Remix 3 应用程序提供国际化 (i18n) 支持。
+keywords:
+  - remix-intlayer
+  - remix
+  - remix-3
+  - intlayer
+  - 国际化
+  - i18n
+slugs:
+  - doc
+  - packages
+  - remix-intlayer
+  - exports
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "remix-intlayer 导出的初始文档"
+author: aymericzip
+---
+
+# remix-intlayer 包
+
+`remix-intlayer` 包提供了将 Intlayer 集成到 Remix 3 应用程序中所需的工具。它包含用于请求语言环境检测的中间件、请求上下文访问以及用于检索字典和管理语言环境的钩子 (hooks)。
+
+## 安装
+
+```bash
+npm install remix-intlayer
+```
+
+## 包导出项
+
+### 中间件
+
+| 导出项     | 类型       | 描述                                                                      | 相关文档                                                                                                                       |
+| ---------- | ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `intlayer` | 中间件函数 | 用于 Remix 3 的中间件，用于检测请求语言环境、处理重定向并填充请求上下文。 | [intlayer 中间件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/remix-intlayer/intlayerMiddleware.md) |
+
+### 上下文存储
+
+| 导出项     | 类型                         | 描述                                                                                     | 相关文档                                                                                                             |
+| ---------- | ---------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `Intlayer` | RequestContext 键 / 存储标识 | 用于从 Remix 3 请求上下文 (`context.get(Intlayer)`) 中检索 Intlayer 状态的请求上下文键。 | [Intlayer 上下文](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/remix-intlayer/Intlayer.md) |
+
+### 钩子 (Hooks)
+
+| 导出项          | 类型 | 描述                                                                           | 相关文档                                                                                                                     |
+| --------------- | ---- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| `useIntlayer`   | 钩子 | 根据当前请求语言环境，按键获取并处理字典内容。                                 | [useIntlayer 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/remix-intlayer/useIntlayer.md)     |
+| `useDictionary` | 钩子 | 从导入的字典对象中获取与当前请求语言环境匹配的内容。                           | [useDictionary 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/remix-intlayer/useDictionary.md) |
+| `useLocale`     | 钩子 | 提供对当前请求语言环境、默认语言环境以及项目中所有可用语言环境列表的访问权限。 | [useLocale 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/remix-intlayer/useLocale.md)         |
+
+## 快速入门
+
+### 在路由器中配置中间件
+
+```ts fileName="src/server.ts"
+import { createRouter } from "remix/router";
+import { intlayer } from "remix-intlayer";
+
+export const router = createRouter({
+  middleware: [intlayer()],
+});
+```
+
+### 在视图与组件中使用内容
+
+```ts fileName="src/views/home.ts"
+import { useIntlayer } from "remix-intlayer";
+
+export const HomeView = () => {
+  const content = useIntlayer("home");
+
+  return `<h1>${content.title}</h1><p>${content.description}</p>`;
+};
+```

package/docs/zh/packages/remix-intlayer/intlayerMiddleware.md

@@ -0,0 +1,55 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: intlayer 中间件文档 | remix-intlayer
+description: 了解如何在 Remix 3 中使用 intlayer 中间件检测语言环境、处理重定向并将 Intlayer 状态注入到请求上下文中。
+keywords:
+  - intlayer
+  - middleware
+  - remix
+  - remix-3
+  - 国际化
+  - i18n
+slugs:
+  - doc
+  - packages
+  - remix-intlayer
+  - intlayerMiddleware
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "intlayer 中间件初始文档"
+author: aymericzip
+---
+
+# intlayer 中间件
+
+`intlayer` 中间件函数在 Remix 3 应用程序中配置按请求进行的国际化处理。它检测每个传入请求的语言环境，应用 URL 重定向规则，并将语言环境状态保存在请求上下文中。
+
+## 使用方法
+
+在 Remix 路由器中注册中间件：
+
+```ts fileName="src/server.ts"
+import { createRouter } from "remix/router";
+import { intlayer } from "remix-intlayer";
+
+export const router = createRouter({
+  middleware: [intlayer()],
+});
+```
+
+## 工作原理
+
+中间件对每个传入请求执行以下任务：
+
+1. **语言环境检测**: 根据 Intlayer 配置，从 URL 路径前缀（例如 `/zh/about`）、Cookie 或 `Accept-Language` 请求头中提取语言环境。
+2. **URL 重定向**: 如果请求的路径缺少语言环境前缀，并且配置要求前缀路由，中间件将返回重定向响应 (302/307/308) 到带前缀的相应 URL。
+3. **填充请求上下文**: 使用 `Intlayer` 键将当前解析的语言环境保存到 Remix 请求上下文中，使钩子 (`useLocale`, `useIntlayer`, `useDictionary`) 能够透明使用。
+4. **Cookie 管理**: 在需要持久保存用户首选语言环境时设置 `Set-Cookie` 标头。
+
+## 相关文档
+
+- [`Intlayer` 请求上下文](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/remix-intlayer/Intlayer.md)
+- [`useLocale` 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/remix-intlayer/useLocale.md)
+- [`useIntlayer` 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/remix-intlayer/useIntlayer.md)