@modern-js/main-doc 3.9.3 → 3.10.1

package/docs/zh/configure/app/tools/less.mdx

@@ -21,12 +21,12 @@ const defaultOptions = {
 
 `tools.less` 用于修改 [@rsbuild/plugin-less](https://rsbuild.rs/plugins/list/plugin-less) 的选项，取值为该插件的完整选项：
 
-| 选项                 | 说明                                                                               |
-| -------------------- | ---------------------------------------------------------------------------------- |
-| `lessLoaderOptions`  | 传给 [less-loader](https://github.com/webpack-contrib/less-loader) 的选项，支持对象或函数 |
-| `include`            | 指定哪些文件交给 less-loader 处理，默认 `/\.less$/`                                  |
-| `exclude`            | 指定哪些文件不交给 less-loader 处理                                                  |
-| `parallel`           | 是否使用 worker 线程并行编译 Less，默认 `false`                                       |
+| 选项                | 说明                                                                                      |
+| ------------------- | ----------------------------------------------------------------------------------------- |
+| `lessLoaderOptions` | 传给 [less-loader](https://github.com/webpack-contrib/less-loader) 的选项，支持对象或函数 |
+| `include`           | 指定哪些文件交给 less-loader 处理，默认 `/\.less$/`                                       |
+| `exclude`           | 指定哪些文件不交给 less-loader 处理                                                       |
+| `parallel`          | 是否使用 worker 线程并行编译 Less，默认 `false`                                           |
 
 ### 修改 less-loader 选项
 
@@ -135,7 +135,6 @@ export default {
 同一个对象里只要出现插件顶层键（`lessLoaderOptions`、`include`、`exclude` 等），整个对象就会按插件选项解析，其中的 loader 选项不会生效。例如 `tools.less: { parallel: true, lessOptions: { ... } }` 里的 `lessOptions` 会被忽略，必须移到 `lessLoaderOptions` 下；开发环境下会打印一条提示。
 :::
 
-
 在之前的版本中，`tools.less` 的取值直接是 less-loader 的选项，例如 `tools.less: { lessOptions: {} }` 或 `tools.less(config, { addExcludes }) {}`。这种写法目前仍然生效，Modern.js 会自动把它包装为 `lessLoaderOptions`，产出的配置与之前完全一致；在开发环境下会打印一条迁移提示，并将在下一个大版本中移除。
 
 ```js

package/docs/zh/configure/app/tools/sass.mdx

@@ -18,12 +18,12 @@ const defaultOptions = {
 
 `tools.sass` 用于修改 [@rsbuild/plugin-sass](https://rsbuild.rs/plugins/list/plugin-sass) 的选项，取值为该插件的完整选项：
 
-| 选项                 | 说明                                                                               |
-| -------------------- | ---------------------------------------------------------------------------------- |
-| `sassLoaderOptions`  | 传给 [sass-loader](https://github.com/webpack-contrib/sass-loader) 的选项，支持对象或函数 |
-| `include`            | 指定哪些文件交给 sass-loader 处理，默认 `/\.s(?:a|c)ss$/`                             |
-| `exclude`            | 指定哪些文件不交给 sass-loader 处理                                                  |
-| `rewriteUrls`        | 是否使用 resolve-url-loader 重写 Sass 文件中的相对 URL，默认 `true`                    |
+| 选项                | 说明                                                                                      |
+| ------------------- | ----------------------------------------------------------------------------------------- |
+| `sassLoaderOptions` | 传给 [sass-loader](https://github.com/webpack-contrib/sass-loader) 的选项，支持对象或函数 |
+| `include`           | 指定哪些文件交给 sass-loader 处理，默认 `/\.s(?:a\|c)ss$/`                                |
+| `exclude`           | 指定哪些文件不交给 sass-loader 处理                                                       |
+| `rewriteUrls`       | 是否使用 resolve-url-loader 重写 Sass 文件中的相对 URL，默认 `true`                       |
 
 ### 修改 sass-loader 选项
 
@@ -126,7 +126,6 @@ export default {
 同一个对象里只要出现插件顶层键（`sassLoaderOptions`、`include`、`exclude` 等），整个对象就会按插件选项解析，其中的 loader 选项不会生效。例如 `tools.sass: { rewriteUrls: false, sassOptions: { ... } }` 里的 `sassOptions` 会被忽略，必须移到 `sassLoaderOptions` 下；开发环境下会打印一条提示。
 :::
 
-
 在之前的版本中，`tools.sass` 的取值直接是 sass-loader 的选项，例如 `tools.sass: { sassOptions: {} }` 或 `tools.sass(config, { addExcludes }) {}`。这种写法目前仍然生效，Modern.js 会自动把它包装为 `sassLoaderOptions`，产出的配置与之前完全一致；在开发环境下会打印一条迁移提示，并将在下一个大版本中移除。
 
 ```js

package/docs/zh/configure/app/tools/svgr.mdx

@@ -18,14 +18,14 @@ const defaultOptions = {
 
 `tools.svgr` 用于修改 [@rsbuild/plugin-svgr](https://rsbuild.rs/plugins/list/plugin-svgr) 的选项，取值为该插件的完整选项。设置为 `false` 时不再注册 SVGR 插件，所有 `.svg` 文件按静态资源处理。
 
-| 选项              | 说明                                                                                          |
-| ----------------- | --------------------------------------------------------------------------------------------- |
+| 选项              | 说明                                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------------------- |
 | `svgrOptions`     | 传给 [SVGR](https://react-svgr.com/docs/options/) 的参数，例如 `exportType`、`icon`、`svgoConfig` |
-| `parallel`        | 是否使用 worker 线程并行转换 SVG，默认 `false`                                                  |
-| `exclude`         | 指定哪些 SVG 文件不交给 SVGR 处理                                                              |
-| `excludeImporter` | 指定从哪些文件导入 SVG 时不交给 SVGR 处理                                                       |
-| `query`           | 指定触发 SVGR 转换的 query，默认 `/react/`                                                     |
-| `mixedImport`     | 是否允许在同一个模块中同时导入 URL 与 React 组件，默认 `true`                                   |
+| `parallel`        | 是否使用 worker 线程并行转换 SVG，默认 `false`                                                    |
+| `exclude`         | 指定哪些 SVG 文件不交给 SVGR 处理                                                                 |
+| `excludeImporter` | 指定从哪些文件导入 SVG 时不交给 SVGR 处理                                                         |
+| `query`           | 指定触发 SVGR 转换的 query，默认 `/react/`                                                        |
+| `mixedImport`     | 是否允许在同一个模块中同时导入 URL 与 React 组件，默认 `true`                                     |
 
 ### 合并规则
 
@@ -83,11 +83,11 @@ export default {
 
 `tools.svgr` 取代了下面两个已废弃的配置项，二者目前仍然生效，并将在下一个大版本中移除：
 
-| 旧配置                                | 新配置                                            |
-| ------------------------------------- | ------------------------------------------------- |
+| 旧配置                                 | 新配置                                                   |
+| -------------------------------------- | -------------------------------------------------------- |
 | `output.svgDefaultExport: 'component'` | `tools.svgr: { svgrOptions: { exportType: 'default' } }` |
 | `output.svgDefaultExport: 'url'`       | `tools.svgr: { svgrOptions: { exportType: 'named' } }`   |
-| `output.disableSvgr: true`             | `tools.svgr: false`                               |
-| `output.disableSvgr: false`            | 默认行为，直接删除即可                            |
+| `output.disableSvgr: true`             | `tools.svgr: false`                                      |
+| `output.disableSvgr: false`            | 默认行为，直接删除即可                                   |
 
 同时设置时以 `tools.svgr` 为准：显式设置了 `tools.svgr` 后，`output.disableSvgr` 不再生效；`tools.svgr.svgrOptions.exportType` 会覆盖 `output.svgDefaultExport` 派生的值。

package/docs/zh/configure/app/usage.mdx

@@ -265,11 +265,7 @@ import { defineConfig } from '@modern-js/app-tools';
 import { xxPlugin } from '@modern-js/plugin-xx';
 
 export default defineConfig({
-  plugins: [
-    xxPlugin({
-      /** 在此处添加参数 */
-    }),
-  ],
+  plugins: [xxPlugin({/** 在此处添加参数 */})],
 });
 ```
 

package/docs/zh/guides/advanced-features/bff.mdx

@@ -1,6 +1,7 @@
 ---
 title: BFF
 ---
+
 # BFF
 
 BFF（Backends for Frontends）是一种架构模式，主要用于解决前后端协作中的数据聚合问题。在 BFF 架构下，前端应用程序不直接与后端服务通信，而是通过一个专门为前端定制的BFF中间层与后端服务交互。

package/docs/zh/guides/advanced-features/international/advanced.mdx

@@ -68,7 +68,7 @@ i18nPlugin({
     localeDetectionByEntry: {
       admin: {
         localePathRedirect: false, // admin 入口不使用路径前缀
-        languages: ['en'],         // admin 只支持英文
+        languages: ['en'], // admin 只支持英文
       },
       mobile: {
         languages: ['zh', 'en', 'ja'], // mobile 支持更多语言

package/docs/zh/guides/advanced-features/international/api.mdx

@@ -10,14 +10,14 @@ title: API 参考
 
 ### 返回值
 
-| 字段 | 类型 | 说明 |
-| --- | --- | --- |
-| `language` | `string` | 当前语言代码 |
-| `changeLanguage` | `(lang: string) => Promise<void>` | 切换语言 |
-| `supportedLanguages` | `string[]` | 支持的语言列表（来自 `localeDetection.languages`） |
-| `isLanguageSupported` | `(lang: string) => boolean` | 检查语言是否在支持列表中 |
-| `isResourcesReady` | `boolean` | 当前语言的翻译资源是否已加载完成 |
-| `i18nInstance` | `I18nInstance` | i18next 实例（用于高级场景） |
+| 字段                  | 类型                              | 说明                                               |
+| --------------------- | --------------------------------- | -------------------------------------------------- |
+| `language`            | `string`                          | 当前语言代码                                       |
+| `changeLanguage`      | `(lang: string) => Promise<void>` | 切换语言                                           |
+| `supportedLanguages`  | `string[]`                        | 支持的语言列表（来自 `localeDetection.languages`） |
+| `isLanguageSupported` | `(lang: string) => boolean`       | 检查语言是否在支持列表中                           |
+| `isResourcesReady`    | `boolean`                         | 当前语言的翻译资源是否已加载完成                   |
+| `i18nInstance`        | `I18nInstance`                    | i18next 实例（用于高级场景）                       |
 
 ### 基本用法
 
@@ -85,13 +85,13 @@ function MyComponent() {
 
 ### Props
 
-| Prop | 类型 | 必填 | 说明 |
-| --- | --- | --- | --- |
-| `to` | `string` | 是 | 目标路径，不需要包含语言前缀 |
-| `children` | `React.ReactNode` | 是 | 链接内容 |
-| `replace` | `boolean` | 否 | 使用 `history.replace` 而非 `push` |
-| `state` | `any` | 否 | 传递给目标路由的状态 |
-| 其他 Link props | — | 否 | 继承自 `@modern-js/runtime/router` 的 `Link` 组件 |
+| Prop            | 类型              | 必填 | 说明                                              |
+| --------------- | ----------------- | ---- | ------------------------------------------------- |
+| `to`            | `string`          | 是   | 目标路径，不需要包含语言前缀                      |
+| `children`      | `React.ReactNode` | 是   | 链接内容                                          |
+| `replace`       | `boolean`         | 否   | 使用 `history.replace` 而非 `push`                |
+| `state`         | `any`             | 否   | 传递给目标路由的状态                              |
+| 其他 Link props | —                 | 否   | 继承自 `@modern-js/runtime/router` 的 `Link` 组件 |
 
 ### 用法
 
@@ -132,6 +132,7 @@ const myPlugin = (): RuntimePlugin => ({
 ```
 
 **注意事项：**
+
 - 确保 i18n 插件在使用 `context.changeLanguage` 的插件之前注册
 - `changeLanguage` 在服务端不会更新 URL 路径，需要配合路由插件或手动处理
 
@@ -165,11 +166,11 @@ interface I18nInstance {
 type I18nSdkLoader = (options: I18nSdkLoadOptions) => Promise<Resources>;
 
 interface I18nSdkLoadOptions {
-  lng?: string;      // 单个语言代码
-  ns?: string;       // 单个命名空间
-  lngs?: string[];   // 多个语言代码
-  nss?: string[];    // 多个命名空间
-  all?: boolean;     // 加载所有资源
+  lng?: string; // 单个语言代码
+  ns?: string; // 单个命名空间
+  lngs?: string[]; // 多个语言代码
+  nss?: string[]; // 多个命名空间
+  all?: boolean; // 加载所有资源
 }
 
 type Resources = {
@@ -184,14 +185,14 @@ type Resources = {
 ```ts
 interface LanguageDetectorOptions {
   order?: string[];
-  lookupQuerystring?: string;   // 默认 'lng'
-  lookupCookie?: string;        // 默认 'i18next'
-  lookupLocalStorage?: string;  // 默认 'i18nextLng'
+  lookupQuerystring?: string; // 默认 'lng'
+  lookupCookie?: string; // 默认 'i18next'
+  lookupLocalStorage?: string; // 默认 'i18nextLng'
   lookupSession?: string;
-  lookupHeader?: string;        // 默认 'accept-language'
+  lookupHeader?: string; // 默认 'accept-language'
   lookupFromPathIndex?: number; // 默认 0
   caches?: false | string[];
-  cookieMinutes?: number;       // 默认 525600（1年）
+  cookieMinutes?: number; // 默认 525600（1年）
   cookieExpirationDate?: Date;
   cookieDomain?: string;
 }
@@ -211,8 +212,8 @@ import { useTranslation } from 'react-i18next';
 import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
 
 function App() {
-  const { t } = useTranslation();                          // 翻译文本
-  const { language, changeLanguage } = useModernI18n();    // 语言切换
+  const { t } = useTranslation(); // 翻译文本
+  const { language, changeLanguage } = useModernI18n(); // 语言切换
 
   return (
     <div>

package/docs/zh/guides/advanced-features/international/best-practices.mdx

@@ -63,8 +63,8 @@ function ButtonGroup() {
   const { t } = useTranslation('common', { keyPrefix: 'button' });
   return (
     <>
-      <button>{t('submit')}</button>   {/* → common:button.submit */}
-      <button>{t('cancel')}</button>   {/* → common:button.cancel */}
+      <button>{t('submit')}</button> {/* → common:button.submit */}
+      <button>{t('cancel')}</button> {/* → common:button.cancel */}
     </>
   );
 }
@@ -94,9 +94,9 @@ function ButtonGroup() {
 ```
 
 ```tsx
-t('page.title')
-t('form.username.label')
-t('form.submit', { defaultValue: '保存' }) // defaultValue 防止键缺失时显示 key 字符串
+t('page.title');
+t('form.username.label');
+t('form.submit', { defaultValue: '保存' }); // defaultValue 防止键缺失时显示 key 字符串
 ```
 
 ## 复数
@@ -121,9 +121,9 @@ i18next 根据 `count` 参数自动选择对应的复数形式。**注意：i18n
 ```
 
 ```tsx
-t('item', { count: 0 })  // → "没有条目" / "No items"
-t('item', { count: 1 })  // → "没有条目" / "1 item"（中文通常只有一种形式）
-t('item', { count: 5 })  // → "5 个条目" / "5 items"
+t('item', { count: 0 }); // → "没有条目" / "No items"
+t('item', { count: 1 }); // → "没有条目" / "1 item"（中文通常只有一种形式）
+t('item', { count: 5 }); // → "5 个条目" / "5 items"
 ```
 
 不同语言的复数规则不同（英语有单复数，俄语有 one/few/many 等多种形式），i18next 会根据语言代码自动匹配 CLDR 规则。
@@ -152,8 +152,8 @@ t('item', { count: 5 })  // → "5 个条目" / "5 items"
 ```
 
 ```tsx
-t('modal.confirm.title')
-t('modal.confirm.actions.ok')
+t('modal.confirm.title');
+t('modal.confirm.actions.ok');
 ```
 
 嵌套层级不建议超过 4 层，过深的结构会让键名变得冗长难维护。
@@ -199,8 +199,8 @@ export default defineRuntimeConfig({
 ```
 
 ```tsx
-t('price', { value: 99.5 })       // → "当前价格：¥99.50"（zh）/ "$99.50"（en）
-t('expiry', { date: new Date() }) // → "到期日：2025年5月12日"（zh）
+t('price', { value: 99.5 }); // → "当前价格：¥99.50"（zh）/ "$99.50"（en）
+t('expiry', { date: new Date() }); // → "到期日：2025年5月12日"（zh）
 ```
 
 ## 错误处理
@@ -237,7 +237,7 @@ if (!i18n.isInitialized) return null;
 通过 `defaultValue` 提供兜底文案，防止界面显示 key 字符串：
 
 ```tsx
-t('missing.key', { defaultValue: '默认文案' })
+t('missing.key', { defaultValue: '默认文案' });
 ```
 
 开发环境可以开启 `saveMissing`，将缺失的键输出到控制台方便排查：
@@ -281,8 +281,8 @@ declare module 'react-i18next' {
 
 ```tsx
 const { t } = useTranslation();
-t('welcome');       // ✅ TypeScript 自动补全
-t('nonExistent');   // ❌ TypeScript 报错
+t('welcome'); // ✅ TypeScript 自动补全
+t('nonExistent'); // ❌ TypeScript 报错
 ```
 
 :::tip 大型项目

package/docs/zh/guides/advanced-features/international/configuration.mdx

@@ -1,13 +1,14 @@
 ---
 title: 配置说明
 ---
+
 # 配置说明
 
 插件配置分为两个文件，各有职责：
 
-| 文件 | 用途 |
-| --- | --- |
-| `modern.config.ts` | 插件基础设置，在构建/启动时读取 |
+| 文件                    | 用途                             |
+| ----------------------- | -------------------------------- |
+| `modern.config.ts`      | 插件基础设置，在构建/启动时读取  |
 | `src/modern.runtime.ts` | i18next 初始化选项，在运行时读取 |
 
 :::warning 函数类型只能在运行时配置中设置
@@ -16,13 +17,13 @@ title: 配置说明
 
 ## 配置归属一览
 
-| 配置项 | 放在哪里 |
-| --- | --- |
-| `localeDetection`（语言检测、路径重定向等） | `modern.config.ts` |
-| `backend`（资源路径、sdk 声明等） | `modern.config.ts` |
-| `i18nInstance` | `modern.runtime.ts` |
+| 配置项                                           | 放在哪里            |
+| ------------------------------------------------ | ------------------- |
+| `localeDetection`（语言检测、路径重定向等）      | `modern.config.ts`  |
+| `backend`（资源路径、sdk 声明等）                | `modern.config.ts`  |
+| `i18nInstance`                                   | `modern.runtime.ts` |
 | `initOptions`（fallbackLng、ns 等 i18next 选项） | `modern.runtime.ts` |
-| `backend.sdk` 的实际加载函数 | `modern.runtime.ts` |
+| `backend.sdk` 的实际加载函数                     | `modern.runtime.ts` |
 
 ## CLI 配置
 
@@ -43,15 +44,15 @@ export default defineConfig({
 
 ### localeDetection 选项
 
-| 字段 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| `languages` | `string[]` | `[]` | 支持的语言列表 |
-| `fallbackLanguage` | `string` | `''` | 语言检测失败时的兜底语言 |
-| `localePathRedirect` | `boolean` | `false` | 接管 URL 语言前缀的识别、重定向和切换，详见[路由集成](./routing.md#启用语言路径前缀) |
-| `i18nextDetector` | `boolean` | `false` | 启用 i18next 检测器（Cookie / Header 等） |
-| `detection` | `LanguageDetectorOptions` | — | i18next 检测器详细配置，见[语言检测](./locale-detection.md) |
-| `ignoreRedirectRoutes` | `string[] \| Function` | — | 跳过重定向的路由，见[语言检测](./locale-detection.md#ignoreredirectroutes) |
-| `localeDetectionByEntry` | `Record<string, ...>` | — | 多入口按入口覆盖配置 |
+| 字段                     | 类型                      | 默认值  | 说明                                                                                 |
+| ------------------------ | ------------------------- | ------- | ------------------------------------------------------------------------------------ |
+| `languages`              | `string[]`                | `[]`    | 支持的语言列表                                                                       |
+| `fallbackLanguage`       | `string`                  | `''`    | 语言检测失败时的兜底语言                                                             |
+| `localePathRedirect`     | `boolean`                 | `false` | 接管 URL 语言前缀的识别、重定向和切换，详见[路由集成](./routing.md#启用语言路径前缀) |
+| `i18nextDetector`        | `boolean`                 | `false` | 启用 i18next 检测器（Cookie / Header 等）                                            |
+| `detection`              | `LanguageDetectorOptions` | —       | i18next 检测器详细配置，见[语言检测](./locale-detection.md)                          |
+| `ignoreRedirectRoutes`   | `string[] \| Function`    | —       | 跳过重定向的路由，见[语言检测](./locale-detection.md#ignoreredirectroutes)           |
+| `localeDetectionByEntry` | `Record<string, ...>`     | —       | 多入口按入口覆盖配置                                                                 |
 
 **示例：**
 
@@ -104,23 +105,24 @@ interface BackendOptions {
 
 **backend 自动启用规则：**
 
-| 情况 | 结果 |
-| --- | --- |
-| 配置了 `loadPath` 或 `addPath` | 自动启用，无需写 `enabled: true` |
-| 未配置 backend，但 `locales` 目录存在且有 JSON 文件 | 自动启用，使用默认 `loadPath` |
-| 显式设置 `enabled: false` | 禁用，不做自动检测 |
+| 情况                                                | 结果                             |
+| --------------------------------------------------- | -------------------------------- |
+| 配置了 `loadPath` 或 `addPath`                      | 自动启用，无需写 `enabled: true` |
+| 未配置 backend，但 `locales` 目录存在且有 JSON 文件 | 自动启用，使用默认 `loadPath`    |
+| 显式设置 `enabled: false`                           | 禁用，不做自动检测               |
 
 自动检测的目录位置（按优先级）：
+
 1. `{项目根目录}/config/public/locales`
 2. `server.publicDir` 配置的目录下的 `locales` 子目录
 
 **选择哪种后端？**
 
-| 场景 | 推荐方式 |
-| --- | --- |
-| 翻译文件放在项目本地 | 静态文件后端（配置 `loadPath`，CSR/SSR 自动切换） |
-| 翻译来自远程 API 或翻译平台 | 自定义后端（配置 `sdk: true`） |
-| 本地兜底 + 远程实时更新 | 链式后端（同时配置 `loadPath` 和 `sdk`） |
+| 场景                        | 推荐方式                                          |
+| --------------------------- | ------------------------------------------------- |
+| 翻译文件放在项目本地        | 静态文件后端（配置 `loadPath`，CSR/SSR 自动切换） |
+| 翻译来自远程 API 或翻译平台 | 自定义后端（配置 `sdk: true`）                    |
+| 本地兜底 + 远程实时更新     | 链式后端（同时配置 `loadPath` 和 `sdk`）          |
 
 详细用法见[资源加载](./resource-loading.md)。
 
@@ -134,7 +136,7 @@ const i18nInstance = i18next.createInstance();
 
 export default defineRuntimeConfig({
   i18n: {
-    i18nInstance,   // 可选，建议使用独立实例
+    i18nInstance, // 可选，建议使用独立实例
     initOptions: {
       fallbackLng: 'en',
       supportedLngs: ['zh', 'en'],
@@ -162,13 +164,13 @@ import Desc from '@site-docs/components/international/init-options-desc';
 
 <Desc />
 
-| 字段 | 说明 |
-| --- | --- |
-| `fallbackLng` | i18next 找不到翻译键时回退到哪个语言的资源，支持字符串、数组或映射（回退链） |
-| `supportedLngs` | i18next 支持的语言列表 |
-| `ns` | 命名空间列表，默认 `['translation']` |
-| `defaultNS` | 默认命名空间，默认 `'translation'` |
-| `lng` | 强制指定初始语言（通常不需要，由检测器决定） |
+| 字段            | 说明                                                                         |
+| --------------- | ---------------------------------------------------------------------------- |
+| `fallbackLng`   | i18next 找不到翻译键时回退到哪个语言的资源，支持字符串、数组或映射（回退链） |
+| `supportedLngs` | i18next 支持的语言列表                                                       |
+| `ns`            | 命名空间列表，默认 `['translation']`                                         |
+| `defaultNS`     | 默认命名空间，默认 `'translation'`                                           |
+| `lng`           | 强制指定初始语言（通常不需要，由检测器决定）                                 |
 
 `fallbackLng` 支持回退链写法，适合区域语言降级的场景：
 

package/docs/zh/guides/advanced-features/international/locale-detection.mdx

@@ -64,8 +64,8 @@ i18nPlugin({
 ```ts
 i18nPlugin({
   localeDetection: {
-    localePathRedirect: true,   // 路径前缀
-    i18nextDetector: true,      // Cookie / Header 等
+    localePathRedirect: true, // 路径前缀
+    i18nextDetector: true, // Cookie / Header 等
     languages: ['zh', 'en'],
     fallbackLanguage: 'en',
     detection: {
@@ -77,39 +77,48 @@ i18nPlugin({
 
 ## 检测选项（detection）
 
-| 选项 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| `order` | `string[]` | 见下方 | i18next 检测器内部的检测顺序 |
-| `lookupQuerystring` | `string` | `'lng'` | 查询参数键名，例如 `?lng=en` |
-| `lookupCookie` | `string` | `'i18next'` | Cookie 键名 |
-| `lookupLocalStorage` | `string` | `'i18nextLng'` | LocalStorage 键名（仅浏览器） |
-| `lookupSession` | `string` | — | SessionStorage 键名（仅浏览器） |
-| `lookupHeader` | `string` | `'accept-language'` | HTTP 请求头键名 |
-| `lookupFromPathIndex` | `number` | `0` | 从 URL 路径的第几段开始识别语言 |
-| `caches` | `false \| string[]` | — | 检测到的语言缓存到哪里，如 `['cookie']` |
-| `cookieMinutes` | `number` | `525600`（1年） | Cookie 过期时间（分钟） |
-| `cookieExpirationDate` | `Date` | — | Cookie 过期日期，优先级高于 `cookieMinutes` |
-| `cookieDomain` | `string` | — | Cookie 域名 |
+| 选项                   | 类型                | 默认值              | 说明                                        |
+| ---------------------- | ------------------- | ------------------- | ------------------------------------------- |
+| `order`                | `string[]`          | 见下方              | i18next 检测器内部的检测顺序                |
+| `lookupQuerystring`    | `string`            | `'lng'`             | 查询参数键名，例如 `?lng=en`                |
+| `lookupCookie`         | `string`            | `'i18next'`         | Cookie 键名                                 |
+| `lookupLocalStorage`   | `string`            | `'i18nextLng'`      | LocalStorage 键名（仅浏览器）               |
+| `lookupSession`        | `string`            | —                   | SessionStorage 键名（仅浏览器）             |
+| `lookupHeader`         | `string`            | `'accept-language'` | HTTP 请求头键名                             |
+| `lookupFromPathIndex`  | `number`            | `0`                 | 从 URL 路径的第几段开始识别语言             |
+| `caches`               | `false \| string[]` | —                   | 检测到的语言缓存到哪里，如 `['cookie']`     |
+| `cookieMinutes`        | `number`            | `525600`（1年）     | Cookie 过期时间（分钟）                     |
+| `cookieExpirationDate` | `Date`              | —                   | Cookie 过期日期，优先级高于 `cookieMinutes` |
+| `cookieDomain`         | `string`            | —                   | Cookie 域名                                 |
 
 **默认检测顺序（未配置 `order` 时）：**
 
 ```ts
-['querystring', 'cookie', 'localStorage', 'header', 'navigator', 'htmlTag', 'path', 'subdomain']
+[
+  'querystring',
+  'cookie',
+  'localStorage',
+  'header',
+  'navigator',
+  'htmlTag',
+  'path',
+  'subdomain',
+];
 ```
 
 **`order` 可用值：**
 
-| 值 | 检测来源 | 限制 |
-| --- | --- | --- |
-| `querystring` | URL 查询参数（`?lng=en`） | — |
-| `cookie` | Cookie | — |
-| `localStorage` | LocalStorage | 仅浏览器 |
-| `sessionStorage` | SessionStorage | 仅浏览器 |
-| `navigator` | 浏览器语言设置 | 仅浏览器 |
-| `htmlTag` | `<html lang="...">` | 仅浏览器 |
-| `header` | `Accept-Language` 请求头 | — |
-| `path` | URL 路径（需同时启用 `localePathRedirect`） | — |
-| `subdomain` | 子域名（`en.example.com`） | — |
+| 值               | 检测来源                                    | 限制     |
+| ---------------- | ------------------------------------------- | -------- |
+| `querystring`    | URL 查询参数（`?lng=en`）                   | —        |
+| `cookie`         | Cookie                                      | —        |
+| `localStorage`   | LocalStorage                                | 仅浏览器 |
+| `sessionStorage` | SessionStorage                              | 仅浏览器 |
+| `navigator`      | 浏览器语言设置                              | 仅浏览器 |
+| `htmlTag`        | `<html lang="...">`                         | 仅浏览器 |
+| `header`         | `Accept-Language` 请求头                    | —        |
+| `path`           | URL 路径（需同时启用 `localePathRedirect`） | —        |
+| `subdomain`      | 子域名（`en.example.com`）                  | —        |
 
 ## ignoreRedirectRoutes
 
@@ -118,7 +127,7 @@ i18nPlugin({
 **写法一：字符串数组**（支持精确匹配和前缀匹配）
 
 ```ts
-ignoreRedirectRoutes: ['/api', '/admin', '/static']
+ignoreRedirectRoutes: ['/api', '/admin', '/static'];
 // '/api' 会匹配 /api 和 /api/users
 ```
 

package/docs/zh/guides/advanced-features/international/resource-loading.mdx

@@ -1,21 +1,23 @@
 ---
 title: 资源加载
 ---
+
 # 资源加载
 
 翻译文件的加载方式取决于你的翻译资源放在哪里：
 
-| 场景 | 加载方式 |
-| --- | --- |
-| 翻译文件放在项目本地 | 静态文件后端（本篇默认方式） |
-| 翻译来自远程 API、翻译平台 | 自定义后端 |
-| 两者都要：本地兜底 + 远程实时更新 | 链式后端 |
+| 场景                              | 加载方式                     |
+| --------------------------------- | ---------------------------- |
+| 翻译文件放在项目本地              | 静态文件后端（本篇默认方式） |
+| 翻译来自远程 API、翻译平台        | 自定义后端                   |
+| 两者都要：本地兜底 + 远程实时更新 | 链式后端                     |
 
 ## 静态文件后端
 
 把翻译文件放在项目里，插件直接加载。这是最常见的方式。
 
 **CSR 和 SSR 的加载机制不同，但配置完全一样：**
+
 - CSR：浏览器通过 HTTP 请求拉取翻译文件（如 `GET /locales/zh/translation.json`）
 - SSR：服务端直接从磁盘读取文件，不走 HTTP
 
@@ -100,11 +102,11 @@ export default defineRuntimeConfig({
 
 ```ts
 interface I18nSdkLoadOptions {
-  lng?: string;      // 单个语言代码
-  ns?: string;       // 单个命名空间
-  lngs?: string[];   // 多个语言代码
-  nss?: string[];    // 多个命名空间
-  all?: boolean;     // 加载所有资源
+  lng?: string; // 单个语言代码
+  ns?: string; // 单个命名空间
+  lngs?: string[]; // 多个语言代码
+  nss?: string[]; // 多个命名空间
+  all?: boolean; // 加载所有资源
 }
 ```
 
@@ -122,7 +124,7 @@ interface I18nSdkLoadOptions {
 i18nPlugin({
   backend: {
     loadPath: '/locales/{{lng}}/{{ns}}.json', // 本地文件，快速显示
-    sdk: true,                                 // 远程加载，异步更新
+    sdk: true, // 远程加载，异步更新
   },
 });
 ```
@@ -135,7 +137,9 @@ export default defineRuntimeConfig({
       backend: {
         sdk: async options => {
           if (options.lng && options.ns) {
-            const res = await fetch(`https://api.example.com/i18n/${options.lng}/${options.ns}`);
+            const res = await fetch(
+              `https://api.example.com/i18n/${options.lng}/${options.ns}`,
+            );
             return { [options.lng]: { [options.ns]: await res.json() } };
           }
           return {};
@@ -148,8 +152,8 @@ export default defineRuntimeConfig({
 
 **`cacheHitMode` 选项**（控制两个后端之间的协作方式）：
 
-| 值 | 行为 |
-| --- | --- |
-| `'none'` | 本地文件加载成功后直接使用，不再请求自定义后端 |
-| `'refresh'` | 继续请求自定义后端并更新缓存，但不更新当前页面 |
+| 值                        | 行为                                                   |
+| ------------------------- | ------------------------------------------------------ |
+| `'none'`                  | 本地文件加载成功后直接使用，不再请求自定义后端         |
+| `'refresh'`               | 继续请求自定义后端并更新缓存，但不更新当前页面         |
 | `'refreshAndUpdateStore'` | 继续请求自定义后端，更新缓存并同步刷新页面文案（默认） |