@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

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

@@ -1,5 +1,7 @@
 # 文件上传
 
-import BffUpload from "@site-docs/components/bff-upload";
+BFF 搭配运行时框架提供了文件上传能力，支持一体化调用及纯函数手动调用。
+
+import BffUpload from '@site-docs/components/bff-upload';
 
 <BffUpload />

package/docs/zh/guides/advanced-features/build-performance.mdx

@@ -16,50 +16,43 @@ Modern.js 默认对构建性能进行了充分优化，但是随着业务场景
 
 以下是一些通用的优化策略，对开发环境和生产环境均有提速效果，其中部分策略对包体积也有优化。
 
-### 使用 Rspack 构建（推荐）
-
-如果你还未使用 Rspack 构建，可以切换到 Rspack 构建模式来提升 5~10 倍的构建速度，请参考 [使用 Rspack](/guides/advanced-features/rspack-start.html) 来进行切换。
-
 ### 升级 Node.js 版本
 
 通常来说，将 Node.js 更新到最新的 [LTS 版本](https://github.com/nodejs/release#release-schedule)，有助于提升构建性能。
 
-尤其是对于 Apple M1/M2 芯片的机型，推荐使用 Node 18 进行构建。
+Modern.js 要求 Node.js 版本 >= 20.19.5，我们强烈推荐使用最新的 LTS 版本（如 Node.js 22 LTS）以获得最佳构建性能。
 
-Node >= 16 默认提供了 Apple Silicon binaries，因此在 M1/M2 机型上性能会比 Node 14 有大幅度提升。根据我们的测试，**从 Node 14 切换到 Node >= 16 后，编译速度可以提升 100% 以上**。
-
-你可以通过以下步骤来切换到 Node 18：
+你可以通过以下步骤来切换到最新的 LTS 版本：
 
 ```bash
-# 安装 Node v18
-nvm install 18
+# 安装最新的 LTS 版本（例如 Node.js 22）
+nvm install --lts
 
-# 切换到 Node 18
-nvm use 18
+# 切换到最新 LTS 版本
+nvm use --lts
 
-# 将 Node 18 设置为默认版本
-nvm default 18
+# 将最新 LTS 版本设置为默认版本
+nvm alias default lts/*
 
 # 查看 Node 版本
 node -v
 ```
 
-### 避免使用 ts-loader
+或者指定安装 Node.js 22 LTS：
 
-默认情况下，Modern.js 使用 Babel 编译 TS 文件，开启 [tools.tsLoader](/configure/app/tools/ts-loader.html) 选项后，会使用 `ts-loader` 编译 TS 文件。
+```bash
+# 安装 Node.js 22 LTS
+nvm install 22 --lts
 
-由于 `ts-loader` 需要进行额外的语法解析和类型检查，因此会导致项目构建速度变慢，请避免使用。
+# 切换到 Node.js 22
+nvm use 22
 
-```js
-export default {
-  tools: {
-    // 移除这项配置
-    tsLoader: {},
-  },
-};
-```
+# 将 Node.js 22 设置为默认版本
+nvm alias default 22
 
-详见 [tools.tsLoader 文档](/configure/app/tools/ts-loader.html)。
+# 查看 Node 版本
+node -v
+```
 
 ## 开发环境优化策略
 
@@ -99,7 +92,7 @@ export default {
 };
 ```
 
-> 关于不同 Source Map 格式之间的详细差异，请查看 [webpack - devtool](https://webpack.js.org/configuration/devtool/)。
+> 关于不同 Source Map 格式之间的详细差异，请查看 [rspack - devtool](https://rspack.rs/zh/config/devtool)。
 
 ### 调整 Browserslist 范围
 
@@ -128,14 +121,14 @@ export default {
 
 ### 禁用 Source Map
 
-如果项目在生产环境下不需要 Source Map，可以通过 `disableSourceMap` 配置项关闭，从而提升 build 构建的速度。
+如果项目在生产环境下不需要 Source Map，可以通过 `sourceMap` 配置项关闭，从而提升 build 构建的速度。
 
 ```js
 export default {
   output: {
-    disableSourceMap: true,
+    sourceMap: false,
   },
 };
 ```
 
-详见 [output.disableSourceMap](/configure/app/output/disable-source-map.html)。
+详见 [output.sourceMap](/configure/app/output/source-map.html)。

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

@@ -6,6 +6,10 @@ sidebar_position: 6
 
 ## Browserslist 配置
 
+Modern.js 支持通过三种方式来设置 Web 应用需要兼容的浏览器范围。
+
+### 方式一：通过`.browserslistrc` 文件配置
+
 Modern.js 支持设置 Web 应用需要兼容的浏览器范围，你可以在 `.browserslistrc` 文件里设置 [Browserslist](https://browsersl.ist/) 的值。
 
 当你创建一个新的 Modern.js 项目时，默认会包含一份 `.browserslistrc` 配置，这表示 JavaScript 代码会被编译至 ES6 格式。
@@ -18,10 +22,50 @@ safari >= 10
 ios_saf >= 10
 ```
 
+当项目中未指定 `overrideBrowserslist` 配置时，该 `.browserslistrc` 文件会默认生效。
+
+### 方式二：通过 package.json 配置
+
+你也可以在 `package.json` 文件中设置 `browserslist` 字段来配置 browserslist:
+
+```json title="package.json"
+{
+  "browserslist": [
+    "chrome >= 51"
+    // 其他浏览器的配置...
+  ]
+}
+```
+
+### 方式三：通过 `output.overrideBrowserslist` 配置
+
+你也可以在 `modern.config.js` 文件中设置 [`output.overrideBrowserslist`](/configure/app/output/override-browserslist) 字段来配置 browserslist:
+
+```js title="modern.config.js"
+export default {
+  output: {
+    overrideBrowserslist: [
+      'chrome >= 51',
+      // 其他浏览器的配置...
+    ],
+  },
+};
+```
+
+### 配置优先级
+
+`overrideBrowserslist` 配置的优先级高于项目中的 `.browserslistrc` 配置文件和 package.json 中的 `browserslist` 字段。
+
+大多数场景下，推荐优先使用 `.browserslistrc` 文件，而不是使用 `overrideBrowserslist` 配置。因为 `.browserslistrc` 文件是官方定义的配置文件，通用性更强，可以被社区中的其他库识别。
+
 :::tip
 请查看 [Rsbuild - 设置浏览器范围](https://rsbuild.rs/zh/guide/advanced/browserslist) 来了解更多内容。
 :::
 
+import UpgradeBrowserslist from '@site-docs/components/upgrade-browserslist';
+
+<UpgradeBrowserslist />
+
 ## Polyfill
 
 ### 编译时 Polyfill

package/docs/zh/guides/advanced-features/international/_meta.json

@@ -0,0 +1,11 @@
+[
+  "basic",
+  "quick-start",
+  "configuration",
+  "locale-detection",
+  "resource-loading",
+  "routing",
+  "api",
+  "advanced",
+  "best-practices"
+]

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

@@ -0,0 +1,193 @@
+---
+title: 高级用法
+---
+
+# 高级用法
+
+## SSR 配置
+
+插件完全支持服务端渲染（SSR）场景。
+
+### 服务端语言检测
+
+在 SSR 场景下，插件会从 HTTP 请求中检测语言：
+
+1. **URL 路径**：从路径中提取语言前缀
+2. **Cookie**：从 Cookie 中读取语言设置
+3. **请求头**：从 `Accept-Language` 请求头读取
+
+**配置示例**：
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    i18nextDetector: true,
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
+    detection: {
+      order: ['path', 'cookie', 'header'],
+      lookupHeader: 'accept-language',
+    },
+  },
+})
+```
+
+### SSR 资源加载
+
+在 SSR 场景下，插件会自动使用文件系统后端加载资源：
+
+```ts
+export default defineConfig({
+  server: {
+    ssr: true,
+    publicDir: './locales', // 资源文件目录
+  },
+  plugins: [
+    i18nPlugin({
+      backend: {
+        enabled: true,
+      },
+    }),
+  ],
+});
+```
+
+资源文件结构：
+
+```
+项目根目录/
+└── locales/
+    ├── en/
+    │   └── translation.json
+    └── zh/
+        └── translation.json
+```
+
+## 多入口配置
+
+如果项目有多个入口，可以为每个入口单独配置语言检测和后端选项。
+
+### 按入口配置语言检测
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    // 全局配置
+    localePathRedirect: true,
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
+
+    // 按入口覆盖配置
+    localeDetectionByEntry: {
+      admin: {
+        localePathRedirect: false, // admin 入口不使用路径重定向
+        languages: ['en'], // admin 入口只支持英文
+      },
+      mobile: {
+        languages: ['zh', 'en', 'ja'], // mobile 入口支持更多语言
+      },
+    },
+  },
+})
+```
+
+### 按入口配置后端
+
+```ts
+i18nPlugin({
+  backend: {
+    enabled: true,
+    loadPath: '/locales/{{lng}}/{{ns}}.json', // 默认路径
+
+    // 按入口覆盖配置
+    backendOptionsByEntry: {
+      admin: {
+        loadPath: '/admin/locales/{{lng}}/{{ns}}.json',
+      },
+      mobile: {
+        loadPath: '/mobile/locales/{{lng}}/{{ns}}.json',
+      },
+    },
+  },
+})
+```
+
+## 自定义 i18next 实例
+
+如果需要使用自定义的 i18next 实例，可以在运行时配置中提供。
+
+### 创建自定义实例
+
+```ts
+// src/i18n.ts
+import i18next from 'i18next';
+
+const customI18n = i18next.createInstance({
+  // 自定义配置
+  fallbackLng: 'en',
+  supportedLngs: ['zh', 'en'],
+  interpolation: {
+    escapeValue: false,
+  },
+});
+
+export default customI18n;
+```
+
+### 传递自定义实例
+
+```ts
+// src/modern.runtime.ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import customI18n from './i18n';
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance: customI18n,
+    initOptions: {
+      // 其他配置选项
+    },
+  },
+});
+```
+
+## 语言切换
+
+### 编程式切换
+
+使用 `useModernI18n` Hook 的 `changeLanguage` 方法：
+
+```tsx
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+
+function LanguageSwitcher() {
+  const { language, changeLanguage, supportedLanguages } = useModernI18n();
+
+  return (
+    <select
+      value={language}
+      onChange={e => changeLanguage(e.target.value)}
+    >
+      {supportedLanguages.map(lang => (
+        <option key={lang} value={lang}>
+          {lang}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+### URL 同步
+
+当启用 `localePathRedirect` 时，切换语言会自动更新 URL：
+
+```tsx
+// 当前 URL: /en/about
+// 调用 changeLanguage('zh')
+// URL 自动更新为: /zh/about
+```
+
+如果未启用 `localePathRedirect`，语言切换只会更新 i18next 实例和缓存，不会改变 URL。
+