@intlayer/docs 9.5.4 → 9.5.6

package/docs/zh/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:
@@ -134,49 +134,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 应用中可用。它集成了使 Intlayer 在 Next.js 环境中工作的基本功能，例如翻译中间件、路由或 `next.config.js` 文件配置。
 
-### 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 应用中可用。它集成了使 Intlayer 能够在 Nuxt 环境中工作的关键功能，例如翻译中间件、路由以及 `nuxt.config.js` 文件配置。
 
-### 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 应用所需的工具。它配置基于区域设置（locale）的路由和字典管理。
+
+  </Tab>
+  <Tab label="Remix" value="remix">
+
+`remix-intlayer` 包提供将 Intlayer 集成到 Remix 应用所需的工具。它配置基于区域设置（locale）的路由、服务端上下文和字典管理。
 
-### react-native-intlayer
+  </Tab>
+  <Tab label="React Native" value="react-native">
 
 `react-native-intlayer` 包提供了集成插件的工具，使 Intlayer 能够与 Metro 打包器一起工作。
 
-### 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 应用提供了一个处理国际化的插件。它会检测用户的 locale 并装饰请求对象。
 
-`lynx-intlayer` 包提供了集成插件的工具，使 Intlayer 能够与 Lynx 打包器一起工作。
+  </Tab>
+  <Tab label="Hono" value="hono">
+
+`hono-intlayer` 包为 Hono 应用程序提供了一个处理国际化的中间件。它检测用户的语言并填充上下文对象。
+
+  </Tab>
+  <Tab label="Elysia" value="elysia">
+
+`elysia-intlayer` 包为 Elysia 应用提供了一个处理国际化的插件。它会检测用户的 locale，并向路由上下文注入一个 `intlayer` 对象。
+
+  </Tab>
+  <Tab label="AdonisJS" value="adonis">
+
+`adonis-intlayer` 包为 AdonisJS 应用程序提供了一个处理国际化的中间件。它检测用户的语言区域并提供翻译函数。
+
+  </Tab>
+</Tabs>
 
 ### vite-intlayer
 
@@ -186,6 +242,10 @@ Intlayer 由多个包组成，每个包在翻译过程中都有特定的角色
 
 包括用于将 Intlayer 集成到基于 Create React App 的应用程序中的 `react-scripts-intlayer` 命令和插件。这些插件基于 [craco](https://craco.js.org/)，并包含针对 [Webpack](https://webpack.js.org/) 打包器的额外配置。
 
+### eslint-plugin-intlayer
+
+`eslint-plugin-intlayer` 包提供 ESLint 和 oxlint 规则，用于捕获未翻译的字符串、验证字典定义并在代码库中强制执行 i18n 最佳实践。
+
 ### intlayer-editor
 
 `intlayer-editor` 包用于支持可视化编辑器的使用。这个包是可选的，可以安装到应用程序中，并由 `react-intlayer` 包使用。
@@ -220,6 +280,18 @@ Intlayer 由多个包组成，每个包在翻译过程中都有特定的角色
 `@intlayer/mcp` 包提供一个 MCP（模型上下文协议）服务器，提供针对 Intlayer 生态系统的 AI 驱动的 IDE 辅助。它会自动加载文档并与 Intlayer CLI 集成。
 `@intlayer/mcp` 包提供一个 MCP（模型上下文协议）服务器，提供针对 Intlayer 生态系统定制的 AI 驱动的 IDE 辅助。它会自动加载文档并与 Intlayer CLI 集成。
 
+### @intlayer/lsp
+
+`@intlayer/lsp` 包提供专门为 Intlayer 定制的语言服务器协议（LSP）服务。它为支持 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 这样的打包工具来获取字典的入口路径。该包及其子路径设计为别名，以便在 Vite、Webpack 和 Turbopack 等各种打包工具中进行打包优化。

package/docs/zh/intlayer_visual_editor.md

@@ -278,6 +278,13 @@ pnpm intlayer-editor start -e development
 
 它是专为开发和预发布 (staging) 环境设计的，在这类环境中编辑后触发重新构建是可以接受的。若要在无需重新部署的情况下直接修改线上运行中的内容，请使用 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) 及其远程字典功能。
 
