@intlayer/docs 9.4.1 → 9.4.3

package/docs/zh/intlayer_with_tanstack+solid.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-25
-updatedAt: 2026-08-25
+updatedAt: 2026-08-30
 title: "TanStack Start + Solid i18n - 翻译你的应用的完整指南"
 description: "告别 i18next。2026 年构建多语言 (i18n) TanStack Start + Solid 应用的完整指南。使用 AI 代理翻译并优化包体积、SEO 和性能。"
 keywords:
@@ -58,8 +58,6 @@ Intlayer 经过优化，可与 TanStack Start 和 Solid 完美配合，提供**
 
 不要将大量 JSON 文件加载到页面中，而只需加载必要的内容。 Intlayer 有助于**将捆绑包和页面大小减少多达 50%**。
 
-</Accordion>
-
 **可维护性**
 
 确定应用程序内容的范围**有利于大型应用程序的维护**。您可以复制或删除单个功能文件夹，而无需承担检查整个内容代码库的精神负担。此外，Intlayer 具有**完全类型化 (fully typed)**，以确保您的内容的准确性。
@@ -72,6 +70,7 @@ Intlayer 经过优化，可与 TanStack Start 和 Solid 完美配合，提供**
 
 **自动化**
 
+</Accordion>
 <Accordion header="自动化">
 
 使用您选择的法学硕士，通过自动化在 CI/CD 管道中进行翻译，而费用由您的 AI 提供商承担。 Intlayer 还提供了一个**编译器**来自动提取内容，以及一个[网络平台](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)来帮助**在后台翻译**。
