@intlayer/docs 9.4.4 → 9.5.0

package/docs/zh/intlayer_with_nestjs.md

@@ -279,25 +279,21 @@ NestJS 拥有 `nestjs-i18n`，这是常见的选择，涵盖了具有请求作
 请参阅 [为什么选择 Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/interest_of_intlayer.md)。
 
 </Question>
-
 <Question title="i18n 会给我的 NestJS 服务端体积增加多少？">
 
 极少。字典在构建前预先编译，仅包含您声明的语言环境，因此启动时无需加载整个大目录，处理请求路径时也无需读取文件系统。这在 Serverless 和 Edge 环境中尤为重要，因为体积直接决定冷启动耗时。请参阅 [Bundle 体积优化](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/bundle_optimization.md)。
 
 </Question>
-
 <Question title="我可以从 i18next 迁移而无需重写路由处理函数吗？">
 
 可以，有两条迁移路径。您可以使用 [i18next 迁移指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/migration_from_i18next_to_intlayer.md) 逐步迁移内容。或者，您可以完全保留当前的 API：[兼容性适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/index.md) 公开与 `i18next` 完全相同的 API，但底层由 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，而无需手动逐一复制字符串到语言目录中。请参阅 [extract 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md)。
@@ -305,7 +301,6 @@ NestJS 拥有 `nestjs-i18n`，这是常见的选择，涵盖了具有请求作
 在同一项目的前端部分，[Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) 则更进一步，可以在构建时直接从 JSX、TSX、Vue 或 Svelte 源码生成字典，使应用的前后端共享同一套内容层，完全无需手动维护键名。
 
 </Question>
-
 <Question title="有哪些可用的编辑器和 AI 代理工具？">
 
 共有 5 个工具，均为可选：
@@ -317,61 +312,51 @@ NestJS 拥有 `nestjs-i18n`，这是常见的选择，涵盖了具有请求作
 - **[ESLint 插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/eslint.md)**：`no-raw-text` 规则标记硬编码字符串，并提供针对静态字典键和未使用内容的额外规则。
 
 </Question>
-
 <Question title="Intlayer 如何知道用哪种语言响应？">
 
 默认情况下，`express-intlayer` 读取传入请求的 `Accept-Language` 请求头，并选择最匹配的已声明语言环境，若无匹配则回退到默认语言环境。您可以通过 `routing.storage` 自定义来源，例如自定义标头或由前端设置的 Cookie，从而使 API 按照用户实际选择的语言响应，而非浏览器默认宣称的语言。请参阅 [配置参考](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
 
 </Question>
-
 <Question title="语言环境在每个请求之间是否隔离？">
 
 是的。中间件会将活动语言环境限定在当前请求范围内，因此两个使用不同语言的并发请求绝不会互相读取或干扰对方的语言环境。这使得在服务内部调用 `t()` 和 `getIntlayer()` 具备完全的线程与并发安全性，而无需在每个函数中显式传递语言环境参数。
 
 </Question>
-
 <Question title="如何使用接收者的语言发送事务性邮件？">
 
 像声明其他内容一样在内容文件中声明邮件文本，然后使用 `getIntlayer` 针对接收者存储的语言环境进行解析，而不是使用请求的语言环境。这对于后台作业和队列处理至关重要，因为这类场景下语言属于用户数据库记录，并不存在传入请求标头可供读取。
 
 </Question>
-
 <Question title="如何本地化 API 错误消息？">
 
 在构建错误对象的代码位置使用 `t()` 包裹消息文本。当前活动的请求语言环境会直接将其解析，使客户端能够直接显示该文本，从而无需在前端维护一套冗余平行的错误码目录。
 
 </Question>
-
 <Question title="我可以将翻译注入到 NestJS 服务或控制器中吗？">
 
 可以。如上所示，直接在服务或控制器内调用 `getIntlayer("app")`。无需为每个功能模块单独注册模块，也无需注入特殊的 Token，因为活动语言环境直接来源于中间件设置的请求上下文。
 
 </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="我在服务端能获得 TypeScript 自动补全吗？">
 
 是的。Intlayer 会在 `./types/intlayer.d.ts` 中为您的字典生成类型定义，因此访问不存在的键会在编译期直接报错，而不会在运行时返回空字符串。在 CI 中运行 `npx intlayer test` 可在声明的语言环境缺失内容时使构建失败。
 
 </Question>
-
 <Question title="前端和后端可以共享相同的内容吗？">
 
 可以，这正是推荐的架构模式。`express-intlayer` 可以与 `react-intlayer`、`next-intlayer` 和 `vite-intlayer` 共同基于完全相同的声明内容工作，因此在 API 响应和页面展示中使用的文案只需声明一次。请参阅 [Intlayer 工作原理](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/how_works_intlayer.md)。
 
 </Question>
-
 <Question title="Intlayer 是免费且开源的吗？">
 
 是的，基于 Apache 2.0 许可证开源，包含商业用途。托管版 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) 是可选的付费服务，同时完全支持 [自托管](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/self_hosting.md)。

