@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/docs/zh/intlayer_with_astro.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-03-07
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Astro i18n - 翻译你的应用的完整指南"
 description: "告别 i18next。2026 年构建多语言 (i18n) Astro 应用的完整指南。使用 AI 代理翻译并优化包体积、SEO 和性能。"
 keywords:
@@ -61,64 +61,102 @@ author: aymericzip
 
 <TOC/>
 
-## 为什么选择 Inlayer 而不是替代品？
+## 为什么选择 Intlayer 而不是替代品？
 
 与“astro-i18n”或“i18next”等主要解决方案相比，Intlayer是一个具有集成优化的解决方案，例如：
 
-**完整的 Astro 报道**
+<AccordionGroup>
+
+<Accordion header="Astro 完整支持">
 
 Intlayer 经过优化，可与 Astro 完美配合，提供**多语言路由**、**站点地图**以及扩展国际化 (i18n) 所需的所有功能。
 
-**捆绑尺寸**
+</Accordion>
+
+<Accordion header="包大小">
 
 不要将大量 JSON 文件加载到页面中，而只需加载必要的内容。 Intlayer 有助于**将捆绑包和页面大小减少多达 50%**。
 
-**可维护性**
+</Accordion>
+
+<Accordion header="可维护性">
 
 确定应用程序内容的范围**有利于大型应用程序的维护**。您可以复制或删除单个功能文件夹，而无需承担检查整个内容代码库的精神负担。此外，Intlayer 具有**完全类型化 (fully typed)**，以确保您的内容的准确性。
 
-**人工智能代理**
+</Accordion>
+
+<Accordion header="人工智能代理就绪">
 
 共置内容**减少大型语言模型 (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) 更加流畅。
 
-**自动化**
+</Accordion>
+
+<Accordion header="自动化">
 
 使用您选择的法学硕士，通过自动化在 CI/CD 管道中进行翻译，而费用由您的 AI 提供商承担。 Intlayer 还提供了一个**编译器**来自动提取内容，以及一个[网络平台](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)来帮助**在后台翻译**。
 
-**表现**
+</Accordion>
+
+<Accordion header="性能">
 
 将大量 JSON 文件连接到组件可能会导致性能和反应性问题。 Intlayer 可在构建时 (build time)优化您的内容加载。
 
-**无需开发即可扩展**
+</Accordion>
+
+<Accordion header="非开发人员扩展">
 
 Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的[可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)**和一个**[完整的 CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)** 来帮助您管理多语言内容**实时**，与译员、文案人员和其他团队成员无缝协作。内容可以本地和/或远程存储。
 
