@intlayer/docs 9.4.3 → 9.5.0

package/docs/zh/intlayer_with_svelte_kit.md

@@ -70,37 +70,31 @@ author: aymericzip
 Intlayer 经过优化，可与 SvelteKit 完美配合，提供**多语言路由**、**SSR 支持**以及扩展国际化 (i18n) 所需的所有功能。
 
 </Accordion>
-
 <Accordion header="捆绑尺寸">
 
 不要将大量 JSON 文件加载到页面中，而只需加载必要的内容。 Intlayer 有助于**将捆绑包和页面大小减少多达 50%**。
 
 </Accordion>
-
 <Accordion header="可维护性">
 
 确定应用程序内容的范围**有利于大型应用程序的维护**。您可以复制或删除单个功能文件夹，而无需承担检查整个内容代码库的精神负担。此外，Intlayer 具有**完全类型化 (fully typed)**，以确保您的内容的准确性。
 
 </Accordion>
-
 <Accordion header="AI Agent">
 
 共置内容**减少大型语言模型 (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/zh/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="使用 none-dev 扩展">
 
 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)** 来帮助您管理多语言内容**实时**，与译员、文案人员和其他团队成员无缝协作。内容可以本地和/或远程存储。
@@ -108,8 +102,6 @@ Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的
 </Accordion>
 </AccordionGroup>
 
