@modern-js/main-doc 3.1.4 → 3.2.0

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

@@ -1,50 +1,43 @@
 ---
 title: 资源加载
 ---
-
 # 资源加载
 
-插件支持三种资源加载方式：HTTP 后端、文件系统后端（FS Backend）和 SDK 后端。同时，插件还支持链式后端，可以组合使用多个后端。
+翻译文件的加载方式取决于你的翻译资源放在哪里：
 
-## HTTP 后端
+| 场景 | 加载方式 |
+| --- | --- |
+| 翻译文件放在项目本地 | 静态文件后端（本篇默认方式） |
+| 翻译来自远程 API、翻译平台 | 自定义后端 |
+| 两者都要：本地兜底 + 远程实时更新 | 链式后端 |
 
-HTTP 后端通过 HTTP 请求加载资源文件，适用于客户端渲染（CSR）场景。
+## 静态文件后端
 
-### 配置方式
+把翻译文件放在项目里，插件直接加载。这是最常见的方式。
 
-```ts
-i18nPlugin({
-  backend: {
-    enabled: true,
-    loadPath: '/locales/{{lng}}/{{ns}}.json',
-  },
-});
-```
+**CSR 和 SSR 的加载机制不同，但配置完全一样：**
+- CSR：浏览器通过 HTTP 请求拉取翻译文件（如 `GET /locales/zh/translation.json`）
+- SSR：服务端直接从磁盘读取文件，不走 HTTP
 
-### 资源文件结构
+插件会根据运行环境自动选择，你只需要配置一次 `loadPath`。
 
-资源文件需要放在 `config/public` 目录或通过 `server.publicDir` 配置的目录中：
+**资源文件位置：**
 
 ```
-config/public/
-└── locales/
-    ├── en/
-    │   └── translation.json
-    └── zh/
-        └── translation.json
+config/public/locales/    ← 默认位置，无需额外配置
+├── en/translation.json
+└── zh/translation.json
 ```
 
-或者通过 `server.publicDir` 配置自定义目录：
-
 ```ts
+// modern.config.ts
 export default defineConfig({
-  server: {
-    publicDir: './locales', // 指定资源文件目录
-  },
   plugins: [
+    appTools(),
     i18nPlugin({
       backend: {
-        enabled: true,
+        // `{{lng}}` 对应语言代码，`{{ns}}` 对应命名空间名称。
+        // SSR 时插件会自动将路径中的 `/` 前缀转换为相对路径后进行文件读取，无需额外处理。
         loadPath: '/locales/{{lng}}/{{ns}}.json',
       },
     }),
@@ -52,115 +45,43 @@ export default defineConfig({
 });
 ```
 
-**资源文件格式**：
-
-```json
-{
-  "key1": "value1",
-  "key2": "value2",
-  "nested": {
-    "key": "value"
-  }
-}
-```
-
-### 路径变量
-
-`loadPath` 支持以下变量：
-
-- `{{lng}}`：语言代码（如 `en`、`zh`）
-- `{{ns}}`：命名空间（如 `translation`、`common`）
-
-**示例**：
-
-```ts
-// 默认路径格式
-loadPath: '/locales/{{lng}}/{{ns}}.json';
-// 实际加载路径：
-// /locales/en/translation.json
-// /locales/zh/translation.json
-
-// 自定义路径格式
-loadPath: '/i18n/{{lng}}/{{ns}}.json';
-// 实际加载路径：
-// /i18n/en/translation.json
-// /i18n/zh/translation.json
-```
-
-## 文件系统后端（FS Backend）
-
-文件系统后端直接从文件系统读取资源文件，适用于服务端渲染（SSR）场景。
-
-### 配置方式
-
-在 SSR 场景下，插件会自动使用文件系统后端。资源文件需要放在项目目录中：
-
-```
-项目根目录/
-└── locales/
-    ├── en/
-    │   └── translation.json
-    └── zh/
-        └── translation.json
-```
-
-### 资源文件路径
-
-文件系统后端的默认路径格式为相对路径：
-
-```
-./locales/{{lng}}/{{ns}}.json
-```
-
-可以通过 `loadPath` 自定义路径：
-
-```ts
-i18nPlugin({
-  backend: {
-    enabled: true,
-    loadPath: '/locales/{{lng}}/{{ns}}.json', // 使用绝对路径（推荐）
-  },
-});
-```
-
-:::warning
-`loadPath` 配置会同时用于 HTTP 后端（前端）和文件系统后端（服务端）。如果配置的是以 `/` 开头的绝对路径（如 `/locales/{{lng}}/{{ns}}.json`），文件系统后端会自动将其转换为相对路径（`./locales/{{lng}}/{{ns}}.json`）。因此，建议在配置中使用绝对路径，这样可以同时满足前后端的需求。
+如果想放在其他目录，通过 `server.publicDir` 指定。其中，**`server.publicDir` 和 `backend.loadPath` 的关系：**
 