package/docs/zh/intlayer_with_next-i18next.md

@@ -40,8 +40,6 @@ author: aymericzip
 > 注意：next-i18next 是构建在 i18next 之上的。本指南使用与 next-i18next 在 App Router 中兼容的 i18next 原语，同时保持架构简单且适合生产环境。
 > 如需更全面的比较，请参见 [next-i18next vs next-intl vs Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/next-i18next_vs_next-intl_vs_intlayer.md)。
 
----
-
 ## 1) 项目结构
 
 安装 next-i18next 依赖：
@@ -93,8 +91,6 @@ bun add next-i18next i18next react-i18next i18next-resources-to-backend
 - 不要过度集中消息；使用小型的页面/功能范围命名空间
 - 避免一次导入所有语言环境；只加载你需要的
 
----
-
 ## 2) 安装依赖
 
 ```bash
@@ -108,8 +104,6 @@ pnpm add i18next react-i18next i18next-resources-to-backend
 pnpm add next-i18next
 ```
 
----
-
 ## 3) 核心 i18n 配置
 
 定义 locales、默认 locale、RTL 以及本地化路径/URL 的辅助函数。
@@ -136,8 +130,6 @@ export function abs(locale: string, path: string) {
 
 高级提示：如果你使用 `next-i18next.config.js`，请确保它与 `i18n.config.ts` 保持一致，以避免偏差。
 
----
-
 ## 4) 服务器端 i18n 初始化
 
 在服务器端初始化 i18next，使用动态后端仅导入所需的 locale/namespace JSON。
@@ -176,8 +168,6 @@ export async function initI18next(
 
 中间提示：保持每页的命名空间列表简短以限制负载。避免使用全局的“捕获所有”包。
 
----
-
 ## 5) React 组件的客户端提供者
 
 使用一个提供者包裹客户端组件，该提供者与服务器配置相对应，并且只加载请求的命名空间。
@@ -234,8 +224,6 @@ export default function I18nProvider({
 
 初级提示：您不需要将所有消息传递给客户端。只需从页面的命名空间开始。
 
----
-
 ## 6) 本地化布局和路由
 
 设置语言和方向，并为每个语言预生成路由，以支持静态渲染。
@@ -271,8 +259,6 @@ export default function LocaleLayout({
 }
 ```
 
----
-
 ## 7) 服务器端 + 客户端使用示例页面
 
 ```tsx fileName="src/app/[locale]/about.tsx"
@@ -388,8 +374,6 @@ const ServerComponent = ({ t, locale, count }: ServerComponentProps) => {
 export default ServerComponent;
 ```
 
----
-
 ## 8) SEO：元数据，Hreflang，站点地图，Robots
 
 翻译内容是提升覆盖范围的一种手段。请彻底配置多语言SEO。
@@ -483,8 +467,6 @@ export default function robots(): MetadataRoute.Robots {
 }
 ```
 
----
-
 ## 9) 用于本地化路由的中间件
 
 检测语言环境，如果缺失则重定向到本地化路由。
@@ -527,8 +509,6 @@ export const config = {
 };
 ```
 
----
-
 ## 10) 性能和开发体验最佳实践
 
 - **设置 html 的 `lang` 和 `dir` 属性**：已在 `src/app/[locale]/layout.tsx` 中完成。
@@ -539,8 +519,6 @@ export const config = {
 - **对重操作进行记忆化**：尤其是在旧版本 React 的客户端代码中。
 - **缓存和头部设置**：尽可能优先使用静态或 `revalidate`，而非动态渲染。
 
----
-
 ## 11) 测试和持续集成（CI）
 
 - 为使用 `t` 的组件添加单元测试，确保键存在。
@@ -549,8 +527,6 @@ export const config = {
 
 Intlayer 将自动化完成大部分这些工作（见下一节）。
 
----
-
 ## 12) 在顶部添加 Intlayer（自动化）
 
 Intlayer 帮助你保持 JSON 翻译同步，测试缺失的键，并在需要时使用 AI 填充。
@@ -636,8 +612,6 @@ export default config;
 
 > 你可以提供 CLI 参数；请参阅[Intlayer CLI 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md)。
 
----
-
 ## 13) 故障排除
 
 - **找不到键**：确保页面/提供者列出了正确的命名空间，并且 JSON 文件存在于 `src/locales/<locale>/<namespace>.json` 目录下。
@@ -646,8 +620,6 @@ export default config;
 - **SEO 替代语言缺失**：确认 `alternates.languages` 包含所有语言环境和 `x-default`。
 - **包体积过大**：进一步拆分命名空间，避免在客户端导入整个 `locales` 目录树。
 
----
-
 ## 14) 接下来做什么
 
 - 随着功能的增长，添加更多的语言环境和命名空间