----
-
 ## 在 SvelteKit 应用中设置 Intlayer 的分步指南
 
 查看 GitHub 上的[应用模板](https://github.com/aymericzip/intlayer-sveltekit-template)。
@@ -157,7 +149,6 @@ Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的
 ```
 
 <Steps>
-
 <Step number={1} title="安装依赖项">
 
 使用 npm 安装必要的包：
@@ -207,7 +198,6 @@ bun add vite-intlayer --save-dev
 - **vite-intlayer**：Vite 插件，用于将内容声明与构建过程集成。
 
 </Step>
-
 <Step number={2} title="配置你的项目">
 
 在项目根目录创建一个配置文件：
@@ -226,7 +216,6 @@ export default config;
 ```
 
 </Step>
-
 <Step number={3} title="在 Vite 配置中集成 Intlayer">
 
 更新你的 `vite.config.ts` 以包含 Intlayer 插件。此插件处理你的内容文件的转译。
@@ -242,7 +231,6 @@ export default defineConfig({
 ```
 
 </Step>
-
 <Step number={4} title="声明你的内容">
 
 在你的 `src` 文件夹的任何地方创建内容声明文件（例如 `src/lib/content` 或在你的组件旁边）。这些文件使用 `t()` 函数为每个语言环境定义应用的可翻译内容。
@@ -266,7 +254,6 @@ export default heroContent;
 ```
 
 </Step>
-
 <Step number={5} title="在你的组件中使用 Intlayer">
 
 现在你可以在任何 Svelte 组件中使用 `useIntlayer` 函数。它返回一个响应式 store，在语言环境改变时自动更新。该函数将自动遵守当前的语言环境（在 SSR 和客户端导航期间）。
@@ -292,7 +279,6 @@ export default heroContent;
 ```
 
 </Step>
-
 <Step number={6} title="设置路由" isOptional={true}>
 
 以下步骤展示如何在 SvelteKit 中设置基于语言环境的路由。这允许你的 URL 包含语言环境前缀（例如 `/en/about`、`/fr/about`），以获得更好的 SEO 和用户体验。
@@ -319,7 +305,6 @@ export default heroContent;
 ```
 
 </Step>
-
 <Step number={7} title="处理服务器端语言环境检测">
 
 在 SvelteKit 中，服务器需要知道用户的语言环境以在 SSR 期间呈现正确的内容。我们使用 `hooks.server.ts` 从 URL 或 cookies 检测语言环境。
@@ -534,7 +519,6 @@ export const prerender = true;
 ```
 
 </Step>
-
 <Step number={8} title="国际化链接" isOptional={true}>
 
 为了 SEO，建议用语言环境前缀你的路由（例如 `/en/about`、`/fr/about`）。此组件自动用当前语言环境前缀任何链接。
@@ -569,7 +553,6 @@ goto(localizedPath); // 根据语言环境导航到 /en/about 或 /fr/about
 ```
 
 </Step>
-
 <Step number={9} title="语言切换器" isOptional={true}>
 
 为了允许用户切换语言，更新 URL。
@@ -612,7 +595,6 @@ goto(localizedPath); // 根据语言环境导航到 /en/about 或 /fr/about
 ```
 
 </Step>
-
 <Step number={10} title="添加后端代理" isOptional={true}>
 
 要将后端代理添加到你的 SvelteKit 应用，你可以使用 `vite-intlayer` 插件提供的 `intlayerProxy` 函数。此插件将根据 URL、cookies 和浏览器语言首选项自动检测用户的最佳语言环境。
@@ -638,7 +620,6 @@ export default defineConfig({
 ```
 
 </Step>
-
 <Step number={11} title="设置 intlayer 编辑器 / CMS" isOptional={true}>
 
 要设置 intlayer 编辑器，你必须遵循 [intlayer 编辑器文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)。
@@ -665,7 +646,6 @@ export default defineConfig({
 ```
 
 </Step>
-
 <Step number={12} title="提取你的组件内容" isOptional={true}>
 
 如果你有现有的 codebase，转换数千个文件可能很耗时。
@@ -780,8 +760,6 @@ bun run build # 或 bun run dev
 .intlayer
 ```
 
----
-
 ### 深入了解
 
 - **可视化编辑器**：集成[Intlayer 可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)，以便直接从用户界面编辑翻译内容。
@@ -800,25 +778,21 @@ bun run build # 或 bun run dev
 在 SvelteKit 上，差异主要体现在服务端能力上：Hooks 中的语言环境检测、本地化链接以及编辑器集成都是库内置自带的，无需每个项目手动搭建组装。请参阅 [为什么选择 Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/interest_of_intlayer.md) 和 [Svelte i18n 性能基准](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/svelte.md)。
 
 </Question>
-
 <Question title="i18n 会给我的 SvelteKit bundle 体积增加多少？">
 
 远少于基于命名空间的方案，因为页面永远不会下载它不渲染的语言目录。服务端渲染的标记在服务端直接解析内容，构建时编译器将 `useIntlayer` 调用替换为组件使用的确切字典条目，因此未使用的键和未使用的语言都会被自动丢弃，并且 [动态字典](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/index.md) 会按语言环境拆分剩余内容。与常规替代方案相比，Intlayer 可将 bundle 和页面体积减少高达 50%。请参阅 [Bundle 体积优化](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/bundle_optimization.md) 和 [性能基准](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/svelte.md)。
 
 </Question>
-
 <Question title="我可以从 svelte-i18n 或 typesafe-i18n 迁移而无需重写组件吗？">
 
 基本可以。请按照 [Svelte I18n 迁移指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/svelte-i18n.md) 迁移内容。您也可以逐步迁移：[JSON 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-json.md) 将现有的 JSON 目录作为单一真实来源（source of truth），并生成 Intlayer 字典，使两个层在逐个组件迁移时保持同步。
 
 </Question>
-
 <Question title="我可以保留现有的 JSON 翻译文件吗？">
 
 可以。[JSON 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-json.md) 将您的 `/messages/{locale}/{namespace}.json` 文件作为单一真实来源（source of truth），并双向生成 Intlayer 字典。[PO 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-po.md) 对 gettext 目录执行相同的操作，而 [按语言环境组织的文件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/per_locale_file.md) 允许您按语言拆分内容，而不是将所有语言打包到一个文件中。
 
 </Question>
-
 <Question title="我必须逐个键迁移我的内容吗？">
 
 不需要。运行 `npx intlayer extract`，Intlayer 会读取您的组件，提取面向用户的字符串，并在每个组件旁边生成 `.content` 文件，这样您只需审查 diff，而无需手动逐一复制字符串到语言目录中。本指南的第 12 步详细介绍了此过程。
@@ -828,7 +802,6 @@ bun run build # 或 bun run dev
 开启编译器前有两个限制值得了解：它通过静态分析工作，因此仅在运行时存在的字符串（如 API 错误代码或 CMS 字段）无法被捕获；此外它需要区分用户文本和应用程序逻辑（如 `className="active"` 或状态代码），在大型代码库中需要少量注解。而 [extract 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md) 则通过让您参与审查避免了这两个问题。
 
 </Question>
-
 <Question title="有哪些可用的编辑器和 AI 代理工具？">
 
 共有 5 个工具，均为可选：
@@ -840,43 +813,36 @@ bun run build # 或 bun run dev
 - **[ESLint 插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/eslint.md)**：`no-raw-text` 规则标记硬编码字符串，并提供针对静态字典键和未使用内容的额外规则。
 
 </Question>
-
 <Question title="Intlayer 是否支持 SvelteKit 服务端渲染 (SSR) 和预渲染？">
 
 是的。第 7 步涵盖了在 `hooks.server.ts` 中进行服务端语言环境检测，因此首次 HTML 响应就已经包含正确的语言，这正是搜索引擎与社交爬虫读取的内容。预渲染路由则在构建时直接解析内容。
 
 </Question>
-
 <Question title="如何设置本地化路由和国际化链接？">
 
 第 6 步和第 8 步对此进行了介绍。路由树上的语言环境段加上用于链接的 `getLocalizedUrl` 可保持在活动语言内部导航，`routing.mode` 决定默认语言环境是否需要前缀。请参阅 [配置参考](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
 
 </Question>
-
 <Question title="如何在 Svelte 中构建语言切换器？">
 
 第 9 步展示了该组件。`useLocale` 公开活动语言环境、声明的语言环境以及在 Cookie 中持久化选择的设置函数，而 `getLocalizedUrl` 会重写当前路径，使读者在切换后保留在同一页面。
 
 </Question>
-
 <Question title="如何使用 AI 自动翻译 SvelteKit 应用？">
 
 运行 `npx intlayer fill`，它会使用您选择的 LLM、您自己的提供商和 API 密钥填充缺失的翻译，并且 `--git-diff` 参数可将处理范围限制在当前分支修改的内容。请参阅 [fill 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/fill.md) 和 [CI/CD 集成](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/CI_CD.md)。
 
 </Question>
-
 <Question title="Intlayer 是否支持复数、性别和富文本？">
 
 支持：包括 [复数形式](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/plurial.md)、[基于性别的内容](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/gender.md)、条件渲染、插值用的 [插入内容 (insertions)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/insertion.md)、用于长文本的 [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/markdown.md)，以及用于数字、日期和货币的 [格式化工具](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/formatters.md)。
 
 </Question>
-
 <Question title="翻译人员如何无需接触代码即可编辑内容？">
 
 可以通过自托管的 [可视化编辑器](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 是免费且开源的吗？">
 
 是的，基于 Apache 2.0 许可证开源，包含商业用途。托管版 CMS 是可选的付费服务，同时完全支持 [自托管](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/self_hosting.md)。

package/docs/zh/intlayer_with_tanstack+solid.md

@@ -47,51 +47,43 @@ author: aymericzip
 与 `react-i18next` 或 `i18next` 等主要解决方案相比，Intlayer 是一个附带集成优化的解决方案，例如：
 
 <AccordionGroup>
-
-与“react-i18next”或“i18next”等主要解决方案相比，Intlayer是一个具有集成优化的解决方案，例如：
-
-**完整的 TanStack Start 覆盖**
+<Accordion header="完整的 TanStack Start 覆盖">
 
 Intlayer 经过优化，可与 TanStack Start 和 Solid 完美配合，提供**多语言路由**、**站点地图**以及扩展国际化 (i18n) 所需的所有功能。
 
-**捆绑尺寸**
+</Accordion>
+<Accordion header="捆绑包大小">
 
 不要将大量 JSON 文件加载到页面中，而只需加载必要的内容。 Intlayer 有助于**将捆绑包和页面大小减少多达 50%**。
 
-**可维护性**
+</Accordion>
+<Accordion header="可维护性">
 
 确定应用程序内容的范围**有利于大型应用程序的维护**。您可以复制或删除单个功能文件夹，而无需承担检查整个内容代码库的精神负担。此外，Intlayer 具有**完全类型化 (fully typed)**，以确保您的内容的准确性。
 
-**人工智能代理**
-
-<Accordion header="AI Agent">
+</Accordion>
+<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 skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/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)来帮助**在后台翻译**。
+使用您选择的 LLM，通过自动化在 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 header="使用 none-dev 扩展">
+</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>
 
----
-
 ## 在 Tanstack Start 应用中设置 Intlayer 的分步指南
 
 <Tabs defaultTab="video">
@@ -127,13 +119,11 @@ Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的
 参见 GitHub 上的[应用模板](https://github.com/aymericzip/intlayer-tanstack-start-solid-template)。
 
 <Steps>
-
 <Step number={1} title="创建项目">
 
 首先按照 TanStack Start 网站上的[新建项目](https://tanstack.com/start/latest/docs/framework/solid/quick-start)指南创建一个新的 TanStack Start 项目。
 
 </Step>
-
 <Step number={2} title="安装 Intlayer 包">
 
 使用您首选的包管理器安装必要的包：
@@ -189,9 +179,42 @@ bun add vite-intlayer --dev
   包含用于将 Intlayer 与 [Vite bundler](https://vite.dev/guide/why.html#why-bundle-for-production) 集成的 Vite 插件，以及用于检测用户首选语言环境、管理 cookies 和处理 URL 重定向的中间件。
 
 </Step>
-
 <Step number={3} title="配置您的项目">
 
+### 架构
+
+在此架构中，所有本地化路由都嵌套在 Solid 的 `{-$locale}` 路由段下。这种方法确保每种语言都拥有专用的 URL，同时支持自动区域前缀、验证和 SEO 优化。
+
+```bash
+.
+├── src
+│   ├── components
+│   │   ├── Header.content.ts
+│   │   ├── Header.tsx
+│   │   ├── LocaleSwitcher.content.ts
+│   │   ├── LocaleSwitcher.tsx
+│   │   └── LocalizedLink.tsx
+│   ├── routes
+│   │   ├── {-$locale}
+│   │   │   ├── 404.content.ts
+│   │   │   ├── 404.tsx
+│   │   │   ├── about.content.ts
+│   │   │   ├── about.tsx
+│   │   │   ├── index.content.tsx
+│   │   │   ├── index.tsx
+│   │   │   └── route.tsx             # Locale layout & prefix validation
+│   │   ├── __root.tsx                # Root route with IntlayerProvider
+│   │   └── sitemap[.]xml.ts
+│   ├── router.tsx
+│   └── styles.css
+├── intlayer.config.ts
+├── package.json
+├── tsconfig.json
+└── vite.config.ts
+```
+
+### 配置
+
 创建一个配置文件来配置应用程序的语言：
 
 ```typescript fileName="intlayer.config.ts"
@@ -212,7 +235,6 @@ export default config;
 > 通过此配置文件，您可以设置本地化的 URL、中间件重定向、cookie 名称、内容声明的位置和扩展名、禁用控制台中的 Intlayer 日志等。关于可用参数的完整列表，请参考[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
 
 </Step>
-
 <Step number={4} title="在您的 Vite 配置中集成 Intlayer">
 
 将 intlayer 插件添加到您的配置中：
@@ -246,7 +268,6 @@ export default defineConfig({
 > `intlayer()` Vite 插件用于将 Intlayer 与 Vite 集成。它确保内容声明文件的构建并在开发模式下监控它们。它在 Vite 应用程序中定义 Intlayer 环境变量。此外，它提供别名以优化性能。
 
 </Step>
-
 <Step number={5} title="创建根布局">
 
 通过使用 `useParams` 检测当前语言环境并在 `html` 标签上设置 `lang` 和 `dir` 属性来配置您的根布局以支持国际化。
@@ -291,7 +312,6 @@ const RootComponent: ParentComponent = (props) => {
 ```
 
 </Step>
-
 <Step number={6} title="创建语言环境布局">
 
 创建一个处理语言环境前缀并执行验证的布局。此布局将确保仅处理有效的语言环境。
@@ -328,7 +348,6 @@ export const Route = createFileRoute("/{-$locale}")({
 > 对于 `'no-prefix'` 或 `'search-params'` 模式，您可以完全删除 slot。
 
 </Step>
-
 <Step number={7} title="声明您的内容">
 
 创建和管理您的内容声明以存储翻译：
@@ -380,7 +399,6 @@ export default appContent;
 > 有关更多详情，请参考[内容声明文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)。
 
 </Step>
-
 <Step number={7} title="创建语言环境感知组件和 Hooks">
 
 为本地化导航创建一个 `LocalizedLink` 组件：
@@ -461,15 +479,12 @@ export const useLocalizedNavigate = () => {
 ```
 
 </Step>
-
 <Step number={8} title="在您的页面中使用 Intlayer">
 
 > 在组件中请默认使用 **`useIntlayer`**：这是读取内容的推荐方式，编译器会把它解析为当前渲染的语言环境。仅在 Solid 树之外（路由 `head`、loader 和服务端函数）才使用 `getIntlayer` / `getIntlayerAsync`。
 
 在整个应用程序中访问您的内容字典：
 
-</Step>
-</Steps>
 #### 本地化主页
 
 ```tsx fileName="src/routes/{-$locale}/index.tsx"
@@ -501,14 +516,15 @@ function RouteComponent() {
 >
 > 如果您想在 `string` 属性中使用您的内容，例如 `alt`、`title`、`href`、`aria-label` 等，可以使用函数的值，如下所示：
 >
-> ```html
-> <img src="{content.image.src.value}" alt="{content.image.value}" />
-> <img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
-> <img src="{String(content.image.src)}" alt="{String(content.image)}" />
+> ```tsx
+> <img src={content.image.src.value} alt={content.image.value} />
+> <img src={content.image.src.toString()} alt={content.image.toString()} />
+> <img src={String(content.image.src)} alt={String(content.image)} />
 > ```
 
 > 要了解更多关于 `useIntlayer` hook 的信息，请参考[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/solid-intlayer/useIntlayer.md)。
 
+</Step>
 <Step number={9} title="创建语言切换器组件">
 
 创建一个组件以允许用户更改语言：
@@ -554,7 +570,6 @@ export default LocaleSwitcher;
 > 要了解更多关于 `useLocale` hook 的信息，请参考[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/solid-intlayer/useLocale.md)。
 
 </Step>
-
 <Step number={10} title="HTML 属性管理">
 
 如步骤 5 所示，您可以在根组件中使用 `useParams` 管理 `html` 标签的 `lang` 和 `dir` 属性。这确保在服务器和客户端上正确设置属性。
@@ -573,7 +588,6 @@ const RootComponent: ParentComponent = (props) => {
 ```
 
 </Step>
-
 <Step number={11} title="添加中间件">
 
 您也可以使用 `intlayerProxy` 为您的应用程序添加服务器端路由。该插件将自动根据 URL 检测当前语言环境并设置适当的语言环境 cookie。如果未指定语言环境，该插件将根据用户的浏览器语言首选项确定最合适的语言环境。如果未检测到语言环境，它将重定向到默认语言环境。
@@ -609,7 +623,6 @@ export default defineConfig({
 ```
 
 </Step>
-
 <Step number={12} title="国际化您的元数据">
 
 <Tabs>
@@ -791,7 +804,6 @@ export const Route = createFileRoute("/{-$locale}/")({
 
 </Tabs>
 
-</Step>
 ### 该选择哪种解析方式？
 
 |                | 静态解析             | 动态解析                    | 带缓存的动态解析                          |
@@ -802,6 +814,7 @@ export const Route = createFileRoute("/{-$locale}/")({
 | 客户端导航     | 无需解析             | 每次匹配都重新执行          | 由路由缓存提供                            |
 | 开发体验       | 最简单               | 一个 `await`                | 内容经由 `loaderData` 传递                |
 
+</Step>
 <Step number={13} title="在服务器操作中检索语言环境">
 
 您可能希望从服务器操作或 API 端点内部访问当前语言环境。
@@ -838,12 +851,10 @@ export const getLocaleServer = createServerFn().handler(async () => {
 ```
 
 </Step>
-
 <Step number={14} title="管理未找到页面">
 
 当用户访问不存在的页面时，您可以显示自定义的未找到页面，语言环境前缀可能会影响未找到页面的触发方式。
 
-</Step>
 #### 理解 TanStack Router 的 404 处理与区域设置前缀
 
 在 TanStack Router 中，处理带有本地化路由的 404 页面需要多层次的方法：
@@ -914,6 +925,7 @@ export const Route = createFileRoute("/{-$locale}/$")({
 });
 ```
 
+</Step>
 <Step number={15} title="提取你的组件内容" isOptional={true}>
 
 如果你有现有的代码库，转换数千个文件可能很耗时。
@@ -1028,7 +1040,6 @@ bun run build # 或 bun run dev
 </Tabs>
 
 </Step>
-
 <Step number={16} title="预渲染和生成 Sitemap">
 
 Intlayer 配备了内置的 sitemap 生成器，可以帮助你轻松为应用创建 sitemap。它处理本地化路由并为搜索引擎添加必要的元数据。
@@ -1101,7 +1112,6 @@ export const Route = createFileRoute("/sitemap.xml")({
 ```
 
 </Step>
-
 <Step number={17} title="配置 TypeScript">
 
 Intlayer 使用模块扩展来获得 TypeScript 的好处并使你的代码库更强大。
@@ -1120,6 +1130,8 @@ Intlayer 使用模块扩展来获得 TypeScript 的好处并使你的代码库
 
 </Step>
 
+</Steps>
+
 ### Git 配置
 
 建议忽略 Intlayer 生成的文件。这可以避免将它们提交到您的 Git 仓库。
@@ -1131,8 +1143,6 @@ Intlayer 使用模块扩展来获得 TypeScript 的好处并使你的代码库
 .intlayer
 ```
 
----
-
 ## VS Code 扩展
 
 为了提升 Intlayer 的开发体验，您可以安装官方的 **Intlayer VS Code 扩展**。
@@ -1148,14 +1158,10 @@ Intlayer 使用模块扩展来获得 TypeScript 的好处并使你的代码库
 
 有关如何使用该扩展的更多详细信息，请参阅 [Intlayer VS Code 扩展文档](https://intlayer.org/doc/vs-code-extension)。
 
----
-
 ## 深入探索
 
 如需深入了解，您可以实现[可视化编辑器](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) 外置您的内容。
 
----
-
 ## 文档参考
 
 - [Intlayer 文档](https://intlayer.org)
@@ -1181,25 +1187,21 @@ TanStack Start 本身不包含 i18n 层，而在 Solid 生态中可用的选择
 请参阅 [为什么选择 Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/interest_of_intlayer.md) 和 [TanStack Start i18n 性能基准](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/tanstack.md)。
 
 </Question>
-
 <Question title="i18n 会给我的 TanStack Start bundle 体积增加多少？">
 
 远少于基于命名空间的方案，因为页面永远不会下载它不渲染的语言目录。服务端渲染的标记在服务端直接解析内容，构建时编译器将 `useIntlayer` 调用替换为组件使用的确切字典条目，因此未使用的键和未使用的语言都会被自动丢弃，并且 [动态字典](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/index.md) 会按语言环境拆分剩余内容。与常规替代方案相比，Intlayer 可将 bundle 和页面体积减少高达 50%。请参阅 [Bundle 体积优化](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/bundle_optimization.md) 和 [性能基准](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/tanstack.md)。
 
 </Question>
-
 <Question title="我可以从 @solid-primitives/i18n 或 i18next 迁移而无需重写组件吗？">
 
 基本可以。请按照 [i18next 迁移指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/migration_from_i18next_to_intlayer.md) 迁移内容。您也可以逐步迁移：[JSON 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-json.md) 将您现有的 JSON 目录作为单一真实来源（source of truth），并据此生成 Intlayer 字典，以便在逐步迁移组件时两个层始终保持同步。
 
 </Question>
-
 <Question title="我可以保留现有的 JSON 翻译文件吗？">
 
 可以。[JSON 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-json.md) 将您的 `/messages/{locale}/{namespace}.json` 文件作为单一真实来源（source of truth），并双向生成 Intlayer 字典。[PO 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-po.md) 对 gettext 目录执行相同的操作，而 [按语言环境组织的文件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/per_locale_file.md) 允许您按语言拆分内容，而不是将所有语言打包到一个文件中。
 
 </Question>
-
 <Question title="我必须逐个键迁移我的内容吗？">
 
 不需要。运行 `npx intlayer extract`，Intlayer 会读取您的组件，提取面向用户的字符串，并在每个组件旁边生成 `.content` 文件，这样您只需审查 diff，而无需手动逐一复制字符串到语言目录中。本指南的第 15 步详细介绍了此过程。
@@ -1209,7 +1211,6 @@ TanStack Start 本身不包含 i18n 层，而在 Solid 生态中可用的选择
 开启编译器前有两个限制值得了解：它通过静态分析工作，因此仅在运行时存在的字符串（如 API 错误代码或 CMS 字段）无法被捕获；此外它需要区分用户文本和应用程序逻辑（如 `className="active"` 或状态代码），在大型代码库中需要少量注解。而 [extract 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md) 则通过让您参与审查避免了这两个问题。
 
 </Question>
-
 <Question title="有哪些可用的编辑器和 AI 代理工具？">
 
 共有 5 个工具，均为可选：
@@ -1221,61 +1222,51 @@ TanStack Start 本身不包含 i18n 层，而在 Solid 生态中可用的选择
 - **[ESLint 插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/eslint.md)**：`no-raw-text` 规则标记硬编码字符串，并提供针对静态字典键和未使用内容的额外规则。
 
 </Question>
-
 <Question title="Intlayer 是否支持这里的服务端渲染和预渲染？">
 
 是的。内容在 SSR 期间解析，第 16 步涵盖了为每个本地化路由输出一个静态文档的预渲染配置，以及从同一路由表生成的本地化站点地图。
 
 </Question>
-
 <Question title="切换语言环境会重新渲染整个应用吗？">
 
 不会。内容由 Solid Signals 提供支持，因此切换语言仅会更新读取已更改值的 DOM 节点。
 
 </Question>
-
 <Question title="如何添加 hreflang 标签和本地化站点地图？">
 
 在 `src/routes/sitemap[.]xml.ts` 路由中使用内置的 `generateSitemap` 函数。它会输出 `xhtml:link` 命名空间，让页面的每个语言版本相互建立双向链接。第 12 步介绍了本地化的 `head` 元数据。
 
 </Question>
-
 <Question title="如何处理本地化路由上的 404 页面？">
 
 第 14 步对此进行了介绍。`validatePrefix` 告诉您 URL 的语言环境段是否属于已声明的语言环境，从而使 `/xx/about` 返回真实的 404，而不会被错误索引为重复页面。
 
 </Question>
-
 <Question title="我必须在 URL 中包含语言环境吗？">
 
 不需要。`routing.mode` 支持 `"prefix-no-default"`（默认）、`"prefix-all"`、`"no-prefix"` 和 `"search-params"`，并且 `routing.domains` 可将语言环境映射到其独立域名。请参阅 [配置参考](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
 
 </Question>
-
 <Question title="如何构建保留当前路由的语言切换器？">
 
 第 9 步展示了该组件。`useLocale` 公开当前活动语言环境、可用语言环境以及用于持久化选择的设置函数，而 `getLocalizedUrl` 会将当前路径重写为目标语言，使用户停留在相同页面。
 
 </Question>
-
 <Question title="如何使用 AI 自动翻译应用？">
 
 运行 `npx intlayer fill`。它会使用您选择的 LLM、您自己的提供商和 API 密钥填充缺失的翻译，并且 `--git-diff` 可将范围限制在当前分支修改的内容。请参阅 [fill 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/fill.md) 和 [CI/CD 集成](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/CI_CD.md)。
 
 </Question>
-
 <Question title="Intlayer 是否支持复数、性别和富文本？">
 
 支持：包括 [复数形式](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/plurial.md)、[基于性别的内容](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/gender.md)、条件渲染、插值用的 [插入内容 (insertions)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/insertion.md)、用于长文本的 [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/markdown.md)，以及用于数字、日期和货币的 [格式化工具](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/formatters.md)。
 
 </Question>
-
 <Question title="翻译人员如何无需接触代码即可编辑内容？">
 
 可以通过在您自己的基础设施上运行的 [可视化编辑器](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 是免费且开源的吗？">
 
 是的，基于 Apache 2.0 许可证开源，包含商业用途。托管版 CMS 是可选的付费服务，同时完全支持 [自托管](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/self_hosting.md)。