-:::
+- `server.publicDir`：决定哪个本地目录被暴露为静态资源，即文件放在哪里
+- `backend.loadPath`：决定 i18next 请求哪个 URL 去加载翻译文件，或者服务端从哪个路径去读取文件
 
-## SDK 后端
+## 自定义后端
 
-SDK 后端允许通过自定义函数加载资源，适用于需要从外部服务、数据库或其他自定义来源加载翻译资源的场景。
+翻译资源不在本地文件，而是来自远程 API、数据库或翻译平台时，通过一个异步函数来加载。
 
-### 启用 SDK 模式
-
-**步骤 1：在 `modern.config.ts` 中启用 SDK 模式**
+**第一步：在 `modern.config.ts` 中声明启用**
 
 ```ts
 i18nPlugin({
   backend: {
-    enabled: true,
-    sdk: true, // 启用 SDK 模式
+    sdk: true,
   },
 });
 ```
 
-**步骤 2：在 `modern.runtime.ts` 中实现 SDK 函数**
+**第二步：在 `modern.runtime.ts` 中实现加载函数**
 
 ```ts
 import { defineRuntimeConfig } from '@modern-js/runtime';
-import type { I18nSdkLoader, Resources } from '@modern-js/plugin-i18n/runtime';
+import type { I18nSdkLoader } from '@modern-js/plugin-i18n/runtime';
 
-const mySdkLoader: I18nSdkLoader = async options => {
-  // 实现资源加载逻辑
-  if (options.all) {
-    // 加载所有资源
-    return await loadAllResources();
+const myLoader: I18nSdkLoader = async options => {
+  // 最常用：按语言 + 命名空间加载单个资源
+  if (options.lng && options.ns) {
+    const res = await fetch(`/api/i18n/${options.lng}/${options.ns}`);
+    const data = await res.json();
+    return { [options.lng]: { [options.ns]: data } };
   }
 
-  if (options.lng && options.ns) {
-    // 加载单个资源
-    return await loadSingleResource(options.lng, options.ns);
+  // 一次性加载所有资源
+  if (options.all) {
+    const res = await fetch('/api/i18n/all');
+    return res.json(); // 格式：{ en: { translation: {...} }, zh: { translation: {...} } }
   }
 
   return {};
@@ -169,238 +90,53 @@ const mySdkLoader: I18nSdkLoader = async options => {
 export default defineRuntimeConfig({
   i18n: {
     initOptions: {
-      backend: {
-        sdk: mySdkLoader,
-      },
+      backend: { sdk: myLoader },
     },
   },
 });
 ```
 