+</Accordion>
+
+</AccordionGroup>
+
 ---
 
 ## 在 Astro 中配置 Intlayer 的分步指南
 
 在 GitHub 上查看[应用程序模板](https://github.com/aymericzip/intlayer-astro-template)。
 
-### 第一步：安装依赖
+<Steps>
+
+<Step number={1} title="安装依赖">
 
 使用您喜欢的包管理器安装所需的软件包：
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` 参数是可选的。如果您是 AI 代理，请使用 `intlayer-cli init`。
+
+> 此命令将检测您的环境并安装所需的软件包。例如：
+
 ```bash packageManager="npm"
 npm install intlayer astro-intlayer
-# 可选：如果添加 React 岛支持
-npm install react react-dom react-intlayer @astrojs/react
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer astro-intlayer
-# 可选：如果添加 React 岛支持
-pnpm add react react-dom react-intlayer @astrojs/react
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer astro-intlayer
-# 可选：如果添加 React 岛支持
-yarn add react react-dom react-intlayer @astrojs/react
+```
+
+```bash packageManager="bun"
+bun add intlayer astro-intlayer
 ```
 
 - **intlayer**
@@ -127,7 +165,9 @@ yarn add react react-dom react-intlayer @astrojs/react
 - **astro-intlayer**
   包含将 Intlayer 与 [Vite 构建器](https://vite.dev/guide/why.html#why-bundle-for-production)集成的 Astro 集成插件，以及用于检测用户首选语言、管理 Cookie 和处理 URL 重定向的中间件。
 
-### 第二步：配置您的项目
+</Step>
+
+<Step number={2} title="配置您的项目">
 
 创建一个配置文件来定义您的应用程序语言：
 
@@ -151,7 +191,9 @@ export default config;
 
 > 通过此配置文件，您可以配置本地化 URL、中间件重定向、Cookie 名称、内容声明的位置和扩展名、在控制台中禁用 Intlayer 日志等。有关可用参数的完整列表，请参阅[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
 
-### 第三步：在 Astro 配置中集成 Intlayer
+</Step>
+
+<Step number={3} title="在 Astro 配置中集成 Intlayer">
 
 将 intlayer 插件添加到您的 Astro 配置中。
 
@@ -169,7 +211,9 @@ export default defineConfig({
 
 > `intlayer()` 集成插件用于将 Intlayer 与 Astro 集成。它确保内容声明文件的构建并在开发模式下进行监视。它在 Astro 应用程序中定义 Intlayer 环境变量，并提供别名以优化性能。
 
-### 第四步：声明您的内容
+</Step>
+
+<Step number={4} title="声明您的内容">
 
 创建并管理您的内容声明以存储翻译：
 
@@ -196,9 +240,11 @@ export default appContent;
 
 > 有关更多信息，请参阅[内容声明文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)。
 
-### 第五步：在 Astro 中使用内容
+</Step>
 
-您可以使用 `intlayer` 导出的核心辅助函数直接在 `.astro` 文件中消费词典。
+<Step number={5} title="在 Astro 中使用内容">
+
+您可以使用 `intlayer` 导出的核心辅助函数直接在 `.astro` 文件中消费词典。您还应该向每个页面添加 SEO 元数据（如 hreflang 和规范链接），并包含一个语言切换器以允许用户更改语言。
 
 ```astro fileName="src/pages/index.astro"
 ---
@@ -269,7 +315,9 @@ const { title } = getIntlayer("app", locale);
 </html>
 ```
 
-### 第六步：本地化路由
+</Step>
+
+<Step number={6} title="本地化路由">
 
 创建动态路由段以提供本地化页面（例如 `src/pages/[locale]/index.astro`）：
 
@@ -286,65 +334,149 @@ const { title } = getIntlayer('app');
 
 Astro 集成添加了一个 Vite 中间件，有助于在开发期间进行语言感知路由和环境定义。您还可以使用自己的逻辑或 `intlayer` 的 `getLocalizedUrl` 等工具创建语言之间的链接。
 
-### 第七步：继续使用您喜欢的框架
+</Step>
 
-继续使用您喜欢的框架构建您的应用程序。
+<Step number={7} title="添加语言切换器">
 
-- Intlayer + React: [Intlayer with React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_vite+react.md)
-- Intlayer + Vue: [Intlayer with Vue](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_vite+vue.md)
-- Intlayer + Svelte: [Intlayer with Svelte](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_vite+svelte.md)
-- Intlayer + Solid: [Intlayer with Solid](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_vite+solid.md)
-- Intlayer + Preact: [Intlayer with Preact](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_vite+preact.md)
+为了允许用户在语言之间进行切换，您可以创建一个 `LocaleSwitcher` 组件。此组件应显示所有受支持语言的列表，并链接到每种语言的相同页面。
 
-### TypeScript 配置
+```astro fileName="src/components/LocaleSwitcher.astro"
+---
+import {
+  locales,
+  getLocaleName,
+  getLocalizedUrl,
+  getLocaleFromPath,
+  getPathWithoutLocale,
+  type LocalesValues,
+} from "intlayer";
 
-Intlayer 使用模块扩展来利用 TypeScript，使您的代码库更加健壮。
+const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
+const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
+---
 
-![自动补全](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
+<nav>
+  {
+    locales.map((localeItem) => (
+      <a
+        href={getLocalizedUrl(pathWithoutLocale, localeItem)}
+        data-locale={localeItem}
+        aria-current={localeItem === locale ? "page" : undefined}
+      >
+        {getLocaleName(localeItem)}
+      </a>
+    ))
+  }
+</nav>
+
+<script>
+  import { setLocaleInStorageClient, getLocalizedUrl, type LocalesValues } from "intlayer";
+
+  const localeLinks = document.querySelectorAll("[data-locale]");
+
+  localeLinks.forEach((link) => {
+    link.addEventListener("click", (e) => {
+      const locale = link.getAttribute("data-locale") as LocalesValues;
+
+      // Update the locale cookie
+      setLocaleInStorageClient(locale);
+    });
+  });
+</script>
+
+<style>
+  nav {
+    display: flex;
+    gap: 1rem;
+  }
+  a[aria-current="page"] {
+    font-weight: bold;
+    text-decoration: underline;
+  }
+</style>
+```
 
-![翻译错误](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
+> **关于持久化的注意：**
+> 在客户端脚本中使用 `setLocaleInStorageClient` 可确保将用户的语言偏好保存在 Cookie 中。这允许 Intlayer 中间件记住该选择，并在以后的访问中自动将用户重定向到其偏好的语言。
 
-确保您的 TypeScript 配置包含自动生成的类型。
+</Step>
 
-```json5 fileName="tsconfig.json"
-{
-  // ... 您现有的 TypeScript 配置
-  "include": [
-    // ... 您现有的 TypeScript 配置
-    ".intlayer/**/*.ts", // 包含自动生成的类型
-  ],
-}
-```
+<Step number={8} title="站点地图和 Robots.txt">
 
-### Git 配置
+Intlayer 提供了实用工具来动态创建您的本地化站点地图和 robots.txt 文件。
 
-建议忽略 Intlayer 生成的文件。这可以避免将它们提交到您的 Git 仓库。
+#### 站点地图
 
-为此，您可以将以下说明添加到 `.gitignore` 文件中：
+Intlayer 附带一个内置的站点地图生成器，可帮助您轻松为应用程序创建站点地图。它能够处理本地化路由，并为搜索引擎添加必要的元数据。
 
-```bash
-# 忽略 Intlayer 生成的文件
-.intlayer
+> Intlayer 生成的站点地图支持 `xhtml:link` 命名空间（Hreflang XML 扩展）。与仅列出原始 URL 的默认站点地图生成器不同，Intlayer 会自动在页面的所有语言版本（例如 `/about`、`/about?lang=fr` 和 `/about?lang=es`）之间创建所需的双向链接。这确保了搜索引擎能够正确索引并向合适的受众提供正确的语言版本。
+
+创建 `src/pages/sitemap.xml.ts` 以生成包含所有本地化路由的站点地图。
+
+```typescript fileName="src/pages/sitemap.xml.ts"
+import type { APIRoute } from "astro";
+import { generateSitemap, type SitemapUrlEntry } from "intlayer";
+
+const pathList: SitemapUrlEntry[] = [
+  { path: "/", changefreq: "daily", priority: 1.0 },
+  { 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 });
+
+  return new Response(xmlOutput, {
+    headers: { "Content-Type": "application/xml" },
+  });
+};
 ```
 
-### VS Code 扩展
+#### Robots.txt
 
-为了改善使用 Intlayer 的开发体验，您可以安装**官方 Intlayer VS Code 扩展**。
+创建 `src/pages/robots.txt.ts` 以控制搜索引擎抓取。
 
-[从 VS Code Marketplace 安装](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+```typescript fileName="src/pages/robots.txt.ts"
+import type { APIRoute } from "astro";
+import { getMultilingualUrls } from "intlayer";
 
-此扩展提供：
+const getAllMultilingualUrls = (urls: string[]) =>
+  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
 
-- 翻译键的**自动补全**。
-- 缺失翻译的**实时错误检测**。
-- 翻译内容的**内联预览**。
-- 轻松创建和更新翻译的**快速操作**。
+const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);
 
-有关使用该扩展的更多信息，请参阅 [Intlayer VS Code 扩展文档](https://intlayer.org/doc/vs-code-extension)。
+export const GET: APIRoute = ({ site }) => {
+  const robotsTxt = [
+    "User-agent: *",
+    "Allow: /",
+    ...disallowedPaths.map((path) => `Disallow: ${path}`),
+    "",
+    `Sitemap: ${new URL("/sitemap.xml", site).href}`,
+  ].join("\n");
 
----
+  return new Response(robotsTxt, {
+    headers: { "Content-Type": "text/plain" },
+  });
+};
+```
+
+</Step>
+
+<Step number={9} title="继续使用您喜欢的框架">
+
+继续使用您选择的框架构建您的应用程序。
+
+- Intlayer + React: [Intlayer with React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_astro_react.md)
+- Intlayer + Vue: [Intlayer with Vue](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_astro_vue.md)
+- Intlayer + Svelte: [Intlayer with Svelte](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_astro_svelte.md)
+- 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}>
 
 如果您有现有的代码库，转换数千个文件可能会非常耗时。
 
@@ -407,6 +539,8 @@ 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"
@@ -416,7 +550,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // 添加编译器插件
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```
@@ -424,6 +558,56 @@ export default defineConfig({
  </Tab>
 </Tabs>
 
+</Step>
+
+</Steps>
+
+### TypeScript 配置
+
+Intlayer 使用模块扩展来利用 TypeScript，使您的代码库更加健壮。
+
+![自动补全](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
+
+![翻译错误](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
+
+确保您的 TypeScript 配置包含自动生成的类型。
+
+```json5 fileName="tsconfig.json"
+{
+  // ... 您现有的 TypeScript 配置
+  "include": [
+    // ... 您现有的 TypeScript 配置
+    ".intlayer/**/*.ts", // 包含自动生成的类型
+  ],
+}
+```
+
+### Git 配置
+
+建议忽略 Intlayer 生成的文件。这可以避免将它们提交到您的 Git 仓库。
+
+为此，您可以将以下说明添加到 `.gitignore` 文件中：
+
+```bash
+# 忽略 Intlayer 生成的文件
+.intlayer
+```
+
+### VS Code 扩展
+
+为了改善使用 Intlayer 的开发体验，您可以安装**官方 Intlayer VS Code 扩展**。
+
+[从 VS Code Marketplace 安装](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+此扩展提供：
+
+- 翻译键的**自动补全**。
+- 缺失翻译的**实时错误检测**。
+- 翻译内容的**内联预览**。
+- 轻松创建和更新翻译的**快速操作**。
+
+有关使用该扩展的更多信息，请参阅 [Intlayer VS Code 扩展文档](https://intlayer.org/doc/vs-code-extension)。
+
 ---
 
 ### 深入了解