@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

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

@@ -0,0 +1,219 @@
+---
+title: 配置说明
+---
+# 配置说明
+
+插件配置分为两个文件，各有职责：
+
+| 文件 | 用途 |
+| --- | --- |
+| `modern.config.ts` | 插件基础设置，在构建/启动时读取 |
+| `src/modern.runtime.ts` | i18next 初始化选项，在运行时读取 |
+
+:::warning 函数类型只能在运行时配置中设置
+`modern.config.ts` 在构建时执行，无法序列化函数。SDK 加载函数、自定义检测函数等必须放在 `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` |
+
+## CLI 配置
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { i18nPlugin } from '@modern-js/plugin-i18n';
+
+export default defineConfig({
+  plugins: [
+    appTools(),
+    i18nPlugin({
+      localeDetection: { ... },
+      backend: { ... },
+    }),
+  ],
+});
+```
+
+### 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, ...>` | — | 多入口按入口覆盖配置 |
+
+**示例：**
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    i18nextDetector: true,
+    languages: ['zh', 'en', 'ja'],
+    fallbackLanguage: 'en',
+    detection: {
+      order: ['path', 'cookie', 'header'],
+      lookupCookie: 'i18next',
+      caches: ['cookie'],
+    },
+  },
+});
+```
+
+### backend 选项
+
+```ts
+interface BackendOptions {
+  // 是否启用后端资源加载
+  // 配置了 loadPath/addPath 时自动启用；locales 目录存在时也会自动检测
+  enabled?: boolean;
+
+  // 决定请求哪个 URL 或本地文件来获取翻译文案，支持 {{lng}} 和 {{ns}} 变量
+  // 默认：'/locales/{{lng}}/{{ns}}.json'
+  loadPath?: string;
+
+  // 缺失翻译的上报路径（可选）
+  addPath?: string;
+
+  // 启用自定义后端 SDK，实际加载函数在运行时配置中提供
+  sdk?: boolean | string;
+
+  // 链式后端的缓存策略（同时配置 loadPath 和 sdk 时生效）
+  // 'none'                  — 本地文件成功后不再请求自定义后端
+  // 'refresh'               — 继续请求自定义后端并更新缓存，不更新页面
+  // 'refreshAndUpdateStore' — 继续请求并同步刷新页面文案（默认）
+  cacheHitMode?: 'none' | 'refresh' | 'refreshAndUpdateStore';
+
+  // 多入口场景下按入口覆盖配置
+  backendOptionsByEntry?: Record<string, BaseBackendOptions>;
+}
+```
+
+**`sdk` 字段说明：** 在 `modern.config.ts` 中设为 `true` 表示声明启用，实际加载函数在 `modern.runtime.ts` 的 `initOptions.backend.sdk` 中提供。详见[资源加载 → 自定义后端](./resource-loading.md#自定义后端)。
+
+**backend 自动启用规则：**
+
+| 情况 | 结果 |
+| --- | --- |
+| 配置了 `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`） |
+
+详细用法见[资源加载](./resource-loading.md)。
+
+## 运行时配置
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import i18next from 'i18next';
+
+const i18nInstance = i18next.createInstance();
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance,   // 可选，建议使用独立实例
+    initOptions: {
+      fallbackLng: 'en',
+      supportedLngs: ['zh', 'en'],
+      ns: ['translation'],
+      defaultNS: 'translation',
+      interpolation: {
+        escapeValue: false, // React 已默认转义文本，此处关闭避免重复转义
+      },
+    },
+  },
+});
+```
+
+### i18nInstance 配置
+
+如果需要使用自定义的 i18n 实例，可以在运行时配置中提供：
+
+import CustomInstanceCode from '@site-docs/components/international/custom-instance-code';
+
+<CustomInstanceCode />
+
+### initOptions
+
+import Desc from '@site-docs/components/international/init-options-desc';
+
+<Desc />
+
+| 字段 | 说明 |
+| --- | --- |
+| `fallbackLng` | i18next 找不到翻译键时回退到哪个语言的资源，支持字符串、数组或映射（回退链） |
+| `supportedLngs` | i18next 支持的语言列表 |
+| `ns` | 命名空间列表，默认 `['translation']` |
+| `defaultNS` | 默认命名空间，默认 `'translation'` |
+| `lng` | 强制指定初始语言（通常不需要，由检测器决定） |
+
+`fallbackLng` 支持回退链写法，适合区域语言降级的场景：
+
+```ts
+initOptions: {
+  lng: 'zh-CN',
+  fallbackLng: {
+    'zh-CN': ['zh', 'en'], // zh-CN 找不到时，先找 zh，再找 en
+    default: ['en'],
+  },
+},
+```
+
+### 自定义后端函数配置
+
+自定义后端的实际加载函数必须在运行时配置中提供：
+
+```ts
+// modern.config.ts：只声明启用
+i18nPlugin({
+  backend: { sdk: true },
+});
+
+// modern.runtime.ts：提供实际函数
+import type { I18nSdkLoader } from '@modern-js/plugin-i18n/runtime';
+
+const myLoader: I18nSdkLoader = async options => {
+  if (options.lng && options.ns) {
+    const res = await fetch(`/api/i18n/${options.lng}/${options.ns}`);
+    return res.json();
+  }
+  return {};
+};
+
+export default defineRuntimeConfig({
+  i18n: {
+    initOptions: {
+      backend: { sdk: myLoader },
+    },
+  },
+});
+```
+
+完整用法见[资源加载 → 自定义后端](./resource-loading.md#自定义后端)。
+
+## 多入口配置
+
+多入口项目可以为每个入口单独覆盖配置，详见[高级用法 → 多入口配置](./advanced.md#多入口配置)。

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

@@ -0,0 +1,130 @@
+---
+title: 语言检测
+---
+
+# 语言检测
+
+语言检测指的是在用户没有手动选择语言的情况下，自动推断应该使用哪种语言。插件支持从 URL 路径、Cookie、请求头、浏览器设置等多个来源检测，可以组合使用。
+
+## 检测优先级
+
+无论启用了哪些检测方式，优先级固定如下（从高到低）：
+
+1. **SSR 数据**：从 `window._SSR_DATA` 读取服务端渲染时已检测到的语言，确保客户端与服务端一致，避免语言闪烁
+2. **路径检测**：从 URL 路径前缀读取（需要启用 `localePathRedirect`）
+3. **i18next 检测器**：按 `detection.order` 配置的顺序依次检测（Cookie、LocalStorage、查询参数等）
+4. **initOptions.lng**：运行时配置中强制指定的语言
+5. **fallbackLanguage**：所有检测方式均失败时的兜底语言
+
+## 检测方式
+
+### URL 路径检测
+
+设置 `localePathRedirect: true` 后，插件从 URL 路径前缀识别语言，并将无前缀的路径自动重定向到默认语言：
+
+```
+/about        → 重定向到 /en/about（fallbackLanguage 为 en）
+/zh/about     → 识别语言为 zh，不重定向
+/en/about     → 识别语言为 en，不重定向
+```
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
+  },
+});
+```
+
+启用路径检测后，还需要在路由中配置 `[lang]` 动态参数，详见[路由集成](./routing.md)。
+
+### i18next 检测器
+
+设置 `i18nextDetector: true` 后，启用从 Cookie、LocalStorage、查询参数、请求头等位置检测语言：
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    i18nextDetector: true,
+    detection: {
+      order: ['cookie', 'querystring', 'header'],
+      lookupCookie: 'i18next',
+      lookupQuerystring: 'lng',
+      lookupHeader: 'accept-language',
+      caches: ['cookie'],
+    },
+  },
+});
+```
+
+两种方式可以同时启用：
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,   // 路径前缀
+    i18nextDetector: true,      // Cookie / Header 等
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
+    detection: {
+      order: ['cookie', 'header'],
+    },
+  },
+});
+```
+
+## 检测选项（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` 时）：**
+
+```ts
+['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`） | — |
+
+## ignoreRedirectRoutes
+
+指定哪些路径跳过语言路径重定向，适用于 API 路由、静态资源等不需要语言前缀的路径。
+
+**写法一：字符串数组**（支持精确匹配和前缀匹配）
+
+```ts
+ignoreRedirectRoutes: ['/api', '/admin', '/static']
+// '/api' 会匹配 /api 和 /api/users
+```
+
+**写法二：函数**（更灵活的自定义逻辑）
+
+```ts
+ignoreRedirectRoutes: pathname =>
+  pathname.startsWith('/api') || pathname.startsWith('/admin'),
+```

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