-### 实现 SDK 加载函数
-
-SDK 函数接收一个 `I18nSdkLoadOptions` 参数，需要返回 `Resources` 格式的数据：
+**加载函数的参数类型：**
 
 ```ts
 interface I18nSdkLoadOptions {
-  /** 单个语言代码 */
-  lng?: string;
-  /** 单个命名空间 */
-  ns?: string;
-  /** 多个语言代码 */
-  lngs?: string[];
-  /** 多个命名空间 */
-  nss?: string[];
-  /** 加载所有资源 */
-  all?: boolean;
-}
-
-type Resources = {
-  [lng: string]: {
-    [ns: string]: Record<string, string>;
-  };
-};
-```
-
-### 批量加载示例
-
-SDK 后端支持多种加载模式：
-
-**1. 加载单个资源**：
-
-```ts
-const sdkLoader: I18nSdkLoader = async options => {
-  if (options.lng && options.ns) {
-    const response = await fetch(`/api/i18n/${options.lng}/${options.ns}`);
-    const data = await response.json();
-    return {
-      [options.lng]: {
-        [options.ns]: data,
-      },
-    };
-  }
-  return {};
-};
-```
-
-**2. 批量加载多个语言**：
-
-```ts
-const sdkLoader: I18nSdkLoader = async options => {
-  if (options.lngs && options.ns) {
-    const resources: Resources = {};
-    for (const lng of options.lngs) {
-      const response = await fetch(`/api/i18n/${lng}/${options.ns}`);
-      resources[lng] = {
-        [options.ns]: await response.json(),
-      };
-    }
-    return resources;
-  }
-  return {};
-};
-```
-
-**3. 批量加载多个命名空间**：
-
-```ts
-const sdkLoader: I18nSdkLoader = async options => {
-  if (options.lng && options.nss) {
-    const resources: Resources = {
-      [options.lng]: {},
-    };
-    for (const ns of options.nss) {
-      const response = await fetch(`/api/i18n/${options.lng}/${ns}`);
-      resources[options.lng][ns] = await response.json();
-    }
-    return resources;
-  }
-  return {};
-};
-```
-
-**4. 加载所有资源**：
-
-```ts
-const sdkLoader: I18nSdkLoader = async options => {
-  if (options.all) {
-    const response = await fetch('/api/i18n/all');
-    return await response.json();
-  }
-  return {};
-};
-```
-
-### 检查资源加载状态
-
-使用 SDK 后端时，可以使用 `isResourcesReady` 检查资源是否已加载：
-
-```tsx
-import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
-
-function MyComponent() {
-  const { isResourcesReady } = useModernI18n();
-
-  if (!isResourcesReady) {
-    return <div>正在加载翻译资源...</div>;
-  }
-
-  return <div>资源已准备好！</div>;
+  lng?: string;      // 单个语言代码
+  ns?: string;       // 单个命名空间
+  lngs?: string[];   // 多个语言代码
+  nss?: string[];    // 多个命名空间
+  all?: boolean;     // 加载所有资源
 }
 ```
 