@@ -144,15 +143,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > `--interactive` 标志是可选的。如果您是 AI agent，请使用 `intlayer-cli init`。
@@ -469,6 +468,8 @@ export const useLocalizedNavigate = () => {
 
 在整个应用程序中访问您的内容字典：
 
+</Step>
+</Steps>
 #### 本地化主页
 
 ```tsx fileName="src/routes/{-$locale}/index.tsx"
@@ -508,8 +509,6 @@ function RouteComponent() {
 
 > 要了解更多关于 `useIntlayer` hook 的信息，请参考[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/solid-intlayer/useIntlayer.md)。
 
-</Step>
-
 <Step number={9} title="创建语言切换器组件">
 
 创建一个组件以允许用户更改语言：
@@ -573,8 +572,6 @@ const RootComponent: ParentComponent = (props) => {
 };
 ```
 
----
-
 </Step>
 
 <Step number={11} title="添加中间件">
@@ -611,8 +608,6 @@ export default defineConfig({
 });
 ```
 
----
-
 </Step>
 
 <Step number={12} title="国际化您的元数据">
@@ -796,6 +791,7 @@ export const Route = createFileRoute("/{-$locale}/")({
 
 </Tabs>
 
+</Step>
 ### 该选择哪种解析方式？
 
 |                | 静态解析             | 动态解析                    | 带缓存的动态解析                          |
@@ -806,10 +802,6 @@ export const Route = createFileRoute("/{-$locale}/")({
 | 客户端导航     | 无需解析             | 每次匹配都重新执行          | 由路由缓存提供                            |
 | 开发体验       | 最简单               | 一个 `await`                | 内容经由 `loaderData` 传递                |
 
----
-
-</Step>
-
 <Step number={13} title="在服务器操作中检索语言环境">
 
 您可能希望从服务器操作或 API 端点内部访问当前语言环境。
@@ -845,14 +837,13 @@ export const getLocaleServer = createServerFn().handler(async () => {
 });
 ```
 
----
-
 </Step>
 
 <Step number={14} title="管理未找到页面">
 
 当用户访问不存在的页面时，您可以显示自定义的未找到页面，语言环境前缀可能会影响未找到页面的触发方式。
 
+</Step>
 #### 理解 TanStack Router 的 404 处理与区域设置前缀
 
 在 TanStack Router 中，处理带有本地化路由的 404 页面需要多层次的方法：
@@ -923,8 +914,6 @@ export const Route = createFileRoute("/{-$locale}/$")({
 });
 ```
 
-</Step>
-
 <Step number={15} title="提取你的组件内容" isOptional={true}>
 
 如果你有现有的代码库，转换数千个文件可能很耗时。
@@ -1038,8 +1027,6 @@ bun run build # 或 bun run dev
  </Tab>
 </Tabs>
 
----
-
 </Step>
 
 <Step number={16} title="预渲染和生成 Sitemap">
@@ -1113,8 +1100,6 @@ export const Route = createFileRoute("/sitemap.xml")({
 });
 ```
 
----
-
 </Step>
 
 <Step number={17} title="配置 TypeScript">
@@ -1133,12 +1118,8 @@ Intlayer 使用模块扩展来获得 TypeScript 的好处并使你的代码库
 }
 ```
 
----
-
 </Step>
 
-</Steps>
-
 ### Git 配置
 
 建议忽略 Intlayer 生成的文件。这可以避免将它们提交到您的 Git 仓库。
@@ -1175,11 +1156,130 @@ Intlayer 使用模块扩展来获得 TypeScript 的好处并使你的代码库
 
 ---
 
-## 参考文献
+## 文档参考
 
 - [Intlayer 文档](https://intlayer.org)
 - [Tanstack Start 文档](https://tanstack.com/start/latest)
-- [useIntlayer 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/solid-intlayer/useIntlayer.md)
-- [useLocale 钩子](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/solid-intlayer/useLocale.md)
+- [useIntlayer Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/solid-intlayer/useIntlayer.md)
+- [useLocale Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/solid-intlayer/useLocale.md)
 - [内容声明](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)
-- [配置](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)
+- [配置指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)
+
+## 常见问题
+
+<FAQ>
+
+<Question title="国际化 TanStack Start + Solid 应用有哪些不同的解决方案？">
+
+TanStack Start 本身不包含 i18n 层，而在 Solid 生态中可用的选择相对有限：
+
+- **`@solid-primitives/i18n`**：扁平化字典，需要您自行组装并手动接入路由器。
+- **带有 Solid 封装的 `i18next`**：成熟的目录体系，但未与 TanStack 路由器、`head` 函数或预渲染流程深度集成。
+- **`Paraglide`**：编译型消息，仅专注于消息层。
+- **`Intlayer`**：最先进的解决方案。内容可以在代码库中的任何位置声明（[靠近每个组件或集中管理](https://intlayer.org/zh/blog/per-component-vs-centralized-i18n)），在构建时编译，提供支持语言环境的路由、站点地图生成、AI 翻译、可视化编辑器和 CMS。
+
+请参阅 [为什么选择 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 步详细介绍了此过程。
+
+如需全自动流程，[Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) 可在构建时执行相同操作：它在每次更改时扫描您的 JSX、TSX、Vue 和 Svelte 源代码，生成字典并通过热模块替换 (HMR) 保持同步，因此完全无需手动维护键名。
+
+开启编译器前有两个限制值得了解：它通过静态分析工作，因此仅在运行时存在的字符串（如 API 错误代码或 CMS 字段）无法被捕获；此外它需要区分用户文本和应用程序逻辑（如 `className="active"` 或状态代码），在大型代码库中需要少量注解。而 [extract 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md) 则通过让您参与审查避免了这两个问题。
+
+</Question>
+
+<Question title="有哪些可用的编辑器和 AI 代理工具？">
+
+共有 5 个工具，均为可选：
+
+- **[VS Code 扩展](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/vs_code_extension.md)**：从 `useIntlayer` 键跳转到声明它的内容文件，从组件中提取内容，并从命令面板或专属的 Intlayer 选项卡运行 build、fill、test、push 和 pull。
+- **[LSP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/lsp.md)**：在任何支持 LSP 的编辑器中提供相同的感知能力，支持跳转到定义、查找所有引用、悬停预览翻译值、键和字段的自动补全，以及在键未声明时发出警告。它还可以解析 `i18next`、`react-i18next`、`next-intl` 和 `use-intl` 调用，助力平滑迁移。
+- **[MCP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/mcp_server.md)**：向 Cursor、VS Code、Claude Desktop、Claude Code 和 ChatGPT 公开 Intlayer 文档与 CLI，使 AI 助手能够基于最新文档进行准确回答，并能自行运行 `intlayer fill` 等命令。
+- **[Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/agent_skills.md)**：针对特定领域的技能（如 `intlayer-config`、`intlayer-cli` 和 `intlayer-content`，以及每个框架对应的专属技能），教导 AI 代理您的路由配置和内容节点类型。
+- **[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)。
+
+</Question>
+
+</FAQ>