@@ -0,0 +1,112 @@
+---
+title: 快速开始
+---
+
+# 快速开始
+
+本指南将帮助你快速在 Modern.js 项目中集成国际化功能。
+
+## 安装插件
+
+import InstallCommand from '@site-docs/components/international/install-command';
+
+<InstallCommand />
+
+## 基础配置
+
+### 第一步：注册插件
+
+在 `modern.config.ts` 中注册插件：
+
+```ts
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { i18nPlugin } from '@modern-js/plugin-i18n';
+
+export default defineConfig({
+  plugins: [
+    appTools(),
+    i18nPlugin({
+      localeDetection: {
+        languages: ['zh', 'en'],
+        fallbackLanguage: 'en',
+      },
+    }),
+  ],
+});
+```
+
+### 第二步：创建翻译文件
+
+:::note 资源加载
+默认情况下，插件本地指定目录下查找翻译资源，在后续章节中我们会介绍更多资源加载方式。
+:::
+
+创建 `config/public/locales` 目录：
+
+```
+config/public/locales/
+├── en/
+│   └── translation.json
+└── zh/
+    └── translation.json
+```
+
+```json
+// locales/en/translation.json
+{
+  "welcome": "Welcome to Modern.js"
+}
+```
+
+```json
+// locales/zh/translation.json
+{
+  "welcome": "欢迎使用 Modern.js"
+}
+```
+
+### 第三步：配置运行时选项
+
+import InstanceCode from '@site-docs/components/international/instance-code';
+
+<InstanceCode />
+
+### 第四步：在组件中使用
+
+通过 `t()` 函数返回的语言文案，在调用 `changeLanguage` 后会自动更新，无需手动刷新。
+
+```tsx
+import { useTranslation } from 'react-i18next';
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+
+function App() {
+  const { t } = useTranslation();
+  const { language, changeLanguage, supportedLanguages } = useModernI18n();
+
+  return (
+    <div>
+      <h1>{t('welcome')}</h1>
+      <p>当前语言：{language}</p>
+      {supportedLanguages.map(lang => (
+        <button
+          key={lang}
+          onClick={() => changeLanguage(lang)}
+          disabled={lang === language}
+        >
+          {lang}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+## 下一步
+
+根据你的需求选择继续阅读：
+
+- **想要 `/en/about` 这样的 URL 结构** → [路由集成](./routing.md)
+- **需要按 Cookie / Header 自动切换语言** → [语言检测](./locale-detection.md)
+- **翻译资源来自远程服务** → [资源加载 → 自定义后端](./resource-loading.md#自定义后端)
+- **SSR 场景** → [高级用法](./advanced.md)
+- **查看所有配置选项** → [配置说明](./configuration.md)

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

@@ -0,0 +1,155 @@
+---
+title: 资源加载
+---
+# 资源加载
+
+翻译文件的加载方式取决于你的翻译资源放在哪里：
+
+| 场景 | 加载方式 |
+| --- | --- |
+| 翻译文件放在项目本地 | 静态文件后端（本篇默认方式） |
+| 翻译来自远程 API、翻译平台 | 自定义后端 |
+| 两者都要：本地兜底 + 远程实时更新 | 链式后端 |
+
+## 静态文件后端
+
+把翻译文件放在项目里，插件直接加载。这是最常见的方式。
+
+**CSR 和 SSR 的加载机制不同，但配置完全一样：**
+- CSR：浏览器通过 HTTP 请求拉取翻译文件（如 `GET /locales/zh/translation.json`）
+- SSR：服务端直接从磁盘读取文件，不走 HTTP
+
+插件会根据运行环境自动选择，你只需要配置一次 `loadPath`。
+
+**资源文件位置：**
+
+```
+config/public/locales/    ← 默认位置，无需额外配置
+├── en/translation.json
+└── zh/translation.json
+```
+
+```ts
+// modern.config.ts
+export default defineConfig({
+  plugins: [
+    appTools(),
+    i18nPlugin({
+      backend: {
+        // `{{lng}}` 对应语言代码，`{{ns}}` 对应命名空间名称。
+        // SSR 时插件会自动将路径中的 `/` 前缀转换为相对路径后进行文件读取，无需额外处理。
+        loadPath: '/locales/{{lng}}/{{ns}}.json',
+      },
+    }),
+  ],
+});
+```
+
+如果想放在其他目录，通过 `server.publicDir` 指定。其中，**`server.publicDir` 和 `backend.loadPath` 的关系：**
+
+- `server.publicDir`：决定哪个本地目录被暴露为静态资源，即文件放在哪里
+- `backend.loadPath`：决定 i18next 请求哪个 URL 去加载翻译文件，或者服务端从哪个路径去读取文件
+
+## 自定义后端
+
+翻译资源不在本地文件，而是来自远程 API、数据库或翻译平台时，通过一个异步函数来加载。
+
+**第一步：在 `modern.config.ts` 中声明启用**
+
+```ts
+i18nPlugin({
+  backend: {
+    sdk: true,
+  },
+});
+```
+
+**第二步：在 `modern.runtime.ts` 中实现加载函数**
+
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import type { I18nSdkLoader } from '@modern-js/plugin-i18n/runtime';
+
+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.all) {
+    const res = await fetch('/api/i18n/all');
+    return res.json(); // 格式：{ en: { translation: {...} }, zh: { translation: {...} } }
+  }
+
+  return {};
+};
+
+export default defineRuntimeConfig({
+  i18n: {
+    initOptions: {
+      backend: { sdk: myLoader },
+    },
+  },
+});
+```
+
+**加载函数的参数类型：**
+
+```ts
+interface I18nSdkLoadOptions {
+  lng?: string;      // 单个语言代码
+  ns?: string;       // 单个命名空间
+  lngs?: string[];   // 多个语言代码
+  nss?: string[];    // 多个命名空间
+  all?: boolean;     // 加载所有资源
+}
+```
+
+使用自定义后端时，翻译资源需要异步加载，可以用 `isResourcesReady` 在加载完成前显示 loading 状态，用法见[最佳实践 → 加载状态处理](./best-practices.md#加载状态处理)。
+
+## 链式后端
+
+同时使用本地文件和自定义后端，实现「先快速显示本地翻译，再异步更新为最新翻译」：
+
+1. 页面加载时，立即从本地文件加载翻译并显示
+2. 后台异步从自定义后端加载最新翻译，完成后自动更新页面
+
+```ts
+// modern.config.ts
+i18nPlugin({
+  backend: {
+    loadPath: '/locales/{{lng}}/{{ns}}.json', // 本地文件，快速显示
+    sdk: true,                                 // 远程加载，异步更新
+  },
+});
+```
+
+```ts
+// modern.runtime.ts
+export default defineRuntimeConfig({
+  i18n: {
+    initOptions: {
+      backend: {
+        sdk: async options => {
+          if (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 {};
+        },
+      },
+    },
+  },
+});
+```
+
+**`cacheHitMode` 选项**（控制两个后端之间的协作方式）：
+
+| 值 | 行为 |
+| --- | --- |
+| `'none'` | 本地文件加载成功后直接使用，不再请求自定义后端 |
+| `'refresh'` | 继续请求自定义后端并更新缓存，但不更新当前页面 |
+| `'refreshAndUpdateStore'` | 继续请求自定义后端，更新缓存并同步刷新页面文案（默认） |