+</Question>
+<Question title="可视化编辑器的成本是多少？如果我不需要它，会不会显得多余？">
+
+如果未进行配置，Intlayer 可视化编辑器对您的应用程序是 **零成本** 的。额外的逻辑仅在显式启用并在需要时才会加载。
+
+即使启用，其开销也极其轻量（仅在激活时动态加载 +5 kB），因为主要逻辑由 [app.intlayer.org](https://app.intlayer.org) 上的服务端编辑器或通过 `intlayer-editor` 软件包进行处理。如果您只需要一个无需可视化编辑的简单翻译方案，Intlayer 不会给您的应用带来任何额外负担。
+
 </Question>
 <Question title="可视化编辑器是免费的吗？">
 

package/docs/zh/intlayer_with_astro.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-03-07
-updatedAt: 2026-08-30
+updatedAt: 2026-09-20
 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/zh/dictionary/content_file.md)、编译和 [CLI 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md)的国际化工具。
 
 - **astro-intlayer**
-  包含将 Intlayer 与 [Vite 构建器](https://vite.dev/guide/why.html#why-bundle-for-production)集成的 Astro 集成插件，以及用于检测用户首选语言、管理 Cookie 和处理 URL 重定向的中间件。
+  包含用于将 Intlayer 与 [Vite 打包器](https://vite.dev/guide/why.html#why-bundle-for-production) 集成的 Astro 集成插件、将每个请求的语言环境解析到 `Astro.locals.intlayer` 的中间件，以及 `useIntlayer` / `useDictionary` / `useLocale` 钩子。相同的导入路径在 `.astro` frontmatter 中解析为服务端实现，在 `<script>` 块中解析为客户端实现（由 `vanilla-intlayer` 支持）。
 
 </Step>
 <Step number={2} title="配置您的项目">
@@ -229,26 +232,28 @@ export default appContent;
 </Step>
 <Step number={5} title="在 Astro 中使用内容">
 
-您可以使用 `intlayer` 导出的核心辅助函数直接在 `.astro` 文件中消费词典。您还应该向每个页面添加 SEO 元数据（如 hreflang 和规范链接），并包含一个语言切换器以允许用户更改语言。
+使用 `astro-intlayer` 导出的钩子在 `.astro` 文件中使用你的字典。它们与 `react-intlayer` 具有相同的签名：`useIntlayer("key")` 返回字典内容，`useLocale()` 返回当前语言环境，无需传递参数。
+
+语言环境来自 `astro-intlayer` 中间件，集成会自动在你的 `src/middleware.ts` 之前注册该中间件。它会依次从 URL 前缀、客户端持久化的语言环境（Cookie 或标头）、`Accept-Language` 解析每个请求的语言环境，并将其存储在 `Astro.locals.intlayer` 中。预渲染页面仅使用 URL，因为它们只为每个访客渲染一次。
+
+你还应该向每个页面添加 hreflang 和规范链接等 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;
+// 中间件解析的语言环境（例如 /zh/about -> 'zh'）
+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 集成添加了一个 Vite 中间件，有助于在开发期间进行语
 
 ```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 { useLocale } from "astro-intlayer";
+  import { getLocalizedUrl, type LocalesValues } from "intlayer";
+
+  // 将选择持久化到语言环境 Cookie 中，然后导航到本地化 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` 可确保将用户的语言偏好保存在 Cookie 中。这允许 Intlayer 中间件记住该选择，并在以后的访问中自动将用户重定向到其偏好的语言。
+> **持久化注意事项：**
+> 客户端 `useLocale` 中的 `setLocale` 将用户的语言偏好保存在 cookie 中。这使 Intlayer 能够记住该选择，并在将来的访问中自动将用户重定向到其首选语言：按需渲染的页面（带有 `output: 'server'` 或 `prerender = false` 的适配器）在发送任何 HTML 之前由 Intlayer 中间件重定向，而作为静态文件提供的预渲染页面则由集成注入每个页面的小脚本重定向。将 `routing.enableProxy` 设置为 `false` 可同时关闭两者。在 `astro dev` 中，除非将 `routing.enableProxy` 设置为 `true`，否则 cookie 将被忽略作为重定向来源，因此过期的 cookie 不会劫持你正在处理的页面。
+>
+> **服务端 / 客户端互兼容性：**
+> `astro-intlayer` 在 frontmatter 中解析为服务端钩子（读取 `Astro.locals`），在 `<script>` 块和孤岛（islands）中解析为 `vanilla-intlayer` 的客户端钩子，具有相同的名称和内容结构。`setLocale` 和 `onChange` 仅在客户端起作用，在客户端调用一次 `installIntlayer()` 以初始化客户端存储。`astro-intlayer/client` 显式公开客户端入口。
 
 </Step>
 <Step number={8} title="站点地图和 Robots.txt">
@@ -404,10 +428,10 @@ const pathList: SitemapUrlEntry[] = [
   { path: "/about", changefreq: "monthly", priority: 0.7 },
 ];
 
-const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
-
 export const GET: APIRoute = async ({ site }) => {
-  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
+  const xmlOutput = generateSitemap(pathList, {
+    siteUrl: "https://example.com",
+  });
 
   return new Response(xmlOutput, {
     headers: { "Content-Type": "application/xml" },
@@ -454,7 +478,6 @@ export const GET: APIRoute = ({ site }) => {
 - Intlayer + Solid: [Intlayer with Solid](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_astro_solid.md)
 - Intlayer + Preact: [Intlayer with Preact](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_astro_preact.md)
 - Intlayer + Lit: [Intlayer with Lit](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_astro_lit.md)
-- Intlayer + Vanilla JS: [Intlayer with Vanilla JS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_astro_vanilla.md)
 </Step>
 
 <Step number={15} title="提取组件中的内容" isOptional={true}>
@@ -520,21 +543,7 @@ 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"
-import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [
-    intlayer(),
-    intlayerCompiler(), // Adds the compiler plugin
-  ],
-});
-```
+构建你的应用程序来转换你的组件并提取内容
 
 ```bash packageManager="npm"
 npm run build # 或 npm run dev

package/docs/zh/intlayer_with_astro_lit.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-24
-updatedAt: 2026-08-30
+updatedAt: 2026-09-20
 title: "Astro + Lit i18n - 翻译你的应用的完整指南"
 description: "告别 i18next。2026 年构建多语言 (i18n) Astro + Lit 应用的完整指南。使用 AI 代理翻译并优化包体积、SEO 和性能。"
 keywords:
@@ -20,6 +20,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 页面中使用 astro-intlayer 的 useIntlayer / useLocale 钩子"
   - version: 8.9.0
     date: 2026-05-04
     changes: "更新 Solid useIntlayer API 用法以直接访问属性"
@@ -151,7 +154,7 @@ bun add intlayer astro-intlayer lit lit-intlayer @astrojs/lit
   核心软件包，提供用于配置管理、翻译、[内容声明](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)、编译和 [CLI 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md)的国际化工具。
 
 - **astro-intlayer**
-  包含将 Intlayer 与 [Vite 构建器](https://vite.dev/guide/why.html#why-bundle-for-production)集成的 Astro 集成插件，以及用于检测用户首选语言、管理 Cookie 和处理 URL 重定向的中间件。
+  包含用于将 Intlayer 与 [Vite 打包器](https://vite.dev/guide/why.html#why-bundle-for-production) 集成的 Astro 集成插件、将每个请求的语言环境解析到 `Astro.locals.intlayer` 的中间件，以及 `useIntlayer` / `useDictionary` / `useLocale` 钩子。相同的导入路径在 `.astro` frontmatter 中解析为服务端实现，在 `<script>` 块中解析为客户端实现（由 `vanilla-intlayer` 支持）。
 
 - **lit**
   核心 Lit 软件包，用于构建快速且轻量级的 Web Components。
@@ -245,19 +248,21 @@ export default litDemoContent;
 </Step>
 <Step number={5} title="在 Astro 中使用内容">
 
-您可以使用 `intlayer` 导出的核心辅助函数直接在 `.astro` 文件中消费词典。您还应在每个页面添加 SEO 元数据（如 hreflang 和规范链接）。Lit 自定义元素通过客户端 `<script>` 导入并放置在 body 中。
+使用 `astro-intlayer` 导出的钩子在 `.astro` 文件中使用你的字典。它们与 `react-intlayer` 具有相同的签名：`useIntlayer("key")` 返回字典内容，`useLocale()` 返回当前语言环境，无需传递参数。
+
+语言环境来自 `astro-intlayer` 中间件，集成会自动在你的 `src/middleware.ts` 之前注册该中间件。它会依次从 URL 前缀、客户端持久化的语言环境（Cookie 或标头）、`Accept-Language` 解析每个请求的语言环境，并将其存储在 `Astro.locals.intlayer` 中。预渲染页面仅使用 URL，因为它们只为每个访客渲染一次。
+
+Lit 自定义元素通过客户端 `<script>` 导入并放置在 body 中。
 
 ```astro fileName="src/pages/[...locale]/index.astro"
 ---
+import { useIntlayer, useLocale } from "astro-intlayer";
 import {
-  getIntlayer,
-  getLocaleFromPath,
   getLocalizedUrl,
-  getHTMLTextDir,
   getPrefix,
   localeMap,
   defaultLocale,
-  type LocalesValues,
+  getHTMLTextDir,
 } from "intlayer";
 
 export const getStaticPaths = () => {
@@ -266,8 +271,11 @@ export const getStaticPaths = () => {
   }));
 };
 
-const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
-const { greeting } = getIntlayer("lit-demo", locale);
+// 中间件解析的语言环境（例如 /zh/about -> 'zh'）
+const { locale } = useLocale();
+
+// 该语言环境的 'lit-demo' 字典内容
+const { greeting } = useIntlayer("lit-demo");
 ---
 
 <!doctype html>
@@ -326,6 +334,8 @@ const { greeting } = getIntlayer("lit-demo", locale);
 > <img src={String(content.image.src)} alt={String(content.image)} />
 > ```
 
+> `Astro.locals.intlayer` 还向你自己的中间件和端点公开 `locale`、`defaultLocale` 和 `availableLocales`。将语言环境或选择器作为第二个参数传递（`useIntlayer("app", "fr")`、`useIntlayer("faq", { item: 2 })`）可在单次调用中覆盖请求语言环境。
+
 > **关于路由设置的说明：**
 > 您使用的目录结构取决于 `intlayer.config.ts` 中的 `middleware.routing` 设置：
 >
@@ -482,10 +492,10 @@ const pathList: SitemapUrlEntry[] = [
   { path: "/about", changefreq: "monthly", priority: 0.7 },
 ];
 
-const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
-
 export const GET: APIRoute = async ({ site }) => {
-  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
+  const xmlOutput = generateSitemap(pathList, {
+    siteUrl: "https://example.com",
+  });
 
   return new Response(xmlOutput, {
     headers: { "Content-Type": "application/xml" },
@@ -585,21 +595,7 @@ 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"
-import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [
-    intlayer(),
-    intlayerCompiler(), // Adds the compiler plugin
-  ],
-});
-```
+构建你的应用程序来转换你的组件并提取内容
 
 ```bash packageManager="npm"
 npm run build # 或 npm run dev

package/docs/zh/intlayer_with_astro_preact.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-24
-updatedAt: 2026-08-30
+updatedAt: 2026-09-20
 title: "Astro + Preact i18n - 翻译你的应用的完整指南"
 description: "告别 i18next。2026 年构建多语言 (i18n) Astro + Preact 应用的完整指南。使用 AI 代理翻译并优化包体积、SEO 和性能。"
 keywords:
@@ -19,6 +19,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 页面中使用 astro-intlayer 的 useIntlayer / useLocale 钩子"
   - version: 8.9.0
     date: 2026-05-04
     changes: "更新 Solid useIntlayer API 用法以直接访问属性"
@@ -150,7 +153,7 @@ bun add intlayer astro-intlayer preact preact-intlayer @astrojs/preact
   核心软件包，提供用于配置管理、翻译、[内容声明](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)、编译和 [CLI 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md)的国际化工具。
 
 - **astro-intlayer**
-  包含将 Intlayer 与 [Vite 构建器](https://vite.dev/guide/why.html#why-bundle-for-production)集成的 Astro 集成插件，以及用于检测用户首选语言、管理 Cookie 和处理 URL 重定向的中间件。
+  包含用于将 Intlayer 与 [Vite 打包器](https://vite.dev/guide/why.html#why-bundle-for-production) 集成的 Astro 集成插件、将每个请求的语言环境解析到 `Astro.locals.intlayer` 的中间件，以及 `useIntlayer` / `useDictionary` / `useLocale` 钩子。相同的导入路径在 `.astro` frontmatter 中解析为服务端实现，在 `<script>` 块中解析为客户端实现（由 `vanilla-intlayer` 支持）。
 
 - **preact**
   核心 Preact 软件包 - React 的快速且轻量级的替代方案。
@@ -242,19 +245,21 @@ export default appContent;
 </Step>
 <Step number={5} title="在 Astro 中使用内容">
 
-您可以使用 `intlayer` 导出的核心辅助函数直接在 `.astro` 文件中消费词典。您还应在每个页面添加 SEO 元数据（如 hreflang 和规范链接），并为客户端交互内容引入 Preact 岛。
+使用 `astro-intlayer` 导出的钩子在 `.astro` 文件中使用你的字典。它们与 `react-intlayer` 具有相同的签名：`useIntlayer("key")` 返回字典内容，`useLocale()` 返回当前语言环境，无需传递参数。
+
+语言环境来自 `astro-intlayer` 中间件，集成会自动在你的 `src/middleware.ts` 之前注册该中间件。它会依次从 URL 前缀、客户端持久化的语言环境（Cookie 或标头）、`Accept-Language` 解析每个请求的语言环境，并将其存储在 `Astro.locals.intlayer` 中。预渲染页面仅使用 URL，因为它们只为每个访客渲染一次。
+
+您还应在每个页面添加 SEO 元数据（如 hreflang 和规范链接），并为客户端交互内容引入 Preact 岛。
 
 ```astro fileName="src/pages/[...locale]/index.astro"
 ---
+import { useIntlayer, useLocale } from "astro-intlayer";
 import {
-  getIntlayer,
-  getLocaleFromPath,
   getLocalizedUrl,
-  getHTMLTextDir,
   getPrefix,
   localeMap,
   defaultLocale,
-  type LocalesValues,
+  getHTMLTextDir,
 } from "intlayer";
 import { PreactIsland } from "../../components/preact/PreactIsland";
 
@@ -264,8 +269,11 @@ export const getStaticPaths = () => {
   }));
 };
 
-const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
-const { title } = getIntlayer("app", locale);
+// 中间件解析的语言环境（例如 /zh/about -> 'zh'）
+const { locale } = useLocale();
+
+// 该语言环境的 'app' 字典内容
+const { title } = useIntlayer("app");
 ---
 
 <!doctype html>
@@ -321,6 +329,8 @@ const { title } = getIntlayer("app", locale);
 > <img src={String(content.image.src)} alt={String(content.image)} />
 > ```
 
+> `Astro.locals.intlayer` 还向你自己的中间件和端点公开 `locale`、`defaultLocale` 和 `availableLocales`。将语言环境或选择器作为第二个参数传递（`useIntlayer("app", "fr")`、`useIntlayer("faq", { item: 2 })`）可在单次调用中覆盖请求语言环境。
+
 > **关于路由设置的说明：**
 > 您使用的目录结构取决于 `intlayer.config.ts` 中的 `middleware.routing` 设置：
 >
@@ -437,10 +447,10 @@ const pathList: SitemapUrlEntry[] = [
   { path: "/about", changefreq: "monthly", priority: 0.7 },
 ];
 
-const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
-
 export const GET: APIRoute = async ({ site }) => {
-  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
+  const xmlOutput = generateSitemap(pathList, {
+    siteUrl: "https://example.com",
+  });
 
   return new Response(xmlOutput, {
     headers: { "Content-Type": "application/xml" },
@@ -540,21 +550,7 @@ 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"
-import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [
-    intlayer(),
-    intlayerCompiler(), // Adds the compiler plugin
-  ],
-});
-```
+构建你的应用程序来转换你的组件并提取内容
 
 ```bash packageManager="npm"
 npm run build # 或 npm run dev
@@ -721,6 +717,13 @@ Astro 页面将语言环境作为 prop 向下传递，孤岛中的 Intlayer Prov
 
 可以通过自托管的 [可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)（任何人都可以直接在运行中的应用上就地修改文案），或通过 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) 进行无需重新部署的内容外部化更新。
 
+</Question>
+<Question title="可视化编辑器的成本是多少？如果我不需要它，会不会显得多余？">
+
+如果未进行配置，Intlayer [可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)对您的应用程序是 **零成本** 的。额外的逻辑仅在显式启用并在需要时才会加载。
+
+即使启用，其开销也极其轻量（仅在激活时动态加载 +5 kB），因为主要逻辑由 [app.intlayer.org](https://app.intlayer.org) 上的服务端编辑器或通过 `intlayer-editor` 软件包进行处理。如果您只需要一个无需可视化编辑的简单翻译方案，Intlayer 不会给您的应用带来任何额外负担。
+
 </Question>
 <Question title="Intlayer 是免费且开源的吗？">