-这在资源异步加载时特别有用，因为它确保当前语言的所有必需命名空间都已加载完成，然后再渲染依赖翻译的内容。
-
-## 链式后端（Chained Backend）
-
-链式后端允许同时使用多个后端，实现资源的渐进式加载和更新。当同时配置 `loadPath`（或 FS 后端）和 `sdk` 时，插件会自动使用 `i18next-chained-backend` 来链式加载资源。
-
-### 工作原理
-
-链式后端的工作流程：
-
-1. **初始加载**：首先从 HTTP/FS 后端加载资源并立即显示（快速显示基础翻译）
-2. **异步更新**：然后从 SDK 后端异步加载资源并更新 i18next store（更新/补充翻译）
-
-这样可以确保用户快速看到页面内容，同时后台加载最新的翻译资源。
-
-### 配置方式
-
-**步骤 1：在 `modern.config.ts` 中配置链式后端**
-
-```ts
-i18nPlugin({
-  backend: {
-    enabled: true,
-    loadPath: '/locales/{{lng}}/{{ns}}.json', // HTTP/FS 后端
-    sdk: true, // SDK 后端
-    // cacheHitMode: 'refreshAndUpdateStore', // 默认值，可省略
-  },
-});
-```
-
-**步骤 2：在 `modern.runtime.ts` 中实现 SDK 函数**
-
-```ts
-import { defineRuntimeConfig } from '@modern-js/runtime';
-
-export default defineRuntimeConfig({
-  i18n: {
-    initOptions: {
-      backend: {
-        sdk: async options => {
-          // SDK 实现
-          if (options.lng && options.ns) {
-            return await mySdk.getResource(options.lng, options.ns);
-          }
-        },
-      },
-    },
-  },
-});
-```
-
-### 缓存命中模式（cacheHitMode）
+使用自定义后端时，翻译资源需要异步加载，可以用 `isResourcesReady` 在加载完成前显示 loading 状态，用法见[最佳实践 → 加载状态处理](./best-practices.md#加载状态处理)。
 
-`cacheHitMode` 选项控制链式后端的行为：
+## 链式后端
 
-- **`'none'`**（默认，仅当未配置链式后端时）：如果第一个后端返回了资源，则停止，不再尝试下一个后端
-- **`'refresh'`**：尝试从下一个后端刷新缓存并更新缓存
-- **`'refreshAndUpdateStore'`**（链式后端的默认值）：尝试从下一个后端刷新缓存，更新缓存并同时更新 i18next 资源存储。这允许先显示 FS/HTTP 资源，然后 SDK 资源会异步更新它们。
+同时使用本地文件和自定义后端，实现「先快速显示本地翻译，再异步更新为最新翻译」：
 
-**配置示例**：
+1. 页面加载时，立即从本地文件加载翻译并显示
+2. 后台异步从自定义后端加载最新翻译，完成后自动更新页面
 
 ```ts
+// modern.config.ts
 i18nPlugin({
   backend: {
-    enabled: true,
-    loadPath: '/locales/{{lng}}/{{ns}}.json',
-    sdk: true,
-    cacheHitMode: 'refreshAndUpdateStore', // 显式指定（默认值）
+    loadPath: '/locales/{{lng}}/{{ns}}.json', // 本地文件，快速显示
+    sdk: true,                                 // 远程加载，异步更新
   },
 });
 ```
 
-### 使用场景
-
-链式后端特别适用于以下场景：
-
-1. **渐进式加载**：先显示本地/静态资源，然后从远程服务加载最新翻译
-2. **离线支持**：本地资源作为离线 fallback，SDK 资源提供在线更新
-3. **性能优化**：快速显示基础翻译，后台加载完整翻译内容
-4. **A/B 测试**：本地资源作为默认值，SDK 提供动态翻译变体
-
-### 完整示例
-
 ```ts
-// modern.config.ts
-i18nPlugin({
-  backend: {
-    enabled: true,
-    loadPath: '/locales/{{lng}}/{{ns}}.json', // 本地资源
-    sdk: true, // 远程 SDK 资源
-    cacheHitMode: 'refreshAndUpdateStore',
-  },
-});
-
 // modern.runtime.ts
-import { defineRuntimeConfig } from '@modern-js/runtime';
-
 export default defineRuntimeConfig({
   i18n: {
     initOptions: {
       backend: {
         sdk: async options => {
           if (options.lng && options.ns) {
-            // 从远程服务加载最新翻译
-            const response = await fetch(
-              `https://api.example.com/i18n/${options.lng}/${options.ns}`,
-            );
-            return {
-              [options.lng]: {
-                [options.ns]: await response.json(),
-              },
-            };
+            const res = await fetch(`https://api.example.com/i18n/${options.lng}/${options.ns}`);
+            return { [options.lng]: { [options.ns]: await res.json() } };
           }
           return {};
         },
@@ -410,8 +146,10 @@ export default defineRuntimeConfig({
 });
 ```
 
-在这个示例中：
+**`cacheHitMode` 选项**（控制两个后端之间的协作方式）：
 
-- 页面加载时，首先从 `/locales/{{lng}}/{{ns}}.json` 加载资源并立即显示
-- 后台异步从 `https://api.example.com/i18n/...` 加载最新翻译
-- SDK 资源加载完成后，自动更新 i18next store，界面文案自动更新
+| 值 | 行为 |
+| --- | --- |
+| `'none'` | 本地文件加载成功后直接使用，不再请求自定义后端 |
+| `'refresh'` | 继续请求自定义后端并更新缓存，但不更新当前页面 |
+| `'refreshAndUpdateStore'` | 继续请求自定义后端，更新缓存并同步刷新页面文案（默认） |