+ {!posts &&
+ );
+}
+```
+
+可以看到我们在首页组件维护了一个 `posts` 状态，当 `posts` 是 `undefined` 时，我们认为是数据尚未加载完成。所以我们可以加入一个 `useEffect`
+让他在组件加载后对 API 路由发起一个请求，去查询目前所有的文章列表：
+
+```tsx
+// pages/index.tsx
+
+import React, { useEffect, useState } from 'react';
+import { history } from "umi";
+
+export default function HomePage() {
+ const [posts, setPosts] = useStateLoading...
} + {posts &&
+ {posts.map(post =>
}
+
+
)}
+ history.push(`/posts/${post.id}`)}>
+
+ {post.title}
+
+ {!posts &&
+ );
+}
+```
+
+可以看到我们加入了一个 `refresh` 函数，他会帮我们从 API 路由查询目前的文章列表。若你现在访问这个页面，应该可以看到一开始是 `Loading ...`
+等一阵子就会有全部文章的标题被渲染出来的效果。
+
+
+
+最后只要帮他加一点样式：
+
+
+
+---
+
+其他页面留给读者实作，可以加入自己的想法及样式的设计来实现，源代码可参考：[https://github.com/umijs/umi-blog-example/blob/main/src/pages](https://github.com/umijs/umi-blog-example/blob/main/src/pages)
+
+## 部署
+
+最后，将你的项目提交到 git 服务上，然后登入 [Vercel](https://vercel.com):
+
+
+
+如果你的项目代码是提交到 GitHub，那么建议你选择 GitHub 登入，这样你就可以在 Vercel 直接导入现有的代码仓库了 👍
+
+
+
+导入以后，他会自动检测到这个项目是使用 Umi.js 框架搭建的，并且自动化完成相关的配置，因此直接点击 **Deploy** 即可开始部署！
+
+
+
+等他部署完成以后，你的博客就正式上线啦 👍
+
+---
+
+但这个时候你会发现，网站内的 API 路由没有办法正常工作，这是因为他缺少了连线到数据库需要的环境变量。我们需要帮他配置一下：
+
+
+
+在项目配置页面，下面有可以设置环境变量的地方：
+
+
+
+你可以把 `DATABASE_URL`, `JWT_KEY` 等等你用到的环境变量从这里传入。
+
+
+
+加入环境变量以后，点击 **Redeploy** 重新部署一次版本，你的博客就能正常运作啦～
diff --git a/docs/blog/legacy-browser.md b/docs/blog/legacy-browser.md
index 389eea0c2e3c..47910222e823 100644
--- a/docs/blog/legacy-browser.md
+++ b/docs/blog/legacy-browser.md
@@ -1,8 +1,8 @@
-# 非现代浏览器兼容
+# Non-Modern Browser Compatibility
-## 默认兼容说明
+## Default Compatibility Explanation
-Umi 4 默认不支持 IE ，编译兼容目标 `targets` 为 `chrome: 80` ，如需调整，请指定明确的 [targets](../docs/api/config#targets) ：
+Umi 4 does not support IE by default. The compilation compatibility target `targets` is set to `chrome: 80`. If you need to adjust this, specify explicit [targets](../docs/api/config#targets):
```ts
// .umirc.ts
@@ -12,13 +12,13 @@ export default {
}
```
-若想反馈更多关于兼容性的问题，或参与讨论，请前往：[issue / 8656](https://github.com/umijs/umi/issues/8658)
+If you want to provide feedback or participate in discussions about compatibility, please visit: [issue / 8656](https://github.com/umijs/umi/issues/8658)
-## 兼容非现代浏览器
+## Compatibility with Non-Modern Browsers
-如果你并不需要兼容至 IE ，只为了提升项目对非现代浏览器的兼容性，可调整兼容目标 [targets](../docs/api/config#targets) 。
+If you don't need to support IE but want to enhance your project's compatibility with non-modern browsers, you can adjust the compatibility [targets](../docs/api/config#targets).
-Umi 4 默认使用现代构建工具，产物生成至 `es6` ，如果你有要打包为 `es5` 产物的考量，请调整配置：
+By default, Umi 4 uses modern build tools and generates output to `es6`. If you want to generate output in `es5`, adjust the configuration:
```ts
// .umirc.ts
@@ -29,13 +29,13 @@ export default {
}
```
-## 兼容旧时代浏览器 ( IE 11 )
+## Compatibility with Older Browsers (IE 11)
-由于 IE 已经淘汰不再主流，当需要兼容至 IE 时，请阅读以下对策。
+Since IE is no longer mainstream, if you need to support IE, consider the following strategies.
-### 框架自带的 legacy mode
+### Framework's Built-In Legacy Mode
-Umi 4 自带提供一个 `legacy` 配置用于构建降级（使用限制等详见 [legacy](../docs/api/config#legacy) ）：
+Umi 4 provides a built-in `legacy` configuration for downgrading (for usage limitations, see [legacy](../docs/api/config#legacy)):
```ts
// .umirc.ts
@@ -45,15 +45,15 @@ export default {
}
```
-默认仅在构建时生效，将尝试构建能使 IE 兼容的产物。
+By default, it only takes effect during the build and attempts to generate compatible output for IE.
-### legacy mode 的更多自定义
+### More Customization for Legacy Mode
-`legacy` 开启时，默认会转译全部 `node_modules` ，这在大型项目中，会极大的增加构建时间。
+When `legacy` is enabled, it will transpile all `node_modules`. However, transpiling `node_modules` can significantly increase build time in large projects.
-若你了解当前项目使用的第三方依赖情况（知道哪些不再提供 `es5` 产物了），可以关闭 `node_modules` 的转换，改为使用 [`extraBabelIncludes`](https://umijs.org/docs/api/config#extrababelincludes) 定点配置那些需要额外纳入转换范围的包。
+If you know which third-party dependencies your project uses (those no longer provide `es5` output), you can disable the `node_modules` transformation and use [`extraBabelIncludes`](https://umijs.org/docs/api/config#extrababelincludes) to specifically configure packages that need extra transformation.
-一个例子：
+An example:
```ts
// .umirc.ts
@@ -69,9 +69,9 @@ export default {
}
```
-### 提高兼容的鲁棒性
+### Enhancing Compatibility Robustness
-`legacy` 选项并不能 100% 保证产物 **没有边界情况** 的运行在被淘汰的浏览器内，你可能还需要添加 **前置的** 全量 polyfill 来增强项目的 [鲁棒性](https://baike.baidu.com/item/%E9%B2%81%E6%A3%92%E6%80%A7/832302) 。
+The `legacy` option cannot guarantee 100% that the output will run smoothly on deprecated browsers. You may need to add a **pre-pended** full polyfill to enhance the project's [robustness](https://en.wikipedia.org/wiki/Robustness).
```ts
// .umirc.ts
@@ -84,29 +84,29 @@ export default {
}
```
-参考的思路有：
+Consider these approaches:
-方案 | 说明
+Approach | Explanation
:-|:-
-CDN 引入 | 以 cdn 形式引入 **script 形式且前置的** 、目标浏览器环境缺少的 polyfill js 文件，如 [es6-shim](https://github.com/paulmillr/es6-shim) 。
-人工 core-js | 利用 [core-js](https://github.com/zloirock/core-js) 系工具，如通过 [core-js-builder](https://github.com/zloirock/core-js/tree/master/packages/core-js-builder) 构建自己需要的 polyfill 产物，再以 **前置 script 脚本** 形式引入项目。
-动态 polyfill 服务 | 使用根据当前浏览器请求 UA 动态下发所需 polyfill 的服务，比如 [polyfill.io](https://polyfill.io/v3/polyfill.min.js) ，考虑到速度，可使用国内的 [alicdn polyfill.io](http://polyfill.alicdn.com/v3/polyfill.min.js) 服务。另外，你还可以使用 [polyfill-service](https://github.com/Financial-Times/polyfill-service) 自建相同的动态 polyfill 下发服务。
+CDN Import | Import polyfill js files that the target browser environment lacks as **script tags that are pre-pended**, such as [es6-shim](https://github.com/paulmillr/es6-shim).
+Manual core-js | Use tools from the [core-js](https://github.com/zloirock/core-js) family, such as building your own required polyfill output using [core-js-builder](https://github.com/zloirock/core-js/tree/master/packages/core-js-builder), and then include it in your project using a **pre-pended script tag**.
+Dynamic Polyfill Service | Use a service that dynamically serves the required polyfills based on the browser's User-Agent (UA) string. For example, [polyfill.io](https://polyfill.io/v3/polyfill.min.js) is a popular option. You can also self-host a similar dynamic polyfill service using [polyfill-service](https://github.com/Financial-Times/polyfill-service).
-注：
+Note:
-1. 当你处于内外网隔离开发环境时，可以考虑将全部 polyfill 的 js 内容传入内网，在内网的 CDN 使用，或放入 public 目录等方式使用。
+1. If you are in a development environment with internal network isolation, consider bringing in all polyfill js content into the internal network and using it on an internal CDN or placing it in the `public` directory.
-2. 使用 script 前置引入的意义在于，在项目 js 资源运行前就准备好一个完整的、被 polyfill 过 api 的环境。
+2. The significance of using pre-pended script tags is to prepare a fully polyfilled environment before the project's JS resources run.
-### 在开发环境验证
+## Verifying in the Development Environment
-推荐的做法是：构建后在本地通过 [`umi preview`](../docs/api/commands#preview) 或 [`serve`](https://www.npmjs.com/package/serve) 、nginx 等启动服务，来验证产物的 IE 11 运行可行性。
+The recommended approach is to build the project and locally verify the IE 11 compatibility by using [`umi preview`](../docs/api/commands#preview), [`serve`](https://www.npmjs.com/package/serve), or nginx to start a local server.
-当你需要在开发环境验证时：
+When you need to verify in the development environment:
-1. 将 `legacy.buildOnly` 置为 `false` 。
+1. Set `legacy.buildOnly` to `false`.
-2. 由于 react fresh 、hmr 等开发注入的 es6 代码始终在第一位运行，你需要以 script 形式添加一个前置的 polyfill ，提前准备好环境。
+2. Due to React Fresh, HMR, and other ES6 code injected during development, you need to add a pre-pended polyfill as a script tag to prepare the environment before the project's JS resources run.
```ts
// .umirc.ts
@@ -122,6 +122,4 @@ export default {
}
```
-注：IE 11 并不能完整支持开发时的热更新，且缓存可能需要人为在控制台进行清除后才能看到最新的页面，请做好准备。
-
-
+Note: IE 11 does not fully support hot updates during development, and the cache might need to be manually cleared in the console to see the latest version of the page. Please be prepared for this.
\ No newline at end of file
diff --git a/docs/blog/legacy-browser.zh-CN.md b/docs/blog/legacy-browser.zh-CN.md
new file mode 100644
index 000000000000..389eea0c2e3c
--- /dev/null
+++ b/docs/blog/legacy-browser.zh-CN.md
@@ -0,0 +1,127 @@
+# 非现代浏览器兼容
+
+## 默认兼容说明
+
+Umi 4 默认不支持 IE ，编译兼容目标 `targets` 为 `chrome: 80` ，如需调整，请指定明确的 [targets](../docs/api/config#targets) ：
+
+```ts
+// .umirc.ts
+
+export default {
+ targets: { chrome: 67 }
+}
+```
+
+若想反馈更多关于兼容性的问题，或参与讨论，请前往：[issue / 8656](https://github.com/umijs/umi/issues/8658)
+
+## 兼容非现代浏览器
+
+如果你并不需要兼容至 IE ，只为了提升项目对非现代浏览器的兼容性，可调整兼容目标 [targets](../docs/api/config#targets) 。
+
+Umi 4 默认使用现代构建工具，产物生成至 `es6` ，如果你有要打包为 `es5` 产物的考量，请调整配置：
+
+```ts
+// .umirc.ts
+
+export default {
+ jsMinifier: 'terser',
+ cssMinifier: 'cssnano'
+}
+```
+
+## 兼容旧时代浏览器 ( IE 11 )
+
+由于 IE 已经淘汰不再主流，当需要兼容至 IE 时，请阅读以下对策。
+
+### 框架自带的 legacy mode
+
+Umi 4 自带提供一个 `legacy` 配置用于构建降级（使用限制等详见 [legacy](../docs/api/config#legacy) ）：
+
+```ts
+// .umirc.ts
+
+export default {
+ legacy: {}
+}
+```
+
+默认仅在构建时生效，将尝试构建能使 IE 兼容的产物。
+
+### legacy mode 的更多自定义
+
+`legacy` 开启时，默认会转译全部 `node_modules` ，这在大型项目中，会极大的增加构建时间。
+
+若你了解当前项目使用的第三方依赖情况（知道哪些不再提供 `es5` 产物了），可以关闭 `node_modules` 的转换，改为使用 [`extraBabelIncludes`](https://umijs.org/docs/api/config#extrababelincludes) 定点配置那些需要额外纳入转换范围的包。
+
+一个例子：
+
+```ts
+// .umirc.ts
+
+export default {
+ legacy: {
+ nodeModulesTransform: false
+ },
+ extraBabelIncludes: [
+ 'some-es6-pkg',
+ /@scope\//
+ ]
+}
+```
+
+### 提高兼容的鲁棒性
+
+`legacy` 选项并不能 100% 保证产物 **没有边界情况** 的运行在被淘汰的浏览器内，你可能还需要添加 **前置的** 全量 polyfill 来增强项目的 [鲁棒性](https://baike.baidu.com/item/%E9%B2%81%E6%A3%92%E6%80%A7/832302) 。
+
+```ts
+// .umirc.ts
+
+export default {
+ headScripts: [
+ 'http://polyfill.alicdn.com/v3/polyfill.min.js' // or https://polyfill.io/v3/polyfill.min.js
+ ],
+ legacy: {}
+}
+```
+
+参考的思路有：
+
+方案 | 说明
+:-|:-
+CDN 引入 | 以 cdn 形式引入 **script 形式且前置的** 、目标浏览器环境缺少的 polyfill js 文件，如 [es6-shim](https://github.com/paulmillr/es6-shim) 。
+人工 core-js | 利用 [core-js](https://github.com/zloirock/core-js) 系工具，如通过 [core-js-builder](https://github.com/zloirock/core-js/tree/master/packages/core-js-builder) 构建自己需要的 polyfill 产物，再以 **前置 script 脚本** 形式引入项目。
+动态 polyfill 服务 | 使用根据当前浏览器请求 UA 动态下发所需 polyfill 的服务，比如 [polyfill.io](https://polyfill.io/v3/polyfill.min.js) ，考虑到速度，可使用国内的 [alicdn polyfill.io](http://polyfill.alicdn.com/v3/polyfill.min.js) 服务。另外，你还可以使用 [polyfill-service](https://github.com/Financial-Times/polyfill-service) 自建相同的动态 polyfill 下发服务。
+
+注：
+
+1. 当你处于内外网隔离开发环境时，可以考虑将全部 polyfill 的 js 内容传入内网，在内网的 CDN 使用，或放入 public 目录等方式使用。
+
+2. 使用 script 前置引入的意义在于，在项目 js 资源运行前就准备好一个完整的、被 polyfill 过 api 的环境。
+
+### 在开发环境验证
+
+推荐的做法是：构建后在本地通过 [`umi preview`](../docs/api/commands#preview) 或 [`serve`](https://www.npmjs.com/package/serve) 、nginx 等启动服务，来验证产物的 IE 11 运行可行性。
+
+当你需要在开发环境验证时：
+
+1. 将 `legacy.buildOnly` 置为 `false` 。
+
+2. 由于 react fresh 、hmr 等开发注入的 es6 代码始终在第一位运行，你需要以 script 形式添加一个前置的 polyfill ，提前准备好环境。
+
+```ts
+// .umirc.ts
+
+const isProd = process.env.NODE_ENV === 'production'
+export default {
+ legacy: {
+ buildOnly: false
+ },
+ headScripts: isProd
+ ? []
+ : ['http://polyfill.alicdn.com/v3/polyfill.min.js']
+}
+```
+
+注：IE 11 并不能完整支持开发时的热更新，且缓存可能需要人为在控制台进行清除后才能看到最新的页面，请做好准备。
+
+
diff --git a/docs/blog/mfsu-faster-than-vite.mdx b/docs/blog/mfsu-faster-than-vite.mdx
index 64cabcfd628e..78cb43b8cb52 100644
--- a/docs/blog/mfsu-faster-than-vite.mdx
+++ b/docs/blog/mfsu-faster-than-vite.mdx
@@ -1,35 +1,32 @@
-# 比 Vite 还快的 MFSU
+# Faster than Vite: MFSU in Umi 4
Loading...
} + {posts &&
+ {posts.map(post =>
}
+
+
)}
+ history.push(`/posts/${post.id}`)}>
+
+ {post.title}
+- 编者按：Change the code, don't Workaround! Webpack - 慢就去改他，优化到位后，Bundle 也可以很快。此方案会在 Umi 4 - 中默认开启，适用于既要 Webpack 功能与生态，又想要 Vite 速度的同学们。 + Editor's Note: Change the code, don't Workaround! If Webpack is slow, fix it. With proper optimization, even Bundle can be fast. This approach will be enabled by default in Umi 4, suitable for those who want both Webpack functionality and ecosystem and Vite speed.
-Umi 4 中同时支持 webpack 和 vite 两种构建方式，跑通了后，迫不及待对比了 Vite 和 Webpack + MFSU 的效果，结果有点意外。关于什么是 MFSU，我在[《SEE Conf: Umi 4 设计思路文字稿》](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ%3D%3D&mid=2247484533&idx=1&sn=9b15a67b88ebc95476fce1798eb49146)中有一段详细介绍。 +Umi 4 supports both Webpack and Vite as two different build options. After setting them up and getting them running, there was an eagerness to compare the performance of Vite with that of Webpack + MFSU. The results were a bit surprising. You can find a detailed introduction to what MFSU is in my article [《SEE Conf: Umi 4 Design Concepts》](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ%3D%3D&mid=2247484533&idx=1&sn=9b15a67b88ebc95476fce1798eb49146).- 两个示例、四种模式、四个维度的对比。 + Two Examples, Four Modes, Four Dimensions of Comparison. - 两个示例分别是大型的全量 ant-design-pro 和小型的 libs example；四种模式分别是 webpack、webpack - + MFSU、webpack + MFSU with esbuild mode、Vite in umi；四个维度分别是无缓存的冷启动、有缓存的热启动、修改代码后的热更新、页面打开速度。 + The two examples are a large-scale full ant-design-pro project and a small libs example. The four modes are Webpack, Webpack + MFSU, Webpack + MFSU with esbuild mode, and Vite in Umi. The four dimensions of comparison are cold start without cache, hot start with cache, hot update after code change, and page opening speed.
-多说几点和统计相关的。上述 webpack 相关模式全部开启物理缓存；Vite 是 Umi 中集成后的 Vite，也有担心是不是 Umi 对于 Vite 的误用，经开发者确认，基本排除误用的可能性，大段时间消耗在预编译依赖上；Ant Design Pro 中包含 less 的使用，这是使用 esbuild 无法加速的部分，这有影响，但对于不同模式应该是公平的；下图数据是本地用 13-inch M1 2022 重启电脑后跑 5 次后平均取值的结果；Vite 的热更速度没统计是因为由于 esm 的特性，改完后要等请求过来后处理完才算结束，无法统计，但肯定是很快的。 +Let's discuss a few points related to statistics. All the mentioned Webpack-related modes have physical caching enabled. The integrated Vite in Umi is based on Vite but with concerns about possible misuse by Umi, which has been largely ruled out by developers. A significant amount of time was spent on pre-compiling dependencies. The use of LESS in Ant Design Pro affects the acceleration achieved by esbuild, but this should be fair across different modes. The data in the following graphs is the average of five runs after restarting the computer using a 13-inch M1 2022 model. The hot update speed of Vite was not measured due to the nature of ES modules; it only concludes when the request is handled, making it very fast. -直接上结果。有兴趣手动验证的同学可到 umijs/umi 仓库的不同 example 目录下执行 npm run dev 验证。 +Let's directly dive into the results. Those who are interested in manual verification can navigate to different example directories in the umijs/umi repository and run `npm run dev` to verify. - 图：全量 ant-design-pro 速度对比图 + Figure: Speed comparison graph for the full ant-design-pro project
- 图：libs example 速度对比图 + Figure: Speed comparison graph for the libs example
-可以看到，在这几个场景下，MFSU with esbuild 数据领先。四个模式的页面打开速度差不多，所以对比数据没在图中列出，这也是让我意外的点，原以为 Vite 请求多会让页面打开速度变慢，也有可能项目还不够复杂？ +As can be seen, in these scenarios, MFSU with esbuild data is leading. The page opening speed of all four modes is nearly the same, so the comparison data is not listed in the graphs. This was also an unexpected finding, as I initially thought that more requests in Vite might slow down the page opening speed. It's also possible that the project might not be complex enough? \ No newline at end of file diff --git a/docs/blog/mfsu-faster-than-vite.zh-CN.mdx b/docs/blog/mfsu-faster-than-vite.zh-CN.mdx new file mode 100644 index 000000000000..64cabcfd628e --- /dev/null +++ b/docs/blog/mfsu-faster-than-vite.zh-CN.mdx @@ -0,0 +1,35 @@ +# 比 Vite 还快的 MFSU + ++ 编者按：Change the code, don't Workaround! Webpack + 慢就去改他，优化到位后，Bundle 也可以很快。此方案会在 Umi 4 + 中默认开启，适用于既要 Webpack 功能与生态，又想要 Vite 速度的同学们。 +
+ +Umi 4 中同时支持 webpack 和 vite 两种构建方式，跑通了后，迫不及待对比了 Vite 和 Webpack + MFSU 的效果，结果有点意外。关于什么是 MFSU，我在[《SEE Conf: Umi 4 设计思路文字稿》](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ%3D%3D&mid=2247484533&idx=1&sn=9b15a67b88ebc95476fce1798eb49146)中有一段详细介绍。 + ++ + 两个示例、四种模式、四个维度的对比。 + + 两个示例分别是大型的全量 ant-design-pro 和小型的 libs example；四种模式分别是 webpack、webpack + + MFSU、webpack + MFSU with esbuild mode、Vite in umi；四个维度分别是无缓存的冷启动、有缓存的热启动、修改代码后的热更新、页面打开速度。 +
+ +多说几点和统计相关的。上述 webpack 相关模式全部开启物理缓存；Vite 是 Umi 中集成后的 Vite，也有担心是不是 Umi 对于 Vite 的误用，经开发者确认，基本排除误用的可能性，大段时间消耗在预编译依赖上；Ant Design Pro 中包含 less 的使用，这是使用 esbuild 无法加速的部分，这有影响，但对于不同模式应该是公平的；下图数据是本地用 13-inch M1 2022 重启电脑后跑 5 次后平均取值的结果；Vite 的热更速度没统计是因为由于 esm 的特性，改完后要等请求过来后处理完才算结束，无法统计，但肯定是很快的。 + +直接上结果。有兴趣手动验证的同学可到 umijs/umi 仓库的不同 example 目录下执行 npm run dev 验证。 + + + ++ 图：全量 ant-design-pro 速度对比图 +
+ + + ++ 图：libs example 速度对比图 +
+ +可以看到，在这几个场景下，MFSU with esbuild 数据领先。四个模式的页面打开速度差不多，所以对比数据没在图中列出，这也是让我意外的点，原以为 Vite 请求多会让页面打开速度变慢，也有可能项目还不够复杂？ diff --git a/docs/blog/mfsu-independent-usage.md b/docs/blog/mfsu-independent-usage.md index ff9902a91750..6022c1ad4af9 100644 --- a/docs/blog/mfsu-independent-usage.md +++ b/docs/blog/mfsu-independent-usage.md @@ -1,32 +1,32 @@ import { Message } from 'umi'; -# 独立使用 MFSU +# Using MFSU Independently -`MFSU` 支持独立在非 umijs 项目中使用，本文将会介绍如何将 `MFSU` 接入你的 webpack 项目。 +`MFSU` can be used independently in non-UmiJS projects. This article will guide you through the process of integrating `MFSU` into your webpack project. -## 示例项目 +## Sample Projects -如何接入 MFSU ？提供以下几个 示例项目 配置供参考： +To demonstrate MFSU integration, here are a few example projects you can refer to: -Webpack 配置示例：examples/mfsu-independent +Webpack Configuration Example: [examples/mfsu-independent](https://github.com/umijs/umi/tree/master/examples/mfsu-independent) -CRA v5 配置示例：cra-v5-with-mfsu-example +CRA v5 Configuration Example: [cra-v5-with-mfsu-example](https://github.com/umijs/cra-v5-with-mfsu-example) -## 安装 +## Installation -首先安装 `mfsu` 的依赖： +First, install the dependencies for `mfsu`: ```bash - pnpm add -D @umijs/mfsu +pnpm add -D @umijs/mfsu ``` -## 配置 MFSU +## Configuring MFSU -配置 MFSU 一共需要简单的四步操作，请确保以下所有行为都只在开发环境生效。 +Configuring MFSU involves four simple steps. Make sure these steps are applied only in the development environment. -### 1. 初始化实例 +### 1. Initialize an Instance -第一步，初始化一个 `MFSU` 实例，这是 `MFSU` 的基础： +In the first step, initialize an `MFSU` instance, which serves as the foundation for `MFSU`: ```js // webpack.config.js @@ -41,9 +41,9 @@ const mfsu = new MFSU({ }); ``` -### 2. 添加中间件 +### 2. Add Middleware -第二步，添加 `MFSU` 的 `devServer` 中间件到 webpack-dev-server 中，他将为你提供 `MFSU` 所需打包后的资源： +In the second step, add the `MFSU` `devServer` middleware to the webpack-dev-server. This middleware provides the required packaged resources for `MFSU`: #### webpack 5 @@ -80,15 +80,15 @@ module.exports = { } ``` -### 3. 配置转换器 +### 3. Configure Transformers -第三步，你需要配置一种源码转换器，他的作用是用来收集、转换依赖导入路径，替换为 `MFSU` 的模块联邦地址（中间件所提供的）。 +The third step involves configuring a source code transformer. Its purpose is to collect and transform dependency import paths, replacing them with `MFSU`'s module federation addresses provided by the middleware. -此处提供两种方案：`babel plugins` 或 `esbuild handler` ，一般情况下选择 `babel plugins` 即可。 +Two options are provided here: `babel plugins` or `esbuild handler`. Generally, `babel plugins` is the preferred choice. #### Babel Plugins -向 `babel-loader` 添加 `MFSU` 的 `babel plugins` 即可。 +Simply add `MFSU`'s `babel plugins` to the `babel-loader`: ```js // webpack.config.js @@ -117,10 +117,10 @@ module.exports = { #### Esbuild handler -另一种方案是使用内置提供的 `esbuild-loader` 来处理 `js/ts` 资源，**仅用于开发环境** 。 +An alternative is using the built-in `esbuild-loader` to handle `js/ts` resources. Note that this is only for the development environment.1. 我有自定义的 `babel plugins` 必须在开发环境使用
2. 我需要显示 `css-in-js` 的开发环境友好类名（一般由 babel plugin 提供支持）
3. 在开发环境多适配一套 `esbuild-loader` 的成本大于配置 `babel plugins` 的成本 +When should I not use the esbuild approach?
1. I have custom `babel plugins` that must be used in the development environment.
2. I need developer-friendly class names for `css-in-js` in the development environment (usually supported by babel plugins).
3. The cost of adapting to a set of `esbuild-loader` in the development environment is higher than configuring `babel plugins`.
1. 我有自定义的 `babel plugins` 必须在开发环境使用
2. 我需要显示 `css-in-js` 的开发环境友好类名（一般由 babel plugin 提供支持）
3. 在开发环境多适配一套 `esbuild-loader` 的成本大于配置 `babel plugins` 的成本 +
🚀 MFSU V3 & 默认开启
🎭 双构建引擎和 ESMi
🕸 Webpack 5
⛹🏾♂️ React Router 6 & 新路由
🐹 最佳实践迭代
🛡️ 依赖预打包
🤺 Umi Max
🐛 Low Import 研发模式
⚠️ 强约束功能集成
🎈 Import All From Umi 迭代
🍀 srcTranspiler 和 depTranspiler
🌼 jsMinifier 和 cssMinifier
🌸 应用元数据
❄️ 微生成器
🧪 贴心小改进
+🎉 New Official Website and Documentation
🚀 MFSU V3 & Enabled by Default
🎭 Dual Build Engines and ESMi
🕸 Webpack 5
⛹🏾♂️ React Router 6 & New Routing System
🐹 Improved Best Practices
🛡️ Pre-bundling Dependencies
🤺 Umi Max
🐛 Low Import Development Mode
⚠️ Strong Constraint Feature Integration
🎈 Import All From Umi Evolution
🍀 srcTranspiler and depTranspiler
🌼 jsMinifier and cssMinifier
🌸 Application Metadata
❄️ Micro Generator
🧪 Thoughtful Enhancements
- 新官网和文档。 - 下图是新官网的首页，包括重新梳理的文档、信息结构、以及新写的文档插件。目前包含基础的配置、API、升级和快速上手等基础文档，剩余文档还在紧张编写中。有个变化是之前插件的文档集成到 - Umi 官网中，成为 Umi Max 的一部分，之后无需跳转。 + New Official Website and Documentation. + The image below shows the homepage of the new official website, including restructured documentation, information architecture, and newly written documentation plugins. Currently, it includes basic configurations, APIs, upgrades, quick start guides, and other foundational documents. The remaining documentation is still being written diligently. One change is that the documentation for plugins has been integrated into the Umi official website as part of Umi Max, eliminating the need for redirection.
- MFSU V3 & 默认开启。 - MFSU 更新了他的第三个大版本，如果你有用 Umi 3 内置的 MFSU 并遇到问题，建议重新尝试，这个版本有很多改进，解决基本所有之前可能会遇到的诡异问题，并且编译速度和页面打开速度都更快。昨天我还有写一篇 - [《比 Vite 更快的 MFSU》](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ==&mid=2247484624&idx=1&sn=2addfa8cc2511fbea91faf831195788f)。基于此，我们自信地把这个功能在 - Umi 4 中默认开启。还有值得一提的是，MFSU 可脱离 Umi 运行。 + MFSU V3 & Enabled by Default. + MFSU has released its third major version. If you encountered issues with the built-in MFSU in Umi 3, it is recommended to give it a try again. This version comes with many improvements, addressing almost all the quirky issues that you might have encountered previously. It also provides faster compilation and page loading speeds. Just yesterday, I even wrote an article about + ["MFSU Faster than Vite"](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ==&mid=2247484624&idx=1&sn=2addfa8cc2511fbea91faf831195788f). Based on this, we are confident to enable this feature by default in Umi 4. Additionally, it's worth mentioning that MFSU can run independently of Umi.
- 双构建引擎和 ESMi。 - Umi 4 提供 Vite 和 Webpack 两种构建模式供开发者选择，并尽可能保证他们之间功能的一致性，可能有些同学会喜欢 - dev 用 vite，build 用 webpack 这样的组合。同时基于 Vite 模式实现了 ESMi 的 Client - 端，ESMi 依赖服务端，在外网还无法使用。 + Dual Build Engines and ESMi. + Umi 4 offers two build modes for developers to choose from: Vite and Webpack. We strive to ensure their functionality consistency as much as possible. Some developers might prefer using Vite for development and Webpack for building. Moreover, based on the Vite mode, we've implemented ESMi on the client side. ESMi requires server-side support and is not yet available on the public internet.
- Webpack 5。Umi 4 - 默认使用 webpack 5 并开启物理缓存。 + Webpack 5. Umi 4 + defaults to using Webpack 5 and enables physical caching.
- React Router 6 & 新路由。 + React Router 6 & New Routing System. - Umi 4 的路由基于 React Router 6 实现，个人非常喜欢这个版本，因为 Remix 的原因，React - Router 6 从设计上考虑了配置式路由的场景，让我得以删除大量 Umi 3 中关于路由渲染的代码。同时基于此，设计了新的路由结构，方便扩展和在未来处理路由的约定式请求。 + Umi 4's routing is built on React Router 6, a version I personally favor due to its consideration of configuration-based routing scenarios, which aligns with Remix's principles. This version allowed for a significant reduction in routing-related code compared to Umi 3. Furthermore, based on this, a new routing structure has been designed to facilitate expansion and handling of conventional routing requests in the future.
- 最佳实践迭代。 - 针对之前 umijs/plugins 仓库中的插件进行了重写、升级，并整合到主仓库。这么做是为了更好的顶层设计，让官方插件之间的风格更一致。 + Improved Best Practices. + We have rewritten, upgraded, and integrated plugins from the umijs/plugins repository into the main repository. This step was taken to improve top-level design and ensure greater consistency in style among official plugins.
- 依赖预打包。 - 由于服务企业内部，安全和稳定是其中很重要点，加上最近 colors 和 faker.js 闹得社区沸沸扬扬，谁都不希望睡一觉醒来，自己负责的业务挂了，还背个故障。Umi - 4 接着 Umi 3 继续做依赖预打包的事，并且更彻底，不仅是 node 侧的依赖，部分运行时的依赖也会做锁定，比如 - core-js 和 @babel/runtime。 + Dependency Pre-bundling. + For enterprises, security and stability are crucial. With the recent buzz around colors and faker.js in the community, no one wants to wake up and find their responsible business down due to an issue. Following Umi 3, Umi 4 continues to work on pre-bundling dependencies, going even further by locking down not only node-side dependencies but also certain runtime dependencies, such as core-js and @babel/runtime.
- Umi Max。Umi Max - 是内部 Bigfish - 框架的对外版本，解我们自己的问题，同时也给社区另一个集中化框架的选择。 + Umi Max. Umi Max + is the external version of our internal Bigfish framework. It addresses our own issues and provides another centralized framework option for the community.
- Low Import 研发模式。 + Low Import Development Mode. - 这是 Umi 4 的试验性功能之一，目前已开发完成，解的问题是让开发者少些或不写 import - 语句。项目中大量的 import 其实都可以通过工程化的方式自动处理。Umi 4 里通过 lowImport:{' '} - {} 开启，然后就可以无 import 直接用路由相关的 Link、useLocation 等，数据流相关的 - connect、useModel，antd 组件 Button、Calendar 等，以及其他更多。 + This is one of Umi 4's experimental features, already completed. It addresses the issue of minimizing or eliminating the need for developers to write import statements. Many imports in projects can be automatically managed through engineering. In Umi 4, by enabling lowImport:{' '} + {}, you can directly use route-related elements like Link and useLocation, data flow-related components like connect and useModel, Ant Design components like Button and Calendar, and more, without the need for imports.
- 强约束功能集成。Umi - 4 提供 API 让强约束和代码校验变得非常容易。API 包括 - api.onCheck、api.onCheckConfig、api.onCheckPkgJSON 和 - api.onCheckCode，顾名思义，非常好理解他们分别是干嘛的，可以分别对依赖类、代码类和配置类的内容做校验和卡点，适用于团队。 + Strong Constraint Feature Integration. Umi + 4 provides APIs that make strong constraints and code validation easy. These APIs include + api.onCheck, api.onCheckConfig, api.onCheckPkgJSON, and + api.onCheckCode. As the names suggest, they are used for checking and controlling dependencies, configuration, package.json, tsconfig.json, npmClient, code, and other aspects. These are suitable for team-based development.
- Import All From Umi 迭代。 + Import All From Umi Evolution. - 这是两年前 Umi 3 加的功能，最近发现 Remix、prisma、vitekit 等框架和工具都有类似实现。这种方式有好有坏。好处是通过 - umi 将大量依赖管理起来，用户无需手动安装。坏处是更黑盒，同时有点 Hack。Umi 4 不能解其黑盒问题，但解了 - Hack 问题，让实现无副作用，可以和 Vite、MFSU 等方案无缝结合。 + This was a feature introduced in Umi 3 two years ago. Recently, similar implementations have been seen in frameworks and tools like Remix, prisma, and vitekit. This approach has its pros and cons. The advantage is that Umi manages a large number of dependencies, reducing the need for manual installation. The downside is that it's more of a black box and somewhat hacky. Umi 4 cannot eliminate the black box issue, but it has addressed the hackiness, making the implementation side-effect-free and seamlessly integratable with solutions like Vite and MFSU.
- srcTranspiler 和 depTranspiler。 + srcTranspiler and depTranspiler. - 提供针对源码编译和依赖编译更多选择。源码编译可选 babel、swc 和 esbuild，目前没有银弹，合适场景做合适的选择。比如 - swc 由于不支持 top level await，和 mfsu 会有些冲突，但他适用于 build，因为有补丁可以兼容到 - es7；比如 esbuild 适用于 dev，因为快。数据方面以 ant-design-pro 项目为例，源码编译用 - esbuild 相比 babel 在 M1 2020 无缓存情况下会快 3s。 + More options are provided for source code and dependency compilation. Options for source code compilation include babel, swc, and esbuild. There's no silver bullet, and the appropriate choice depends on the context. For example, swc conflicts with top-level await and MFSU due to patching issues, but it's suitable for building as it's compatible with es7. On the other hand, esbuild is suitable for development due to its speed. In terms of data, taking the ant-design-pro project as an example, esbuild is around 3 seconds faster than babel for source code compilation on an M1 2020 MacBook without cache.
- jsMinifier 和 cssMinifier。 + jsMinifier and cssMinifier. - js 压缩和 css 压缩 Umi 4 默认都用的 esbuild，因为快。同时也提供更多选择，js 压缩还支持 - swc、terser 和 uglifyJs，css 压缩还支持 cssnano。 + Umi 4 defaults to using esbuild for js and css compression due to its speed. More options are also provided. For js compression, swc, terser, and uglifyJs are supported, while css compression supports cssnano.
- 应用元数据。Umi 4 - 有通过 api.appData - 收集各种项目数据，从配置、路由、package.json、tsconfig.json、npmClient - 到数据流、国际化、antd 用了哪个版本、react 和 react-dom - 的版本等，应有尽有，这对于插件开发者会非常实用，也适用于有统计需求的场景。 + Application Metadata. Umi 4 + collects various project data through api.appData, including configurations, routes, package.json, tsconfig.json, npmClient, data flow, internationalization, versions of antd, react, and react-dom used, and more. This is extremely useful for plugin developers and scenarios requiring statistics.
- 微生成器。没错，就是 - modern.js 的微生成器，这功能从 modern.js - 里学习了不少，名字就不改了。举个例子，比如 prettier - 功能，可能不是每个项目都需要，就比较适用于微生成器，按需启用、添加配置、安装依赖。 + Micro Generator. Yes, it's the micro generator from modern.js, which was inspired by modern.js and retains its name. For example, features like prettier may not be needed in every project, making it suitable for the micro generator. You can enable it as needed, add configurations, and install dependencies.
- 贴心小改进。 - 还有不少贴心小改进，举两个例子。1 是项目中新增 plugin.ts，会默认作为插件添加，方便项目进行一些插件级的扩展；2 - 是调试问题时通常需要修改编译后的代码看看有没有改对，你把 umi.js 下下来存到项目根目录，umi - 会优先使用这份代码。 + Thoughtful Enhancements. + There are many thoughtful enhancements as well. Here are two examples: 1. In projects, adding plugin.ts will automatically be treated as a plugin, making it convenient for project-level extensions; 2. When debugging issues, you often need to modify compiled code to check if you've made the right changes. If you download umi.js and place it in the project's root directory, Umi will prioritize using this code.
-以上是 Umi 4 目前的新功能。 +The above are the new features in Umi 4 so far. -除此之外，还有一些计划在正式版发布之前做的事情。包括 api route、umi server and adapter、route loader、稳定的 lint、更多命令、组件研发 father 4、文档工具 dumi 2 等，会在之后的 RC 版本中与大家见面。 +In addition to these, there are other plans to be completed before the official release. This includes api route, umi server and adapter, route loader, stable lint, more commands, component development with father 4, and documentation tool dumi 2, which will be introduced in subsequent RC versions. -欢迎大家尝鲜 Umi 4，官方文档有准备 ant-design-pro 从 Umi 3 到 4 的升级文档。同时 RC 阶段，还准备了一个手把手升级的微信交流群，欢迎 Umi 4 的先行者们加入，祝大家升级顺利，也提前祝大家新年快乐 🧨，🐯 年吉祥。 +Feel free to give Umi 4 a try! The official documentation includes an upgrade guide from Umi 3 to 4 for ant-design-pro. During the RC phase, we've also prepared a WeChat group for step-by-step upgrades, welcoming pioneers of Umi 4 to join. We wish you a smooth upgrade and an early happy New Year 🧨, auspicious year of the 🐯.
🚀 MFSU V3 & 默认开启
🎭 双构建引擎和 ESMi
🕸 Webpack 5
⛹🏾♂️ React Router 6 & 新路由
🐹 最佳实践迭代
🛡️ 依赖预打包
🤺 Umi Max
🐛 Low Import 研发模式
⚠️ 强约束功能集成
🎈 Import All From Umi 迭代
🍀 srcTranspiler 和 depTranspiler
🌼 jsMinifier 和 cssMinifier
🌸 应用元数据
❄️ 微生成器
🧪 贴心小改进
+
+
+ 新官网和文档。 + 下图是新官网的首页，包括重新梳理的文档、信息结构、以及新写的文档插件。目前包含基础的配置、API、升级和快速上手等基础文档，剩余文档还在紧张编写中。有个变化是之前插件的文档集成到 + Umi 官网中，成为 Umi Max 的一部分，之后无需跳转。 +
+ + + ++ MFSU V3 & 默认开启。 + MFSU 更新了他的第三个大版本，如果你有用 Umi 3 内置的 MFSU 并遇到问题，建议重新尝试，这个版本有很多改进，解决基本所有之前可能会遇到的诡异问题，并且编译速度和页面打开速度都更快。昨天我还有写一篇 + [《比 Vite 更快的 MFSU》](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ==&mid=2247484624&idx=1&sn=2addfa8cc2511fbea91faf831195788f)。基于此，我们自信地把这个功能在 + Umi 4 中默认开启。还有值得一提的是，MFSU 可脱离 Umi 运行。 +
+ + + ++ 双构建引擎和 ESMi。 + Umi 4 提供 Vite 和 Webpack 两种构建模式供开发者选择，并尽可能保证他们之间功能的一致性，可能有些同学会喜欢 + dev 用 vite，build 用 webpack 这样的组合。同时基于 Vite 模式实现了 ESMi 的 Client + 端，ESMi 依赖服务端，在外网还无法使用。 +
+ ++ Webpack 5。Umi 4 + 默认使用 webpack 5 并开启物理缓存。 +
+ ++ + React Router 6 & 新路由。 + + Umi 4 的路由基于 React Router 6 实现，个人非常喜欢这个版本，因为 Remix 的原因，React + Router 6 从设计上考虑了配置式路由的场景，让我得以删除大量 Umi 3 中关于路由渲染的代码。同时基于此，设计了新的路由结构，方便扩展和在未来处理路由的约定式请求。 +
+ ++ 最佳实践迭代。 + 针对之前 umijs/plugins 仓库中的插件进行了重写、升级，并整合到主仓库。这么做是为了更好的顶层设计，让官方插件之间的风格更一致。 +
+ ++ 依赖预打包。 + 由于服务企业内部，安全和稳定是其中很重要点，加上最近 colors 和 faker.js 闹得社区沸沸扬扬，谁都不希望睡一觉醒来，自己负责的业务挂了，还背个故障。Umi + 4 接着 Umi 3 继续做依赖预打包的事，并且更彻底，不仅是 node 侧的依赖，部分运行时的依赖也会做锁定，比如 + core-js 和 @babel/runtime。 +
+ + + ++ Umi Max。Umi Max + 是内部 Bigfish + 框架的对外版本，解我们自己的问题，同时也给社区另一个集中化框架的选择。 +
+ ++ + Low Import 研发模式。 + + 这是 Umi 4 的试验性功能之一，目前已开发完成，解的问题是让开发者少些或不写 import + 语句。项目中大量的 import 其实都可以通过工程化的方式自动处理。Umi 4 里通过 lowImport:{' '} + {} 开启，然后就可以无 import 直接用路由相关的 Link、useLocation 等，数据流相关的 + connect、useModel，antd 组件 Button、Calendar 等，以及其他更多。 +
+ + + ++ 强约束功能集成。Umi + 4 提供 API 让强约束和代码校验变得非常容易。API 包括 + api.onCheck、api.onCheckConfig、api.onCheckPkgJSON 和 + api.onCheckCode，顾名思义，非常好理解他们分别是干嘛的，可以分别对依赖类、代码类和配置类的内容做校验和卡点，适用于团队。 +
+ ++ + Import All From Umi 迭代。 + + 这是两年前 Umi 3 加的功能，最近发现 Remix、prisma、vitekit 等框架和工具都有类似实现。这种方式有好有坏。好处是通过 + umi 将大量依赖管理起来，用户无需手动安装。坏处是更黑盒，同时有点 Hack。Umi 4 不能解其黑盒问题，但解了 + Hack 问题，让实现无副作用，可以和 Vite、MFSU 等方案无缝结合。 +
+ ++ + srcTranspiler 和 depTranspiler。 + + 提供针对源码编译和依赖编译更多选择。源码编译可选 babel、swc 和 esbuild，目前没有银弹，合适场景做合适的选择。比如 + swc 由于不支持 top level await，和 mfsu 会有些冲突，但他适用于 build，因为有补丁可以兼容到 + es7；比如 esbuild 适用于 dev，因为快。数据方面以 ant-design-pro 项目为例，源码编译用 + esbuild 相比 babel 在 M1 2020 无缓存情况下会快 3s。 +
+ ++ + jsMinifier 和 cssMinifier。 + + js 压缩和 css 压缩 Umi 4 默认都用的 esbuild，因为快。同时也提供更多选择，js 压缩还支持 + swc、terser 和 uglifyJs，css 压缩还支持 cssnano。 +
+ ++ 应用元数据。Umi 4 + 有通过 api.appData + 收集各种项目数据，从配置、路由、package.json、tsconfig.json、npmClient + 到数据流、国际化、antd 用了哪个版本、react 和 react-dom + 的版本等，应有尽有，这对于插件开发者会非常实用，也适用于有统计需求的场景。 +
+ ++ 微生成器。没错，就是 + modern.js 的微生成器，这功能从 modern.js + 里学习了不少，名字就不改了。举个例子，比如 prettier + 功能，可能不是每个项目都需要，就比较适用于微生成器，按需启用、添加配置、安装依赖。 +
+ ++ 贴心小改进。 + 还有不少贴心小改进，举两个例子。1 是项目中新增 plugin.ts，会默认作为插件添加，方便项目进行一些插件级的扩展；2 + 是调试问题时通常需要修改编译后的代码看看有没有改对，你把 umi.js 下下来存到项目根目录，umi + 会优先使用这份代码。 +
+ +以上是 Umi 4 目前的新功能。 + +除此之外，还有一些计划在正式版发布之前做的事情。包括 api route、umi server and adapter、route loader、稳定的 lint、更多命令、组件研发 father 4、文档工具 dumi 2 等，会在之后的 RC 版本中与大家见面。 + +欢迎大家尝鲜 Umi 4，官方文档有准备 ant-design-pro 从 Umi 3 到 4 的升级文档。同时 RC 阶段，还准备了一个手把手升级的微信交流群，欢迎 Umi 4 的先行者们加入，祝大家升级顺利，也提前祝大家新年快乐 🧨，🐯 年吉祥。 + +
+ 
+
-
- 社区有非常多小伙伴在和我们一同建设 Umi，如果你有兴趣，欢迎 - 加入我们 。 + There are many community members who are contributing to Umi. If + you're interested, feel free to + join us.
diff --git a/docs/components/Contributing/Contributing.zh-CN.tsx b/docs/components/Contributing/Contributing.zh-CN.tsx
new file mode 100644
index 000000000000..912e919930e0
--- /dev/null
+++ b/docs/components/Contributing/Contributing.zh-CN.tsx
@@ -0,0 +1,29 @@
+import SectionHeader from '@/docs/components/SectionHeader/SectionHeader';
+import React from 'react';
+// @ts-ignore
+import { Link } from 'umi';
+// @ts-ignore
+import styles from './Contributing.css';
+
+export default () => {
+ return (
+
+
+ );
+};
diff --git a/docs/components/Features/Features.tsx b/docs/components/Features/Features.tsx
index 016ca53f4364..ccf5fbb3c7c8 100644
--- a/docs/components/Features/Features.tsx
+++ b/docs/components/Features/Features.tsx
@@ -7,62 +7,62 @@ export default () => {
// prettier-ignore
return (
+
+ + 社区有非常多小伙伴在和我们一同建设 Umi，如果你有兴趣，欢迎 + 加入我们 。 +
+
+
+ 
+
+
+
+
+
-
-
-
开箱即用
+Out of the Box
- 内置路由、构建、部署、测试、Lint 等，仅需一个 Umi 依赖即可上手开发。 + Built-in routing, building, deployment, testing, linting, and more. Start developing with just a Umi dependency.
-
-
企业级
+Enterprise-Grade
- 蚂蚁集团 10000+ 应用的选择。同时也在阿里、字节、腾讯、网易、美团、快手等公司有大量应用。 + Choice of over 10,000 applications within the Ant Group. Also extensively used in companies such as Alibaba, ByteDance, Tencent, NetEase, Meituan, and Kuaishou.
-
-
最佳实践
+Best Practices
- 内置微前端、数据流、权限、国际化、icons 方案、埋点、antd、请求、CSS 方案、图表等最佳实践。 + Built-in best practices including micro-frontends, data flows, permissions, internationalization, icons solution, analytics, antd, requests, CSS solutions, charts, and more.
-
-
可扩展
+Extensible
- Umi 实现了 web 应用开发的完整生命周期，并使之插件化，包括 Umi 内部功能也是全由插件实现。 + Umi provides a complete lifecycle of web application development and makes it plugin-friendly. Even internal features of Umi are implemented as plugins.
-
-
完备路由
+Comprehensive Routing
- 基于 React Router 6，类 Remix，支持嵌套、动态、动态可选、预加载、基于路由的请求优化等。 + Built on top of React Router 6, similar to Remix, supporting nesting, dynamic routing, dynamic optional routing, preloading, and route-based request optimization.
-
-
默认快
+Natively Fast
- MFSU 解 Webpack 编译慢的问题，通过 esbuild 解压缩、配置、测试的性能问题，还有运行时... + MFSU solves the slow Webpack compilation problem, and esbuild handles performance issues related to compression, configuration, testing, and runtime...
-
-
双构建引擎
+Dual Build Engines
- 提供 Vite 和 Webpack 两种构建模式供开发者选择，并尽可能保证他们之间功能的一致性。 + Provides both Vite and Webpack as build options for developers, aiming to ensure consistency in functionality between the two.
-
-
依赖预打包
+Pre-Bundled Dependencies
- Umi 针对依赖做了预打包处理，彻底地锁定依赖，定期更新，让框架的每个版本在 10 年后依旧可用。 + Umi pre-bundles dependencies, ensuring dependency locking and regular updates, making each version of the framework usable even after 10 years.
+
+ );
+};
diff --git a/docs/components/Footer/Footer.tsx b/docs/components/Footer/Footer.tsx
index 071fc7ac3bf1..fb1782aa6037 100644
--- a/docs/components/Footer/Footer.tsx
+++ b/docs/components/Footer/Footer.tsx
@@ -11,34 +11,38 @@ export default () => {
-
+
-
+
+
开箱即用
++ 内置路由、构建、部署、测试、Lint 等，仅需一个 Umi 依赖即可上手开发。 +
+
+ -
+
+
企业级
++ 蚂蚁集团 10000+ 应用的选择。同时也在阿里、字节、腾讯、网易、美团、快手等公司有大量应用。 +
+
+ -
+
+
最佳实践
++ 内置微前端、数据流、权限、国际化、icons 方案、埋点、antd、请求、CSS 方案、图表等最佳实践。 +
+
+ -
+
+
可扩展
++ Umi 实现了 web 应用开发的完整生命周期，并使之插件化，包括 Umi 内部功能也是全由插件实现。 +
+
+ -
+
+
完备路由
++ 基于 React Router 6，类 Remix，支持嵌套、动态、动态可选、预加载、基于路由的请求优化等。 +
+
+ -
+
+
默认快
++ MFSU 解 Webpack 编译慢的问题，通过 esbuild 解压缩、配置、测试的性能问题，还有运行时... +
+
+ -
+
+
双构建引擎
++ 提供 Vite 和 Webpack 两种构建模式供开发者选择，并尽可能保证他们之间功能的一致性。 +
+
+ -
+
+
依赖预打包
++ Umi 针对依赖做了预打包处理，彻底地锁定依赖，定期更新，让框架的每个版本在 10 年后依旧可用。 +
+
+
-
文档和帮助
+Docs
- 反馈和交流群
+ Feedback
{' '}
·{' '}
- 给 Umi 提 Bug
+ Report a Bug
{' '}
- · 向 Umi 贡献代码 ·{' '}
- 升级到 Umi 4
+ · Contribute to Umi{' '}
+ ·{' '}
+
+ Upgrade to Umi 4
+
-
Umi 生态
+Ecosystem
- 开发日志 · 团队 · 里程碑 ·{' '}
+ Development Log · Team · Milestones ·{' '}
- 乾坤
+ Qiankun
-
diff --git a/docs/components/Footer/Footer.zh-CN.tsx b/docs/components/Footer/Footer.zh-CN.tsx
new file mode 100644
index 000000000000..071fc7ac3bf1
--- /dev/null
+++ b/docs/components/Footer/Footer.zh-CN.tsx
@@ -0,0 +1,55 @@
+import React from 'react';
+// @ts-ignore
+import { Link } from 'umi';
+import NewsLetterForm from './NewsLetterForm';
+// @ts-ignore
+import styles from './Footer.css';
+
+export default () => {
+ return (
+ Umi 资源
+Resources
- 文档 · 示例 · 插件 ·{' '}
+ Documentation ·
+ Examples · Plugins ·{' '}
- 发布日志
+ Release Notes
+
+ );
+};
diff --git a/docs/components/Footer/NewsLetterForm.tsx b/docs/components/Footer/NewsLetterForm.tsx
index 5fa0c141e577..13a1d9b88573 100644
--- a/docs/components/Footer/NewsLetterForm.tsx
+++ b/docs/components/Footer/NewsLetterForm.tsx
@@ -5,7 +5,7 @@ import styles from './NewsLetterForm.css';
export default () => {
return (
+
+
+
+
+
+ 文档和帮助
+
+
+ 反馈和交流群
+ {' '}
+ ·{' '}
+
+ 给 Umi 提 Bug
+ {' '}
+ · 向 Umi 贡献代码 ·{' '}
+ 升级到 Umi 4
+
+
+
+ Umi 生态
+
+ 开发日志 · 团队 · 里程碑 ·{' '}
+
+ 乾坤
+
+
+
+
+ Umi 资源
+
+ 文档 · 示例 · 插件 ·{' '}
+
+ 发布日志
+
+
+
+
+
+ Open-source MIT Licensed · Copyright © 2017-present
+
+
-
diff --git a/docs/components/Footer/NewsLetterForm.zh-CN.tsx b/docs/components/Footer/NewsLetterForm.zh-CN.tsx
new file mode 100644
index 000000000000..5fa0c141e577
--- /dev/null
+++ b/docs/components/Footer/NewsLetterForm.zh-CN.tsx
@@ -0,0 +1,25 @@
+import React from 'react';
+// @ts-ignore
+import styles from './NewsLetterForm.css';
+
+export default () => {
+ return (
+ 订阅 Umi 的最新动态
+Subscribe to the Latest Updates from Umi
+
+ );
+};
diff --git a/docs/components/Hero/GithubStar.zh-CN.tsx b/docs/components/Hero/GithubStar.zh-CN.tsx
new file mode 100644
index 000000000000..693d01bdf6dc
--- /dev/null
+++ b/docs/components/Hero/GithubStar.zh-CN.tsx
@@ -0,0 +1,20 @@
+import React, { useEffect, useState } from 'react';
+
+const LS_KEY = 'github-stars';
+
+export default () => {
+ const [count, setCount] = useState(localStorage.getItem(LS_KEY) || '12K+');
+
+ useEffect(() => {
+ (async () => {
+ const res = await fetch('https://api.github.com/repos/umijs/umi');
+ const count = (await res.json()).stargazers_count;
+ if (count) {
+ setCount(count);
+ localStorage.setItem(LS_KEY, count);
+ }
+ })();
+ }, []);
+
+ return {count} Github Stars;
+};
diff --git a/docs/components/Hero/Hero.tsx b/docs/components/Hero/Hero.tsx
index 9c8152e98afc..97650627f8e3 100644
--- a/docs/components/Hero/Hero.tsx
+++ b/docs/components/Hero/Hero.tsx
@@ -7,8 +7,8 @@ import { Link } from 'umi';
import styles from './Hero.css';
export default () => {
- // TODO: github stars 存 localStorage
- // 采用 stale-while-revalidate 的策略
+ // TODO: Save github stars to localStorage
+ // Using the stale-while-revalidate strategy
return (
订阅 Umi 的最新动态
+ +
@@ -17,7 +17,7 @@ export default () => {
` 组件拥有 `accessible` 和 `fallback` 两个属性，当 `accessible` 为 `true` 时会渲染子组件，当 `accessible` 为 `false` 会渲染 `fallback` 属性对应的 `ReactNode`。
diff --git a/docs/docs/max/analytics.md b/docs/docs/max/analytics.md
index 3d08d694c004..f7d088ec62e8 100644
--- a/docs/docs/max/analytics.md
+++ b/docs/docs/max/analytics.md
@@ -1,25 +1,25 @@
-# 站点统计
+# Website Analytics
-`@umijs/max` 内置了站点统计的功能，目前支持 [Google Analytics](https://analytics.google.com/analytics/web/) 和[百度统计](https://tongji.baidu.com/web/welcome/login)
+`@umijs/max` comes with built-in website analytics functionality, currently supporting [Google Analytics](https://analytics.google.com/analytics/web/) and [Baidu Tongji](https://tongji.baidu.com/web/welcome/login).
-## 启用方式
+## Activation
-配置开启，按照需求配置进对应的统计服务的 key 即可。
+Enable analytics by configuring it and providing the corresponding tracking keys as needed.
-举例：
+For example:
```ts
{
analytics: {
- ga_v2: 'G-abcdefg', // google analytics 的 key (GA 4)
+ ga_v2: 'G-abcdefg', // Google Analytics key (GA 4)
baidu: 'baidu_tongji_key',
- // 若你在使用 GA v1 旧版本，请使用 `ga` 来配置
+ // If you are using the older GA v1 version, use `ga` to configure
ga: 'ga_old_key'
}
}
```
-### 环境变量
+### Environment Variables
-[Google Analytics 4](https://support.google.com/analytics/answer/10089681) 的 key 也可以通过环境变量 `GA_V2_KEY` 来配置，旧版本为 `GA_KEY` 。
+You can also configure the key for [Google Analytics 4](https://support.google.com/analytics/answer/10089681) using the environment variable `GA_V2_KEY`, and for the older version, you can use `GA_KEY`.
\ No newline at end of file
diff --git a/docs/docs/max/analytics.zh-CN.md b/docs/docs/max/analytics.zh-CN.md
new file mode 100644
index 000000000000..3d08d694c004
--- /dev/null
+++ b/docs/docs/max/analytics.zh-CN.md
@@ -0,0 +1,25 @@
+# 站点统计
+
+`@umijs/max` 内置了站点统计的功能，目前支持 [Google Analytics](https://analytics.google.com/analytics/web/) 和[百度统计](https://tongji.baidu.com/web/welcome/login)
+
+## 启用方式
+
+配置开启，按照需求配置进对应的统计服务的 key 即可。
+
+举例：
+
+```ts
+{
+ analytics: {
+ ga_v2: 'G-abcdefg', // google analytics 的 key (GA 4)
+ baidu: 'baidu_tongji_key',
+
+ // 若你在使用 GA v1 旧版本，请使用 `ga` 来配置
+ ga: 'ga_old_key'
+ }
+}
+```
+
+### 环境变量
+
+[Google Analytics 4](https://support.google.com/analytics/answer/10089681) 的 key 也可以通过环境变量 `GA_V2_KEY` 来配置，旧版本为 `GA_KEY` 。
diff --git a/docs/docs/max/antd.md b/docs/docs/max/antd.md
index 37a73d3f7848..e091231a555a 100644
--- a/docs/docs/max/antd.md
+++ b/docs/docs/max/antd.md
@@ -1,10 +1,10 @@
-# antd
+# Ant Design (antd)
-整合 antd 组件库。
+Integrating the antd component library.
-## 启用方式
+## Activation Method
-配置开启，示例：
+Enable through configuration, for example:
```ts
// config/config.ts
@@ -35,37 +35,37 @@ export default {
};
```
-## 介绍
+## Introduction
-包含以下功能：
+Includes the following features:
-1. 内置 [antd](https://ant.design/)，目前内置版本是 `^4.0.0`
-2. 基于 [babel-plugin-import](https://github.com/ant-design/babel-plugin-import) 做按需编译
-3. 使用 antd@4 时，可一键切换为暗色主题，见下图
+1. Built-in [antd](https://ant.design/), currently built-in version is `^4.0.0`
+2. Uses [babel-plugin-import](https://github.com/ant-design/babel-plugin-import) for on-demand compilation
+3. When using antd@4, you can switch to dark theme with a single click, as shown in the image below
-## 配置
+## Configuration
-### 构建时配置
+### Build-time Configuration
-注意：构建时配置会经过 json 转换，所以这里只能进行符合 json 格式的配置，如有例如 algorithm 等函数配置，可在[运行时配置](#运行时配置)中进行设置。
+Note: Build-time configuration goes through JSON conversion, so only configurations that conform to JSON format can be performed here. If there are function configurations such as `algorithm`, they can be set in the [runtime configuration](#runtime-configuration).
#### dark
-开启暗色主题。
+Enable dark theme.
- Type: `boolean`
- Default: `false`
#### compact
-开启紧凑主题。
+Enable compact theme.
- Type: `boolean`
- Default: `false`
-比如：
+For example:
```ts
export default {
@@ -76,62 +76,62 @@ export default {
};
```
-启用暗色主题，只有 antd 使用版本 4 时才支持。紧凑主题在 `antd@>4.1.0` 时支持。
+Dark theme is only supported when antd is used in version 4. Compact theme is supported in `antd@>4.1.0`.
#### import
- Type: `boolean`
-配置 `antd` 的 `babel-plugin-import` 按需加载。
+Configure `babel-plugin-import` for on-demand loading of `antd`.
#### style
- Type: `"less" | "css"`
- Default: `less`
-配置使用 `antd` 的样式，默认 `less`。
+Configure whether to use the styles of `antd`, default is `less`.
#### configProvider
- Type: `object`
-配置 `antd` 的 `configProvider`。
+Configure the `configProvider` of `antd`.
#### theme
- Type: `object`
-配置 `antd@5` 的 theme token，等同于配置 `configProvider.theme`，且该配置项拥有更高的优先级。
+Configure theme tokens for `antd@5`, equivalent to configuring `configProvider.theme`, and this configuration has a higher priority.
-**注意：该配置项仅 antd v5 可用**
+**Note: This configuration is only available for antd v5**
#### appConfig
- Type: `object`
-配置 `antd` 的 App 包裹组件，请注意 `antd@5.1.0 ~ 5.2.3` 仅能通过 `appConfig: {}` 启用，只有 `antd >=5.3.0` 才支持更多 App 配置项目。
+Configure the App wrapper component of `antd`, please note that only `appConfig: {}` can be used to enable `antd@5.1.0 ~ 5.2.3`, and only `antd >=5.3.0` supports more App configuration items.
-**注意：该配置项仅 antd v5.1.0 及以上可用**
+**Note: This configuration is only available for antd v5.1.0 and above**
#### momentPicker
- Type: `boolean`
-配置 `antd` 的 `DatePicker`、`TimePicker`、`Calendar` 组件是否使用 `moment` 作为日期处理库，默认为 `false`。
+Configure whether the `DatePicker`, `TimePicker`, and `Calendar` components of `antd` should use `moment` as the date processing library, default is `false`.
-**注意：该配置项仅 antd v5 及以上可用**
+**Note: This configuration is only available for antd v5 and above**
#### styleProvider
- Type: `object`
-配置 `antd` 的 `StyleProvider` 组件，该组件用于兼容低版本浏览器，如 IE11。当你的项目配置了 `legacy` 或者 `targets` 包含 `ie` 时，会自动进行降级处理，不需要手动配置。
+Configure the `StyleProvider` component of `antd`, this component is used to be compatible with older browsers like IE11. When your project is configured with `legacy` or `targets` includes `ie`, it will automatically degrade, and manual configuration is not needed.
-**注意：该配置项仅 antd v5 及以上可用**
+**Note: This configuration is only available for antd v5 and above**
-### 运行时配置
+### Runtime Configuration
-在 app.ts(x) 文件中可以对 antd 进行更丰富的配置，比如配置 antd5 的预设算法和 message 最大显示数：
+In the `app.ts(x)` file, you can have more extensive configuration for antd, such as configuring antd5's preset algorithms and the maximum display count of messages:
```ts
// app.ts
@@ -140,11 +140,11 @@ import { theme } from 'antd';
export const antd: RuntimeAntdConfig = (memo) => {
memo.theme ??= {};
- memo.theme.algorithm = theme.darkAlgorithm; // 配置 antd5 的预设 dark 算法
+ memo.theme.algorithm = theme.darkAlgorithm; // Configure antd5's preset dark algorithm
memo.appConfig = {
message: {
- // 配置 message 最大显示数，超过限制时，最早的消息会被自动关闭
+ // Configure the maximum display count of messages, and the earliest message will be automatically closed when it exceeds the limit
maxCount: 3,
}
}
@@ -155,6 +155,23 @@ export const antd: RuntimeAntdConfig = (memo) => {
## FAQ
-### 如何使用 antd 的其他版本？
+### How to use other versions of antd?
-在项目中安装你需要的 antd 版本。
+Install the antd version you need in your project.
+
+
+```shell
+# Install the desired version of antd
+$ npm install antd@version
+```
+
+Then specify the version of antd you want to use in the configuration:
+
+```ts
+// config/config.ts
+export default {
+ antd: {
+ version: '4.16.0', // or any other version you installed
+ },
+};
+```
diff --git a/docs/docs/max/antd.zh-CN.md b/docs/docs/max/antd.zh-CN.md
new file mode 100644
index 000000000000..37a73d3f7848
--- /dev/null
+++ b/docs/docs/max/antd.zh-CN.md
@@ -0,0 +1,160 @@
+# antd
+
+整合 antd 组件库。
+
+## 启用方式
+
+配置开启，示例：
+
+```ts
+// config/config.ts
+export default {
+ antd: {
+ // configProvider
+ configProvider: {},
+ // themes
+ dark: true,
+ compact: true,
+ // babel-plugin-import
+ import: true,
+ // less or css, default less
+ style: 'less',
+ // shortcut of `configProvider.theme`
+ // use to configure theme token, antd v5 only
+ theme: {},
+ // antd [] = [
{
dataIndex: 'realName',
- title: '姓名',
+ title: 'Name',
},
{
dataIndex: 'nickName',
- title: '昵称',
+ title: 'Nickname',
},
{
dataIndex: 'email',
- title: '账号',
+ title: 'Account',
},
{
dataIndex: 'phone',
- title: '手机号',
+ title: 'Phone Number',
},
{
- title: '操作',
+ title: 'Action',
dataIndex: 'x',
valueType: 'option',
render: (_, record) => {
- return [编辑, 移除];
+ return [Edit, Remove];
},
},
];
@@ -431,13 +433,13 @@ const MemberList: React.FC = () => {
}
```
-完整的表格代码和效果可查看[此页面](https://procomponents.ant.design/components/table)。
+The complete code and result of the table can be viewed on [this page](https://procomponents.ant.design/components/table).
-### Pro List 高级列表
+### Pro List: Advanced List
-现在，您需要快速构建一个包含测试信息的列表。
+Now, you need to quickly construct a list containing test information.
-测试信息如下：
+Test information is as follows:
```ts
export type Test = {
@@ -450,36 +452,36 @@ export type Test = {
const testList: Test[] = [
{
id: 9903,
- name: '语雀的天空',
+ name: 'Sparrow\'s Sky',
image:
'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
- desc: '覆盖了登录模块的所有测试用例',
+ desc: 'Covers all test cases of the login module',
},
{
id: 9904,
name: 'Ant Design',
image:
'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
- desc: '覆盖了所有测试用例，所有的案例均已在 Node 17 测试环境验证完成',
+ desc: 'Covers all test cases, all scenarios have been validated in the Node 17 test environment',
},
{
id: 9905,
- name: '蚂蚁集团体验科技',
+ name: 'Ant Group User Experience Technology',
image:
'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
- desc: '覆盖了所有测试需求，所有的案例均已在 Ubuntu 14.04 测试环境验证完成',
+ desc: 'Covers all test requirements, all scenarios have been validated in the Ubuntu 14.04 test environment',
},
{
id: 9906,
name: 'TechUI',
image:
'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
- desc: '覆盖了所有测试需求，所有的案例均已在 MacOS 测试环境验证完成',
+ desc: 'Covers all test requirements, all scenarios have been validated in the MacOS test environment',
},
];
```
-将测试信息传递给 Pro List，快速构建列表：
+Pass the test information to Pro List to quickly build the list:
```tsx
import React from 'react';
@@ -494,12 +496,12 @@ const MemberList: React.FC = () => {
toolBarRender={() => {
return [
,
];
}}
rowKey="id"
- headerTitle="测试结果"
+ headerTitle="Test Results"
dataSource={testList}
showActions="hover"
showExtra="hover"
@@ -515,9 +517,9 @@ const MemberList: React.FC = () => {
},
actions: {
render: (text, row) => [
- 链路,
- 报警,
- 查看,
+ Link,
+ Warning,
+ View,
],
},
}}
@@ -526,4 +528,4 @@ const MemberList: React.FC = () => {
}
```
-完整的列表代码和效果可查看[此页面](https://procomponents.ant.design/components/list)。
+The complete code and result of the list can be viewed on [this page](https://procomponents.ant.design/components/list).
diff --git a/docs/docs/max/charts.zh-CN.md b/docs/docs/max/charts.zh-CN.md
new file mode 100644
index 000000000000..d81af8f44ead
--- /dev/null
+++ b/docs/docs/max/charts.zh-CN.md
@@ -0,0 +1,529 @@
+# 图表
+
+Umi 团队推荐使用与 Ant Design 一脉相承的 [Ant Design Charts](https://charts.ant.design/) 或 [Pro Components](https://procomponents.ant.design/) 来为您的项目添加可视化图表 📈。
+
+本教程将为您提供一些常见的使用案例。
+
+## Ant Design Charts
+
+Ant Design Charts 是 [AntV](https://antv.vision/zh) 项目的 React 实现，由蚂蚁集团数据可视化团队开发。
+
+您可以安装完整的 Ant Design Charts 包：
+
+```bash
+pnpm install @ant-design/charts
+```
+
+也可以仅引入使用到的子包，例如：
+
+```bash
+# 安装统计图表包
+pnpm install @ant-design/plots
+```
+
+在下面的使用示例中，我们将最小化引入。
+
+您也可以直接阅读 Ant Design Charts 完整的[上手文档](https://charts.ant.design/zh/docs/manual/getting-started)和[图表示例](https://charts.ant.design/zh/examples/gallery)。
+
+### 曲线图
+
+现在，我们需要将[这些数据](https://gw.alipayobjects.com/os/bmw-prod/1d565782-dde4-4bb6-8946-ea6a38ccf184.json)制作为一个曲线图展示出来。
+
+首先，引入统计图表包：
+
+```bash
+pnpm install @ant-design/plots
+```
+
+编写代码获取数据（后略）：
+
+```tsx
+import { useState, useEffect } from 'react';
+
+const DemoLine = () => {
+ const [data, setData] = useState([]);
+
+ useEffect(() => {
+ asyncFetch();
+ }, []);
+
+ const asyncFetch = () => {
+ fetch('https://gw.alipayobjects.com/os/bmw-prod/1d565782-dde4-4bb6-8946-ea6a38ccf184.json')
+ .then((response) => response.json())
+ .then((json) => setData(json))
+ .catch((error) => {
+ console.log('fetch data failed', error);
+ });
+ };
+};
+```
+
+这样，我们获取到了数据，并将数据 JSON 对象的内容保存到 `data` 中去。每个数据对象形如：
+
+```json
+{
+ "Date": "2010-01",
+ "scales": 1998,
+}
+```
+
+将数据展示到曲线图上：
+
+```tsx
+import React from 'react';
+import { Line } from '@ant-design/plots';
+
+const DemoLine: React.FC = () => {
+ // fetch data
+
+ const config = {
+ data,
+ padding: 'auto',
+ xField: 'Date',
+ yField: 'scales',
+ xAxis: {
+ // type: 'timeCat',
+ tickCount: 5,
+ },
+ smooth: true,
+ };
+
+ return [] = [
+ {
+ dataIndex: 'realName',
+ title: '姓名',
+ },
+ {
+ dataIndex: 'nickName',
+ title: '昵称',
+ },
+ {
+ dataIndex: 'email',
+ title: '账号',
+ },
+ {
+ dataIndex: 'phone',
+ title: '手机号',
+ },
+ {
+ title: '操作',
+ dataIndex: 'x',
+ valueType: 'option',
+ render: (_, record) => {
+ return [编辑, 移除];
+ },
+ },
+ ];
+
+ return (
+
+ columns={columns}
+ request={(params, sorter, filter) => {
+ console.log(params, sorter, filter);
+ return Promise.resolve({
+ data: memberList,
+ success: true,
+ });
+ }}
+ rowKey="id"
+ pagination={{
+ showQuickJumper: true,
+ }}
+ toolBarRender={false}
+ search={false}
+ />
+ );
+}
+```
+
+完整的表格代码和效果可查看[此页面](https://procomponents.ant.design/components/table)。
+
+### Pro List 高级列表
+
+现在，您需要快速构建一个包含测试信息的列表。
+
+测试信息如下：
+
+```ts
+export type Test = {
+ id: number;
+ name: string;
+ image: string;
+ desc: string;
+};
+
+const testList: Test[] = [
+ {
+ id: 9903,
+ name: '语雀的天空',
+ image:
+ 'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
+ desc: '覆盖了登录模块的所有测试用例',
+ },
+ {
+ id: 9904,
+ name: 'Ant Design',
+ image:
+ 'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
+ desc: '覆盖了所有测试用例，所有的案例均已在 Node 17 测试环境验证完成',
+ },
+ {
+ id: 9905,
+ name: '蚂蚁集团体验科技',
+ image:
+ 'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
+ desc: '覆盖了所有测试需求，所有的案例均已在 Ubuntu 14.04 测试环境验证完成',
+ },
+ {
+ id: 9906,
+ name: 'TechUI',
+ image:
+ 'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
+ desc: '覆盖了所有测试需求，所有的案例均已在 MacOS 测试环境验证完成',
+ },
+];
+```
+
+将测试信息传递给 Pro List，快速构建列表：
+
+```tsx
+import React from 'react';
+import { Button } from 'antd';
+import ProList from '@ant-design/pro-list';
+
+// resolve test info list
+
+const MemberList: React.FC = () => {
+ return (
+
+ toolBarRender={() => {
+ return [
+ ,
+ ];
+ }}
+ rowKey="id"
+ headerTitle="测试结果"
+ dataSource={testList}
+ showActions="hover"
+ showExtra="hover"
+ metas={{
+ title: {
+ dataIndex: 'name',
+ },
+ avatar: {
+ dataIndex: 'image',
+ },
+ description: {
+ dataIndex: 'desc',
+ },
+ actions: {
+ render: (text, row) => [
+ 链路,
+ 报警,
+ 查看,
+ ],
+ },
+ }}
+ />
+ );
+}
+```
+
+完整的列表代码和效果可查看[此页面](https://procomponents.ant.design/components/list)。
diff --git a/docs/docs/max/data-flow.md b/docs/docs/max/data-flow.md
index 3d0be9d897ec..b5a8b2b65238 100644
--- a/docs/docs/max/data-flow.md
+++ b/docs/docs/max/data-flow.md
@@ -1,28 +1,28 @@
import { Message } from 'umi';
-# 数据流
+# Data Flow
-`@umi/max` 内置了**数据流管理**[插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/model.ts)，它是一种基于 `hooks` 范式的轻量级数据管理方案，可以在 Umi 项目中管理全局的共享数据。
+The `@umi/max` comes with a built-in **data flow management** [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/model.ts). It is a lightweight data management solution based on the `hooks` paradigm, designed to manage global shared data in Umi projects.
-## 开始使用
+## Getting Started
-### 创建 Model
+### Creating a Model
-数据流管理插件采用约定式目录结构，我们约定可以在 `src/models`, `src/pages/xxxx/models/`目录中，和 `src/pages/xxxx/model.{js,jsx,ts,tsx}` 文件引入 Model 文件。
-Model 文件允许使用 `.(tsx|ts|jsx|js)` 四种后缀格式，**命名空间（namespace）** 生成规则如下。
+The data flow management plugin follows a convention-based directory structure. We conventionally place Model files in the `src/models` and `src/pages/xxxx/models/` directories, or you can also include them as `src/pages/xxxx/model.{js,jsx,ts,tsx}` files.
+Model files can use any of the four suffix formats: `.(tsx|ts|jsx|js)`. The generation rules for **namespaces** are as follows.
-| 路径 | 命名空间 | 说明 |
-| :--- |:--- | :--- |
-| `src/models/count.ts` | `count` | `src/models` 目录下不支持目录嵌套定义 model |
+| Path | Namespace | Description |
+| :--- | :--- | :--- |
+| `src/models/count.ts` | `count` | Model definitions in the `src/models` directory do not support nested folders |
| `src/pages/pageA/model.ts` | `pageA.model` | |
| `src/pages/pageB/models/product.ts` | `pageB.product` | |
-| `src/pages/pageB/models/fruit/apple.ts` | `pageB.fruit.apple` | `pages/xxx/models` 下 model 定义支持嵌套定义 |
+| `src/pages/pageB/models/fruit/apple.ts` | `pageB.fruit.apple` | Nested model definitions are supported under `pages/xxx/models` |
-所谓的 Model，就是一个自定义的 `hooks`，没有任何使用者需要关注的“黑魔法”。
+A Model, in essence, is a custom `hooks` without any "black magic" that users need to be concerned about.
-当我们需要获取 Model 中的全局数据时，调用该命名空间即可。例如，对于 Model 文件 `userModel.ts`，它的命名空间为 `userModel`。
+When you need to access global data from a Model, you can simply call that namespace. For example, for a Model file named `userModel.ts`, its namespace would be `userModel`.
-编写一个默认导出的函数：
+Write a default export function:
```ts
// src/models/userModel.ts
@@ -35,13 +35,13 @@ export default function Page() {
};
```
-这就是一个 Model。插件所做的工作就是将其中的状态或数据变成了**全局数据**，不同的组件在使用该 Model 时，拿到的是同一份状态或数据。
+This is a Model. The plugin's role is to turn the states or data within it into **global data**. Different components using the same Model will access the same state or data.
-Model 文件需要默认导出一个函数，此函数定义了一个 `hook`。对于不符合此规范的文件，将会被过滤掉，并无法通过命名空间调用。
+Model files need to export a default function, which defines a `hook`. Files that do not follow this convention will be filtered out and cannot be accessed through namespaces.
-Model 中允许使用其它 `hooks`，以计数器为例：
+Other `hooks` can be used within a Model, as shown in the counter example:
```ts
// src/models/counterModel.ts
@@ -57,11 +57,11 @@ export default function Page() {
};
```
-在项目实践中，我们通常需要请求后端接口，来获取所需的数据。现在让我们来扩展前面获取用户信息的例子：
+In real-world projects, we often need to make backend API requests to fetch necessary data. Let's extend the previous example of fetching user information:
```ts
// src/models/userModel.ts
-import { useState } from 'react';
+import { useState, useEffect } from 'react';
import { getUser } from '@/services/user';
export default function Page() {
@@ -82,7 +82,7 @@ export default function Page() {
};
```
-如果您在项目中使用了 [ahooks](https://ahooks.js.org)，可以像这样组织您的代码：
+If you're using [ahooks](https://ahooks.js.org) in your project, you can organize your code like this:
```ts
// src/models/userModel.ts
@@ -105,9 +105,9 @@ export default function Page() {
};
```
-### 使用 Model
+### Using a Model
-现在，您想要在某个组件中使用全局的 Model。以用户信息为例，只需要调用 `useModel` 这一钩子函数：
+Now, if you want to use a global Model in a component, let's take the user information as an example. You can simply call the `useModel` hook function:
```tsx
// src/components/Username/index.tsx
@@ -117,21 +117,21 @@ export default function Page() {
const { user, loading } = useModel('userModel');
return (
- {loading ? <>:
-如果您使用 VSCode 作为 Umi 项目开发的 IDE，推荐搭配 [@umijs/plugin-model](https://marketplace.visualstudio.com/items?itemName=litiany4.umijs-plugin-model)插件使用。它允许您快速跳转到定义 Model 的文件：
-
+If you're using VSCode as your IDE for Umi project development, it's recommended to use the [@umijs/plugin-model](https://marketplace.visualstudio.com/items?itemName=litiany4.umijs-plugin-model) plugin. It allows you to quickly navigate to the file defining the Model:
+
-## 性能优化
+## Performance Optimization
-`useModel()` 方法可以接受可选的第二个参数，当组件只需要使用 Model 中的部分参数，而对其它参数的变化不感兴趣时，可以传入一个函数进行过滤。以实现计数器的操作按钮为例：
+The `useModel()` method can accept an optional second parameter. When a component only needs to use certain parameters from the Model and isn't interested in changes to other parameters, you can pass a filtering function. Let's use the example of operation buttons for a counter:
```tsx
// src/components/CounterActions/index.tsx
@@ -152,17 +152,15 @@ export default function Page() {
};
```
-上面的组件并不关心计数器 Model 中的 `counter` 值，只需要使用 Model 提供的 `increment()` 和 `decrement()` 方法。于是我们传入了一个函数作为 `useModel()` 方法的第二个参数，该函数的返回值将作为 `useModel()` 方法的返回值。
+In the above component, the `counter` value from the counter Model isn't relevant. The component only needs to use the `increment()` and `decrement()` methods provided by the Model. Therefore, we pass a function as the second parameter to the `useModel()` method, and the return value of this function becomes the return value of the `useModel()` method. This way, we filter out the frequently changing `counter` value, avoiding the performance hit from unnecessary re-renders.
-这样，我们过滤掉了 `counter` 这一频繁变化的值，避免了组件重复渲染带来的性能损失。
+## Global Initial State
-## 全局初始状态
+The `@umi/max` comes with a built-in **global initial state management** [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/initial-state.ts), allowing you to quickly build and retrieve the Umi project's global initial state within components.
-`@umi/max` 内置了**全局初始状态管理**[插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/initial-state.ts)，允许您快速构建并在组件内获取 Umi 项目全局的初始状态。
+The global initial state is a special kind of Model.
-全局初始状态是一种特殊的 Model。
-
-全局初始状态在整个 Umi 项目的最开始创建。编写 `src/app.ts` 的导出方法 `getInitialState()`，其返回值将成为全局初始状态。例如：
+The global initial state is created at the very beginning of the Umi project. Write the export method `getInitialState()` in `src/app.ts`, and its return value becomes the global initial state. For example:
```ts
// src/app.ts
@@ -174,7 +172,7 @@ export async function getInitialState() {
}
```
-现在，各种插件和您定义的组件都可以通过 `useModel('@@initialState')` 直接获取到这份全局的初始状态，如下所示：
+Now, various plugins and components can directly access this global initial state by using `useModel('@@initialState')`, as shown below:
```tsx
import { useModel } from 'umi';
@@ -186,30 +184,30 @@ export default function Page() {
};
```
-| 对象属性 | 类型 | 介绍 |
+| Object Property | Type | Description |
| --- | --- | --- |
-| `initialState` | `any` | 导出的 `getInitialState()` 方法的返回值 |
-| `loading` | `boolean` | `getInitialState()` 或 `refresh()` 方法是否正在进行中。在首次获取到初始状态前，页面其他部分的渲染都会**被阻止** |
-| `error` | `Error` | 如果导出的 `getInitialState()` 方法运行时报错，报错的错误信息 |
-| `refresh` | `() => void` | 重新执行 `getInitialState` 方法，并获取新的全局初始状态 |
-| `setInitialState` | `(state: any) => void` | 手动设置 `initialState` 的值，手动设置完毕会将 `loading` 置为 `false` |
+| `initialState` | `any` | Return value of the exported `getInitialState()` method |
+| `loading` | `boolean` | Whether `getInitialState()` or `refresh()` methods are currently in progress. Rendering of other parts of the page is **blocked** until the initial state is obtained for the first time |
+| `error` | `Error` | If an error occurs during the execution of the exported `getInitialState()` method |
+| `refresh` | `() => void` | Re-execute the `getInitialState` method and retrieve a new global initial state |
+| `setInitialState` | `(state: any) => void` | Manually set the value of `initialState`, and set `loading` to `false` when done manually |
-## Qiankun 父子应用间通信
+## Qiankun Communication Between Parent and Child Applications
-`@umi/max` 内置了 **Qiankun 微前端**[插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/qiankun.ts)，当使用数据流插件时，它允许微应用通过 `useModel('@@qiankunStateFromMaster')` 方法获取父应用传递给子应用的数据 Model，进而实现父子应用间的通信。
+The `@umi/max` comes with the **Qiankun micro-frontends** [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/qiankun.ts). When using data flow plugins, this plugin allows micro-applications to use the `useModel('@@qiankunStateFromMaster')` method to access the data Model passed from the parent application to the child application, enabling communication between parent and child applications.
-具体的使用方法请查阅[微前端的父子应用通信章节](./micro-frontend#父子应用通信)。
+For specific usage, please refer to the [Communication Between Parent and Child Applications](./micro-frontend#communication-between-parent-and-child-applications) section.
## API
### `useModel`
-`useModel()` 是一个钩子函数，提供了使用 Model 的能力。它接受两个参数：
+`useModel()` is a hook function that provides the ability to use a Model. It takes two parameters:
-| 参数 | 类型 | 介绍 |
+| Parameter | Type | Description |
| --- | --- | --- |
-| `namespace` | `String` | Model 文件的命名空间 |
-| `updater` | `(model: any) => any` | 可选参数。传入一个函数，函数的返回值为当前组件中需要使用到的 Model 状态或数据，并作为 `useModel()` 方法的返回值。对优化组件性能具有重要意义。 |
+| `namespace` | `String` | Namespace of the Model file |
+| `updater` | `(model: any) => any` | Optional parameter. Pass a function that returns the Model's state or data that the current component needs to use. This return value becomes the return value of the `useModel()` method. It's crucial for optimizing component performance. |
```tsx
// src/components/AdminInfo/index.tsx
diff --git a/docs/docs/max/data-flow.zh-CN.md b/docs/docs/max/data-flow.zh-CN.md
new file mode 100644
index 000000000000..f2e0de54fa38
--- /dev/null
+++ b/docs/docs/max/data-flow.zh-CN.md
@@ -0,0 +1,226 @@
+import { Message } from 'umi';
+
+# 数据流
+
+`@umi/max` 内置了**数据流管理**[插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/model.ts)，它是一种基于 `hooks` 范式的轻量级数据管理方案，可以在 Umi 项目中管理全局的共享数据。
+
+## 开始使用
+
+### 创建 Model
+
+数据流管理插件采用约定式目录结构，我们约定可以在 `src/models`, `src/pages/xxxx/models/`目录中，和 `src/pages/xxxx/model.{js,jsx,ts,tsx}` 文件引入 Model 文件。
+Model 文件允许使用 `.(tsx|ts|jsx|js)` 四种后缀格式，**命名空间（namespace）** 生成规则如下。
+
+| 路径 | 命名空间 | 说明 |
+| :--- |:--- | :--- |
+| `src/models/count.ts` | `count` | `src/models` 目录下不支持目录嵌套定义 model |
+| `src/pages/pageA/model.ts` | `pageA.model` | |
+| `src/pages/pageB/models/product.ts` | `pageB.product` | |
+| `src/pages/pageB/models/fruit/apple.ts` | `pageB.fruit.apple` | `pages/xxx/models` 下 model 定义支持嵌套定义 |
+
+所谓的 Model，就是一个自定义的 `hooks`，没有任何使用者需要关注的“黑魔法”。
+
+当我们需要获取 Model 中的全局数据时，调用该命名空间即可。例如，对于 Model 文件 `userModel.ts`，它的命名空间为 `userModel`。
+
+编写一个默认导出的函数：
+
+```ts
+// src/models/userModel.ts
+export default function Page() {
+ const user = {
+ username: 'umi',
+ };
+
+ return { user };
+};
+```
+
+这就是一个 Model。插件所做的工作就是将其中的状态或数据变成了**全局数据**，不同的组件在使用该 Model 时，拿到的是同一份状态或数据。
+
+
+Model 文件需要默认导出一个函数，此函数定义了一个 `hook`。对于不符合此规范的文件，将会被过滤掉，并无法通过命名空间调用。
+
+
+Model 中允许使用其它 `hooks`，以计数器为例：
+
+```ts
+// src/models/counterModel.ts
+import { useState, useCallback } from 'react';
+
+export default function Page() {
+ const [counter, setCounter] = useState(0);
+
+ const increment = useCallback(() => setCounter((c) => c + 1), []);
+ const decrement = useCallback(() => setCounter((c) => c - 1), []);
+
+ return { counter, increment, decrement };
+};
+```
+
+在项目实践中，我们通常需要请求后端接口，来获取所需的数据。现在让我们来扩展前面获取用户信息的例子：
+
+```ts
+// src/models/userModel.ts
+import { useState, useEffect } from 'react';
+import { getUser } from '@/services/user';
+
+export default function Page() {
+ const [user, setUser] = useState({});
+ const [loading, setLoading] = useState(true);
+
+ useEffect(() => {
+ getUser().then((res) => {
+ setUser(res);
+ setLoading(false);
+ });
+ }, []);
+
+ return {
+ user,
+ loading,
+ };
+};
+```
+
+如果您在项目中使用了 [ahooks](https://ahooks.js.org)，可以像这样组织您的代码：
+
+```ts
+// src/models/userModel.ts
+import { useRequest } from 'ahooks';
+import { getUser } from '@/services/user';
+
+export default function Page() {
+ const { data: user, loading: loading } = useRequest(async () => {
+ const res = await getUser();
+ if (res) {
+ return res;
+ }
+ return {};
+ });
+
+ return {
+ user,
+ loading,
+ };
+};
+```
+
+### 使用 Model
+
+现在，您想要在某个组件中使用全局的 Model。以用户信息为例，只需要调用 `useModel` 这一钩子函数：
+
+```tsx
+// src/components/Username/index.tsx
+import { useModel } from 'umi';
+
+export default function Page() {
+ const { user, loading } = useModel('userModel');
+
+ return (
+ {loading ? <>:
+如果您使用 VSCode 作为 Umi 项目开发的 IDE，推荐搭配 [@umijs/plugin-model](https://marketplace.visualstudio.com/items?itemName=litiany4.umijs-plugin-model)插件使用。它允许您快速跳转到定义 Model 的文件：
+
+
+
+## 性能优化
+
+`useModel()` 方法可以接受可选的第二个参数，当组件只需要使用 Model 中的部分参数，而对其它参数的变化不感兴趣时，可以传入一个函数进行过滤。以实现计数器的操作按钮为例：
+
+```tsx
+// src/components/CounterActions/index.tsx
+import { useModel } from 'umi';
+
+export default function Page() {
+ const { add, minus } = useModel('counterModel', (model) => ({
+ add: model.increment,
+ minus: model.decrement,
+ }));
+
+ return (
+
-
+ );
+};
+```
+
+- `useAccess()` 的返回值 `access` 就是 `src/access.ts` 中定义的权限集合，可以利用它进行组件内代码执行流的控制。
+
+- `快速上手 →
+ Get Started →
- 用 Umi 构建你的下一个{' '}
+ Build your next with Umi{' '}
React
Vue
@@ -37,12 +37,13 @@ export default () => {
SPA
SSR
CSR
- 中后台
+ Enterprise
{' '}
- 应用
+ applications
- 带给你简单而愉悦的 Web 开发体验
+ Providing you with a simple and{' '}
+ pleasant web development experience
+
+
+ );
+};
diff --git a/docs/components/SectionHeader/SectionHeader.zh-CN.tsx b/docs/components/SectionHeader/SectionHeader.zh-CN.tsx
new file mode 100644
index 000000000000..6b3b0d195dac
--- /dev/null
+++ b/docs/components/SectionHeader/SectionHeader.zh-CN.tsx
@@ -0,0 +1,13 @@
+import React from 'react';
+// @ts-ignore
+import styles from './SectionHeader.css';
+
+export default (props: { title: string }) => {
+ return (
+
+
+
+
+
+
+
+
+ 快速上手 →
+
+
+
+
+
+
+
+
+ 用 Umi 构建你的下一个{' '}
+
+ React
+ Vue
+ PC
+ Mobile
+ SPA
+ SSR
+ CSR
+ 中后台
+ {' '}
+ 应用
+
+
+ 带给你简单而愉悦的 Web 开发体验
+
+
+
+
+
+ );
+};
diff --git a/docs/components/WhoIsUsing/WhoIsUsing.tsx b/docs/components/WhoIsUsing/WhoIsUsing.tsx
index 31ebdb392c7e..938a59ca8a87 100644
--- a/docs/components/WhoIsUsing/WhoIsUsing.tsx
+++ b/docs/components/WhoIsUsing/WhoIsUsing.tsx
@@ -6,65 +6,65 @@ import styles from './WhoIsUsing.css';
export default () => {
return (
{props.title}
+ +
-
}
+ >
+ Delete foo.
+
+ -
-
-
-
-
-
-
-
-
-
diff --git a/docs/components/WhoIsUsing/WhoIsUsing.zh-CN.tsx b/docs/components/WhoIsUsing/WhoIsUsing.zh-CN.tsx
new file mode 100644
index 000000000000..31ebdb392c7e
--- /dev/null
+++ b/docs/components/WhoIsUsing/WhoIsUsing.zh-CN.tsx
@@ -0,0 +1,74 @@
+import SectionHeader from '@/docs/components/SectionHeader/SectionHeader';
+import React from 'react';
+// @ts-ignore
+import styles from './WhoIsUsing.css';
+
+export default () => {
+ return (
+ -
+
+
+
-
+
+
+
-
+
+
+
-
+
+
+
-
+
+
+
-
+
+
+
-
+
+
+
-
+
+
+
-
+
+
+
-
+
+
+
isActive ? { color: 'red' } : undefined}>Messages
+ isActive ? 'active' : undefined}>Tasks
+ {({ isActive }) => Blog}
+
+
+ );
+};
diff --git a/docs/docs/README.zh-CN.md b/docs/docs/README.zh-CN.md
index d8e8a26ee78f..51a66aaec8b1 100644
--- a/docs/docs/README.zh-CN.md
+++ b/docs/docs/README.zh-CN.md
@@ -1 +1,3 @@
-# 文档首页
+import { Navigate } from 'umi';
+
+-
+
@@ -562,14 +561,14 @@ const Layout = ()=>{
### useOutletContext
-`useOutletContext` 用于返回 `Outlet` 组件上挂载的 `context` 。
+`useOutletContext` is used to retrieve the `context` attached to the `Outlet` component in child components.
-类型定义如下：
+Type definition:
```ts
declare function useOutletContext(): Context;
```
-示例：
+Example:
```ts
import { useOutletContext, Outlet } from 'umi';
@@ -588,22 +587,22 @@ const SomeRouteComponentUnderLayout = () => {
### useParams
-`useParams` 钩子函数返回动态路由的匹配参数键值对对象；子路由中会集成父路由的动态参数。
+`useParams` hook function returns a key-value object of matched dynamic route parameters; child routes inherit parent route's dynamic parameters.
-类型定义如下：
+Type definition:
```ts
declare function useParams<
K extends string = string
>(): Readonly>;
```
-示例：
+Example:
```ts
import { useParams } from 'umi';
-// 假设有路由配置 user/:uId/repo/:rId
-// 当前路径 user/abc/repo/def
+// Assuming the route configuration is user/:uId/repo/:rId
+// and the current path is user/abc/repo/def
const params = useParams()
/* params
{ uId: 'abc', rId: 'def'}
@@ -612,14 +611,14 @@ const params = useParams()
### useResolvedPath
-`useResolvedPath` 根据当前路径将目标地址解析出完整的路由信息。
+`useResolvedPath` resolves the target route path based on the current path.
-类型定义如下：
+Type definition:
```ts
declare function useResolvedPath(to: To): Path;
```
-示例：
+Example:
```ts
import { useResolvedPath } from 'umi';
@@ -632,18 +631,18 @@ const path = useResolvedPath('docs')
### useRouteData
-`useRouteData` 返回当前匹配路由的数据的钩子函数。
+`useRouteData` is a hook function that returns data of the currently matched route.
-类型定义如下：
+Type definition:
```ts
declare function useRouteData(): {
route: Route;
};
```
-注意：此处 API 可能还会调整。
+Note: This API might be subject to change.
-示例：
+Example:
```ts
import { useRouteData } from 'umi';
@@ -662,9 +661,9 @@ const route = useRouteData();
### useRoutes
-`useRoutes` 渲染路由的钩子函数，传入路由配置和可选参数 `location`, 即可得到渲染结果；如果没有匹配的路由，结果为 `null`。
+`useRoutes` is a hook function to render routes. It takes route configuration and an optional `location` parameter and returns the rendering result. If there are no matched routes, it returns `null`.
-类型定义如下：
+Type definition:
```ts
declare function useRoutes(
routes: RouteObject[],
@@ -672,7 +671,7 @@ declare function useRoutes(
): React.ReactElement | null;
```
-示例：
+Example:
```ts
import * as React from "react";
@@ -700,7 +699,7 @@ function App() {
### useRouteProps
-读取当前路由在路由配置里的 props 属性，你可以用此 hook 来获取路由配置中的额外信息。
+`useRouteProps` is used to read the `props` property from the route configuration. You can use this hook to access additional information defined in the route configuration.
```ts
// .umirc.ts
@@ -722,13 +721,13 @@ export default function Page() {
}
```
-注：同样适用于约定式路由。
+Note: This also works with conventional routes.
### useSelectedRoutes
-用于读取当前路径命中的所有路由信息。比如在 `layout` 布局中可以获取到当前命中的所有子路由信息，同时可以获取到在 `routes` 配置中的参数，这格外有用。
+`useSelectedRoutes` is used to read information about all matched routes for the current path. For example, it can be used in the `layout` component to obtain information about all child routes matched, along with any parameters defined in the `routes` configuration, which can be quite useful.
-实例：
+Example:
```tsx
// layouts/index.tsx
@@ -753,9 +752,9 @@ export default function Layout() {
### useSearchParams
-`useSearchParams` 用于读取和修改当前 URL 的 query string。类似 React 的 `useState`，其返回包含两个值的数组，当前 URL 的 search 参数和用于更新 search 参数的函数。
+`useSearchParams` is used to read and modify the query string of the current URL. Similar to React's `useState`, it returns an array containing two values: the current search parameters and a function to update the search parameters.
-类型定义如下：
+Type definition:
```ts
declare function useSearchParams(defaultInit?: URLSearchParamsInit): [
@@ -773,7 +772,7 @@ type URLSearchParamsInit =
| URLSearchParams;
```
-示例：
+Example:
```ts
import React from 'react';
import { useSearchParams } from 'umi';
@@ -790,9 +789,9 @@ function App() {
### withRouter
-`withRouter` 参考 [react-router faq](https://reactrouter.com/docs/en/v6/getting-started/faq#what-happened-to-withrouter-i-need-it) 实现的版本, 仅实现了部分能力, 请参考类型定义按需使用, 建议迁移到 React Hook API。
+`withRouter` is an implementation of the [react-router faq](https://reactrouter.com/docs/en/v6/getting-started/faq#what-happened-to-withrouter-i-need-it), which only implements part of its capabilities. Please refer to the type definitions for usage details. It's recommended to migrate to React Hook API.
-类型定义如下:
+Type definition:
```ts
export interface RouteComponentProps> {
@@ -811,7 +810,7 @@ export interface RouteComponentProps> {
}
```
-示例：
+Example:
```tsx
import React from 'react';
import { withRouter } from 'umi';
diff --git a/docs/docs/api/api.zh-CN.md b/docs/docs/api/api.zh-CN.md
new file mode 100644
index 000000000000..fd6992358063
--- /dev/null
+++ b/docs/docs/api/api.zh-CN.md
@@ -0,0 +1,838 @@
+import { Message } from 'umi';
+
+# API
+
+为方便查找，以下内容通过字母排序。
+
+## umi
+
+### createBrowserHistory
+
+创建使用浏览器内置 `history` 来跟踪应用的 `BrowserHistory`。推荐在支持 HTML5 `history` 接口的 现代 Web 浏览器中使用。
+
+类型定义如下：
+```ts
+function createBrowserHistory(options?: { window?: Window }) => BrowserHistory;
+```
+
+使用范例：
+```ts
+// create a BrowserHistory
+import { createBrowserHistory } from 'umi';
+const history = createBrowserHistory();
+// or a iframe BrowserHistory
+import { createBrowserHistory } from 'umi';
+const history = createBrowserHistory({
+ window: iframe.contentWindow,
+});
+```
+### createHashHistory
+
+`createHashHistory` 返回一个 `HashHistory` 实例。`window` 默认为当前 `document` 的 `defaultView`。
+
+`HashHistory` 与 `BrowserHistory` 的主要区别在于，`HashHistory` 将当前位置存储在 URL 的哈希部分中，这意味着它在路由切换时不会发送请求到服务器。如果您将站点托管在您无法完全控制服务器上，或者在只提供同单页面的 Electron 应用程序中，推荐使用 `HashHistory`。
+
+使用范例：
+```ts
+// create a HashHistory
+import { createHashHistory } from 'umi';
+const history = createHashHistory();
+```
+
+### createMemoryHistory
+
+`MemoryHistory` 不会在地址栏被操作或读取。它也非常适合测试和其他的渲染环境。
+
+```ts
+const history = createMemoryHistory(location)
+```
+
+### createSearchParams
+
+包装 `new URLSearchParams(init)` 的工具函数，支持使用数组和对象创建
+
+```ts
+import { createSearchParams } from 'umi';
+
+
+// 假设路径 http://a.com?foo=1&bar=2
+createSearchParams(location.search);
+createSearchParams("foo=1&bar=2");
+createSearchParams("?foo=1&bar=2");
+
+// 键值对对象
+createSearchParams({ foo: 'bar', qux: 'qoo'}).toString()
+// foo=bar&qux=qoo
+
+// 键值元组数组
+createSearchParams([["foo", "1"], ["bar", "2"]]).toString()
+// foo=1&bar=2
+```
+
+[URLSearchParams 文档](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/URLSearchParams)
+
+{
+/*
+
+### dynamic
+
+TODO: SUPPORT
+*/
+}
+
+### generatePath
+
+使用给定的带参数的 path 和对应的 params 生成实际要访问的路由。
+
+```ts
+import { generatePath } from 'umi';
+
+generatePath("/users/:id", { id: "42" }); // "/users/42"
+generatePath("/files/:type/*", {
+ type: "img",
+ "*": "cat.jpg",
+}); // "/files/img/cat.jpg"
+```
+
+### Helmet
+
+即 [react-helmet-async](https://github.com/staylor/react-helmet-async) 提供的 Helmet 组件，用于在页面中动态配置 `head` 中的标签，例如 `title`。
+
+> 注意：为了确保 SSR 时 Helmet 仍能正常工作，请务必使用 Umi 提供的 Helmet 而不是单独安装 react-helmet
+
+```tsx
+import { Helmet } from 'umi';
+
+export default function Page() {
+ return (
+
+ Hello World
+
+ );
+}
+```
+
+### history
+
+和 history 相关的操作，用于获取当前路由信息、执行路由跳转、监听路由变更。
+
+```ts
+// 建议组件或 hooks 里用 useLocation 取
+import { useLocation } from 'umi';
+export default function Page() {
+ let location = useLocation();
+ return (
+
+注意：history.push 和 history.replace 需要使用 `state` 需将 `state` 作为这两个 API 的第二个参数传递
+
+
+
+路由监听。
+
+```ts
+import { history } from 'umi';
+
+const unlisten = history.listen(({ location, action }) => {
+ console.log(location.pathname);
+});
+unlisten();
+```
+
+### Link
+
+`` 是 React 组件，是带路由跳转功能的 `` 元素。
+
+类型定义如下：
+
+```ts
+declare function Link(props: {
+ prefetch?: boolean;
+ to: string | Partial<{ pathname: string; search: string; hash: string }>;
+ replace?: boolean;
+ state?: any;
+ reloadDocument?: boolean;
+}): React.ReactElement;
+```
+
+示例：
+
+```tsx
+import { Link } from 'umi';
+
+function IndexPage({ user }) {
+ return {user.name};
+}
+```
+
+`` 支持相对路径跳转；`` 不做路由跳转，等同于 `` 的跳转行为。
+
+若开启了 `prefetch` 则当用户将鼠标放到该组件上方时，Umi 就会自动开始进行跳转路由的组件 js 文件和数据预加载。
+
+### matchPath
+
+`matchPath` 可以将给定的路径以及一个已知的路由格式进行匹配，并且返回匹配结果。
+
+类型定义如下：
+
+```ts
+declare function matchPath(
+ pattern: PathPattern | string,
+ pathname: string
+): PathMatch | null;
+interface PathMatch {
+ params: Params;
+ pathname: string;
+ pattern: PathPattern;
+}
+interface PathPattern {
+ path: string;
+ caseSensitive?: boolean;
+ end?: boolean;
+}
+```
+
+示例：
+```ts
+import { matchPath } from 'umi';
+const match = matchPath(
+ { path: "/users/:id" },
+ "/users/123",
+);
+// {
+// "params": { "id": "123" },
+// "pathname": "/users/123",
+// "pathnameBase": "/users/123",
+// "pattern": { "path": "/users/:id" }
+// }
+```
+### matchRoutes
+
+`matchRoutes` 可以将给定的路径以及多个可能的路由选择进行匹配，并且返回匹配结果。
+
+类型定义如下：
+
+```ts
+declare function matchRoutes(
+ routes: RouteObject[],
+ location: Partial | string,
+ basename?: string
+): RouteMatch[] | null;
+interface RouteMatch {
+ params: Params;
+ pathname: string;
+ route: RouteObject;
+}
+```
+
+示例：
+
+```ts
+import { matchRoutes } from 'umi';
+const match = matchRoutes(
+ [
+ {
+ path: "/users/:id",
+ },
+ {
+ path: "/users/:id/posts/:postId",
+ },
+ ],
+ "/users/123/posts/456",
+);
+// [
+// {
+// "params": {
+// "id": "123",
+// "postId": "456"
+// },
+// "pathname": "/users/123/posts/456",
+// "pathnameBase": "/users/123/posts/456",
+// "route": {
+// "path": "/users/:id/posts/:postId"
+// }
+// }
+// ]
+```
+
+### NavLink
+
+`` 是 `` 的特殊形态，他知道当前是否为路由激活状态。通常在导航菜单、面包屑、Tabs 中会使用，用于显示当前的选中状态。
+
+类型定义如下：
+
+```ts
+declare function NavLink(props: LinkProps & {
+ caseSensitive?: boolean;
+ children?: React.ReactNode | ((props: { isActive: boolean }) => React.ReactNode);
+ className?: string | ((props: { isActive: boolean }) => string | undefined);
+ end?: boolean;
+ style?: React.CSSProperties | ((props: { isActive: boolean }) => string | React.CSSProperties);
+}): React.ReactElement;
+```
+
+下方示例分别用了 style、className 和 children 来渲染 active 状态。
+
+```ts
+import { NavLink } from 'umi';
+
+function Navs() {
+ return ` 用于渲染父路由中渲染子路由。如果父路由被严格匹配，会渲染子路由中的 index 路由（如有）。
+
+类型定义如下：
+
+```ts
+interface OutletProps {
+ context?: unknown;
+}
+declare function Outlet(
+ props: OutletProps
+): React.ReactElement | null;
+```
+
+示例：
+
+```ts
+import { Outlet } from 'umi';
+
+function Dashboard() {
+ return (
+ | string,
+ fromPathname?: string
+): {
+ pathname: string;
+ search: string;
+ hash: string;
+};
+```
+
+示例：
+
+```ts
+// 同级相对跳转，返回 { pathname: '/parent/child', search: '', hash: '' }
+resolvePath('child', '/parent');
+resolvePath('./child', '/parent');
+resolvePath('', '/parent/child');
+resolvePath('.', '/parent/child');
+
+// 祖先层级相对跳转，返回 { pathname: '/parent/sibling', search: '', hash: '' }
+resolvePath('../sibling', '/parent/child');
+resolvePath('../../parent/sibling', '/other/child');
+
+// 绝对跳转，返回 { pathname: '/target', search: '', hash: '' }
+resolvePath('/target', '/parent');
+resolvePath('/target', '/parent/child');
+
+// 携带 search 和 hash 跳转，返回 { pathname: '/params', search: '?a=b', hash: '#c' }
+resolvePath('/params?a=b#c', '/prev');
+```
+
+### terminal
+
+`terminal` 用于在开发阶段在浏览器向 node 终端输出日志的工具。
+
+示例：
+```ts
+import {terminal} from 'umi';
+// 下面三条命令会在 umi 启动终端上打出用不同颜色代表的日志
+terminal.log('i am log level');
+terminal.warn('i am warn level');
+terminal.error('i am error level');
+```
+注意 `terminal` 只在环境变量 `NODE_ENV` 非 `production` 时生效；在 Umi 的构建产物中对应的日志调用函数不会有任何作用，所以可以不必删除调用 `terminal` 的代码。
+
+### useAppData
+
+`useAppData` 返回全局的应用数据。
+
+类型定义如下：
+
+```ts
+declare function useAppData(): {
+ routes: Record;
+ routeComponents: Record>;
+ clientRoutes: ClientRoute[];
+ pluginManager: any;
+ rootElement: string;
+ basename: string;
+ clientLoaderData: { [routeKey: string]: any };
+ preloadRoute: (to: string) => void;
+};
+```
+注意：此处 API 可能还会调整。
+
+### useLocation
+
+`useLocation` 返回当前 location 对象。
+
+类型定义如下：
+
+```ts
+declare function useLocation(): {
+ pathname: string;
+ search: string;
+ state: unknown;
+ key: Key;
+};
+```
+
+一个场景是在 location change 时做一些 side effect 操作，比如 page view 统计。
+
+```ts
+import { useLocation } from 'umi';
+
+function App() {
+ const location = useLocation();
+ React.useEffect(() => {
+ ga('send', 'pageview');
+ }, [location]);
+ // ...
+}
+```
+
+### useMatch
+
+`useMatch` 返回传入 path 的匹配信息；如果匹配失败将返回 `null`
+
+类型定义如下：
+
+```ts
+declare function useMatch(pattern: {
+ path: string;
+ caseSensitive?: boolean;
+ end?: boolean;
+} | string): {
+ params: Record;
+ pathname: string;
+ pattern: {
+ path: string;
+ caseSensitive?: boolean;
+ end?: boolean;
+ };
+};
+```
+
+示例：
+```tsx
+import { useMatch } from 'umi';
+
+// when url = '/events/12'
+const match = useMatch('/events/:eventId');
+console.log(match?.pathname, match?.params.eventId);
+// '/events/12 12'
+```
+
+### useNavigate
+
+`useNavigate` 钩子函数返回一个可以控制跳转的函数；比如可以用在提交完表单后跳转到其他页面。
+
+```ts
+declare function useNavigate(): NavigateFunction;
+
+interface NavigateFunction {
+ (
+ to: To,
+ options?: { replace?: boolean; state?: any }
+ ): void;
+ (delta: number): void;
+}
+```
+
+示例：
+
+* 跳转路径
+```ts
+import { useNavigate } from 'umi';
+
+let navigate = useNavigate();
+navigate("../success", { replace: true });
+```
+
+* 返回上一页
+```ts
+import { useNavigate } from 'umi';
+
+let navigate = useNavigate();
+navigate(-1);
+```
+
+### useOutlet
+
+`useOutlet` 返回当前匹配的子路由元素，`` 内部使用的就是此 hook 。
+
+类型定义如下：
+```ts
+declare function useOutlet(): React.ReactElement | null;
+```
+
+示例：
+```ts
+import { useOutlet } from 'umi';
+
+const Layout = ()=>{
+ const outlet = useOutlet()
+
+ return (): Context;
+```
+
+示例：
+```ts
+import { useOutletContext, Outlet } from 'umi';
+
+const Layout = () => {
+ return >;
+```
+
+示例：
+
+```ts
+import { useParams } from 'umi';
+
+// 假设有路由配置 user/:uId/repo/:rId
+// 当前路径 user/abc/repo/def
+const params = useParams()
+/* params
+{ uId: 'abc', rId: 'def'}
+*/
+```
+
+### useResolvedPath
+
+`useResolvedPath` 根据当前路径将目标地址解析出完整的路由信息。
+
+类型定义如下：
+```ts
+declare function useResolvedPath(to: To): Path;
+```
+
+示例：
+
+```ts
+import { useResolvedPath } from 'umi';
+
+const path = useResolvedPath('docs')
+/* path
+{ pathname: '/a/new/page/docs', search: '', hash: '' }
+*/
+```
+
+### useRouteData
+
+`useRouteData` 返回当前匹配路由的数据的钩子函数。
+
+类型定义如下：
+
+```ts
+declare function useRouteData(): {
+ route: Route;
+};
+```
+注意：此处 API 可能还会调整。
+
+示例：
+```ts
+import { useRouteData } from 'umi';
+
+const route = useRouteData();
+/* route
+{
+ route: {
+ path: 'a/page',
+ id: 'a/page/index',
+ parentId: '@@/global-layout',
+ file: 'a/page/index.tsx'
+ }
+}
+*/
+```
+
+### useRoutes
+
+`useRoutes` 渲染路由的钩子函数，传入路由配置和可选参数 `location`, 即可得到渲染结果；如果没有匹配的路由，结果为 `null`。
+
+类型定义如下：
+```ts
+declare function useRoutes(
+ routes: RouteObject[],
+ location?: Partial | string;
+): React.ReactElement | null;
+```
+
+示例：
+
+```ts
+import * as React from "react";
+import { useRoutes } from "umi";
+
+function App() {
+ let element = useRoutes([
+ {
+ path: "/",
+ element:
+ | URLSearchParams;
+```
+
+示例：
+```ts
+import React from 'react';
+import { useSearchParams } from 'umi';
+
+function App() {
+ let [searchParams, setSearchParams] = useSearchParams();
+ function handleSubmit(event) {
+ event.preventDefault();
+ setSearchParams(serializeFormQuery(event.target));
+ }
+ return ;
+}
+```
+
+### withRouter
+
+`withRouter` 参考 [react-router faq](https://reactrouter.com/docs/en/v6/getting-started/faq#what-happened-to-withrouter-i-need-it) 实现的版本, 仅实现了部分能力, 请参考类型定义按需使用, 建议迁移到 React Hook API。
+
+类型定义如下:
+
+```ts
+export interface RouteComponentProps> {
+ history: {
+ back: () => void;
+ goBack: () => void;
+ location: ReturnType;
+ push: (url: string, state?: any) => void;
+ };
+ location: ReturnType;
+ match: {
+ params: T;
+ };
+ params: T;
+ navigate: ReturnType;
+}
+```
+
+示例：
+```tsx
+import React from 'react';
+import { withRouter } from 'umi';
+
+class HelloWorld extends React.Component {
+ render() {
+ return (
+ [options]
@@ -31,15 +33,15 @@ Commands:
generate generate code snippets quickly
g generate code snippets quickly
-Run `umi help ` for more information of specific commands.
+Run `umi help ` for more information on specific commands.
Visit https://umijs.org/ to learn more about Umi.
```
-> 为方便查找，以下命令通过字母排序。
+> For easier searching, the following commands are sorted alphabetically.
## build
-构建项目，适用于生产环境的部署。
+Builds the project, suitable for production deployment.
```bash
$ umi build
@@ -47,9 +49,9 @@ $ umi build
## config
-通过命令行快速查看和修改配置。
+Quickly view and modify configurations through the command line.
-查看配置，可以用 `list` 或 `get`。
+To view configurations, you can use `list` or `get`.
```bash
$ umi config list
@@ -60,7 +62,7 @@ $ umi config get mfsu
- [key: externals] { esbuild: true }
```
-修改配置，可以用 `set` 或 `remove`。
+To modify configurations, you can use `set` or `remove`.
```bash
$ umi config set polyfill false
@@ -72,7 +74,7 @@ remove config:polyfill on /private/tmp/sorrycc-wsYpty/.umirc.ts
## dev
-启动本地开发服务器，进行项目的开发与调试。
+Starts the local development server for project development and debugging.
```bash
$ umi dev
@@ -81,36 +83,36 @@ $ umi dev
║ > Local: https://127.0.0.1:8001 ║
ready - ║ > Network: https://192.168.1.1:8001 ║
║ ║
- ║ Now you can open browser with the above addresses👆 ║
+ ║ Now you can open the browser with the above addresses👆 ║
╚═════════════════════════════════════════════════════╝
event - compiled successfully in 1051 ms (416 modules)
```
## generate
-用于增量生成文件或启用功能，命令行别名是 `g`。
+Used to incrementally generate files or enable features. The command-line alias is `g`.
-不加任何参数时会给交互式的生成器选择。
+When no parameters are added, an interactive generator selection will be provided.
```bash
$ umi g
-# 或
+# Or
$ umi generate
-? Pick generator type › - Use arrow-keys. Return to submit.
+? Pick generator type › - Use arrow keys. Return to submit.
❯ Create Pages -- Create a umi page by page name
Enable Prettier -- Enable Prettier
```
-也可以指定参数。
+You can also specify parameters.
```bash
-# 生成路由文件
+# Generate a route file
$ umi g page index --typescript --less
```
## help
-查看帮助。
+Displays help information.
```bash
$ umi help
@@ -127,11 +129,11 @@ Commands:
plugin inspect umi plugins
generate generate code snippets quickly
-Run `umi help ` for more information of specific commands.
+Run `umi help ` for more information on specific commands.
Visit https://umijs.org/ to learn more about Umi.
```
-也可指定命令，查看特定命令的详细帮助。
+You can also specify a command to see detailed help for a specific command.
```bash
$ umi help build
@@ -150,27 +152,26 @@ Details:
## lint
-用于检查及修正代码是否符合规则。
+Used to check and correct whether the code complies with the rules.
```bash
$ umi lint
Usage: umi lint
- 支持只校验 js、ts、tsx、jsx 类型文件： umi lint --eslint-only
-
- 支持只校验 css、less 等样式文件： umi lint --stylelint-only
+ Supports checking only js, ts, tsx, jsx type files: umi lint --eslint-only
- 支持校验 cssinjs 模式校验： umi lint --stylelint-only --cssinjs
+ Supports checking only style files like css, less: umi lint --stylelint-only
- 修正代码： --fix
+ Supports checking css-in-js mode: umi lint --stylelint-only --cssinjs
+ Fix code issues: --fix
```
## plugin
-插件相关操作，目前只支持 `list` 子命令。
+Plugin-related operations, currently only supports the `list` sub-command.
-列出所有插件。
+List all plugins.
```bash
$ umi plugin list
@@ -189,29 +190,29 @@ $ umi plugin list
## preview
-`umi preview` 命令会在本地启动一个静态 Web 服务器，将 dist 文件夹运行在 http://127.0.0.1:4172, 用于预览构建后产物, 支持 proxy、mock 等设置。
+The `umi preview` command starts a local static web server that runs the `dist` folder at http://127.0.0.1:4172. This is used to preview the built artifacts and supports settings like proxy and mock.
-你可以通过 `--port` 参数来配置服务的运行端口。
+You can configure the server's port using the `--port` parameter.
```bash
$ umi preview --port 9527
```
-现在 `preview` 命令会将服务器运行在 http://127.0.0.1:9527.
+Now the `preview` command will run the server at http://127.0.0.1:9527.
-通过 `--host` 参数来指定 配置服务运行的 hostname。
+You can use the `--host` parameter to specify the hostname for the service to run.
-以下用户配置在 `preview` 时也会生效
+The following user configurations will also take effect during `preview`:
-* [https](./config#https)
-* [proxy](../guides/proxy)
-* [mock](../guides/mock)
+- [https](./config#https)
+- [proxy](../guides/proxy)
+- [mock](../guides/mock)
-注意 `dist` 目录会随着配置 `outputPath` 的变更而变更。
+Note that the `dist` directory will change with the change in the `outputPath` configuration.
## run
-`umi run` 命令可以让你像 node 运行 js 一样来运行 TypeScript 和 ESM 文件。你可以搭配 [zx](https://github.com/google/zx) 来更好的使用脚本命令。
+The `umi run` command allows you to run TypeScript and ESM files like you would run JavaScript using Node. You can also use [zx](https://github.com/google/zx) to better utilize script commands.
```bash
$ umi run ./script.ts
@@ -219,9 +220,9 @@ $ umi run ./script.ts
## setup
-初始化项目，会做临时文件的生成等操作。通常在 package.json 的 `scripts.postinstall` 里设置。
+Initializes the project by performing operations like generating temporary files. Usually set in `scripts.postinstall` in `package.json`.
-```bash
+```json
{
"scripts": { "postinstall": "umi setup" }
}
@@ -229,7 +230,7 @@ $ umi run ./script.ts
## deadcode
-用于查找 src 目录下未被引用的文件，并在根目录输出文件。
+Used to find unused files in the `src` directory and output them to the root directory.
```bash
$ umi deadcode
@@ -241,14 +242,13 @@ $ umi deadcode
## mfsu
-`umi mfsu` 命令可以查看 MFSU 依赖信息、重新构建 MFSU 依赖和清除 MFSU 依赖。
-
+The `umi mfsu` command can be used to view MFSU dependency information, rebuild MFSU dependencies, and clear MFSU dependencies.
-```bash title="获取 MFSU 命令帮忙"
+```bash title="Get MFSU Command Help"
$ umi mfsu
```
-```bash title="获取 MFSU 依赖列表"
+```bash title="Get MFSU Dependency List"
$ umi mfsu ls
warning@4.0.3
regenerator-runtime/runtime.js@0.13.11
@@ -263,7 +263,7 @@ lodash/concat@4.17.21
...
```
-```bash title="重新构建 MFSU 依赖"
+```bash title="Rebuild MFSU Dependencies"
$ umi mfsu build
info - Preparing...
info - MFSU eager strategy enabled
@@ -273,18 +273,18 @@ info - [MFSU] buildDeps since cacheDependency has changed
info - [plugin: @umijs/preset-umi/dist/commands/mfsu/mfsu] [MFSU][eager] build success
```
-```bash title="清除 MFSU 依赖"
-$ # 删除依赖信息列表
+```bash title="Clear MFSU Dependencies"
+$ # Remove dependency information list
$ umi mfsu remove
-$ # 删除依赖信息列表和产物文件
+$ # Remove both dependency information list and artifact files
$ umi mfsu remove --all
```
## verifyCommit
-验证 commit message 信息，通常和 [husky](https://github.com/typicode/husky) 搭配使用。
+Verifies commit message information, usually used in conjunction with [husky](https://github.com/typicode/husky).
-比如在 `.husky/commit-msg` 做如下配置，
+For example, configure the `.husky/commit-msg` as follows,
```bash
#!/bin/sh
@@ -295,7 +295,7 @@ npx --no-install umi verify-commit $1
## version
-查看 `umi` 版本，等同于 `umi -v`。
+Displays the `umi` version, equivalent to `umi -v`.
```bash
$ umi version
diff --git a/docs/docs/api/commands.zh-CN.md b/docs/docs/api/commands.zh-CN.md
new file mode 100644
index 000000000000..61ea8ceddabf
--- /dev/null
+++ b/docs/docs/api/commands.zh-CN.md
@@ -0,0 +1,304 @@
+# 命令行
+
+umi 提供了很多内置的命令行用于启动，构建项目，另外还有一些辅助开发的命令，如生成器等。
+
+要获取可用的命令列表，你可以在项目目录中运行 help 命令：
+
+```bash
+umi help
+```
+
+你应该能看到类似如下的日志：
+
+```bash
+Usage: umi [options]
+
+Commands:
+
+ build build app for production
+ config umi config cli
+ dev dev server for development
+ help show commands help
+ lint lint source code using eslint and stylelint
+ setup setup project
+ deadcode check dead code
+ version show umi version
+ v show umi version
+ plugin inspect umi plugins
+ verify-commit verify the commit message, which is usually used with husky.
+ preview locally preview production build
+ run run the script commands, support for ts and zx
+ generate generate code snippets quickly
+ g generate code snippets quickly
+
+Run `umi help ` for more information of specific commands.
+Visit https://umijs.org/ to learn more about Umi.
+```
+
+> 为方便查找，以下命令通过字母排序。
+
+## build
+
+构建项目，适用于生产环境的部署。
+
+```bash
+$ umi build
+```
+
+## config
+
+通过命令行快速查看和修改配置。
+
+查看配置，可以用 `list` 或 `get`。
+
+```bash
+$ umi config list
+ - [key: polyfill] false
+ - [key: externals] { esbuild: true }
+
+$ umi config get mfsu
+ - [key: externals] { esbuild: true }
+```
+
+修改配置，可以用 `set` 或 `remove`。
+
+```bash
+$ umi config set polyfill false
+set config:polyfill on /private/tmp/sorrycc-wsYpty/.umirc.ts
+
+$ umi config remove polyfill
+remove config:polyfill on /private/tmp/sorrycc-wsYpty/.umirc.ts
+```
+
+## dev
+
+启动本地开发服务器，进行项目的开发与调试。
+
+```bash
+$ umi dev
+ ╔═════════════════════════════════════════════════════╗
+ ║ App listening at: ║
+ ║ > Local: https://127.0.0.1:8001 ║
+ready - ║ > Network: https://192.168.1.1:8001 ║
+ ║ ║
+ ║ Now you can open browser with the above addresses👆 ║
+ ╚═════════════════════════════════════════════════════╝
+event - compiled successfully in 1051 ms (416 modules)
+```
+
+## generate
+
+用于增量生成文件或启用功能，命令行别名是 `g`。
+
+不加任何参数时会给交互式的生成器选择。
+
+```bash
+$ umi g
+# 或
+$ umi generate
+? Pick generator type › - Use arrow-keys. Return to submit.
+❯ Create Pages -- Create a umi page by page name
+ Enable Prettier -- Enable Prettier
+```
+
+也可以指定参数。
+
+```bash
+# 生成路由文件
+$ umi g page index --typescript --less
+```
+
+## help
+
+查看帮助。
+
+```bash
+$ umi help
+Usage: umi [options]
+
+Commands:
+
+ build build app for production
+ config umi config cli
+ dev dev server for development
+ help show commands help
+ setup setup project
+ version show umi version
+ plugin inspect umi plugins
+ generate generate code snippets quickly
+
+Run `umi help ` for more information of specific commands.
+Visit https://umijs.org/ to learn more about Umi.
+```
+
+也可指定命令，查看特定命令的详细帮助。
+
+```bash
+$ umi help build
+Usage: umi build [options]
+build app for production.
+
+Details:
+ umi build
+
+ # build without compression
+ COMPRESS=none umi build
+
+ # clean and build
+ umi build --clean
+```
+
+## lint
+
+用于检查及修正代码是否符合规则。
+
+```bash
+$ umi lint
+Usage: umi lint
+
+ 支持只校验 js、ts、tsx、jsx 类型文件： umi lint --eslint-only
+
+ 支持只校验 css、less 等样式文件： umi lint --stylelint-only
+
+ 支持校验 cssinjs 模式校验： umi lint --stylelint-only --cssinjs
+
+ 修正代码： --fix
+
+```
+
+## plugin
+
+插件相关操作，目前只支持 `list` 子命令。
+
+列出所有插件。
+
+```bash
+$ umi plugin list
+- @umijs/core/dist/service/servicePlugin
+- @umijs/preset-umi (from preset)
+- @umijs/preset-umi/dist/registerMethods (from preset)
+- @umijs/preset-umi/dist/features/appData/appData (from preset)
+- @umijs/preset-umi/dist/features/check/check (from preset)
+- @umijs/preset-umi/dist/features/configPlugins/configPlugins (from preset)
+- virtual: config-styles
+- virtual: config-scripts
+- virtual: config-routes
+- virtual: config-plugins
+...
+```
+
+## preview
+
+`umi preview` 命令会在本地启动一个静态 Web 服务器，将 dist 文件夹运行在 http://127.0.0.1:4172, 用于预览构建后产物, 支持 proxy、mock 等设置。
+
+你可以通过 `--port` 参数来配置服务的运行端口。
+
+```bash
+$ umi preview --port 9527
+```
+
+现在 `preview` 命令会将服务器运行在 http://127.0.0.1:9527.
+
+通过 `--host` 参数来指定 配置服务运行的 hostname。
+
+以下用户配置在 `preview` 时也会生效
+
+* [https](./config#https)
+* [proxy](../guides/proxy)
+* [mock](../guides/mock)
+
+注意 `dist` 目录会随着配置 `outputPath` 的变更而变更。
+
+## run
+
+`umi run` 命令可以让你像 node 运行 js 一样来运行 TypeScript 和 ESM 文件。你可以搭配 [zx](https://github.com/google/zx) 来更好的使用脚本命令。
+
+```bash
+$ umi run ./script.ts
+```
+
+## setup
+
+初始化项目，会做临时文件的生成等操作。通常在 package.json 的 `scripts.postinstall` 里设置。
+
+```bash
+{
+ "scripts": { "postinstall": "umi setup" }
+}
+```
+
+## deadcode
+
+用于查找 src 目录下未被引用的文件，并在根目录输出文件。
+
+```bash
+$ umi deadcode
+- Preparing...
+- begin check deadCode
+- write file /examples/umi-run/DeadCodeList-{timeStamp}.txt
+- check dead code end, please be careful if you want to remove them
+```
+
+## mfsu
+
+`umi mfsu` 命令可以查看 MFSU 依赖信息、重新构建 MFSU 依赖和清除 MFSU 依赖。
+
+
+```bash title="获取 MFSU 命令帮忙"
+$ umi mfsu
+```
+
+```bash title="获取 MFSU 依赖列表"
+$ umi mfsu ls
+warning@4.0.3
+regenerator-runtime/runtime.js@0.13.11
+react/jsx-dev-runtime@18.1.0
+react-intl@3.12.1
+react-error-overlay/lib/index.js@6.0.9
+react@18.1.0
+qiankun@2.8.4
+lodash/noop@4.17.21
+lodash/mergeWith@4.17.21
+lodash/concat@4.17.21
+...
+```
+
+```bash title="重新构建 MFSU 依赖"
+$ umi mfsu build
+info - Preparing...
+info - MFSU eager strategy enabled
+warn - Invalidate webpack cache since mfsu cache is missing
+info - [MFSU] buildDeps since cacheDependency has changed
+...
+info - [plugin: @umijs/preset-umi/dist/commands/mfsu/mfsu] [MFSU][eager] build success
+```
+
+```bash title="清除 MFSU 依赖"
+$ # 删除依赖信息列表
+$ umi mfsu remove
+$ # 删除依赖信息列表和产物文件
+$ umi mfsu remove --all
+```
+
+## verifyCommit
+
+验证 commit message 信息，通常和 [husky](https://github.com/typicode/husky) 搭配使用。
+
+比如在 `.husky/commit-msg` 做如下配置，
+
+```bash
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+npx --no-install umi verify-commit $1
+```
+
+## version
+
+查看 `umi` 版本，等同于 `umi -v`。
+
+```bash
+$ umi version
+4.0.0
+```
+
diff --git a/docs/docs/api/config.md b/docs/docs/api/config.md
index 47ea27ffdc7a..b4251566ebdf 100644
--- a/docs/docs/api/config.md
+++ b/docs/docs/api/config.md
@@ -1,16 +1,16 @@
import { Message } from 'umi'
-# 配置
+# Configuration
-对于 umi 中能使用的自定义配置，你可以使用项目根目录的 `.umirc.ts` 文件或者 `config/config.ts`，值得注意的是这两个文件功能一致，仅仅是存在目录不同，2 选 1 ，`.umirc.ts` 文件优先级较高。
+For custom configurations that can be used in umi, you can use the `.umirc.ts` file in the project root directory or `config/config.ts`. It's worth noting that these two files have the same functionality and differ only in directory location, so you can choose either one, but `.umirc.ts` has higher priority.
-> 更多目录相关信息介绍，你可以在[目录结构](../guides/directory-structure)了解。
+> For more information about directory-related details, you can refer to [Directory Structure](../guides/directory-structure).
-umi 的配置文件是一个正常的 node 模块，它在执行 umi [命令行](./commands)的时候使用，并且不包含在浏览器端构建中。
+The configuration file for umi is a regular Node.js module. It is used when executing umi [commands](./commands) and is not included in the browser-side build.
-> 关于浏览器端构建需要用到的一些配置，还有一些在样式表现上产生作用的一些配置，在 umi 中被统一称为“运行时配置”，你可以在[运行时配置](./runtime-config)看到更多关于它的说明。
+> Some configurations required for browser-side builds and other configurations affecting styling are collectively referred to as "runtime configurations" in umi. You can find more information about them in [Runtime Configuration](./runtime-config).
-这里有一个最简单的 umi 配置文件的范例：
+Here's a simple example of a umi configuration file:
```ts
import { defineConfig } from 'umi';
@@ -20,20 +20,20 @@ export default defineConfig({
});
```
-使用 `defineConfig` 包裹配置是为了在书写配置文件的时候，能得到更好的拼写联想支持。如果你不需要，直接 `export default {}` 也可以。
+Using `defineConfig` to wrap the configuration provides better auto-completion support while writing configuration files. If you don't need it, you can also use `export default {}` directly.
-值得关注的是在你使用 umi 的时候，你不需要了解每一个配置的作用。你可以大致的浏览一下以下 umi 支持的所有配置，然后在你需要的时候，再回来查看如何启用和修改你需要的内容。
+It's worth noting that when using umi, you don't need to understand the purpose of every configuration. You can roughly browse through all the configurations supported by umi, and then come back to see how to enable and modify the ones you need when necessary.
-> 为方便查找，以下配置项通过字母排序。
+> For easy reference, the following configuration options are listed in alphabetical order.
## alias
-- 类型：`Record`
-- 默认值：`{}`
+- Type: `Record`
+- Default: `{}`
-配置别名，对 import 语句的 source 做映射。
+Configures aliases for mapping `import` statements to sources.
-比如：
+For example:
```js
{
@@ -43,11 +43,11 @@ export default defineConfig({
}
```
-然后代码里 `import 'foo'` 实际上会 `import '/tmp/to/foo'`。
+Then the code `import 'foo'` will actually import from `/tmp/to/foo`.
-有几个 Tip。
+A couple of tips:
-1、alias 的值最好用绝对路径，尤其是指向依赖时，记得加 `require.resolve`，比如，
+1. It's better to use absolute paths for alias values, especially when referring to dependencies. Remember to use `require.resolve`, for example:
```js
// ⛔
@@ -65,17 +65,17 @@ export default defineConfig({
}
```
-2、如果不需要子路径也被映射，记得加 `$` 后缀，比如
+2. If you don't want sub-paths to be mapped, add a `$` suffix, for example:
```js
-// import 'foo/bar' 会被映射到 import '/tmp/to/foo/bar'
+// import 'foo/bar' will be mapped to import '/tmp/to/foo/bar'
{
alias: {
foo: '/tmp/to/foo',
}
}
-// import 'foo/bar' 还是 import 'foo/bar'，不会被修改
+// import 'foo/bar' will still be import 'foo/bar', not modified
{
alias: {
foo$: '/tmp/to/foo',
@@ -85,55 +85,55 @@ export default defineConfig({
## autoprefixer
-- 类型：`object`
-- 默认值：`{ flexbox: 'no-2009' }`
+- Type: `object`
+- Default: `{ flexbox: 'no-2009' }`
-用于解析 CSS 并使用来自 Can I Use 的值将供应商前缀添加到 CSS 规则。如自动给 CSS 添加 `-webkit-` 前缀。
+Used to parse CSS and add vendor prefixes to CSS rules based on values from Can I Use. For example, automatically adding `-webkit-` prefixes to CSS.
-更多配置，请查阅 [autoprefixer 的配置项](https://github.com/postcss/autoprefixer#options)。
+For more configuration options, please refer to [autoprefixer options](https://github.com/postcss/autoprefixer#options).
## analyze
-- 类型：`object`
-- 默认值：`{}`
+- Type: `object`
+- Default: `{}`
-通过指定 [`ANALYZE`](../guides/env-variables#analyze) 环境变量分析产物构成时，analyzer 插件的具体配置项，见 [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer#options-for-plugin)
+Configures specific options for the analyzer plugin when analyzing the composition of artifacts using the specified [`ANALYZE`](../guides/env-variables#analyze) environment variable. See [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer#options-for-plugin) for detailed configuration options for the analyzer plugin.
-使用 Vite 模式时，除了可以自定义 [rollup-plugin-visualizer](https://github.com/btd/rollup-plugin-visualizer) 的配置， `excludeAssets`、`generateStatsFile`、`openAnalyzer`、`reportFilename`、`reportTitle` 这些选项会自动转换适配。
+When using Vite mode, in addition to customizing the configuration for [rollup-plugin-visualizer](https://github.com/btd/rollup-plugin-visualizer), the options `excludeAssets`, `generateStatsFile`, `openAnalyzer`, `reportFilename`, and `reportTitle` will be automatically adapted.
## base
-- 类型：`string`
-- 默认值：`/`
+- Type: `string`
+- Default: `/`
-要在非根目录下部署 umi 项目时，你可以使用 base 配置。
+When deploying a umi project under a non-root directory, you can use the base configuration.
-base 配置允许你为应用程序设置路由前缀。比如有路由 `/` 和 `/users`，设置 base 为 `/foo/` 后就可通过 `/foo/` 和 `/foo/users` 访问到之前的路由。
+The base configuration allows you to set a route prefix for the application. For example, if you have routes `/` and `/users`, setting the base to `/foo/` would allow accessing the previous routes via `/foo/` and `/foo/users`.
-> 注意：base 配置必须在构建时设置，并且不能在不重新构建的情况下更改，因为该值内联在客户端包中。
+> Note: The base configuration must be set during build and cannot be changed without a rebuild, as this value is inlined in the client bundle.
## cacheDirectoryPath
-- 类型：`string`
-- 默认值：`node_modules/.cache`
+- Type: `string`
+- Default: `node_modules/.cache`
-默认情况下 Umi 会将构建中的一些缓存文件存放在 `node_modules/.cache` 目录下，比如 logger 日志，webpack 缓存，mfsu 缓存等。你可以通过使用 `cacheDirectoryPath` 配置来修改 Umi 的缓存文件目录。
+By default, Umi stores certain cache files from the build in the `node_modules/.cache` directory, such as logger logs, webpack cache, mfsu cache, etc. You can use the `cacheDirectoryPath` configuration to change the cache directory for Umi.
-示例，
+Example:
```js
-// 更改缓存文件路径到 node_modules/.cache1 文件夹
+// Change the cache file path to the folder node_modules/.cache1
cacheDirectoryPath: 'node_modules/.cache1',
```
## chainWebpack
-- 类型：`(memo, args) => void`
-- 默认值：`null`
+- Type: `(memo, args) => void`
+- Default: `null`
-为了扩展 Umi 内置的 webpack 配置，我们提供了用链式编程的方式修改 webpack 配置，基于 webpack-chain，具体 API 可参考 [webpack-api 的文档](https://github.com/mozilla-neutrino/webpack-chain)。
+To extend the built-in webpack configuration of Umi, a chainable approach to modifying the webpack configuration is provided, based on webpack-chain. For specific API details, you can refer to the [webpack-chain documentation](https://github.com/mozilla-neutrino/webpack-chain).
-如下所示：
+For example:
```js
export default {
@@ -143,23 +143,23 @@ export default {
};
```
-该函数具有两个参数：
+This function has two parameters:
-- `memo` 是现有 webpack 配置
-- `args` 包含一些额外信息和辅助对象，目前有 `env` 和 `webpack`。`env` 为当前环境，值为 `development` 或 `production`；`webpack` 为 webpack 对象，可从中获取 webpack 内置插件等
+- `memo` is the existing webpack configuration.
+- `args` contains additional information and helper objects, currently including `env` and `webpack`. `env` is the current environment, with values `development` or `production`; `webpack` is the webpack object from which built-in plugins and more can be obtained.
-用法示例：
+Usage example:
```js
export default {
chainWebpack(memo, { env, webpack }) {
- // 设置 alias
+ // Set alias
memo.resolve.alias.set('foo', '/tmp/to/foo');
- // 添加额外插件
+ // Add additional plugins
memo.plugin('hello').use(Plugin, [...args]);
- // 删除 Umi 内置插件
+ // Remove built-in Umi plugins
memo.plugins.delete('hmr');
},
};
@@ -167,18 +167,18 @@ export default {
## clickToComponent
-- 类型: `{ editor?: string }`
-- 默认值: `false`
+- Type: `{ editor?: string }`
+- Default: `false`
-> 当前仅 React 项目支持。
+> Currently, only React projects are supported.
-开启后，可通过 `Option+Click/Alt+Click` 点击组件跳转至编辑器源码位置，`Option+Right-click/Alt+Right-click` 可以打开上下文，查看父组件。
+When enabled, you can use `Option+Click` or `Alt+Click` to navigate to the source code location of a component in the editor when clicking on a component. You can also use `Option+Right-click` or `Alt+Right-click` to open the context and view the parent component.
-关于参数。`editor` 为编辑器名称，默认为 'vscode'，支持 `vscode` & `vscode-insiders`。
+Regarding parameters, the `editor` parameter is the editor name and is set to 'vscode' by default. Supported options are `vscode` and `vscode-insiders`.
-配置 clickToComponent 的行为，详见 [click-to-component](https://github.com/ericclemmons/click-to-component)。
+You can configure the behavior of `clickToComponent` using the [click-to-component](https://github.com/ericclemmons/click-to-component) documentation.
-示例：
+Example:
```ts
// .umirc.ts
@@ -189,13 +189,13 @@ export default {
## clientLoader
-- 类型: `{}`
-- 默认值: `false`
+- Type: `{}`
+- Default: `false`
-开启后，可以为每个路由声明一个数据加载函数 `clientLoader`，将页面需要的加载数据程序提取到 `clientLoader` 可以让 Umi
-提前在页面组件尚未加载好的时候提前进行数据的加载，避免瀑布流请求的问题，详细介绍请看 [路由数据预加载](../guides/client-loader)。
+When enabled, you can declare a data loading function `clientLoader` for each route. Extracting the data loading program that the page requires to `clientLoader` allows Umi
+to preload data before the page component is fully loaded. This avoids the waterfall request problem. For more details, see [Route Data Preloading](../guides/client-loader).
-示例：
+Example:
```ts
// .umirc.ts
@@ -204,7 +204,7 @@ export default {
};
```
-配置开启后，在路由组件中使用：
+With this configuration enabled, you can use it in the route component:
```jsx
// pages/.../some_page.tsx
@@ -224,47 +224,47 @@ export async function clientLoader() {
## codeSplitting
-- 类型：`{ jsStrategy: 'bigVendors' | 'depPerChunk' | 'granularChunks'; jsStrategyOptions: {} }`
-- 默认值：`null`
+- Type: `{ jsStrategy: 'bigVendors' | 'depPerChunk' | 'granularChunks'; jsStrategyOptions: {} }`
+- Default: `null`
-提供 code splitting 的策略方案。
+Provides strategies for code splitting.
-bigVendors 是大 vendors 方案，会将 async chunk 里的 node_modules 下的文件打包到一起，可以避免重复。同时缺点是，1）单文件的尺寸过大，2）毫无缓存效率可言。
+bigVendors bundles all node_modules files from async chunks together to avoid redundancy. However, it results in large single files without caching efficiency.
-depPerChunk 和 bigVendors 类似，不同的是把依赖按 package name + version 进行拆分，算是解了 bigVendors 的尺寸和缓存效率问题。但同时带来的潜在问题是，可能导致请求较多。我的理解是，对于非大型项目来说其实还好，因为，1）单个页面的请求不会包含非常多的依赖，2）基于 HTTP/2，几十个请求不算问题。但是，对于大型项目或巨型项目来说，需要考虑更合适的方案。
+depPerChunk is similar to `bigVendors` but splits dependencies based on package name and version, addressing the issues of size and cache efficiency. It may increase the number of requests.
-granularChunks 在 bigVendors 和 depPerChunk 之间取了中间值，同时又能在缓存效率上有更好的利用。无特殊场景，建议用 granularChunks 策略。
+granularChunks strikes a balance between `bigVendors` and `depPerChunk`, offering better cache efficiency. For typical scenarios, using `granularChunks` is recommended.
## conventionLayout
-- 类型：`boolean`
-- 默认值：`undefined`
+- Type: `boolean`
+- Default: `undefined`
-`src/layouts/index.[tsx|vue|jsx|js]` 为约定式布局，默认开启。可通过配置 `conventionLayout: false` 关闭该默认行为。
+`src/layouts/index.[tsx|vue|jsx|js]` is the convention for layout. It's enabled by default. You can disable this default behavior by setting `conventionLayout: false`.
## conventionRoutes
-- 类型：`{ base: string; exclude: RegExp[] }`
-- 默认值：`null`
+- Type: `{ base: string; exclude: RegExp[] }`
+- Default: `null`
-修改默认的约定式路由规则，仅在使用 umi 约定式路由时有效，约定式路由也叫文件路由，就是不需要手写配置，文件系统即路由，通过目录和文件及其命名分析出路由配置。
+Modifies the default convention for routing. Only applicable when using umi's convention-based routing, also known as file-based routing, where the file system defines the routing configuration.
-使用约定式路由时，约定 `src/pages` 下所有的 `(j|t)sx?` 文件即路由。
+With convention-based routing, all `(j|t)sx?` files under `src/pages` are treated as routes.
-> 你可以从[约定式路由](../guides/routes#约定式路由)查看更多说明。
+> You can find more explanations in [Convention-Based Routing](../guides/routes#convention-based-routing).
### base
-`base` 用于设置约定的路由的基础路径，默认从 `src/pages` 读取，如果是文档站点可能会需要将其改成 `./docs`；
+`base` is used to set the base path for the conventional routes. By default, it reads from `src/pages`. This might need to be changed to `./docs` for documentation sites, for instance.
### exclude
-你可以使用 `exclude` 配置过滤一些不需要的文件，比如用于过滤 components、models 等。
+You can use `exclude` to filter out files that don't need to be treated as routes, e.g., to exclude `components` and `models` directories.
-示例，
+Example:
```js
-// 不识别 components 和 models 目录下的文件为路由
+// Exclude files in the components and models directories from being recognized as routes
conventionRoutes: {
exclude: [/\/components\//, /\/models\//],
}
@@ -272,18 +272,18 @@ conventionRoutes: {
## copy
-- 类型：`Array`
-- 默认值：`[]`
+- Type: `Array`
+- Default: `[]`
-配置要复制到输出目录的文件或文件夹。
+Configures files or directories to be copied to the output directory.
-当配置字符串时，默认拷贝到产物目录，如：
+When specifying a string, the file or directory will be copied to the build output directory. For example:
```ts
copy: ['foo.json', 'src/bar.json']
```
-会产生如下产物的结构：
+This results in the following structure in the output:
```
+ dist
@@ -294,7 +294,7 @@ copy: ['foo.json', 'src/bar.json']
- foo.json
```
-你也可以通过对象配置具体的拷贝位置，其中相对路径的起点为项目根目录：
+You can also use objects to specify specific copy locations, where relative paths are based on the project root:
```ts
copy: [
@@ -303,7 +303,7 @@ copy: [
]
```
-此时将产生如下产物结构：
+This results in the following structure:
```
+ dist
@@ -317,20 +317,20 @@ copy: [
## crossorigin
-- 类型：`{ includes?: string[] }`
-- 默认值：`false`
+- Type: `{ includes?: string[] }`
+- Default: `false`
-配置 script 标签的 crossorigin。如果有声明，会为本地 script 加上 crossorigin="anonymous" 的属性。
+Configures the `crossorigin` attribute of `script` tags. If defined, it adds the `crossorigin="anonymous"` attribute to local scripts.
-关于参数。`includes` 参数可以为额外的非本地 script 标签加上此属性。
+Regarding parameters, the `includes` parameter can be used to add this attribute to additional non-local `script` tags.
-比如：
+For example:
```
crossorigin: {}
```
-然后输出的 HTML 中会有这些变化，
+This will result in the following change in the output HTML:
```diff
-
@@ -341,12 +341,12 @@ crossorigin: {}
## cssMinifier
-- 类型：`string` 可选的值：`esbuild`, `cssnano`, `parcelCSS`, `none`
-- 默认值：`esbuild`
+- Type: `string` Possible values: `esbuild`, `cssnano`, `parcelCSS`, `none`
+- Default: `esbuild`
-配置构建时使用的 CSS 压缩工具; `none` 表示不压缩。
+Configures the CSS minification tool to use during the build; `none` means no minification.
-示例：
+Example:
```js
{
@@ -356,12 +356,12 @@ crossorigin: {}
## cssMinifierOptions
-- 类型：`Object`
-- 默认值：`{}`
+- Type: `Object`
+- Default: `{}`
-`cssMinifier` CSS 压缩工具配置选项。
+Configures options for the `cssMinifier` CSS minification tool.
-示例：
+Example:
```js
{
@@ -373,49 +373,49 @@ crossorigin: {}
}
```
-对应 CSS 压缩的配置请查看对应的文档。
+Refer to the respective CSS minification documentation for the corresponding configuration.
-- [esbuild 参考](https://esbuild.github.io/api/#minify)
-- [cssnano 参考](https://cssnano.co/docs/config-file/)
-- [parcelCSS 参考](https://github.com/parcel-bundler/parcel-css/blob/master/node/index.d.ts)
+- [esbuild reference](https://esbuild.github.io/api/#minify)
+- [cssnano reference](https://cssnano.co/docs/config-file/)
+- [parcelCSS reference](https://github.com/parcel-bundler/parcel-css/blob/master/node/index.d.ts)
## cssLoader
-- 类型：`object`
-- 默认值：`{}`
+- Type: `object`
+- Default: `{}`
-配置 css-loader ，详见 [css-loader > options](https://github.com/webpack-contrib/css-loader#options)
+Configures the `css-loader`, see [css-loader > options](https://github.com/webpack-contrib/css-loader#options).
## cssLoaderModules
-- 类型：`object`
-- 默认值：`{}`
+- Type: `object`
+- Default: `{}`
-配置 css modules 的行为，详见 [css-loader > modules](https://github.com/webpack-contrib/css-loader#modules)。
+Configures the behavior of CSS modules, see [css-loader > modules](https://github.com/webpack-contrib/css-loader#modules).
-如：
+For example:
```ts
cssLoaderModules: {
- // 配置驼峰式使用
+ // Configure to use camelCase
exportLocalsConvention: 'camelCase'
}
```
## deadCode
-- 类型：`{ patterns?: string[]; exclude?: string[]; failOnHint?: boolean; detectUnusedFiles?: boolean; detectUnusedExport?: boolean; context?: string }`
-- 默认值：`false`
+- Type: `{ patterns?: string[]; exclude?: string[]; failOnHint?: boolean; detectUnusedFiles?: boolean; detectUnusedExport?: boolean; context?: string }`
+- Default: `false`
-检测未使用的文件和导出，仅在 build 阶段开启。
+Detects unused files and exports during the build phase. This is enabled only during the build process.
-比如：
+For example:
```
deadCode: {}
```
-然后执行 build，如有发现问题，会打印警告：
+When running the build, if any issues are detected, a warning will be printed:
```
Warning: There are 1 unused files:
@@ -423,19 +423,21 @@ Warning: There are 1 unused files:
Please be careful if you want to remove them (¬º-°)¬.
```
-可配置项：
+Configuration options:
- - `patterns` : 识别代码的范围，如 `['src/pages/**']`
- - `exclude` : 排除检测的范围，如 `['src/pages/utils/**']`
- - `failOnHint` : 检测失败是否终止进程，默认 `false` 不终止
- - `detectUnusedFiles` : 是否检测未使用的文件，默认 `true` 检测
- - `detectUnusedExport` : 是否检测未使用的导出，默认 `true` 检测
- - `context` : 匹配开始的目录，默认为当前项目根目录
+ - `patterns`: Defines the scope of code recognition, e.g., `['src/pages/**']`.
+ - `exclude`: Excludes specific files from detection, e.g., `['src/pages/utils/**']`.
+ - `failOnHint`: Specifies whether the build process should fail if issues are detected. Default is `false` (no failure).
+ - `detectUnusedFiles`: Specifies whether to detect unused files. Default is `true`.
+ - `detectUnusedExport`: Specifies whether to detect unused exports. Default is `true`.
+ - `context`: Specifies the starting directory for matching. Defaults to the project root directory.
## define
-- 类型：`Record`
-- 默认值： 如下
+- Type:
+
+ `Record`
+- Default: As shown below
```
{
@@ -445,31 +447,31 @@ Warning: There are 1 unused files:
}
```
-基于[define-plugin 插件](https://webpack.js.org/plugins/define-plugin/)设置代码中的可用变量。
+Sets available variables in the code based on the [define-plugin](https://webpack.js.org/plugins/define-plugin/) plugin.
-1. 属性值会经过一次 `JSON.stringify` 转换。
-2. key 值的替换是通过语法形式来匹配的，比如配置了 `{'a.b.c': 'abcValue'}` 是无法替换代码中的 `a.b?.c` 的
+1. The property values will undergo a `JSON.stringify` transformation.
+2. The key replacement is done using syntax, so configuring `{'a.b.c': 'abcValue'}` won't replace `a.b?.c` in the code.
-比如，
+For example:
```
define: { FOO: 'bar' }
```
-然后代码里的 `console.log(hello, FOO)` 会被编译成 `console.log(hello, 'bar')`。
+This will compile `console.log(hello, FOO)` in the code to `console.log(hello, 'bar')`.
-当你在 ts 的项目中使用这些变量时，你需要在 typings 文件中声明变量类型，以支持 ts 类型提示，比如：
+When using these variables in a TypeScript project, you need to declare their types in a typings file to support type hinting. For example:
-如果你的 typings 文件是全局的：
+If your typings file is global:
```ts
// typings.d.ts
declare const FOO: string;
```
-如果你的 typings 文件是非全局的（包含了 import/export）：
+If your typings file is not global (includes import/export):
```ts
// typings.d.ts
@@ -481,80 +483,80 @@ declare global {
```
## devtool
-- 类型：`string`
-- 默认值：dev 时默认 `cheap-module-source-map`，build 时候默认无 sourcemap
+- Type: `string`
+- Default: For dev, default is `cheap-module-source-map`. For build, default is no sourcemap.
-设置 sourcemap 生成方式。
+Set the source map generation method.
-常见可选值有：
+Common options:
-- `eval`，最快的类型，缺点是不支持低版本浏览器
-- `source-map`，最慢但最全的类型
+- `eval`, the fastest type, but not supported by older browsers.
+- `source-map`, the slowest but most comprehensive type.
-示例，
+Example,
```js
-// 关闭 dev 阶段的 sourcemap 生成
+// Turn off source map generation during development
devtool: false;
-// 只设置 dev 阶段的 sourcemap
+// Only set source map for development
devtool: process.env.NODE_ENV === 'development' ? 'eval' : false;
```
## classPropertiesLoose
-- 类型：`object`
-- 默认值：`{}`
+- Type: `object`
+- Default: `{}`
-设置 babel class-properties 启用 loose
+Enable loose mode for Babel class properties.
## esbuildMinifyIIFE
-- 类型：`boolean`
-- 默认值：`false`
+- Type: `boolean`
+- Default: `false`
-修复 esbuild 压缩器自动引入的全局变量导致的命名冲突问题。
+Resolve naming conflicts caused by automatically injected global variables by the esbuild minifier.
-由于 Umi 4 默认使用 esbuild 作为压缩器，该压缩器会自动注入全局变量作为 polyfill ，这可能会引发 异步块全局变量冲突、 qiankun 子应用和主应用全局变量冲突 等问题，通过打开该选项或切换 [`jsMinifier`](#jsminifier-webpack) 压缩器可解决此问题。
+Umi 4 defaults to using esbuild as the minifier, which injects global variables as polyfills. This can lead to issues such as conflicts with global variables in asynchronous blocks, conflicts between qiankun sub-apps and main apps, etc. Enabling this option or switching the [`jsMinifier`](#jsminifier-webpack) minifier can solve these problems.
-更多信息详见 [vite#7948](https://github.com/vitejs/vite/pull/7948) 。
+For more information, see [vite#7948](https://github.com/vitejs/vite/pull/7948).
-示例,
+Example,
```ts
esbuildMinifyIIFE: true
```
## externals
-- 类型：`Record | Function`
-- 默认值：`{}`
+- Type: `Record | Function`
+- Default: `{}`
-设置哪些模块不打包，转而通过 `
```
-如果需要额外属性，切换到对象格式，比如，
+If you need additional attributes, switch to the object format. For example,
```js
headScripts: [
{ src: '/foo.js', defer: true },
- { content: `alert('你好');`, charset: 'utf-8' },
+ { content: `alert('Hello');`, charset: 'utf-8' },
],
```
## helmet
-- 类型：`boolean`
-- 默认值：`true`
+- Type: `boolean`
+- Default: `true`
-配置 `react-helmet-async` 的集成，当设置为 `false` 时，不会集成 `react-helmet-async`，此时无法从框架中 `import { Helmet }` 使用，同时构建产物也会减少[相应的尺寸](https://bundlephobia.com/package/react-helmet-async)。
+Configure integration with `react-helmet-async`. When set to `false`, `react-helmet-async` integration
+
+ is disabled. This means you cannot use `import { Helmet }` from the framework, and the resulting build size will be reduced as well.
## history
-- 类型：`{ type: 'browser' | 'hash' | 'memory' }`
-- 默认值：`{ type: 'browser' }`
+- Type: `{ type: 'browser' | 'hash' | 'memory' }`
+- Default: `{ type: 'browser' }`
-设置路由 history 类型。
+Set the routing history type.
## historyWithQuery
-- 类型：`{}`
-- 默认值：`false`
+- Type: `{}`
+- Default: `false`
-让 history 带上 query。除了通过 `useNavigate` 进行的跳转场景，此时还需自行处理 query。
+Include query parameters in the history. Apart from navigation using `useNavigate`, you also need to manually handle query parameters in this scenario.
## https
-- 类型：`{ cert: string; key: string; hosts: string[]; http2?: boolean }`
-- 默认值：`{ hosts: ['127.0.0.1', 'localhost'] }`
+- Type: `{ cert: string; key: string; hosts: string[]; http2?: boolean }`
+- Default: `{ hosts: ['127.0.0.1', 'localhost'] }`
-开启 dev 的 https 模式，Umi 4 默认使用 [`mkcert`](https://github.com/FiloSottile/mkcert) 快捷创建证书，请确保已经安装。
+Enable HTTPS mode during development. Umi 4 uses [`mkcert`](https://github.com/FiloSottile/mkcert) for quickly creating certificates. Make sure it is installed.
-关于参数。
+Parameters:
-- `cert` 和 `key` 分别用于指定 cert 和 key 文件。
-- `hosts` 用于指定要支持 https 访问的 host，默认是 `['127.0.0.1', 'localhost']`。
-- `http2` 用于指定是否使用 HTTP 2.0 协议，默认是 true（使用 HTTP 2.0 在 Chrome 或 Edge 浏览器中中有偶然出现 `ERR_HTTP2_PROTOCOL_ERRO`报错，如有遇到，建议配置为 false）。
+- `cert` and `key` are used to specify certificate and key files.
+- `hosts` specifies the hosts that support HTTPS access. Default is `['127.0.0.1', 'localhost']`.
+- `http2` specifies whether to use HTTP 2.0 protocol. Default is true (using HTTP 2.0 in Chrome or Edge browsers might occasionally result in `ERR_HTTP2_PROTOCOL_ERROR` errors; if encountered, consider setting it to false).
-示例，
+Example,
```js
https: {
@@ -771,85 +775,85 @@ https: {
## icons
-- 类型：`{ autoInstall: {}; alias: Record; include: Array; }`
-- 默认值：`false`
+- Type: `{ autoInstall: {}; alias: Record; include: Array; }`
+- Default: `false`
-你就可以通过 umi 导出的 Icon 组件快捷地引用 icon 集或者本地的 icon。
+Quickly reference icon sets or local icons using the Icon component provided by Umi.
-### icon 集使用
+### Using icon sets
-在 umi 配置文件设置，开启 icons 功能，并允许自动安装图标库。
+In the Umi configuration file, enable the icons feature and allow automatic installation of icon collections.
```ts
icons: { autoInstall: {} },
```
-页面使用：
+Usage in pages:
```ts
import { Icon } from 'umi';
}`
-- 默认值：`{ mfName: 'mf', strategy: 'normal' }`
+- Type: `{ esbuild: boolean; mfName: string; cacheDirectory: string; strategy: 'normal' | 'eager'; include?: string[]; chainWebpack: (memo, args) => void; exclude?: Array }`
+- Default: `{ mfName: 'mf', strategy: 'normal' }`
-配置基于 [Module Federation](https://module-federation.github.io/) 的提速功能。
+Configure the performance optimization feature based on [Module Federation](https://module-federation.github.io/).
-关于参数
+Parameters:
-- `esbuild` 配为 `true` 后会让依赖的预编译走 esbuild，从而让首次启动更快，缺点是二次编译不会有物理缓存，稍慢一些；推荐项目依赖比较稳定的项目使用。
-- `mfName` 是此方案的 remote 库的全局变量，默认是 mf，通常在微前端中为了让主应用和子应用不冲突才会进行配置
-- `cacheDirectory` 可以自定义缓存目录，默认是 `node_modules/.cache/mfsu`
-- `chainWebpack` 用链式编程的方式修改 依赖的 webpack 配置，基于 webpack-chain，具体 API 可参考 [webpack-api 的文档](https://github.com/sorrycc/webpack-chain)；
-- `runtimePublicPath` 会让修改 mf 加载文件的 publicPath 为 `window.publicPath`
-- `strategy` 指定 mfsu 编译依赖的时机; `normal` 模式下，采用 babel 编译分析后，构建 Module Federation 远端包；`eager` 模式下采用静态分析的方式，和项目代码同时发起构建。
-- `include` 仅在 `strategy: 'eager' ` 模式下生效， 用于补偿在 eager 模式下，静态分析无法分析到的依赖，例如 `react` 未进入 Module Federation 远端模块可以这样配置 `{ include: [ 'react' ] }`
-- `exclude` 手动排除某些不需要被 MFSU 处理的依赖, 字符串或者正则的形式，比如 `vant` 不希望走 MFSU 处理，可以配置 `{ exclude: [ 'vant' ] }` 匹配逻辑为全词匹配，也可以配置 `{ exclude: [ /vant/ ] }` 只要 `import` 路径中匹配该正则的依赖都不走 MFSU 处理
+- `esbuild`: When set to `true`, it uses esbuild for dependency pre-compilation, making the initial startup faster. The drawback is that there won't be physical caching for subsequent compilations, making them slightly slower. Recommended for projects with relatively stable dependencies.
+- `mfName`: The global variable for remote libraries in this approach. The default is `mf`, and it's usually configured to avoid conflicts between the main app and sub-applications in a micro-frontend setup.
+- `cacheDirectory`: Customize the cache directory. The default is `node_modules/.cache/mfsu`.
+- `chainWebpack`: Use webpack-chain to modify the webpack configuration for dependencies. This function is provided with two arguments, `memo` (the current configuration) and `args` (other arguments). For detailed API reference, see [webpack-chain Documentation](https://github.com/sorrycc/webpack-chain).
+- `runtimePublicPath`: Changes the `publicPath` of the loading files for modules in Module Federation to `window.publicPath`.
+- `strategy`: Specifies when mfsu should build dependencies. In `normal` mode, the dependencies are built based on babel analysis and then used in the Module Federation remote bundle. In `eager` mode, the dependencies are built based on static analysis and are built concurrently with the project code.
+- `include`: Only works in `strategy: 'eager'` mode. It's used to compensate for dependencies that couldn't be statically analyzed in eager mode. For example, if `react` is not included in the remote module, you can configure `{ include: [ 'react' ] }`.
+- `exclude`: Manually exclude certain dependencies that should not be processed by MFSU. It can be a string or a regular expression. For example, `{ exclude: [ 'vant' ] }` will exclude the `vant` library from MFSU processing.
-示例，
+Example,
```js
-// 用 esbuild 做依赖预编译
+// Use esbuild for dependency pre-compilation
mfsu: {
esbuild: true,
}
-// 关闭 mfsu 功能
+// Disable MFSU
mfsu: false;
```
```js
-// webpack 配置修改
+// Modify webpack configuration
mfsu: {
chainWebpack(memo, args) {
- // 添加额外插件
+ // Add additional plugins
memo.plugin('hello').use(Plugin, [...args]);
return memo;
}
}
```
-注意：此功能默认开。配置 `mfsu: false` 关闭。
+Note: This feature is enabled by default. Configure `mfsu: false` to disable it.
## mock
-- 类型：`{ exclude: string[], include: string[] }`
-- 默认值：`{}`
+- Type: `{ exclude: string[], include: string[] }`
+- Default: `{}`
+
+Configure the mock feature.
-配置 mock 功能。
+Parameters:
-关于参数。`exclude` 用于排除不需要的 mock 文件；`include` 用于额外添加 mock 目录之外的 mock 文件。
+- `exclude`: Excludes mock files that are not needed.
+- `include`: Adds mock files outside the mock directory.
-示例，
+Example,
```js
-// 让所有 pages 下的 _mock.ts 文件成为 mock 文件
+// Make all _mock.ts files under pages become mock files
mock: {
include: ['src/pages/**/_mock.ts'],
}
```
-注意：此功能默认开。配置 `mock: false` 关闭。
+Note: This feature is enabled by default. Configure `mock: false` to disable it.
## mountElementId
-- 类型：`string`
-- 默认值：`'root'`
+- Type: `string`
+- Default: `'root'`
-配置 react 组件树渲染到 HTML 中的元素 id。
+Configure the HTML element ID where the React component tree should be rendered.
-示例，
+Example,
```js
mountElementId: 'container'
@@ -1055,74 +1062,74 @@ mountElementId: 'container'
## monorepoRedirect
-- 类型：`{ srcDir?: string[], exclude?: RegExp[], peerDeps?: boolean }`
-- 默认值：`false`
+- Type: `{ srcDir?: string[], exclude?: RegExp[], peerDeps?: boolean }`
+- Default: `false`
-在 monorepo 中使用 Umi 时，你可能需要引入其他子包的组件、工具方法等，通过开启此选项来重定向这些子包的导入到他们的源码位置（默认为 `src` 文件夹），这也可以解决 `MFSU` 场景改动子包不热更新的问题。
+When using Umi within a monorepo, you might need to import components, utility methods, etc., from other sub-packages. You can enable this option to redirect imports from these sub-packages to their source code locations (by default, the `src` folder). This can also solve the issue of non-hot updates in the `MFSU` scenario.
-这种重定向的好处是：支持热更新，无需预构建其他子包即可进行开发。
+The benefit of this redirection is that it supports hot updates, allowing you to develop without pre-building other sub-packages.
-通过配置 `srcDir` 来调整识别源码文件夹的优先位置，通过 `exclude` 来设定不需要重定向的依赖范围。
+Adjust the recognition priority of the source code folder by configuring `srcDir` and set the dependency scope that should not be redirected using `exclude`.
-示例：
+Examples:
```js
-// 默认重定向到子包的 src 文件夹
+// Default redirection to the src folder of the sub-packages
monorepoRedirect: {}
-// 在子包中寻找，优先定向到 libs 文件夹
+// Look within the sub-package and prioritize redirection to the libs folder
monorepoRedirect: {
srcDir: ['libs', 'src'],
}
-// 不重定向 @scope/* 的子包
+// Do not redirect sub-packages under @scope/*
monorepoRedirect: {
exclude: [/^@scope\/.+/],
}
```
-在实际的大型业务 monorepo 中，每个子包的依赖都是从他们的目录开始向上寻找 `node_modules` 并加载的，但在本地开发时，依赖都安装在 `devDependencies` ，和从 npm 上安装表现不一致，所以不可避免会遇到多实例问题。
+In large-scale business monorepos, each sub-package's dependencies are loaded starting from their directories to `node_modules`. However, during local development, dependencies are installed in `devDependencies`, which is inconsistent with installing from npm. As a result, multiple instances of the same dependency can be encountered.
-举个例子，每个子包在本地开发时都需要 `antd` ，在 `devDependencies` 中安装了，也在 `peerDependencies` 中指明了 `antd` ，我们预期该包发布到 npm ，被某个项目安装后， `antd` 是使用的项目本身的依赖，全局唯一，但由于在 monorepo 中，指定在 `devDependencies` 中的依赖必定存在，且子包代码寻找依赖时是从该子包进行的，导致了每个子包都用了自己的 `antd` ，出现了产物中有多份 `antd` 、产物体积增大、消息队列被破坏等情况。
+For example, each sub-package requires `antd` during local development, which is installed in `devDependencies` and also specified in `peerDependencies`. When the package is expected to be installed via npm and used by a project, `antd` should be a project's own dependency, unique globally. However, in a monorepo, dependencies specified in `devDependencies` are always present, and sub-packages search for dependencies from within themselves. This leads to each sub-package using its own instance of `antd`, causing multiple copies of `antd` in the build, increased build size, disruption of message queues, and other issues.
-为了解决这种问题，我们约定：
+To address this problem, we have a convention:
-当打开 `peerDeps` 选项时，所有子包指明的 `peerDependencies` 都会被自动添加 `alias` 重定向唯一化，避免多实例的存在：
+When the `peerDeps` option is enabled, all `peerDependencies` specified in sub-packages are automatically added as `alias` to ensure uniqueness and avoid multiple instances:
```ts
monorepoRedirect: { peerDeps: true }
```
-经过重定向，依赖全局唯一，便可以在开发时保持和在 npm 上安装包后的体验一致。
+With redirection in place, the dependencies are unique globally, and the development experience can be consistent with installing packages from npm.
## mpa
-- 类型：`object`
-- 默认值：`false`
+- Type: `object`
+- Default: `false`
-启用 [mpa 模式](../guides/mpa)。
+Enable the [mpa mode](../guides/mpa).
## outputPath
-- 类型：`string`
-- 默认值：`dist`
+- Type: `string`
+- Default: `dist`
-配置输出路径。
+Configure the output path.
-注意：不允许设定为 src、public、pages、mock、config、locales、models 等约定式功能相关的目录。
+Note: Not allowed to be set to directories related to conventional functionalities like src, public, pages, mock, config, locales, models, etc.
## phantomDependency
-- 类型：`{ exclude: string[] }`
-- 默认值：`false`
+- Type: `{ exclude: string[] }`
+- Default: `false`
-执行幽灵依赖检测。
+Perform phantom dependency detection.
-当使用未在 package.json 中声明的依赖，以及也没有通过 alias 或 externals 进行配置时，会抛错并提醒。
+When using undeclared dependencies in `package.json`, and no configuration is provided through alias or externals, an error will be thrown with a reminder.
-如遇到有需要需做白名单处理，可通过 exclude 配置项实现，exclude 的项是 npm 依赖的包名。
+If whitelist handling is needed, it can be achieved through the `exclude` configuration, where the excluded items are the package names of npm dependencies.
```ts
export default {
@@ -1134,34 +1141,34 @@ export default {
## plugins
-- 类型：`string[]`
-- 默认值：`[]`
+- Type: `string[]`
+- Default: `[]`
-配置额外的 Umi 插件。
+Configure additional Umi plugins.
-数组项为指向插件的路径，可以是 npm 依赖、相对路径或绝对路径。如果是相对路径，则会从项目根目录开始找。
+Items in the array are paths pointing to the plugins, which can be npm dependencies, relative paths, or absolute paths. If it's a relative path, it will be searched from the project's root directory.
-示例，
+Examples:
```js
plugins: [
- // npm 依赖
+ // npm dependency
'umi-plugin-hello',
- // 相对路径
+ // relative path
'./plugin',
- // 绝对路径
+ // absolute path
`${__dirname}/plugin.js`,
],
```
## polyfill
-- 类型：`{ imports: string[] }`
-- 默认值：`{}`
+- Type: `{ imports: string[] }`
+- Default: `{}`
-设置按需引入的 polyfill。默认全量引入。
+Set up on-demand imports of polyfills. Defaults to importing all.
-比如只引入 core-js 的 stable 部分，
+For example, import only the stable part of core-js:
```js
polyfill: {
@@ -1169,7 +1176,7 @@ polyfill: {
}
```
-如果对于性能有更极致的要求，可以考虑按需引入，
+If there's a need for more performance optimization, you can consider importing on-demand:
```js
polyfill: {
@@ -1177,45 +1184,45 @@ polyfill: {
}
```
-注意：此功能默认开。配置 `polyfill: false` 或设置环境变量 `BABEL_POLYFILL=none` 关闭。
+Note: This feature is enabled by default. To disable it, set `polyfill: false` or use the environment variable `BABEL_POLYFILL=none`.
## postcssLoader
-- 类型：`object`
-- 默认值：`{}`
+- Type: `object`
+- Default: `{}`
-设置 [postcss-loader 的配置项](https://github.com/webpack-contrib/postcss-loader#options)。
+Configure options for [postcss-loader](https://github.com/webpack-contrib/postcss-loader#options).
## presets
-- 类型：`string[]`
-- 默认值：`[]`
+- Type: `string[]`
+- Default: `[]`
-配置额外的 Umi 插件集。
+Configure additional Umi plugin sets.
-数组项为指向插件集的路径，可以是 npm 依赖、相对路径或绝对路径。如果是相对路径，则会从项目根目录开始找。
+Items in the array are paths pointing to the plugin sets, which can be npm dependencies, relative paths, or absolute paths. If it's a relative path, it will be searched from the project's root directory.
-示例，
+Examples:
```js
presets: [
- // npm 依赖
+ // npm dependency
'umi-preset-hello',
- // 相对路径
+ // relative path
'./preset',
- // 绝对路径
+ // absolute path
`${__dirname}/preset.js`,
],
```
## proxy
-- 类型：`object`
-- 默认值：`{}`
+- Type: `object`
+- Default: `{}`
-配置代理功能。
+Configure proxy functionality.
-比如，
+For example:
```js
proxy: {
@@ -1227,42 +1234,42 @@ proxy: {
}
```
-然后访问 `/api/users` 就能访问到 http://jsonplaceholder.typicode.com/users 的数据。
+Then, accessing `/api/users` will fetch data from http://jsonplaceholder.typicode.com/users.
-注意：proxy 功能仅在 dev 时有效。
+Note: Proxy functionality only works during development (`dev` mode).
## publicPath
-- 类型：`string`
-- 默认值：`/`
+- Type: `string`
+- Default: `/`
-配置 webpack 的 publicPath。
+Configure webpack's publicPath.
## reactRouter5Compat
-- 类型：`object`
-- 默认值：`false`
+- Type: `object`
+- Default: `false`
-启用 react-router 5 兼容模式。此模式下，路由组件的 props 会包含 location、match、history 和 params 属性，和 react-router 5 的保持一致。
+Enable react-router 5 compatibility mode. In this mode, the route component's props will include `location`, `match`, `history`, and `params` properties, consistent with react-router 5.
-但要注意的是，
+However, note that:
-1. 此模式下会有额外的 re-render
-2. 由于依赖库 history 更新，location 中依旧没有 query 属性
+1. This mode introduces additional re-renders.
+2. Due to the updated dependency library history, the `query` property is not present in the `location`.
## routes
-- 类型：`Route[]`
-- 默认值：`[]`
+- Type: `Route[]`
+- Default: `[]`
-配置路由。更多信息，请查看 [配置路由](../guides/routes#配置路由)
+Configure routes. For more information, see [Configuring Routes](../guides/routes#配置路由).
## routeLoader
-- 类型：`{ moduleType: 'esm' | 'cjs' }`
-- 默认值：`{ moduleType: 'esm' }`
+- Type: `{ moduleType: 'esm' | 'cjs' }`
+- Default: `{ moduleType: 'esm' }`
-配置路由加载方式。moduleType 配置为 'cjs' 会用 `require` 的方式加载路由组件。
+Configure the route loading method. When `moduleType` is configured as 'cjs', route components will be loaded using the `require` method.
```ts
// moduleType: esm
@@ -1274,19 +1281,19 @@ proxy: {
## run
-- 类型：`{ globals: string[] }`
-- 默认值：`null`
+- Type: `{ globals: string[] }`
+- Default: `null`
-run 命令的全局注入配置。添加`['zx/globals']`，在使用`umi run ./script.ts`的时候，umi会自动注入`import 'zx/globals';`，从而省略掉每个脚本都要写`import 'zx/globals';`。
+Global injection configuration for the run command. Adding `['zx/globals']` will automatically inject `import 'zx/globals';` when using `umi run ./script.ts`, eliminating the need to write `import 'zx/globals';` in every script.
## runtimePublicPath
-- 类型：`object`
-- 默认值：`null`
+- Type: `object`
+- Default: `null`
-启用运行时 publicPath，开启后会使用 `window.publicPath` 作为资源动态加载的起始路径。
+Enable runtime publicPath, which uses `window.publicPath` as the starting path for dynamically loading resources.
-比如，
+For example:
```js
runtimePublicPath: {},
@@ -1294,18 +1301,18 @@ runtimePublicPath: {},
## scripts
-- 类型：`string[] | Script[]`
-- 默认值：`[]`
+- Type: `string[] | Script[]`
+- Default: `[]`
-配置 `` 中额外的 script 标签。
+Configure additional script tags in the ``.
-比如，
+For example:
```js
scripts: [`alert(1);`, `https://a.com/b.js`],
```
-会生成 HTML，
+This will generate HTML:
```html
```
-如果需要额外属性，切换到对象格式，比如，
+If additional attributes are needed, switch to the object format:
```js
scripts: [
@@ -1325,36 +1332,36 @@ scripts: [
## sassLoader
-- 类型：`object`
-- 默认值：`{}`
+- Type: `object`
+- Default: `{}`
-配置 sass-loader ，详见 [sass-loader > options](https://github.com/webpack-contrib/sass-loader#options)
+Configure sass-loader, details in [sass-loader > options](https://github.com/webpack-contrib/sass-loader#options).
## styleLoader
-- 类型：`object`
-- 默认值：`false`
+- Type: `object`
+- Default: `false`
-启用 style loader 功能，让 CSS 内联在 JS 中，不输出额外的 CSS 文件。
+Enable style loader functionality to inline CSS into JS, without generating separate CSS files.
## styles
-- 类型：`string[]`
-- 默认值：`[]`
+- Type: `string[]`
+- Default: `[]`
-配置额外的 CSS。
+Configure additional CSS.
-配置项支持内联样式和外联样式路径，后者通过是否以 https?:// 开头来判断。
+Items in the configuration array can include inline styles and external style paths, with external styles determined by whether they start with https?://.
-插入的样式会前置，优先级低于项目内用户编写样式。
+The inserted styles will be prefixed and have lower priority than user-written styles in the project.
-比如：
+For example:
```js
styles: [`body { color: red; }`, `https://a.com/b.css`],
```
-会生成以下 HTML，
+This will generate the following HTML:
```html
+
+```
+
+## srcTranspiler
+
+- 类型：`string` 可选的值：`babel`, `swc`, `esbuild`, `none`
+- 默认值：`babel`
+
+配置构建时转译 js/ts 的工具。
+
+## srcTranspilerOptions
+
+- 类型：`{ swc?: SwcConfig, esbuild?: EsbuildConfig }`
+- 默认值：`undefined`
+
+如果你使用了 `swc` / `esbuild` 作为 `srcTranspiler` 转译器，你可以通过此选项对转译器做进一步的配置，详见 [SwcConfig](https://swc.rs/docs/configuration/swcrc) 、 [EsbuildConfig](https://esbuild.github.io/api/#transform-api) 配置文档。
+
+如给 swc 添加其他的插件：
+
+```ts
+srcTranspilerOptions: {
+ swc: {
+ jsc: {
+ experimental: {
+ plugins: [
+ [
+ '@swc/plugin-styled-components',
+ {
+ displayName: true,
+ ssr: true,
+ },
+ ],
+ ],
+ },
+ },
+ },
+}
+```
+
+## svgr
+
+- 类型：`object`
+- 默认值：`{}`
+
+svgr 默认开启，支持如下方式使用 React svg 组件：
+
+```ts
+import SmileUrl, { ReactComponent as SvgSmile } from './smile.svg';
+```
+
+可配置 svgr 的行为，配置项详见 [@svgr/core > Config](https://github.com/gregberge/svgr/blob/main/packages/core/src/config.ts#L9)。
+
+## svgo
+
+- 类型：`object`
+- 默认值：`{}`
+
+默认使用 svgo 来优化 svg 资源，配置项详见 [svgo](https://github.com/svg/svgo#configuration) 。
+
+## targets
+
+- 类型：`object`
+- 默认值：`{ chrome: 80 }`
+
+配置需要兼容的浏览器最低版本。Umi 会根据这个自定引入 polyfill、配置 autoprefixer 和做语法转换等。
+
+示例，
+
+```js
+// 兼容 ie11
+targets: {
+ ie: 11;
+}
+```
+
+## theme
+
+- 类型：`object`
+- 默认值：`{}`
+
+配置 less 变量主题。
+
+示例：
+
+```js
+theme: { '@primary-color': '#1DA57A' }
+```
+
+## title
+
+- 类型：`string`
+- 默认值：`null`
+
+配置全局页面 title，暂时只支持静态的 Title。
+
+## verifyCommit
+
+- 类型：`{ scope: string[]; allowEmoji: boolean }`
+- 默认值：`{ scope: ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'workflow', 'build', 'ci', 'chore', 'types', 'wip', 'release', 'dep', 'deps', 'example', 'examples', 'merge', 'revert'] }`
+
+针对 verify-commit 命令的配置项。
+
+关于参数。`scope` 用于配置允许的 scope，不区分大小写，配置后会覆盖默认的；`allowEmoji` 开启后会允许加 EMOJI 前缀，比如 `💥 feat(模块): 添加了个很棒的功能`。
+
+```
+verifyCommit: {
+ scope: ['feat', 'fix'],
+ allowEmoji: true,
+}
+```
+
+注意：使用 `git revert` 或 `git merge` 命令以及 `changesets` 的发版 merge 格式所产生的 commit message 会默认通过校验。
+
+## vite
+
+- 类型：`object`
+- 默认值：`{}`
+
+开发者的配置会 merge 到 vite 的 [默认配置](https://vitejs.dev/config/)。
+
+示例，
+
+```js
+// 更改临时文件路径到 node_modules/.bin/.vite 文件夹
+vite: {
+ cacheDir: 'node_modules/.bin/.vite',
+}
+```
+
+## writeToDisk
+
+- 类型：`boolean`
+- 默认值：`false`
+
+开启后会在 dev 模式下额外输出一份文件到 dist 目录，通常用于 chrome 插件、electron 应用、sketch 插件等开发场景。
+
diff --git a/docs/docs/api/plugin-api.md b/docs/docs/api/plugin-api.md
index 26f285271a49..49e2f3bafb98 100644
--- a/docs/docs/api/plugin-api.md
+++ b/docs/docs/api/plugin-api.md
@@ -1,31 +1,31 @@
-# 插件 API
+# Plugin API
-Umi 的核心就在于它的插件机制。基于 Umi 的插件机制，你可以获得扩展项目的编译时和运行时的能力。以下罗列出我们为你提供的所有的插件API，以帮助你能自由编写插件。
+The core of Umi lies in its plugin mechanism. Based on Umi's plugin mechanism, you can extend the capabilities of your project at both compile time and runtime. Below is a list of all the plugin APIs we provide to help you freely write plugins.
-在查用 Umi 插件 API 之前，我们建议你先阅读[插件](../guides/plugins)一节，以了解 umi 插件的机制及原理，这将帮助你更好的使用插件 API。
+Before looking at the Umi plugin APIs, we recommend that you read the [Plugins](../guides/plugins) section to understand the mechanism and principles of Umi plugins. This will help you better utilize the plugin API.
-> 为方便查找，以下内容通过字母排序。
+> For easier searching, the following content is sorted alphabetically.
-## 核心 API
-service 和 PluginAPI 里定义的方法。
+## Core APIs
+Methods defined in `service` and `PluginAPI`.
### applyPlugins
```ts
api.applyPlugins({ key: string, type?: api.ApplyPluginsType, initialValue?: any, args?: any })
```
-取得 `register()` 注册的 hooks 执行后的数据，这是一个异步函数，因此它返回的将是一个 Promise。这个方法的例子和详解见 [register](#register) api
+Retrieve the data after the execution of hooks registered with `register()`. This is an asynchronous function, so it returns a Promise. Examples and explanations of this method can be found in the [register](#register) API.
### describe
```ts
api.describe({ key?:string, config?: { default , schema, onChange }, enableBy? })
```
-在插件注册阶段( initPresets or initPlugins stage )执行，用于描述插件或者插件集的 key、配置信息和启用方式等。
+Executed during the plugin registration phase (initPresets or initPlugins stage), used to describe the key, configuration information, and enablement method of the plugin or plugin set.
-- `key` 是配置中该插件配置的键名
-- `config.default` 是插件配置的默认值，当用户没有在配置中配置 key 时，默认配置将生效。
-- `config.schema` 用于声明配置的类型，基于 [joi](https://joi.dev/) 。 **如果你希望用户进行配置，这个是必须的** ，否则用户的配置无效
-- `config.onChange` 是 dev 模式下，配置被修改后的处理机制。默认值为 `api.ConfigChangeType.reload`，表示在 dev 模式下，配置项被修改时会重启 dev 进程。 你也可以修改为 `api.ConfigChangeType.regenerateTmpFiles`, 表示只重新生成临时文件。你还可以传入一个方法，来自定义处理机制。
-- `enableBy` 是插件的启用方式，默认是`api.EnableBy.register`，表示注册启用，即插件只要被注册就会被启用。可以更改为 `api.EnableBy.config` ，表示配置启用，只有配置插件的配置项才启用插件。你还可以自定义一个返回布尔值的方法（ true 为启用 ）来决定其启用时机，这通常用来实现动态生效。
+- `key` is the key under which the plugin is configured in the configuration.
+- `config.default` is the default value of the plugin configuration. When the user does not configure the key in the configuration, the default configuration will take effect.
+- `config.schema` declares the type of the configuration, based on [joi](https://joi.dev/). **This is required if you want users to configure it**, otherwise the user's configuration will be invalid.
+- `config.onChange` is the handling mechanism after the configuration is modified in dev mode. The default value is `api.ConfigChangeType.reload`, which means that the dev process will be restarted when the configuration item is modified. You can also change it to `api.ConfigChangeType.regenerateTmpFiles`, which means that only temporary files will be regenerated. You can also pass in a function to customize the processing mechanism.
+- `enableBy` is the enabling method of the plugin, defaulting to `api.EnableBy.register`, which means register to enable, i.e., the plugin will be enabled as long as it is registered. You can change it to `api.EnableBy.config`, which means configuration to enable, and only the configuration items of the plugin will enable the plugin. You can also customize a method that returns a boolean value (true for enable) to determine when it should be enabled. This is usually used to achieve dynamic activation.
e.g.
```ts
@@ -40,55 +40,55 @@ api.describe({
enableBy: api.EnableBy.config,
})
```
-这个例子中，插件的 `key` 为 `foo`，因此配置中的键名为 `foo`，配置的类型是字符串，当配置 `foo` 发生变化时，dev 只会重新生成临时文件。该插件只有在用户配置了 `foo` 之后才会启用。
+In this example, the plugin key is `foo`, so the key in the configuration is `foo`. The type of the configuration is a string. When the configuration `foo` changes, dev will only regenerate temporary files. This plugin will only be enabled if the user configures `foo`.
### isPluginEnable
```ts
api.isPluginEnable( key：string)
```
-判断插件是否启用，传入的参数是插件的 key
+Determine whether the plugin is enabled. The parameter passed in is the key of the plugin.
### register
```ts
api.register({ key: string, fn, before?: string, stage?: number})
```
-为 `api.applyPlugins` 注册可供其使用的 hook。
+Register hooks that can be used by `api.applyPlugins`.
-- `key` 是注册的 hook 的类别名称，可以多次使用 `register` 向同一个 `key` 注册 hook，它们将会依次执行。这个 `key` 也同样是使用 `applyPlugins` 收集 hooks 数据时使用的 `key`。注意： **这里的 key 和 插件的 key 没有任何联系。**
-- `fn` 是 hook 的定义，可以是同步的，也可以是异步的（返回一个 Promise 即可）
-- `stage` 用于调整执行顺序，默认为 0，设为 -1 或更少会提前执行，设为 1 或更多会后置执行。
-- `before` 同样用于调整执行的顺序，传入的值为注册的 hook 的名称。注意：**`register` 注册的 hook 的名称是所在 Umi 插件的 id。** stage 和 before 的更多用法参考 [tapable](https://github.com/webpack/tapable)
+- `key` is the category name of the registered hook. You can use `register` multiple times to register hooks under the same `key`, and they will be executed in sequence. This `key` is also used when collecting hook data using `applyPlugins`. Note: **The key here has no connection with the key of the plugin.**
+- `fn` is the definition of the hook, which can be synchronous or asynchronous (returning a Promise).
+- `stage` is used to adjust the execution order, defaulting to 0. Setting it to -1 or lower will execute it in advance, while setting it to 1 or higher will execute it after.
+- `before` is also used to adjust the execution order. The value passed in is the name of the registered hook. Note: **The name of the hook registered by `register` is the id of the Umi plugin it belongs to.** For more usage of `stage` and `before`, please refer to [tapable](https://github.com/webpack/tapable).
-注意： 相较于 `umi@3`， `umi@4` 去除了 `pluginId` 参数。
+Note: Compared to `umi@3`, `umi@4` has removed the `pluginId` parameter.
-fn 的写法需要结合即将使用的 applyPlugins 的 type 参数来确定：
-- `api.ApplyPluginsType.add` `applyPlugins` 将按照 hook 顺序来将它们的返回值拼接成一个数组。此时 `fn` 需要有返回值，`fn` 将获取 `applyPlugins` 的参数 `args` 来作为自己的参数。`applyPlugins` 的 `initialValue` 必须是一个数组，它的默认值是空数组。当 `key` 以 `'add'` 开头且没有显式地声明 `type` 时，`applyPlugins` 会默认按此类型执行。
-- `api.ApplyPluginsType.modify` `applyPlugins` 将按照 hook 顺序来依次更改 `applyPlugins` 接收的 `initialValue`， 因此此时 **`initialValue` 是必须的** 。此时 `fn` 需要接收一个 `memo` 作为自己的第一个参数，而将会把 `applyPlugins` 的参数 `args` 来作为自己的第二个参数。`memo` 是前面一系列 hook 修改 `initialValue` 后的结果， `fn` 需要返回修改后的`memo` 。当 `key` 以 `'modify'` 开头且没有显式地声明 `type` 时，`applyPlugins` 会默认按此类型执行。
-- `api.ApplyPluginsType.event` `applyPlugins` 将按照 hook 顺序来依次执行。此时不用传入 `initialValue` 。`fn` 不需要有返回值，并且将会把 `applyPlugins` 的参数 `args` 来作为自己的参数。当 `key` 以 `'on'` 开头且没有显式地声明 `type` 时，`applyPlugins` 会默认按此类型执行。
+The writing of `fn` needs to be combined with the `type` parameter of the upcoming `applyPlugins` to determine:
+- `api.ApplyPluginsType.add` `applyPlugins` will concatenate their return values into an array in hook order. In this case, `fn` needs to have a return value, and `fn` will receive `args` of `applyPlugins` as its own parameters. The `initialValue` of `applyPlugins` must be an array, and its default value is an empty array. When the `key` starts with `'add'` and `type` is not explicitly declared, `applyPlugins` will default to execute according to this type.
+- `api.ApplyPluginsType.modify` `applyPlugins` will sequentially change the `initialValue` received by `applyPlugins` according to the hook order. Therefore, **`initialValue` is required in this case**. In this case, `fn` needs to receive a `memo` as its first parameter and will receive `args` of `applyPlugins` as its second parameter. `memo` is the result of modifying `initialValue` by a series of previous hooks, and `fn` needs to return the modified `memo`. When the `key` starts with `'modify'` and `type` is not explicitly declared, `applyPlugins` will default to execute according to this type.
+- `api.ApplyPluginsType.event` `applyPlugins` will execute sequentially according to the hook order. In this case, you don't need to pass in `initialValue`. `fn` doesn't need to have a return value, and it will receive `args` of `applyPlugins` as its own parameters. When the `key` starts with `'on'` and `type` is not explicitly declared, `applyPlugins` will default to execute according to this type.
-e.g.1 add 型
+e.g.1 add type
```ts
api.register({
key: 'addFoo',
- // 同步
+ // Synchronous
fn: (args) => args
});
api.register({
key: 'addFoo',
- // 异步
+ // Asynchronous
fn: async (args) => args * 2
})
api.applyPlugins({
key: 'addFoo',
- // key 是 add 型，不用显式声明为 api.ApplyPluginsType.add
+ // key is of add type, no need to explicitly declare it as api.ApplyPluginsType.add
args: 1
}).then((data)=>{
console.log(data); // [1,2]
})
```
-e.g.2 modify 型
+e.g.2 modify type
```ts
api.register({
key: 'foo',
@@ -101,7 +101,7 @@ api.register({
api.applyPlugins({
key: 'foo',
type: api.ApplyPluginsType.modify,
- // 必须有 initialValue
+ // initialValue is required
initialValue: {
a: 0,
b: 0
@@ -124,36 +124,36 @@ api.registerCommand({
resolveConfigMode? : 'strict' | 'loose'
})
```
-注册命令。
-- `alias` 为别名，比如 generate 的别名 g
-- `fn` 的参数为 `{ args }`， args 的格式同 [yargs](https://github.com/yargs/yargs) 的解析结果，需要注意的是 `_` 里的 command 本身被去掉了，比如执行`umi generate page foo`，`args._` 为 `['page','foo']`
-- `resolveConfigMode` 参数控制执行命令时配置解析的方式，`strict` 模式下强校验 Umi 项目的配置文件内容，如果有非法内容中断命令执行；`loose` 模式下不执行配置文件的校验检查。
+Register a command.
+- `alias` is the alias, e.g., the alias of `generate` is `g`.
+- The parameter of `fn` is `{ args }`, where the format of `args` is the parsing result of [yargs](https://github.com/yargs/yargs), and it should be noted that the command itself in `_` has been removed, for example, when executing `umi generate page foo`, `args._` is `['page','foo']`.
+- The `resolveConfigMode` parameter controls the way configuration is resolved when executing the command. In `strict` mode, the content of the Umi project's configuration file is strongly validated, and the command execution is interrupted if there is any illegal content; in `loose` mode, the validation check of the configuration file is not executed.
### registerMethod
```ts
api.registerMethod({ name: string, fn? })
```
-往 api 上注册一个名为 `'name'` 的方法。
+Register a method on the `api` with the name `'name'`.
-- 当传入了 fn 时，执行 fn
-- 当没有传入 fn 时，`registerMethod` 会将 `name` 作为 `api.register` 的 `key` 并且将其柯里化后作为 `fn`。这种情况下相当于注册了一个 `register` 的快捷调用方式，便于注册 hook。
+- When `fn` is provided, execute `fn`.
+- When `fn` is not provided, `registerMethod` will use `'name'` as the `key` for `api.register` and curry it as `fn`. In this case, it is equivalent to registering a shortcut for `register`, which facilitates hook registration.
-注意：
-- 相较于 `umi@3`， `umi@4` 去除了 exitsError 参数。
-- 通常不建议注册额外的方法，因为它们不会有 ts 提示，直接使用 `api.register()` 是一个更安全的做法。
+Note:
+- Compared to `umi@3`, `umi@4` has removed the `exitsError` parameter.
+- It is generally not recommended to register additional methods, as they won't have TypeScript prompts. Using `api.register()` directly is a safer approach.
e.g.1
```ts
api.registerMethod({
name: foo,
- // 有 fn
+ // With fn
fn: (args) => {
console.log(args);
}
})
api.foo('hello, umi!'); // hello, umi!
```
-该例子中，我们往api上注册了一个 foo 方法，该方法会把参数 console 到控制台。
+In this example, we registered a method named `foo` on the `api`, which will log the arguments to the console.
e.g.2
```ts
@@ -161,7 +161,7 @@ import api from './api';
api.registerMethod({
name: 'addFoo'
- // 没有 fn
+ // Without fn
})
api.addFoo( args => args );
@@ -174,13 +174,13 @@ api.applyPlugins({
console.log(data); // [ 1, 2 ]
});
```
-该例子中，我们没有向 `api.registerMethod` 中传入 fn。此时，我们相当于往 api 上注册了一个"注册器"：`addFoo`。每次调用该方法都相当于调用了 `register({ key: 'addFoo', fn })`。因此当我们使用 `api.applyPlugins` 的时候（由于我们的方法是 add 型的，可以不用显式声明其 type ）就可以获取刚刚注册的 hook 的值。
+In this example, we didn't provide an `fn` to `api.registerMethod`. In this case, we essentially registered a "register" method on the `api`: `addFoo`. Each time this method is called, it's equivalent to calling `register({ key: 'addFoo', fn })`. Therefore, when we use `api.applyPlugins` (since our method is of the add type, we don't need to explicitly declare its type), we can retrieve the value of the just registered hook.
### registerPresets
```ts
api.registerPresets( presets: string[] )
```
-注册插件集，参数为路径数组。该 api 必须在 initPresets stage 执行，即只可以在 preset 中注册其他 presets
+Register plugin sets, where the parameter is an array of paths. This API must be executed during the `initPresets` stage, which means you can only register other presets in presets.
e.g.
```ts
@@ -194,7 +194,7 @@ api.registerPresets([
```ts
api.registerPlugins( plugins: string[] )
```
-注册插件，参数为路径数组。该 api 必须在 initPresets 和 initPlugins stage 执行。
+Register plugins, where the parameter is an array of paths. This API must be executed during the `initPresets` and `initPlugins` stages.
e.g.
```ts
@@ -204,7 +204,7 @@ api.registerPlugins([
])
```
-注意： 相较于 `umi@3` ，`umi@4` 不再支持在 `registerPresets` 和 `registerPlugins` 中直接传入插件对象了，现在只允许传入插件的路径。
+Note: Compared to `umi@3`, `umi@4` no longer supports directly passing plugin objects in `registerPresets` and `registerPlugins`. Now, only the paths of the plugins are allowed to be passed in.
### registerGenerator
@@ -212,12 +212,12 @@ api.registerPlugins([
```ts
api.skipPlugins( keys: string[])
```
-声明哪些插件需要被禁用，参数为插件 key 的数组
+Declare which plugins need to be skipped. The parameter is an array of plugin keys.
-## 扩展方法
-通过`api.registerMethod()` 扩展的方法，它们的作用都是注册一些 hook 以供使用，因此都需要接收一个 fn。这些方法中的大部分都按照 `add-` `modify-` `on-` 的方式命名，它们分别对应了 `api.ApplyPluginsType`的三种方式，不同方式接收的 fn 不太相同，详见 [register](#register) 一节。
+## Extension Methods
+Methods extended through `api.registerMethod()`. Their purpose is to register hooks for use, so they all need to accept an `fn`. Most of these methods are named in the format of `add-`, `modify-`, and `on-`, which correspond to the three types of `api.ApplyPluginsType`. The differences in the `fn` received for different types are not quite the same; see the [register](#register) section for details.
-注意： 下文提到的所有 fn 都可以是同步的或者异步的（返回一个 Promise 即可）。fn 都可以被
+Note: All the `fn` mentioned below can be synchronous or asynchronous (returning a Promise). The `fn` can also be replaced with:
```ts
{
@@ -228,13 +228,13 @@ api.skipPlugins( keys: string[])
}
```
-代替。其中各个参数的作用详见 [tapable](https://github.com/webpack/tapable)
+Where the roles of various parameters are detailed in [tapable](https://github.com/webpack/tapable).
### addBeforeBabelPlugins
-增加额外的 Babel 插件。传入的 fn 不需要参数，且需要返回一个 Babel 插件或插件数组。
+Add additional Babel plugins. The provided `fn` doesn't require any parameters and should return a Babel plugin or an array of plugins.
```ts
api.addBeforeBabelPlugins(() => {
- // 返回一个 Babel 插件（来源于 Babel 官网的例子）
+ // Return a Babel plugin (from Babel's official example)
return () => {
visitor: {
Identifier(path) {
@@ -247,10 +247,10 @@ api.addBeforeBabelPlugins(() => {
```
### addBeforeBabelPresets
-增加额外的 Babel 插件集。传入的 fn 不需要参数，且需要返回一个 Babel 插件集( presets )或插件集数组。
+Add additional Babel presets. The provided `fn` doesn't require any parameters and should return a Babel preset or an array of presets.
```ts
api.addBeforeBabelPresets(() => {
- // 返回一个 Babel 插件集
+ // Return a Babel preset
return () => {
return {
plugins: ["Babel_Plugin_A","Babel_Plugin_B"]
@@ -260,7 +260,7 @@ api.addBeforeBabelPresets(() => {
```
### addBeforeMiddlewares
-在 webpack-dev-middleware 之前添加中间件。传入的 fn 不需要参数，且需要返回一个 express 中间件或其数组。
+Add middleware before webpack-dev-middleware. The provided `fn` doesn't require any parameters and should return an express middleware or an array of middlewares.
```ts
api.addBeforeMiddlewares(() => {
return (req, res, next) => {
@@ -273,19 +273,19 @@ api.addBeforeMiddlewares(() => {
```
### addEntryCode
-在入口文件的最后面添加代码（render 后）。传入的 fn 不需要参数，且需要返回一个 string 或者 string 数组。
+Add code to the end of the entry file (after render). The provided `fn` doesn't require any parameters and should return a string or an array of strings.
```ts
api.addEntryCode(() => `console.log('I am after render!')`);
```
### addEntryCodeAhead
-在入口文件的最前面添加代码（render 前，import 后）。传入的 fn 不需要参数，且需要返回一个 string 或者 string 数组。
+Add code to the beginning of the entry file (before render, after imports). The provided `fn` doesn't require any parameters and should return a string or an array of strings.
```ts
api.addEntryCodeAhead(() => `console.log('I am before render!')`)
```
### addEntryImports
-在入口文件中添加 import 语句 （import 最后面）。传入的 fn 不需要参数，其需要返回一个 `{source: string, specifier?: string}` 或其数组。
+Add import statements to the entry file (after the last import). The provided `fn` doesn't require any parameters and should return an object `{source: string, specifier?: string}` or an array of such objects.
```ts
api.addEntryImports(() => ({
source: '/modulePath/xxx.js',
@@ -294,7 +294,7 @@ api.addEntryImports(() => ({
```
### addEntryImportsAhead
-在入口文件中添加 import 语句 （import 最前面）。传入的 fn 不需要参数，其需要返回一个 `{source: string, specifier?: string}` 或其数组。
+Add import statements to the entry file (before the first import). The provided `fn` doesn't require any parameters and should return an object `{source: string, specifier?: string}` or an array of such objects.
```ts
api.addEntryImportsAhead(() => ({
source: 'anyPackage'
@@ -302,19 +302,19 @@ api.addEntryImportsAhead(() => ({
```
### addExtraBabelPlugins
-添加额外的 Babel 插件。 传入的 fn 不需要参数，且需要返回一个 Babel 插件或插件数组。
+Add additional Babel plugins. The provided `fn` doesn't require any parameters and should return a Babel plugin or an array of plugins.
### addExtraBabelPresets
-添加额外的 Babel 插件集。传入的 fn 不需要参数，且需要返回一个 Babel 插件集或其数组。
+Add additional Babel presets. The provided `fn` doesn't require any parameters and should return a Babel preset or an array of presets.
### addHTMLHeadScripts
-往 HTML 的 `` 元素里添加 Script。传入的 fn 不需要参数，且需要返回一个 string（想要加入的代码） 或者 `{ async?: boolean, charset?: string, crossOrigin?: string | null, defer?: boolean, src?: string, type?: string, content?: string }` 或者它们的数组。
+Add scripts to the `` element of the HTML. The provided `fn` doesn't require any parameters and should return a string (the code you want to add) or an object or an array of objects with properties like `async`, `charset`, `crossOrigin`, `defer`, `src`, `type`, or `content`.
```ts
api.addHTMLHeadScripts(() => `console.log('I am in HTML-head')`)
```
### addHTMLLinks
-往 HTML 里添加 Link 标签。 传入的 fn 不需要参数，返回的对象或其数组接口如下：
+Add Link tags to the HTML. The provided `fn` doesn't require any parameters and should return an object with properties like `as`, `crossOrigin`, `disabled`, `href`, `hreflang`, `imageSizes`, `imageSrcset`, `integrity`, `media`, `referrerPolicy`, `rel`, `rev`, `target`, or `type`.
```ts
{
as?: string, crossOrigin: string | null,
@@ -334,7 +334,7 @@ api.addHTMLHeadScripts(() => `console.log('I am in HTML-head')`)
```
### addHTMLMetas
-往 HTML 里添加 Meta 标签。 传入的 fn 不需要参数，返回的对象或其数组接口如下：
+Add Meta tags to the HTML. The provided `fn` doesn't require any parameters and should return an object with properties like `content`, `http-equiv`, `name`, or `scheme`.
```ts
{
content?: string,
@@ -345,47 +345,49 @@ api.addHTMLHeadScripts(() => `console.log('I am in HTML-head')`)
```
### addHTMLScripts
-往 HTML 尾部添加 Script。 传入的 fn 不需要参数，返回的对象接口同 [addHTMLHeadScripts](#addHTMLHeadScripts)
+Add scripts to the end of the HTML. The provided `fn` doesn't require any parameters and should return an object with properties like `async`, `charset`, `crossOrigin`, `defer`, `src`, `type`, or `content`.
### addHTMLStyles
-往 HTML 里添加 Style 标签。 传入的 fn 不需要参数，返回一个 string （style 标签里的代码）或者 `{ type?: string, content?: string }`，或者它们的数组。
-
+Add style tags to the HTML. The provided `fn` doesn't require any parameters and should return a string (the content of the style tag) or an object with properties like `type` or `content`.
+```ts
+api.addHTMLStyles(() => 'body { background-color: red; }')
+```
### addLayouts
-添加全局 layout 组件。 传入的 fn 不需要参数，返回 `{ id?: string, file: string }`
+Add global layout components. The provided `fn` doesn't require any parameters and should return an object `{ id?: string, file: string }`.
### addMiddlewares
-添加中间件，在 route 中间件之后。 传入的 fn 不需要参数，返回 express 中间件。
+Add middlewares after route middlewares. The provided `fn` doesn't require any parameters and should return an express middleware.
### addPolyfillImports
-添加补丁 import，在整个应用的最前面执行。 传入的 fn 不需要参数，返回 `{ source: string, specifier?:string }`
+Add polyfill imports, executed at the very beginning of the application. The provided `fn` doesn't require any parameters and should return an object `{ source: string, specifier?: string }`.
### addPrepareBuildPlugins
### addRuntimePlugin
-添加运行时插件，传入的 fn 不需要参数，返回 string ，表示插件的路径。
+Add runtime plugins. The provided `fn` doesn't require any parameters and should return a string representing the plugin's path.
### addRuntimePluginKey
-添加运行时插件的 Key， 传入的 fn 不需要参数，返回 string ，表示插件的路径。
+Add keys for runtime plugins. The provided `fn` doesn't require any parameters and should return a string representing the plugin's path.
### addTmpGenerateWatcherPaths
-添加监听路径，变更时会重新生成临时文件。传入的 fn 不需要参数，返回 string，表示要监听的路径。
+Add paths to watch. When changed, temporary files will be regenerated. The provided `fn` doesn't require any parameters and should return a string representing the path to be watched.
### addOnDemandDeps
-添加按需安装的依赖，他们会在项目启动时检测是否安装：
+Add on-demand installed dependencies. They will be checked for installation when the project starts:
```ts
- api.addOnDemandDeps(() => [{ name: '@swc/core', version: '^1.0.0', dev: true }])
+api.addOnDemandDeps(() => [{ name: '@swc/core', version: '^1.0.0', dev: true }])
```
### chainWebpack
-通过 [webpack-chain](https://github.com/neutrinojs/webpack-chain) 的方式修改 webpack 配置。传入一个fn，该 fn 不需要返回值。它将接收两个参数：
-- `memo` 对应 webpack-chain 的 config
-- `args:{ webpack, env }` `arg.webpack` 是 webpack 实例， `args.env` 代表当前的运行环境。
+Modify webpack configuration using [webpack-chain](https://github.com/neutrinojs/webpack-chain). Pass a function as an argument to this method; this function doesn't require a return value. It will receive two parameters:
+- `memo`, corresponding to the webpack config from webpack-chain.
+- `args: { webpack, env }`, where `args.webpack` is the webpack instance, and `args.env` represents the current environment.
e.g.
```ts
-api.chainWebpack(( memo, { webpack, env}) => {
+api.chainWebpack((memo, { webpack, env}) => {
// set alias
memo.resolve.alias.set('a','path/to/a');
// Delete progess bar plugin
@@ -393,9 +395,9 @@ api.chainWebpack(( memo, { webpack, env}) => {
})
```
-### modifyAppData （`umi@4` 新增）
+### modifyAppData (Added in `umi@4`)
-修改 app 元数据。传入的 fn 接收 appData 并且返回它。
+Modify app metadata. The provided `fn` receives `appData` and should return it.
```ts
api.modifyAppData((memo) => {
memo.foo = 'foo';
@@ -404,7 +406,7 @@ api.modifyAppData((memo) => {
```
### modifyConfig
-修改配置，相较于用户的配置，这份是最终传给 Umi 使用的配置。传入的 fn 接收 config 作为第一个参数，并且返回它。另外 fn 可以接收 `{ paths }` 作为第二个参数。`paths` 保存了 Umi 的各个路径。
+Modify the configuration. Compared to the user's configuration, this is the configuration passed to Umi for use. The provided `fn` receives `config` as the first parameter and should return it. Additionally, the `fn` can receive `{ paths }` as the second parameter. `paths` contains various paths of Umi.
```ts
api.modifyConfig((memo, { paths }) => {
memo.alias = {
@@ -416,10 +418,10 @@ api.modifyConfig((memo, { paths }) => {
```
### modifyDefaultConfig
-修改默认配置。传入的 fn 接收 config 并且返回它。
+Modify the default configuration. The provided `fn` receives `config` and should return it.
### modifyHTML
-修改 HTML，基于 cheerio 的 ast。传入的 fn 接收 cheerioAPI 并且返回它。另外 fn 还可以接收`{ path }` 作为它的第二个参数，该参数代表路由的 path
+Modify the HTML based on cheerio's AST. The provided `fn` receives the cheerio API and should return it. Additionally, `fn` can also receive `{ path }` as its second parameter, which represents the route's path.
```ts
api.modifyHTML(($, { path }) => {
$('h2').addClass('welcome');
@@ -428,14 +430,14 @@ api.modifyHTML(($, { path }) => {
```
### modifyHTMLFavicon
-修改 HTML 的 favicon 路径。 传入的 fn 接收原本的 favicon 路径(string 类型)并且返回它。
+Modify the HTML's favicon path. The provided `fn` receives the original favicon path (as a string) and should return it.
### modifyPaths
-修改 paths，比如 absOutputPath、absTmpPath。传入的 fn 接收 paths 并且返回它。
+Modify paths, such as `absOutputPath` and `absTmpPath`. The provided `fn` receives `paths` and should return it.
-paths 的接口如下：
+The interface for `paths` is as follows:
```ts
-paths:{
+paths: {
cwd?: string;
absSrcPath?: string;
absPagesPath?: string;
@@ -446,13 +448,13 @@ paths:{
```
### modifyRendererPath
-修改 renderer path。传入的 fn 接收原本的 path （string 类型）并且返回它。
+Modify the renderer path. The passed `fn` receives the original path (of type `string`) and returns it.
### modifyServerRendererPath
-修改 server renderer path。传入的 fn 接收原本的 path （string 类型）并且返回它。
+Modify the server renderer path. The passed `fn` receives the original path (of type `string`) and returns it.
### modifyRoutes
-修改路由。 传入的 fn 接收 id-route 的 map 并且返回它。其中 route 的接口如下：
+Modify routes. The passed `fn` receives the `id-route` map and returns it. The interface of the `route` is as follows:
```ts
interface IRoute {
path: string;
@@ -477,7 +479,7 @@ api.modifyRoutes((memo) => {
### modifyTSConfig
-修改临时目录下的 tsconfig 文件内容。
+Modify the contents of the tsconfig file in the temporary directory.
```ts
api.modifyTSConfig((memo) => {
@@ -487,7 +489,7 @@ api.modifyTSConfig((memo) => {
```
### modifyViteConfig
-修改 vite 最终配置。 传入的 fn 接收 vite 的 Config 对象作为第一个参数并且返回它。另外 fn 还可以接收 `{ env }` 作为第二个参数，可以通过该参数获取当前的环境。
+Modify the final Vite configuration. The passed `fn` receives the Vite Config object as the first parameter and returns it. Additionally, the `fn` can also receive `{ env }` as the second parameter, allowing you to access the current environment.
```ts
api.modifyViteConfig((memo, { env }) => {
if(env === 'development'){
@@ -497,7 +499,7 @@ api.modifyViteConfig((memo, { env }) => {
})
```
### modifyWebpackConfig
-修改 webpack 最终配置。传入的 fn 接收 webpack 的 Config 对象作为第一个参数并且返回它。另外 fn 还可以接收 `{ webpack, env }` 作为第二个参数，其中 webpack 是 webpack 实例，env 代表当前环境。
+Modify the final Webpack configuration. The passed `fn` receives the Webpack Config object as the first parameter and returns it. Additionally, the `fn` can also receive `{ webpack, env }` as the second parameter, where `webpack` is the Webpack instance and `env` represents the current environment.
```ts
api.modifyWebpackConfig((memo, { webpack, env }) => {
@@ -508,10 +510,10 @@ api.modifyWebpackConfig((memo, { webpack, env }) => {
```
### onBeforeCompiler
-generate 之后，webpack / vite compiler 之前。传入的 fn 不接收任何参数。
+After generate, before webpack/vite compiler. The passed `fn` doesn't receive any parameters.
### onBeforeMiddleware
-提供在服务器内部执行所有其他中间件之前执行自定义中间件的能力, 这可以用来定义自定义处理程序， 例如:
+Provides the ability to execute custom middleware inside the server before all other middlewares. This can be used to define custom handlers, for example:
```ts
api.onBeforeMiddleware(({ app }) => {
@@ -522,16 +524,16 @@ api.onBeforeMiddleware(({ app }) => {
```
### onBuildComplete
-build 完成时。传入的 fn 接收 `{ isFirstCompile: boolean, stats, time: number, err?: Error }` 作为参数。
+When build is completed. The passed `fn` receives `{ isFirstCompile: boolean, stats, time: number, err?: Error }` as parameters.
### onBuildHtmlComplete
-build 完成且 html 完成构建之后。
+After build is completed and HTML is built.
### onCheck
-检查时，在 onStart 之前执行。传入的 fn 不接收任何参数
+During checking, executed before `onStart`. The passed `fn` doesn't receive any parameters.
### onCheckCode
-检查代码时。传入的 fn 接收的参数接口如下：
+During code checking. The passed `fn` receives the following parameter interface:
```ts
args: {
file: string;
@@ -551,13 +553,13 @@ args: {
```
### onCheckConfig
-检查 config 时。传入的 fn 接收 `{ config, userConfig }`作为参数，它们分别表示实际的配置和用户的配置。
+During checking configuration. The passed `fn` receives `{ config, userConfig }` as parameters, where they represent the actual configuration and the user's configuration respectively.
### onCheckPkgJSON
-检查 package.json 时。传入的 fn 接收 `{origin?, current}` 作为参数。它们的类型都是 package.json 对象
+During checking package.json. The passed `fn` receives `{origin?, current}` as parameters. Both are package.json objects.
### onDevCompileDone
-dev 完成时。传入的 fn 接收的参数接口如下：
+When dev is completed. The passed `fn` receives the following parameter interface:
```ts
args: {
isFirstCompile: boolean;
@@ -567,7 +569,7 @@ args: {
```
### onGenerateFiles
-生成临时文件时，随着文件变化会频繁触发，有缓存。 传入的 fn 接收的参数接口如下：
+When generating temporary files, this event can trigger frequently due to file changes, and it is cached. The passed `fn` receives the following parameter interface:
```ts
args: {
isFirstTime?: boolean;
@@ -580,52 +582,54 @@ args: {
### onPatchRoute
-匹配单个路由，可以修改路由，给路由打补丁
+Matches a single route and can modify the route, applying patches to it.
### onPkgJSONChanged
-package.json 变更时。传入的 fn 接收 `{origin?, current}` 作为参数。它们的类型都是 package.json 对象
+When package.json changes. The passed `fn` receives `{origin?, current}` as parameters. Both are package.json objects.
### onPrepareBuildSuccess
### onStart
-启动时。传入的 fn 不接收任何参数。
+When starting. The passed `fn` doesn't receive any parameters.
### writeTmpFile
-`api.writeTmpFile()`的 type 参数的类型。
+The type of the `type` parameter for `api.writeTmpFile()`.
-- content: 写入的文本内容，有内容就不会使用模板。
-- context: 模板上下文。
-- noPluginDir: 是否使用插件名做为目录。
-- path: 写入文件的路径。
-- tpl: 使用模板字符串，没有模板路径会使用它。
-- tplPath: 使用模板文件的路径。
+- `content`: The text content to write, if provided, the template won't be used.
+- `context`: The template context.
+- `noPluginDir`: Whether to use the plugin name as a directory.
+- `path`: The path to write the file.
+- `tpl`: Use a template string, if no template path is provided.
+- `tplPath`: Use a template file path.
-## 属性
-从 api 可以直接访问到的属性，这些属性有一部分来自于 service
+## Properties
+Attributes that can be directly accessed from the `api`, some of which come from the `service`.
### appData
### args
-命令行参数，这里去除了命令本身。
+Command-line arguments, excluding the command itself.
e.g.
-- `$ umi dev --foo`, args 为 `{ _:[], foo: true }`
-- `$ umi g page index --typescript --less` , args 为 `{ _: [ 'page', 'index''], typescript: true, less: true }`
+- `$ umi dev --foo`,
+
+ args are `{ _:[], foo: true }`
+- `$ umi g page index --typescript --less`, args are `{ _: [ 'page', 'index''], typescript: true, less: true }`
### config
-最终的配置（取决于你访问的时机，可能是当前收集到的最终配置）
+Final configuration (depends on the context of access, possibly the current collected final configuration).
### cwd
-当前路径
+Current working directory.
### env
-即 `process.env.NODE_ENV` 可能有 `development`、`production` 和 `test`
+Equivalent to `process.env.NODE_ENV`, can be `development`, `production`, or `test`.
### logger
-插件日志对象，包含 `{ log, info, debug, error, warn, profile }`，他们都是方法。其中 `api.logger.profile` 可用于性能耗时记录。
+Plugin logging object, containing `{ log, info, debug, error, warn, profile }`, all of which are methods. `api.logger.profile` can be used for profiling performance time.
```ts
api.logger.profile('barId');
@@ -636,60 +640,60 @@ setTimeout(() => {
```
### name
-当前命令的名称，例如 `$ umi dev `， `name` 就是 `dev`
+Name of the current command, for example, `$ umi dev `, `name` is `dev`.
### paths
-项目相关的路径：
-- `absNodeModulesPath`，node_modules 目录绝对路径
-- `absOutputPath`，输出路径，默认是 ./dist
-- `absPagesPath`，pages 目录绝对路径
-- `absSrcPath`，src 目录绝对路径，需注意 src 目录是可选的，如果没有 src 目录，absSrcPath 等同于 cwd
-- `absTmpPath`，临时目录绝对路径
-- `cwd`，当前路径
+Project-related paths:
+- `absNodeModulesPath`: Absolute path to the node_modules directory.
+- `absOutputPath`: Output path, default is `./dist`.
+- `absPagesPath`: Absolute path to the pages directory.
+- `absSrcPath`: Absolute path to the src directory. Note that the src directory is optional. If there's no src directory, `absSrcPath` is the same as `cwd`.
+- `absTmpPath`: Absolute path to the temporary directory.
+- `cwd`: Current working directory.
-注意： 注册阶段不能获取到。因此不能在插件里直接获取，要在 hook 里使用。
+Note: Cannot be accessed during the registration stage. So, it can't be directly accessed in plugins, only in hooks.
### pkg
-当前项目的 `package.json` 对象
+`package.json` object of the current project.
### pkgPath
-当前项目的 `package.json` 的绝对路径。
+Absolute path to the `package.json` of the current project.
### plugin
-当前插件的对象。
-- `type` 插件类型，有 preset 和 plugin 两种
-- `path` 插件路径
-- `id` 插件 id
-- `key` 插件 key
-- `config` 插件的配置
-- `enableBy` 插件的启用方式
+Object of the current plugin.
+- `type`: Plugin type, either preset or plugin.
+- `path`: Plugin path.
+- `id`: Plugin id.
+- `key`: Plugin key.
+- `config`: Plugin configuration.
+- `enableBy`: Plugin enable method.
-注意： 注册阶段使用的 plugin 对象是你 `describe` 之前的对象。
+Note: The plugin object used during the registration stage is the one before your `describe`.
### service
-Umi 的 `Service` 实例。通常不需要用到，除非你知道为什么。
+Umi's `Service` instance. Generally not needed unless you know why.
### userConfig
-用户的配置，从 `.umirc` 或 `config/config` 中读取的内容，没有经过 defaultConfig 以及插件的任何处理。可以在注册阶段使用。
+User's configuration, read from `.umirc` or `config/config`, without any processing from defaultConfig or plugins. Can be used during the registration stage.
### ApplyPluginsType
-`api.applyPlugins()` 的 type 参数的类型。包含
-- add
-- modify
-- event
+Type parameter for `api.applyPlugins()`. Contains:
+- `add`
+- `modify`
+- `event`
### ConfigChangeType
-为 `api.describe()` 提供 `config.onChange` 的类型，目前包含两种：
-- restart，重启 dev 进程，是默认值
-- regenerateTmpFiles，重新生成临时文件
+Type for `config.onChange` in `api.describe()`, currently contains two types:
+- `restart`, restart the dev process (default).
+- `regenerateTmpFiles`, regenerate temporary files.
### EnableBy
-插件的启用方式，包含三种：
-- register
-- config
+Plugin enable method, contains three methods:
+- `register`
+- `config`
### ServiceStage
-Umi service 的运行阶段。有如下阶段：
+Umi service run stages. Contains stages like:
- uninitialized
- init
- initPresets
@@ -698,4 +702,4 @@ Umi service 的运行阶段。有如下阶段：
- collectAppData
- onCheck
- onStart
-- runCommand
+- runCommand
\ No newline at end of file
diff --git a/docs/docs/api/plugin-api.zh-CN.md b/docs/docs/api/plugin-api.zh-CN.md
new file mode 100644
index 000000000000..26f285271a49
--- /dev/null
+++ b/docs/docs/api/plugin-api.zh-CN.md
@@ -0,0 +1,701 @@
+# 插件 API
+
+Umi 的核心就在于它的插件机制。基于 Umi 的插件机制，你可以获得扩展项目的编译时和运行时的能力。以下罗列出我们为你提供的所有的插件API，以帮助你能自由编写插件。
+
+在查用 Umi 插件 API 之前，我们建议你先阅读[插件](../guides/plugins)一节，以了解 umi 插件的机制及原理，这将帮助你更好的使用插件 API。
+
+> 为方便查找，以下内容通过字母排序。
+
+## 核心 API
+service 和 PluginAPI 里定义的方法。
+
+### applyPlugins
+```ts
+api.applyPlugins({ key: string, type?: api.ApplyPluginsType, initialValue?: any, args?: any })
+```
+取得 `register()` 注册的 hooks 执行后的数据，这是一个异步函数，因此它返回的将是一个 Promise。这个方法的例子和详解见 [register](#register) api
+
+### describe
+```ts
+api.describe({ key?:string, config?: { default , schema, onChange }, enableBy? })
+```
+在插件注册阶段( initPresets or initPlugins stage )执行，用于描述插件或者插件集的 key、配置信息和启用方式等。
+
+- `key` 是配置中该插件配置的键名
+- `config.default` 是插件配置的默认值，当用户没有在配置中配置 key 时，默认配置将生效。
+- `config.schema` 用于声明配置的类型，基于 [joi](https://joi.dev/) 。 **如果你希望用户进行配置，这个是必须的** ，否则用户的配置无效
+- `config.onChange` 是 dev 模式下，配置被修改后的处理机制。默认值为 `api.ConfigChangeType.reload`，表示在 dev 模式下，配置项被修改时会重启 dev 进程。 你也可以修改为 `api.ConfigChangeType.regenerateTmpFiles`, 表示只重新生成临时文件。你还可以传入一个方法，来自定义处理机制。
+- `enableBy` 是插件的启用方式，默认是`api.EnableBy.register`，表示注册启用，即插件只要被注册就会被启用。可以更改为 `api.EnableBy.config` ，表示配置启用，只有配置插件的配置项才启用插件。你还可以自定义一个返回布尔值的方法（ true 为启用 ）来决定其启用时机，这通常用来实现动态生效。
+
+e.g.
+```ts
+api.describe({
+ key: 'foo',
+ config: {
+ schema(joi){
+ return joi.string();
+ },
+ onChange: api.ConfigChangeType.regenerateTmpFiles,
+ },
+ enableBy: api.EnableBy.config,
+})
+```
+这个例子中，插件的 `key` 为 `foo`，因此配置中的键名为 `foo`，配置的类型是字符串，当配置 `foo` 发生变化时，dev 只会重新生成临时文件。该插件只有在用户配置了 `foo` 之后才会启用。
+
+### isPluginEnable
+```ts
+api.isPluginEnable( key：string)
+```
+判断插件是否启用，传入的参数是插件的 key
+
+### register
+```ts
+api.register({ key: string, fn, before?: string, stage?: number})
+```
+为 `api.applyPlugins` 注册可供其使用的 hook。
+
+- `key` 是注册的 hook 的类别名称，可以多次使用 `register` 向同一个 `key` 注册 hook，它们将会依次执行。这个 `key` 也同样是使用 `applyPlugins` 收集 hooks 数据时使用的 `key`。注意： **这里的 key 和 插件的 key 没有任何联系。**
+- `fn` 是 hook 的定义，可以是同步的，也可以是异步的（返回一个 Promise 即可）
+- `stage` 用于调整执行顺序，默认为 0，设为 -1 或更少会提前执行，设为 1 或更多会后置执行。
+- `before` 同样用于调整执行的顺序，传入的值为注册的 hook 的名称。注意：**`register` 注册的 hook 的名称是所在 Umi 插件的 id。** stage 和 before 的更多用法参考 [tapable](https://github.com/webpack/tapable)
+
+注意： 相较于 `umi@3`， `umi@4` 去除了 `pluginId` 参数。
+
+fn 的写法需要结合即将使用的 applyPlugins 的 type 参数来确定：
+- `api.ApplyPluginsType.add` `applyPlugins` 将按照 hook 顺序来将它们的返回值拼接成一个数组。此时 `fn` 需要有返回值，`fn` 将获取 `applyPlugins` 的参数 `args` 来作为自己的参数。`applyPlugins` 的 `initialValue` 必须是一个数组，它的默认值是空数组。当 `key` 以 `'add'` 开头且没有显式地声明 `type` 时，`applyPlugins` 会默认按此类型执行。
+- `api.ApplyPluginsType.modify` `applyPlugins` 将按照 hook 顺序来依次更改 `applyPlugins` 接收的 `initialValue`， 因此此时 **`initialValue` 是必须的** 。此时 `fn` 需要接收一个 `memo` 作为自己的第一个参数，而将会把 `applyPlugins` 的参数 `args` 来作为自己的第二个参数。`memo` 是前面一系列 hook 修改 `initialValue` 后的结果， `fn` 需要返回修改后的`memo` 。当 `key` 以 `'modify'` 开头且没有显式地声明 `type` 时，`applyPlugins` 会默认按此类型执行。
+- `api.ApplyPluginsType.event` `applyPlugins` 将按照 hook 顺序来依次执行。此时不用传入 `initialValue` 。`fn` 不需要有返回值，并且将会把 `applyPlugins` 的参数 `args` 来作为自己的参数。当 `key` 以 `'on'` 开头且没有显式地声明 `type` 时，`applyPlugins` 会默认按此类型执行。
+
+e.g.1 add 型
+```ts
+api.register({
+ key: 'addFoo',
+ // 同步
+ fn: (args) => args
+});
+
+api.register({
+ key: 'addFoo',
+ // 异步
+ fn: async (args) => args * 2
+})
+
+api.applyPlugins({
+ key: 'addFoo',
+ // key 是 add 型，不用显式声明为 api.ApplyPluginsType.add
+ args: 1
+}).then((data)=>{
+ console.log(data); // [1,2]
+})
+```
+e.g.2 modify 型
+```ts
+api.register({
+ key: 'foo',
+ fn: (memo, args) => ({ ...memo, a: args})
+})
+api.register({
+ key: 'foo',
+ fn: (memo) => ({...memo, b: 2})
+})
+api.applyPlugins({
+ key: 'foo',
+ type: api.ApplyPluginsType.modify,
+ // 必须有 initialValue
+ initialValue: {
+ a: 0,
+ b: 0
+ },
+ args: 1
+}).then((data) => {
+ console.log(data); // { a: 1, b: 2 }
+});
+```
+
+### registerCommand
+```ts
+api.registerCommand({
+ name: string,
+ description? : string,
+ options? : string,
+ details? : string,
+ fn,
+ alias? : string | string[]
+ resolveConfigMode? : 'strict' | 'loose'
+})
+```
+注册命令。
+- `alias` 为别名，比如 generate 的别名 g
+- `fn` 的参数为 `{ args }`， args 的格式同 [yargs](https://github.com/yargs/yargs) 的解析结果，需要注意的是 `_` 里的 command 本身被去掉了，比如执行`umi generate page foo`，`args._` 为 `['page','foo']`
+- `resolveConfigMode` 参数控制执行命令时配置解析的方式，`strict` 模式下强校验 Umi 项目的配置文件内容，如果有非法内容中断命令执行；`loose` 模式下不执行配置文件的校验检查。
+
+### registerMethod
+```ts
+api.registerMethod({ name: string, fn? })
+```
+往 api 上注册一个名为 `'name'` 的方法。
+
+- 当传入了 fn 时，执行 fn
+- 当没有传入 fn 时，`registerMethod` 会将 `name` 作为 `api.register` 的 `key` 并且将其柯里化后作为 `fn`。这种情况下相当于注册了一个 `register` 的快捷调用方式，便于注册 hook。
+
+注意：
+- 相较于 `umi@3`， `umi@4` 去除了 exitsError 参数。
+- 通常不建议注册额外的方法，因为它们不会有 ts 提示，直接使用 `api.register()` 是一个更安全的做法。
+
+e.g.1
+```ts
+api.registerMethod({
+ name: foo,
+ // 有 fn
+ fn: (args) => {
+ console.log(args);
+ }
+})
+api.foo('hello, umi!'); // hello, umi!
+```
+该例子中，我们往api上注册了一个 foo 方法，该方法会把参数 console 到控制台。
+
+e.g.2
+```ts
+import api from './api';
+
+api.registerMethod({
+ name: 'addFoo'
+ // 没有 fn
+})
+
+api.addFoo( args => args );
+api.addFoo( args => args * 2 );
+
+api.applyPlugins({
+ key: 'addFoo',
+ args: 1
+}).then((data)=>{
+ console.log(data); // [ 1, 2 ]
+});
+```
+该例子中，我们没有向 `api.registerMethod` 中传入 fn。此时，我们相当于往 api 上注册了一个"注册器"：`addFoo`。每次调用该方法都相当于调用了 `register({ key: 'addFoo', fn })`。因此当我们使用 `api.applyPlugins` 的时候（由于我们的方法是 add 型的，可以不用显式声明其 type ）就可以获取刚刚注册的 hook 的值。
+
+### registerPresets
+```ts
+api.registerPresets( presets: string[] )
+```
+注册插件集，参数为路径数组。该 api 必须在 initPresets stage 执行，即只可以在 preset 中注册其他 presets
+
+e.g.
+```ts
+api.registerPresets([
+ './preset',
+ require.resolve('./preset_foo')
+])
+```
+
+### registerPlugins
+```ts
+api.registerPlugins( plugins: string[] )
+```
+注册插件，参数为路径数组。该 api 必须在 initPresets 和 initPlugins stage 执行。
+
+e.g.
+```ts
+api.registerPlugins([
+ './plugin',
+ require.resolve('./plugin_foo')
+])
+```
+
+注意： 相较于 `umi@3` ，`umi@4` 不再支持在 `registerPresets` 和 `registerPlugins` 中直接传入插件对象了，现在只允许传入插件的路径。
+
+### registerGenerator
+
+### skipPlugins
+```ts
+api.skipPlugins( keys: string[])
+```
+声明哪些插件需要被禁用，参数为插件 key 的数组
+
+## 扩展方法
+通过`api.registerMethod()` 扩展的方法，它们的作用都是注册一些 hook 以供使用，因此都需要接收一个 fn。这些方法中的大部分都按照 `add-` `modify-` `on-` 的方式命名，它们分别对应了 `api.ApplyPluginsType`的三种方式，不同方式接收的 fn 不太相同，详见 [register](#register) 一节。
+
+注意： 下文提到的所有 fn 都可以是同步的或者异步的（返回一个 Promise 即可）。fn 都可以被
+
+```ts
+{
+ fn,
+ name?: string,
+ before?: string | string[],
+ stage: number,
+}
+
+```
+代替。其中各个参数的作用详见 [tapable](https://github.com/webpack/tapable)
+
+### addBeforeBabelPlugins
+增加额外的 Babel 插件。传入的 fn 不需要参数，且需要返回一个 Babel 插件或插件数组。
+```ts
+api.addBeforeBabelPlugins(() => {
+ // 返回一个 Babel 插件（来源于 Babel 官网的例子）
+ return () => {
+ visitor: {
+ Identifier(path) {
+ const name = path.node.name;
+ path.node.name = name.split("").reverse().join("");
+ }
+ }
+ }
+})
+```
+
+### addBeforeBabelPresets
+增加额外的 Babel 插件集。传入的 fn 不需要参数，且需要返回一个 Babel 插件集( presets )或插件集数组。
+```ts
+api.addBeforeBabelPresets(() => {
+ // 返回一个 Babel 插件集
+ return () => {
+ return {
+ plugins: ["Babel_Plugin_A","Babel_Plugin_B"]
+ }
+ }
+})
+```
+
+### addBeforeMiddlewares
+在 webpack-dev-middleware 之前添加中间件。传入的 fn 不需要参数，且需要返回一个 express 中间件或其数组。
+```ts
+api.addBeforeMiddlewares(() => {
+ return (req, res, next) => {
+ if(false) {
+ res.end('end');
+ }
+ next();
+ }
+})
+```
+
+### addEntryCode
+在入口文件的最后面添加代码（render 后）。传入的 fn 不需要参数，且需要返回一个 string 或者 string 数组。
+```ts
+api.addEntryCode(() => `console.log('I am after render!')`);
+```
+
+### addEntryCodeAhead
+在入口文件的最前面添加代码（render 前，import 后）。传入的 fn 不需要参数，且需要返回一个 string 或者 string 数组。
+```ts
+api.addEntryCodeAhead(() => `console.log('I am before render!')`)
+```
+
+### addEntryImports
+在入口文件中添加 import 语句 （import 最后面）。传入的 fn 不需要参数，其需要返回一个 `{source: string, specifier?: string}` 或其数组。
+```ts
+api.addEntryImports(() => ({
+ source: '/modulePath/xxx.js',
+ specifier: 'moduleName'
+}))
+```
+
+### addEntryImportsAhead
+在入口文件中添加 import 语句 （import 最前面）。传入的 fn 不需要参数，其需要返回一个 `{source: string, specifier?: string}` 或其数组。
+```ts
+api.addEntryImportsAhead(() => ({
+ source: 'anyPackage'
+}))
+```
+
+### addExtraBabelPlugins
+添加额外的 Babel 插件。 传入的 fn 不需要参数，且需要返回一个 Babel 插件或插件数组。
+
+### addExtraBabelPresets
+添加额外的 Babel 插件集。传入的 fn 不需要参数，且需要返回一个 Babel 插件集或其数组。
+
+### addHTMLHeadScripts
+往 HTML 的 `` 元素里添加 Script。传入的 fn 不需要参数，且需要返回一个 string（想要加入的代码） 或者 `{ async?: boolean, charset?: string, crossOrigin?: string | null, defer?: boolean, src?: string, type?: string, content?: string }` 或者它们的数组。
+```ts
+api.addHTMLHeadScripts(() => `console.log('I am in HTML-head')`)
+```
+
+### addHTMLLinks
+往 HTML 里添加 Link 标签。 传入的 fn 不需要参数，返回的对象或其数组接口如下：
+```ts
+{
+ as?: string, crossOrigin: string | null,
+ disabled?: boolean,
+ href?: string,
+ hreflang?: string,
+ imageSizes?: string,
+ imageSrcset?: string,
+ integrity?: string,
+ media?: string,
+ referrerPolicy?: string,
+ rel?: string,
+ rev?: string,
+ target?: string,
+ type?: string
+}
+```
+
+### addHTMLMetas
+往 HTML 里添加 Meta 标签。 传入的 fn 不需要参数，返回的对象或其数组接口如下：
+```ts
+{
+ content?: string,
+ 'http-equiv'?: string,
+ name?: string,
+ scheme?: string
+}
+```
+
+### addHTMLScripts
+往 HTML 尾部添加 Script。 传入的 fn 不需要参数，返回的对象接口同 [addHTMLHeadScripts](#addHTMLHeadScripts)
+
+### addHTMLStyles
+往 HTML 里添加 Style 标签。 传入的 fn 不需要参数，返回一个 string （style 标签里的代码）或者 `{ type?: string, content?: string }`，或者它们的数组。
+
+
+### addLayouts
+添加全局 layout 组件。 传入的 fn 不需要参数，返回 `{ id?: string, file: string }`
+
+### addMiddlewares
+添加中间件，在 route 中间件之后。 传入的 fn 不需要参数，返回 express 中间件。
+
+### addPolyfillImports
+添加补丁 import，在整个应用的最前面执行。 传入的 fn 不需要参数，返回 `{ source: string, specifier?:string }`
+
+### addPrepareBuildPlugins
+
+### addRuntimePlugin
+添加运行时插件，传入的 fn 不需要参数，返回 string ，表示插件的路径。
+
+### addRuntimePluginKey
+添加运行时插件的 Key， 传入的 fn 不需要参数，返回 string ，表示插件的路径。
+
+### addTmpGenerateWatcherPaths
+添加监听路径，变更时会重新生成临时文件。传入的 fn 不需要参数，返回 string，表示要监听的路径。
+
+### addOnDemandDeps
+添加按需安装的依赖，他们会在项目启动时检测是否安装：
+
+```ts
+ api.addOnDemandDeps(() => [{ name: '@swc/core', version: '^1.0.0', dev: true }])
+```
+
+### chainWebpack
+通过 [webpack-chain](https://github.com/neutrinojs/webpack-chain) 的方式修改 webpack 配置。传入一个fn，该 fn 不需要返回值。它将接收两个参数：
+- `memo` 对应 webpack-chain 的 config
+- `args:{ webpack, env }` `arg.webpack` 是 webpack 实例， `args.env` 代表当前的运行环境。
+
+e.g.
+```ts
+api.chainWebpack(( memo, { webpack, env}) => {
+ // set alias
+ memo.resolve.alias.set('a','path/to/a');
+ // Delete progess bar plugin
+ memo.plugins.delete('progess');
+})
+```
+
+### modifyAppData （`umi@4` 新增）
+
+修改 app 元数据。传入的 fn 接收 appData 并且返回它。
+```ts
+api.modifyAppData((memo) => {
+ memo.foo = 'foo';
+ return memo;
+})
+```
+
+### modifyConfig
+修改配置，相较于用户的配置，这份是最终传给 Umi 使用的配置。传入的 fn 接收 config 作为第一个参数，并且返回它。另外 fn 可以接收 `{ paths }` 作为第二个参数。`paths` 保存了 Umi 的各个路径。
+```ts
+api.modifyConfig((memo, { paths }) => {
+ memo.alias = {
+ ...memo.alias,
+ '@': paths.absSrcPath
+ }
+ return memo;
+})
+```
+
+### modifyDefaultConfig
+修改默认配置。传入的 fn 接收 config 并且返回它。
+
+### modifyHTML
+修改 HTML，基于 cheerio 的 ast。传入的 fn 接收 cheerioAPI 并且返回它。另外 fn 还可以接收`{ path }` 作为它的第二个参数，该参数代表路由的 path
+```ts
+api.modifyHTML(($, { path }) => {
+ $('h2').addClass('welcome');
+ return $;
+})
+```
+
+### modifyHTMLFavicon
+修改 HTML 的 favicon 路径。 传入的 fn 接收原本的 favicon 路径(string 类型)并且返回它。
+
+### modifyPaths
+修改 paths，比如 absOutputPath、absTmpPath。传入的 fn 接收 paths 并且返回它。
+
+paths 的接口如下：
+```ts
+paths:{
+ cwd?: string;
+ absSrcPath?: string;
+ absPagesPath?: string;
+ absTmpPath?: string;
+ absNodeModulesPath?: string;
+ absOutputPath?: string;
+}
+```
+
+### modifyRendererPath
+修改 renderer path。传入的 fn 接收原本的 path （string 类型）并且返回它。
+
+### modifyServerRendererPath
+修改 server renderer path。传入的 fn 接收原本的 path （string 类型）并且返回它。
+
+### modifyRoutes
+修改路由。 传入的 fn 接收 id-route 的 map 并且返回它。其中 route 的接口如下：
+```ts
+interface IRoute {
+ path: string;
+ file?: string;
+ id: string;
+ parentId?: string;
+ [key: string]: any;
+}
+```
+e.g.
+```ts
+api.modifyRoutes((memo) => {
+ Object.keys(memo).forEach((id) => {
+ const route = memo[id];
+ if(route.path === '/'){
+ route.path = '/redirect'
+ }
+ });
+ return memo;
+})
+```
+
+### modifyTSConfig
+
+修改临时目录下的 tsconfig 文件内容。
+
+```ts
+api.modifyTSConfig((memo) => {
+ memo.compilerOptions.paths['foo'] = ['bar'];
+ return memo;
+});
+```
+
+### modifyViteConfig
+修改 vite 最终配置。 传入的 fn 接收 vite 的 Config 对象作为第一个参数并且返回它。另外 fn 还可以接收 `{ env }` 作为第二个参数，可以通过该参数获取当前的环境。
+```ts
+api.modifyViteConfig((memo, { env }) => {
+ if(env === 'development'){
+ // do something
+ }
+ return memo;
+})
+```
+### modifyWebpackConfig
+修改 webpack 最终配置。传入的 fn 接收 webpack 的 Config 对象作为第一个参数并且返回它。另外 fn 还可以接收 `{ webpack, env }` 作为第二个参数，其中 webpack 是 webpack 实例，env 代表当前环境。
+
+```ts
+api.modifyWebpackConfig((memo, { webpack, env }) => {
+ // do something
+
+ return memo;
+})
+```
+
+### onBeforeCompiler
+generate 之后，webpack / vite compiler 之前。传入的 fn 不接收任何参数。
+
+### onBeforeMiddleware
+提供在服务器内部执行所有其他中间件之前执行自定义中间件的能力, 这可以用来定义自定义处理程序， 例如:
+
+```ts
+api.onBeforeMiddleware(({ app }) => {
+ app.get('/some/path', function (req, res) {
+ res.json({ custom: 'response' });
+ });
+});
+```
+
+### onBuildComplete
+build 完成时。传入的 fn 接收 `{ isFirstCompile: boolean, stats, time: number, err?: Error }` 作为参数。
+
+### onBuildHtmlComplete
+build 完成且 html 完成构建之后。
+
+### onCheck
+检查时，在 onStart 之前执行。传入的 fn 不接收任何参数
+
+### onCheckCode
+检查代码时。传入的 fn 接收的参数接口如下：
+```ts
+args: {
+ file: string;
+ code: string;
+ isFromTmp: boolean;
+ imports: {
+ source: string;
+ loc: any;
+ default: string;
+ namespace: string;
+ kind: babelImportKind;
+ specifiers: Record;
+ }[];
+ exports: any[];
+ cjsExports: string[];
+}
+```
+
+### onCheckConfig
+检查 config 时。传入的 fn 接收 `{ config, userConfig }`作为参数，它们分别表示实际的配置和用户的配置。
+
+### onCheckPkgJSON
+检查 package.json 时。传入的 fn 接收 `{origin?, current}` 作为参数。它们的类型都是 package.json 对象
+
+### onDevCompileDone
+dev 完成时。传入的 fn 接收的参数接口如下：
+```ts
+args: {
+ isFirstCompile: boolean;
+ stats: any;
+ time: number;
+}
+```
+
+### onGenerateFiles
+生成临时文件时，随着文件变化会频繁触发，有缓存。 传入的 fn 接收的参数接口如下：
+```ts
+args: {
+ isFirstTime?: boolean;
+ files?: {
+ event: string;
+ path: string;
+ } | null;
+}
+```
+
+
+### onPatchRoute
+匹配单个路由，可以修改路由，给路由打补丁
+
+
+### onPkgJSONChanged
+package.json 变更时。传入的 fn 接收 `{origin?, current}` 作为参数。它们的类型都是 package.json 对象
+
+### onPrepareBuildSuccess
+
+### onStart
+启动时。传入的 fn 不接收任何参数。
+
+
+### writeTmpFile
+`api.writeTmpFile()`的 type 参数的类型。
+
+- content: 写入的文本内容，有内容就不会使用模板。
+- context: 模板上下文。
+- noPluginDir: 是否使用插件名做为目录。
+- path: 写入文件的路径。
+- tpl: 使用模板字符串，没有模板路径会使用它。
+- tplPath: 使用模板文件的路径。
+
+
+## 属性
+从 api 可以直接访问到的属性，这些属性有一部分来自于 service
+
+### appData
+
+### args
+命令行参数，这里去除了命令本身。
+
+e.g.
+- `$ umi dev --foo`, args 为 `{ _:[], foo: true }`
+- `$ umi g page index --typescript --less` , args 为 `{ _: [ 'page', 'index''], typescript: true, less: true }`
+
+### config
+最终的配置（取决于你访问的时机，可能是当前收集到的最终配置）
+
+### cwd
+当前路径
+
+### env
+即 `process.env.NODE_ENV` 可能有 `development`、`production` 和 `test`
+
+### logger
+插件日志对象，包含 `{ log, info, debug, error, warn, profile }`，他们都是方法。其中 `api.logger.profile` 可用于性能耗时记录。
+
+```ts
+api.logger.profile('barId');
+setTimeout(() => {
+ api.logger.profile('barId');
+})
+// profile - barId Completed in 6254ms
+```
+
+### name
+当前命令的名称，例如 `$ umi dev `， `name` 就是 `dev`
+
+### paths
+项目相关的路径：
+- `absNodeModulesPath`，node_modules 目录绝对路径
+- `absOutputPath`，输出路径，默认是 ./dist
+- `absPagesPath`，pages 目录绝对路径
+- `absSrcPath`，src 目录绝对路径，需注意 src 目录是可选的，如果没有 src 目录，absSrcPath 等同于 cwd
+- `absTmpPath`，临时目录绝对路径
+- `cwd`，当前路径
+
+注意： 注册阶段不能获取到。因此不能在插件里直接获取，要在 hook 里使用。
+
+### pkg
+当前项目的 `package.json` 对象
+
+### pkgPath
+当前项目的 `package.json` 的绝对路径。
+
+### plugin
+当前插件的对象。
+- `type` 插件类型，有 preset 和 plugin 两种
+- `path` 插件路径
+- `id` 插件 id
+- `key` 插件 key
+- `config` 插件的配置
+- `enableBy` 插件的启用方式
+
+注意： 注册阶段使用的 plugin 对象是你 `describe` 之前的对象。
+
+### service
+Umi 的 `Service` 实例。通常不需要用到，除非你知道为什么。
+
+### userConfig
+用户的配置，从 `.umirc` 或 `config/config` 中读取的内容，没有经过 defaultConfig 以及插件的任何处理。可以在注册阶段使用。
+
+### ApplyPluginsType
+`api.applyPlugins()` 的 type 参数的类型。包含
+- add
+- modify
+- event
+
+### ConfigChangeType
+为 `api.describe()` 提供 `config.onChange` 的类型，目前包含两种：
+- restart，重启 dev 进程，是默认值
+- regenerateTmpFiles，重新生成临时文件
+
+### EnableBy
+插件的启用方式，包含三种：
+- register
+- config
+
+### ServiceStage
+Umi service 的运行阶段。有如下阶段：
+- uninitialized
+- init
+- initPresets
+- initPlugins
+- resolveConfig
+- collectAppData
+- onCheck
+- onStart
+- runCommand
diff --git a/docs/docs/api/runtime-config.md b/docs/docs/api/runtime-config.md
index 89432508ff38..076b62340f92 100644
--- a/docs/docs/api/runtime-config.md
+++ b/docs/docs/api/runtime-config.md
@@ -1,14 +1,14 @@
-# 运行时配置
+# Runtime Configuration
-运行时配置和配置的区别是他跑在浏览器端，基于此，我们可以在这里写函数、tsx、import 浏览器端依赖等等，注意不要引入 node 依赖。
+The difference between runtime configuration and regular configuration is that runtime configuration runs on the browser side. Based on this, you can write functions, TypeScript JSX, and import browser-specific dependencies. Be cautious not to include Node.js dependencies.
-## 配置方式
+## Configuration Approach
-约定 `src/app.tsx` 为运行时配置。
+Conventionally, `src/app.tsx` is used for runtime configuration.
-## TypeScript 提示
+## TypeScript Suggestions
-如果你想在写配置时也有提示，可以通过 umi 的 defineApp 方法定义配置。
+If you want to have suggestions while writing configurations, you can define configurations using Umi's `defineApp` method.
```js
import { defineApp } from 'umi';
@@ -29,15 +29,15 @@ export const layout: RuntimeConfig['layout'] = () => {
};
```
-## 配置项
+## Configuration Items
-> 以下配置项按字母排序。
+> The following configuration items are listed in alphabetical order.
### dva
-如果你使用的 dva，那么支持配置 dva 插件的运行时配置，具体参考[插件配置](../max/dva)。
+If you are using dva, you can configure the runtime options for dva plugins. Refer to the [Plugin Configuration](../max/dva) for more details.
-比如：
+For example:
```ts
export default {
@@ -51,25 +51,25 @@ export default {
#### extraModels
- Type: string[]
-- Default: [] 配置额外到 dva model。
+- Default: [] Configure additional dva models.
#### immer
- Type: boolean | object
-- Default: false 表示是否启用 immer 以方便修改 reducer。
+- Default: false Indicates whether to enable immer for easier reducer modification.
-注：如需兼容 IE11，需配置 `{ immer: { enableES5: true }}`。
+Note: To maintain compatibility with IE11, configure `{ immer: { enableES5: true }}`.
-### 数据流
+### Data Flow
-若你需要定义初始化数据，使用 `getInitialState` 、`useModel` 等 [数据流](../max/data-flow) 相关功能：
+If you need to define initial data or use features like `getInitialState` and `useModel` in [Data Flow](../max/data-flow):
-1. 你可以创建自带数据流功能的 `@umijs/max` 项目，详见 [Umi max 简介](../max/introduce) 。
+1. You can create an `@umijs/max` project with built-in data flow functionality. Refer to [Umi Max Introduction](../max/introduce) for more details.
-2. 或者手动开启数据流功能的插件使用该功能：
+2. Alternatively, you can manually enable data flow functionality using plugins:
```bash
- pnpm add -D @umijs/plugins
+ pnpm add -D @umijs/plugins
```
```ts
@@ -86,9 +86,9 @@ export default {
### layout
-修改[内置布局](../max/layout-menu)的配置，比如配置退出登陆、自定义导航暴露的渲染区域等。
+Modify the configuration of the [built-in layout](../max/layout-menu), such as configuring logout, customizing the rendered area exposed by navigation, and more.
-> 注意：需要开启 [layout](../api/config#layout) 插件，才能使用它的运行时配置。
+> Note: You need to enable the [layout](../api/config#layout) plugin to use its runtime configuration.
```js
export const layout = {
@@ -96,13 +96,13 @@ export const layout = {
};
```
-更多具体配置参考[插件文档](../max/layout-menu#运行时配置)。
+For more specific configurations, refer to the [Plugin Documentation](../max/layout-menu#runtime-configuration).
### onRouteChange(\{ routes, clientRoutes, location, action, basename, isFirst \})
-在初始加载和路由切换时做一些事情。
+Perform actions when initially loading or changing routes.
-比如用于做埋点统计，
+For example, use it for tracking analytics:
```ts
export function onRouteChange({
@@ -113,11 +113,11 @@ export function onRouteChange({
basename,
isFirst,
}) {
- bacon(location.pathname);
+ trackAnalytics(location.pathname);
}
```
-比如用于设置标题，
+Use it to set titles:
```ts
import { matchRoutes } from 'umi';
@@ -138,17 +138,17 @@ export function patchRoutes({ routes, routeComponents }) {
}
```
-- `routes`: 打平的路由列表。
+- `routes`: Flattened route list.
-- `routeComponents`: 路由对应的组件映射。
+- `routeComponents`: Mapping of routes to components.
-注：如需动态更新路由，建议使用 `patchClientRoutes()` ，否则你可能需要同时修改 `routes` 和 `routeComponents`。
+Note: If you need to dynamically update routes, it is recommended to use `patchClientRoutes()`, otherwise you may need to modify both `routes` and `routeComponents` simultaneously.
### patchClientRoutes(\{ routes \})
-修改被 react-router 渲染前的树状路由表，接收内容同 [useRoutes](https://reactrouter.com/en/main/hooks/use-routes)。
+Modify the tree-shaped routing table before it is rendered by react-router. Receives content similar to [useRoutes](https://reactrouter.com/en/main/hooks/use-routes).
-比如在最前面添加一个 `/foo` 路由，
+For example, add a `/foo` route at the beginning:
```tsx
import Page from '@/extraRoutes/foo';
@@ -161,7 +161,7 @@ export function patchClientRoutes({ routes }) {
}
```
-比如在最前面添加一个重定向路由：
+Add a redirect route at the beginning:
```tsx
import { Navigate } from 'umi';
@@ -174,7 +174,7 @@ export const patchClientRoutes = ({ routes }) => {
};
```
-比如添加一个嵌套路由：
+Add a nested route:
```tsx
import Page from '@/extraRoutes/foo';
@@ -190,13 +190,13 @@ export const patchClientRoutes = ({ routes }) => {
};
```
-比如和 `render` 配置配合使用，请求服务端根据响应动态更新路由，
+Use in conjunction with the `render` configuration to dynamically update routes based on server responses:
```ts
let extraRoutes;
export function patchClientRoutes({ routes }) {
- // 根据 extraRoutes 对 routes 做一些修改
+ // Modify routes based on extraRoutes
patch(routes, extraRoutes);
}
@@ -210,19 +210,19 @@ export function render(oldRender) {
}
```
-注意：
+Note:
-- 直接修改 routes，不需要返回
+- Directly modify `routes` without needing to return anything.
### qiankun
-Umi 内置了 `qiankun` 插件来提供微前端的能力，具体参考[插件配置](../max/micro-frontend)。
+Umi comes with a built-in `qiankun` plugin to provide micro-frontends capabilities. Refer to [Plugin Configuration](../max/micro-frontend) for more details.
### render(oldRender: `Function`)
-覆写 render。
+Override the `render` function.
-比如用于渲染之前做权限校验，
+For example, use it to perform permission checks before rendering:
```bash
export function render(oldRender) {
@@ -238,13 +238,13 @@ export function render(oldRender) {
### request
-如果你使用了 `import { request } from 'umi';` 来请求数据，那么你可以通过该配置来自定义中间件、拦截器、错误处理适配等。具体参考 [request](../max/request) 插件配置。
+If you use `import { request } from 'umi';` to make data requests, you can use this configuration to customize middleware, interceptors, error handling, and more. Refer to the [request](../max/request) plugin configuration for more details.
### rootContainer(lastRootContainer, args)
-修改交给 react-dom 渲染时的根组件。
+Modify the root component handed over to react-dom for rendering.
-比如用于在外面包一个 Provider，
+For example, use it to wrap a Provider around the container:
```js
export function rootContainer(container) {
@@ -252,12 +252,12 @@ export function rootContainer(container) {
}
```
-args 包含：
+`args` contains:
-- routes，全量路由配置
-- plugin，运行时插件机制
-- history，history 实例
+- `routes`: The full route configuration
+- `plugin`: Runtime plugin mechanism
+- `history`: History instance
-## 更多配置
+## More configuration
-Umi 允许插件注册运行时配置，如果你使用插件，肯定会在插件里找到更多运行时的配置项。
+Umi allows plugins to register runtime configuration. If you use plugins, you will definitely find more runtime configuration items in the plugin.
diff --git a/docs/docs/api/runtime-config.zh-CN.md b/docs/docs/api/runtime-config.zh-CN.md
new file mode 100644
index 000000000000..89432508ff38
--- /dev/null
+++ b/docs/docs/api/runtime-config.zh-CN.md
@@ -0,0 +1,263 @@
+# 运行时配置
+
+运行时配置和配置的区别是他跑在浏览器端，基于此，我们可以在这里写函数、tsx、import 浏览器端依赖等等，注意不要引入 node 依赖。
+
+## 配置方式
+
+约定 `src/app.tsx` 为运行时配置。
+
+## TypeScript 提示
+
+如果你想在写配置时也有提示，可以通过 umi 的 defineApp 方法定义配置。
+
+```js
+import { defineApp } from 'umi';
+export default defineApp({
+ layout: () => {
+ return {
+ title: 'umi',
+ };
+ },
+});
+
+// or
+import { RuntimeConfig } from 'umi';
+export const layout: RuntimeConfig['layout'] = () => {
+ return {
+ title: 'umi',
+ };
+};
+```
+
+## 配置项
+
+> 以下配置项按字母排序。
+
+### dva
+
+如果你使用的 dva，那么支持配置 dva 插件的运行时配置，具体参考[插件配置](../max/dva)。
+
+比如：
+
+```ts
+export default {
+ dva: {
+ immer: true,
+ extraModels: [],
+ },
+};
+```
+
+#### extraModels
+
+- Type: string[]
+- Default: [] 配置额外到 dva model。
+
+#### immer
+
+- Type: boolean | object
+- Default: false 表示是否启用 immer 以方便修改 reducer。
+
+注：如需兼容 IE11，需配置 `{ immer: { enableES5: true }}`。
+
+### 数据流
+
+若你需要定义初始化数据，使用 `getInitialState` 、`useModel` 等 [数据流](../max/data-flow) 相关功能：
+
+1. 你可以创建自带数据流功能的 `@umijs/max` 项目，详见 [Umi max 简介](../max/introduce) 。
+
+2. 或者手动开启数据流功能的插件使用该功能：
+
+ ```bash
+ pnpm add -D @umijs/plugins
+ ```
+
+ ```ts
+ // .umirc.ts
+ export default {
+ plugins: [
+ '@umijs/plugins/dist/initial-state',
+ '@umijs/plugins/dist/model',
+ ],
+ initialState: {},
+ model: {},
+ };
+ ```
+
+### layout
+
+修改[内置布局](../max/layout-menu)的配置，比如配置退出登陆、自定义导航暴露的渲染区域等。
+
+> 注意：需要开启 [layout](../api/config#layout) 插件，才能使用它的运行时配置。
+
+```js
+export const layout = {
+ logout: () => {}, // do something
+};
+```
+
+更多具体配置参考[插件文档](../max/layout-menu#运行时配置)。
+
+### onRouteChange(\{ routes, clientRoutes, location, action, basename, isFirst \})
+
+在初始加载和路由切换时做一些事情。
+
+比如用于做埋点统计，
+
+```ts
+export function onRouteChange({
+ location,
+ clientRoutes,
+ routes,
+ action,
+ basename,
+ isFirst,
+}) {
+ bacon(location.pathname);
+}
+```
+
+比如用于设置标题，
+
+```ts
+import { matchRoutes } from 'umi';
+
+export function onRouteChange({ clientRoutes, location }) {
+ const route = matchRoutes(clientRoutes, location.pathname)?.pop()?.route;
+ if (route) {
+ document.title = route.title || '';
+ }
+}
+```
+
+### patchRoutes(\{ routes \})
+
+```ts
+export function patchRoutes({ routes, routeComponents }) {
+ console.log('patchRoutes', routes, routeComponents);
+}
+```
+
+- `routes`: 打平的路由列表。
+
+- `routeComponents`: 路由对应的组件映射。
+
+注：如需动态更新路由，建议使用 `patchClientRoutes()` ，否则你可能需要同时修改 `routes` 和 `routeComponents`。
+
+### patchClientRoutes(\{ routes \})
+
+修改被 react-router 渲染前的树状路由表，接收内容同 [useRoutes](https://reactrouter.com/en/main/hooks/use-routes)。
+
+比如在最前面添加一个 `/foo` 路由，
+
+```tsx
+import Page from '@/extraRoutes/foo';
+
+export function patchClientRoutes({ routes }) {
+ routes.unshift({
+ path: '/foo',
+ element:
-经常使用 XSwitch 的话，可新建一个规则保存。
+If you frequently use XSwitch, you can create a rule to save it for later use.
diff --git a/docs/docs/guides/debug.zh-CN.md b/docs/docs/guides/debug.zh-CN.md
new file mode 100644
index 000000000000..655d439c0f7e
--- /dev/null
+++ b/docs/docs/guides/debug.zh-CN.md
@@ -0,0 +1,74 @@
+import { Message } from 'umi';
+
+# 调试
+
+除了使用浏览器的调试工具来完成开发中的调试外，Umi 还推荐以下调试方式来协助项目的调试。
+
+## 调试 dev 产物
+
+如果你需要在 dev 阶段调试项目的构建产物，以 `umi.js` 举例。先将原来的 `umi.js` 下载到当前项目根目录下。根据调试需要进行编辑后，刷新浏览器，项目使用的 `umi.js` 就替换成了根目录下的 `umi.js` 文件。调试完毕需要恢复就直接删除根目录的 `umi.js` 即可。
+
+举例：
+```bash
+# 下载当前项目的 umi.js
+$curl http://127.0.0.1:8000/umi.js -O
+
+# 增加想调试的内容，举例增加 "debug!!!" 弹窗
+$ echo -e '\n;alert("debug!!!");\n' >> umi.js
+# 打开浏览器就能看到 alert 弹窗
+
+# 退出调试，恢复到正常状态
+$rm umi.js
+```
+
+以此类推即可调试其他的 JavaScript 文件。
+
+## XSwitch
+
+如果需要在特定的域名环境调试或者验证当前的修改的代码，推荐使用 Chrome 插件 [XSwitch](https://chrome.google.com/webstore/detail/xswitch/idkjhjggpffolpidfkikidcokdkdaogg)。
+
+
+
+
+
+假设我们想在线上项目地址 `https://www.myproject.com` 上调试本地代码。项目使用 `https://www.myproject.com/umi.hash.js`，为了验证本地的项目，需要将它替换成本地开发环境的 `http://127.0.0.1:000/umi.js`
+
+首先使用环境变量 `SOCKET_SERVER` 启动本地环境（防止因为连接不上 socket server 导致页面不断刷新）。
+```bash
+$SOCKET_SERVER=http://127.0.0.1:8000/ npx umi dev
+```
+
+然后，在 XSwitch 中配置资源转发规则。
+```json
+{
+ "proxy": [
+ // 数组的第 0 项的资源会被第 1 项目替换
+ [
+ "https://www.myproject.com/umi.2c8a01df.js",
+ "http://127.0.0.1:8000/umi.js"
+ ],
+ // 使用正则可以方便处理分包情况下 js 资源的加载
+ [
+ "https://www.myproject.com/(.*\.js)",
+ "http://127.0.0.1:8000/$1",
+ ],
+ // 如果需要验证视觉表现，不要忘记替换 css 资源
+ [
+ "https://www.myproject.com/umi.ae8b10e0.css",
+ "http://127.0.0.1:8000/umi.css"
+ ]
+ ]
+}
+```
+
+刷新页面，正式域名下的内容就被替换了，这个时候就能方便的指定环境下调试了。
+
+如果要退出调试，关闭 XSwitch 插件功能即可。
+
+
+
+
+经常使用 XSwitch 的话，可新建一个规则保存。
+
+
+
diff --git a/docs/docs/guides/deployment.zh-CN.md b/docs/docs/guides/deployment.zh-CN.md
new file mode 100644
index 000000000000..20a15eec7a06
--- /dev/null
+++ b/docs/docs/guides/deployment.zh-CN.md
@@ -0,0 +1 @@
+# 部署
diff --git a/docs/docs/guides/directory-structure.md b/docs/docs/guides/directory-structure.md
index cde3f80dfa22..ca42f59adb9f 100644
--- a/docs/docs/guides/directory-structure.md
+++ b/docs/docs/guides/directory-structure.md
@@ -1,8 +1,8 @@
-import { Message } from 'umi'
+import { Message } from 'umi';
-# 目录结构
+# Directory Structure
-这里罗列了 Umi 项目中约定(或推荐)的目录结构，在项目开发中，请遵照这个目录结构组织代码。
+Here is the directory structure convention (or recommendation) for Umi projects. When developing a project, organize your code following this directory structure.
```bash
.
@@ -23,9 +23,9 @@ import { Message } from 'umi'
│ ├── pages
│ │ ├── index.less
│ │ └── index.tsx
-│ ├── utils // 推荐目录
+│ ├── utils // Recommended directory
│ │ └── index.ts
-│ ├── services // 推荐目录
+│ ├── services // Recommended directory
│ │ └── api.ts
│ ├── app.(ts|tsx)
│ ├── global.ts
@@ -40,20 +40,21 @@ import { Message } from 'umi'
│ └── mfsu-deps
├── .env
├── plugin.ts
-├── .umirc.ts // 与 config/config 文件 2 选一
+├── .umirc.ts // Choose either .umirc.ts or config/config.ts
├── package.json
├── tsconfig.json
└── typings.d.ts
```
-## 根目录
+
+## Root Directory
### package.json
-与 Umi 3 不同，Umi 4 不会自动注册 `package.json` 中以 `@umijs/preset-`、`@umijs/plugin-`、`umi-preset-` 和 `umi-plugin-` 开头的插件、预设，若你需要自定义额外的插件、预设，需要手动配置到 [`plugins`](../api/config#plugins) 。
+Unlike Umi 3, Umi 4 doesn't automatically register plugins and presets that start with `@umijs/preset-`, `@umijs/plugin-`, `umi-preset-`, and `umi-plugin-` from the `package.json`. If you want to use custom plugins or presets, you need to manually configure them in the [`plugins`](../api/config#plugins) section.
### .env
-环境变量，比如：
+Environment variables, for example:
```text
PORT=8888
@@ -62,11 +63,11 @@ COMPRESS=none
### .umirc.ts
-> 与 `config/config.ts` 文件功能相同，2 选 1 。`.umirc.ts` 文件优先级较高
+> Same functionality as `config/config.ts`, choose either one. `.umirc.ts` has higher priority.
-配置文件，包含 Umi 所有[非运行时配置](../api/config)（运行时配置一般定义于 [`app.ts`](#apptstsx)）。
+Configuration file containing all of Umi's [non-runtime configurations](../api/config) (runtime configurations are usually defined in [`app.ts`](#apptstsx)).
-若你需要在不同环境中加载不同配置，这在 Umi 中是根据 [`UMI_ENV`](./env-variables#umi_env) 来实现的，一个不同环境启动的例子：
+If you need to load different configurations in different environments, you can achieve this in Umi by using the [`UMI_ENV`](./env-variables#umi_env) variable. Here's an example of starting different environments:
```ts
// package.json
@@ -80,65 +81,63 @@ COMPRESS=none
### config/config.ts
-> 与 `.umirc.ts` 文件功能相同，2 选 1 。`.umirc.ts` 文件优先级较高
-
-与 [`.umirc.ts`](#umircts) 相同，区别是你可以单独在一个 `config` 文件夹下集中管理所有的配置，保持项目根目录整洁。
+> Same functionality as `.umirc.ts`, but you can centralize all configurations in a `config` folder to keep the root directory clean.
-### dist 目录
+### dist Directory
-执行 `umi build` 后产物的默认输出文件夹。可通过 [`outputPath`](../api/config#outputpath) 配置修改产物输出文件夹。
+The default output folder for artifacts generated after running `umi build`. You can modify the output folder using [`outputPath`](../api/config#outputpath) configuration.
-### mock 目录
+### mock Directory
-存放 mock 文件，此目录下所有 `.ts` / `.js` 文件会被 mock 服务加载，从而提供模拟数据，使用方法详见 [Mock](./mock) 。
+This directory is used to store mock files. All `.ts` / `.js` files in this directory will be loaded by the mock service to provide mock data. Learn more about usage in [Mock](./mock).
-### public 目录
+### public Directory
-存放固定的静态资源，如存放 `public/image.png` ，则开发时可以通过 `/image.png` 访问到，构建后会被拷贝到输出文件夹。
+This directory is used to store fixed static resources. For instance, if you have a file named `public/image.png`, you can access it as `/image.png` during development. After building, it will be copied to the output folder.
-注：
+Note:
-1. 对于 svg 资源，Umi 支持 [svgr](../api/config#svgr) ，可以直接导入作为组件使用：
+1. For SVG resources, Umi supports [svgr](../api/config#svgr) and you can directly import SVG files as components:
```ts
import SmileUrl, { ReactComponent as SvgSmile } from './smile.svg';
// 
>
+ //
```
-### `src` 目录
+### `src` Directory
-#### .umi 目录
+#### .umi Directory
-**不要提交 `.umi` 临时文件到 git 仓库，默认已在 `.gitignore` 被忽略。**
+**Do not commit `.umi` temporary files to the git repository. They are ignored by default in `.gitignore`.**
-dev 时的临时文件目录，比如入口文件、路由等，都会被临时生成到这里。
+This is the temporary files directory during development. It contains temporary files such as entry files and routes.
-#### .umi-production 目录
+#### .umi-production Directory
-**不要提交 `.umi-production` 临时文件到 git 仓库，默认已在 `.gitignore` 被忽略。**
+**Do not commit `.umi-production` temporary files to the git repository. They are ignored by default in `.gitignore`.**
-build 时的临时文件目录，比如入口文件、路由等，都会被临时生成到这里。
+This is the temporary files directory during building. It contains temporary files such as entry files and routes.
#### app.[ts｜tsx]
-[运行时配置](../api/runtime-config) 文件，可以在这里扩展运行时的能力，比如修改路由、修改 render 方法等。
+[Runtime configuration](../api/runtime-config) file. You can extend the runtime capabilities here, such as modifying routes, modifying the render method, etc.
-运行时配置带来的逻辑会在浏览器中运行，因此当有远程配置、动态内容时，这些我们在本地开发时还不确定，不能写死，所以需要在浏览器实际运行项目时动态获取他们。
+The logic introduced by the runtime configuration will run in the browser. Therefore, when you have remote configuration or dynamic content that cannot be hard-coded during local development, you need to dynamically obtain them when the project is actually running in the browser.
#### layouts/index.tsx
-全局布局，默认会在所有路由下生效，比如有以下路由关系：
+Global layout. It is applied to all routes by default. For example, consider the following route configuration:
```
[
@@ -147,7 +146,7 @@ build 时的临时文件目录，比如入口文件、路由等，都会被临
]
```
-输出为：
+The output will be:
```jsx
@@ -156,7 +155,7 @@ build 时的临时文件目录，比如入口文件、路由等，都会被临
```
-当你需要关闭 layout 时可以使用 `layout: false` ，当你需要更多层 layout 时，可以考虑使用 [`wrappers`](./routes#wrappers) ，仅在配置式路由可用：
+You can disable the layout using `layout: false`. If you need nested layouts, you can consider using [`wrappers`](./routes#wrappers), which is only available for configuration-based routes:
```ts
routes: [
@@ -169,11 +168,11 @@ build 时的临时文件目录，比如入口文件、路由等，都会被临
]
```
-#### pages 目录
+#### pages Directory
-约定式路由默认以 `pages/*` 文件夹的文件层级结构来生成路由表。
+Conventional routes are generated based on the file hierarchy within the `pages/*` folder.
-在配置式路由中，`component` 若写为相对路径，将从该文件夹为起点开始寻找文件：
+In configuration-based routing, if `component` is written as a relative path, it will start looking for files from this directory:
```ts
routes: [
@@ -182,9 +181,9 @@ build 时的临时文件目录，比如入口文件、路由等，都会被临
]
```
-##### 基础路由
+##### Basic Routing
-假设 `pages` 目录结构如下：
+Assuming the directory structure of `pages` is as follows:
```
+ pages/
@@ -193,7 +192,7 @@ build 时的临时文件目录，比如入口文件、路由等，都会被临
- index.tsx
```
-那么，会自动生成路由配置如下：
+The generated route configuration will be:
```ts
[
@@ -202,9 +201,9 @@ build 时的临时文件目录，比如入口文件、路由等，都会被临
]
```
-##### 动态路由
+##### Dynamic Routing
-约定带 `$` 前缀的目录或文件为动态路由。若 `$` 后不指定参数名，则代表 `*` 通配，比如以下目录结构：
+Directories or files prefixed with `$` are considered dynamic routes. If no parameter name is specified after `$`, it represents the `*` wildcard. For example, consider the following directory structure:
```
+ pages/
@@ -215,9 +214,9 @@ build 时的临时文件目录，比如入口文件、路由等，都会被临
- index.tsx
```
-会生成路由配置如下：
+The generated route configuration will be:
-```ts
+```
[
{ path: '/', component: '@/pages/index.tsx' },
{ path: '/foo/:slug', component: '@/pages/foo/$slug.tsx' },
@@ -227,7 +226,7 @@ build 时的临时文件目录，比如入口文件、路由等，都会被临
##### pages/404.tsx
-在使用约定式路由时，该文件会自动被注册为全局 404 的 fallback 页面。若你使用配置式路由，需要自行配置兜底路由到路由表最后一个：
+In conventional routing, this file is automatically registered as the global fallback page for 404 errors. If you use configuration-based routing, you need to manually configure a catch-all route to this file as the last route in the route configuration:
```ts
routes: [
@@ -238,39 +237,39 @@ build 时的临时文件目录，比如入口文件、路由等，都会被临
#### global.(j|t)sx?
-全局前置脚本文件。
+Global pre-script file.
-Umi 区别于其他前端框架，没有显式的程序主入口（如 `src/index.ts`），所以当你有需要在应用前置、全局运行的逻辑时，优先考虑写入 `global.ts` 。
+Unlike other frontend frameworks, Umi doesn't have an explicit main entry point (like `src/index.ts`). When you need logic to run globally or before the application starts, consider adding it to `global.ts`.
-当你需要添加全局 Context 、修改应用运行时，请使用 [`app.tsx`](#apptstsx) 。
+If you need to add global context or modify the application runtime, use [`app.tsx`](#apptstsx).
#### global.(css|less|sass|scss)
-全局样式文件。
+Global style file.
-当你有需要全局使用的样式时，请考虑加入此文件。
+When you need styles to be applied globally, consider adding them to this file.
-需要注意的是，此文件的优先级在第三方组件库的样式之后，所以当你有覆盖第三方库样式的需求时，请使用 [`overrides.css`](#overridescsslesssassscss) 。
+Note that this file has a lower priority than third-party component library styles. So, if you need to override styles from a third-party library, use [`overrides.css`](#overridescsslesssassscss).
#### overrides.(css|less|sass|scss)
-高优先级全局样式文件。
+High-priority global style file.
-该文件一般专用于覆盖第三方库样式，其中所有 CSS 选择器都会附加 `body` 前缀以抬高优先级。
+This file is typically used to override third-party library styles. All CSS selectors in this file are prefixed with `body` to increase their specificity.
#### loading.(tsx|jsx)
-全局加载组件。
+Global loading component.
-Umi 4 默认 [按页分包](../../blog/code-splitting) ，从而在页面切换时存在加载过程，通过该文件来配置加载动画。
+Umi 4 defaults to [page-based splitting](../../blog/code-splitting), which introduces a loading process when switching pages. Use this file to configure loading animations.
### plugin.ts
-项目级 Umi 插件。
+Project-level Umi plugins.
-当你有 Umi 定制需求时，往往会用到 [插件 API](../api/plugin-api) （比如 [修改产物 html](../api/plugin-api#modifyhtml)），此时可创建该文件进行自定义：
+When you have custom requirements for Umi, you'll often need to use [plugin APIs](../api/plugin-api) (e.g., [modify HTML output](../api/plugin-api#modifyhtml)). You can create this file for customization:
```ts
import type { IApi } from 'umi';
@@ -292,12 +291,12 @@ export default (api: IApi) => {
### favicon
-站点 `favicon` 图标文件。
+Site `favicon` icon file.
-当存在 `src/favicon.(ico|gif|png|jpg|jpeg|svg|avif|webp)` 文件时，将会自动在产物中添加站点 `favicon` ：
+When the `src/favicon.(ico|gif|png|jpg|jpeg|svg|avif|webp)` file exists, it will automatically add a `favicon` link to the produced HTML:
```html
```
-若使用外部资源等，可以使用 [favicons](../api/config#favicons) 手动配置站点图标，配置值优先于约定。
+If you use external resources, you can manually configure the site icon using [favicons](../api/config#favicons), and the configured value takes precedence over conventions.
\ No newline at end of file
diff --git a/docs/docs/guides/directory-structure.zh-CN.md b/docs/docs/guides/directory-structure.zh-CN.md
new file mode 100644
index 000000000000..cde3f80dfa22
--- /dev/null
+++ b/docs/docs/guides/directory-structure.zh-CN.md
@@ -0,0 +1,303 @@
+import { Message } from 'umi'
+
+# 目录结构
+
+这里罗列了 Umi 项目中约定(或推荐)的目录结构，在项目开发中，请遵照这个目录结构组织代码。
+
+```bash
+.
+├── config
+│ └── config.ts
+├── dist
+├── mock
+│ └── app.ts｜tsx
+├── src
+│ ├── .umi
+│ ├── .umi-production
+│ ├── layouts
+│ │ ├── BasicLayout.tsx
+│ │ ├── index.less
+│ ├── models
+│ │ ├── global.ts
+│ │ └── index.ts
+│ ├── pages
+│ │ ├── index.less
+│ │ └── index.tsx
+│ ├── utils // 推荐目录
+│ │ └── index.ts
+│ ├── services // 推荐目录
+│ │ └── api.ts
+│ ├── app.(ts|tsx)
+│ ├── global.ts
+│ ├── global.(css|less|sass|scss)
+│ ├── overrides.(css|less|sass|scss)
+│ ├── favicon.(ico|gif|png|jpg|jpeg|svg|avif|webp)
+│ └── loading.(tsx|jsx)
+├── node_modules
+│ └── .cache
+│ ├── bundler-webpack
+│ ├── mfsu
+│ └── mfsu-deps
+├── .env
+├── plugin.ts
+├── .umirc.ts // 与 config/config 文件 2 选一
+├── package.json
+├── tsconfig.json
+└── typings.d.ts
+```
+## 根目录
+
+### package.json
+
+与 Umi 3 不同，Umi 4 不会自动注册 `package.json` 中以 `@umijs/preset-`、`@umijs/plugin-`、`umi-preset-` 和 `umi-plugin-` 开头的插件、预设，若你需要自定义额外的插件、预设，需要手动配置到 [`plugins`](../api/config#plugins) 。
+
+### .env
+
+环境变量，比如：
+
+```text
+PORT=8888
+COMPRESS=none
+```
+
+### .umirc.ts
+
+> 与 `config/config.ts` 文件功能相同，2 选 1 。`.umirc.ts` 文件优先级较高
+
+配置文件，包含 Umi 所有[非运行时配置](../api/config)（运行时配置一般定义于 [`app.ts`](#apptstsx)）。
+
+若你需要在不同环境中加载不同配置，这在 Umi 中是根据 [`UMI_ENV`](./env-variables#umi_env) 来实现的，一个不同环境启动的例子：
+
+```ts
+// package.json
+{
+ "scripts": {
+ "dev": "umi dev",
+ "dev:pre": "cross-env UMI_ENV=pre umi dev"
+ }
+}
+```
+
+### config/config.ts
+
+> 与 `.umirc.ts` 文件功能相同，2 选 1 。`.umirc.ts` 文件优先级较高
+
+与 [`.umirc.ts`](#umircts) 相同，区别是你可以单独在一个 `config` 文件夹下集中管理所有的配置，保持项目根目录整洁。
+
+### dist 目录
+
+执行 `umi build` 后产物的默认输出文件夹。可通过 [`outputPath`](../api/config#outputpath) 配置修改产物输出文件夹。
+
+### mock 目录
+
+存放 mock 文件，此目录下所有 `.ts` / `.js` 文件会被 mock 服务加载，从而提供模拟数据，使用方法详见 [Mock](./mock) 。
+
+### public 目录
+
+存放固定的静态资源，如存放 `public/image.png` ，则开发时可以通过 `/image.png` 访问到，构建后会被拷贝到输出文件夹。
+
+注：
+
+1. 对于 svg 资源，Umi 支持 [svgr](../api/config#svgr) ，可以直接导入作为组件使用：
+
+ ```ts
+ import SmileUrl, { ReactComponent as SvgSmile } from './smile.svg';
+ //
+**不要提交 `.umi` 临时文件到 git 仓库，默认已在 `.gitignore` 被忽略。**
+
+
+dev 时的临时文件目录，比如入口文件、路由等，都会被临时生成到这里。
+
+#### .umi-production 目录
+
+
+**不要提交 `.umi-production` 临时文件到 git 仓库，默认已在 `.gitignore` 被忽略。**
+
+
+build 时的临时文件目录，比如入口文件、路由等，都会被临时生成到这里。
+
+#### app.[ts｜tsx]
+
+[运行时配置](../api/runtime-config) 文件，可以在这里扩展运行时的能力，比如修改路由、修改 render 方法等。
+
+运行时配置带来的逻辑会在浏览器中运行，因此当有远程配置、动态内容时，这些我们在本地开发时还不确定，不能写死，所以需要在浏览器实际运行项目时动态获取他们。
+
+#### layouts/index.tsx
+
+全局布局，默认会在所有路由下生效，比如有以下路由关系：
+
+```
+[
+ { path: '/', component: '@/pages/index' },
+ { path: '/users', component: '@/pages/users' },
+]
+```
+
+输出为：
+
+```jsx
+
+ index
+ users
+
+```
+
+当你需要关闭 layout 时可以使用 `layout: false` ，当你需要更多层 layout 时，可以考虑使用 [`wrappers`](./routes#wrappers) ，仅在配置式路由可用：
+
+```ts
+ routes: [
+ { path: '/', component: './index', layout: false },
+ {
+ path: '/users',
+ component: './users',
+ wrappers: ['@/wrappers/auth']
+ }
+ ]
+```
+
+#### pages 目录
+
+约定式路由默认以 `pages/*` 文件夹的文件层级结构来生成路由表。
+
+在配置式路由中，`component` 若写为相对路径，将从该文件夹为起点开始寻找文件：
+
+```ts
+ routes: [
+ // `./index` === `@/pages/index`
+ { path: '/', component: './index' }
+ ]
+```
+
+##### 基础路由
+
+假设 `pages` 目录结构如下：
+
+```
++ pages/
+ + users/
+ - index.tsx
+ - index.tsx
+```
+
+那么，会自动生成路由配置如下：
+
+```ts
+[
+ { path: '/', component: '@/pages/index.tsx' },
+ { path: '/users/', component: '@/pages/users/index.tsx' },
+]
+```
+
+##### 动态路由
+
+约定带 `$` 前缀的目录或文件为动态路由。若 `$` 后不指定参数名，则代表 `*` 通配，比如以下目录结构：
+
+```
++ pages/
+ + foo/
+ - $slug.tsx
+ + $bar/
+ - $.tsx
+ - index.tsx
+```
+
+会生成路由配置如下：
+
+```ts
+[
+ { path: '/', component: '@/pages/index.tsx' },
+ { path: '/foo/:slug', component: '@/pages/foo/$slug.tsx' },
+ { path: '/:bar/*', component: '@/pages/$bar/$.tsx' },
+]
+```
+
+##### pages/404.tsx
+
+在使用约定式路由时，该文件会自动被注册为全局 404 的 fallback 页面。若你使用配置式路由，需要自行配置兜底路由到路由表最后一个：
+
+```ts
+ routes: [
+ // other routes ...
+ { path: '/*', component: '@/pages/404.tsx' }
+ ]
+```
+
+#### global.(j|t)sx?
+
+全局前置脚本文件。
+
+Umi 区别于其他前端框架，没有显式的程序主入口（如 `src/index.ts`），所以当你有需要在应用前置、全局运行的逻辑时，优先考虑写入 `global.ts` 。
+
+当你需要添加全局 Context 、修改应用运行时，请使用 [`app.tsx`](#apptstsx) 。
+
+#### global.(css|less|sass|scss)
+
+全局样式文件。
+
+当你有需要全局使用的样式时，请考虑加入此文件。
+
+
+需要注意的是，此文件的优先级在第三方组件库的样式之后，所以当你有覆盖第三方库样式的需求时，请使用 [`overrides.css`](#overridescsslesssassscss) 。
+
+
+#### overrides.(css|less|sass|scss)
+
+高优先级全局样式文件。
+
+该文件一般专用于覆盖第三方库样式，其中所有 CSS 选择器都会附加 `body` 前缀以抬高优先级。
+
+#### loading.(tsx|jsx)
+
+全局加载组件。
+
+Umi 4 默认 [按页分包](../../blog/code-splitting) ，从而在页面切换时存在加载过程，通过该文件来配置加载动画。
+
+### plugin.ts
+
+项目级 Umi 插件。
+
+当你有 Umi 定制需求时，往往会用到 [插件 API](../api/plugin-api) （比如 [修改产物 html](../api/plugin-api#modifyhtml)），此时可创建该文件进行自定义：
+
+```ts
+import type { IApi } from 'umi';
+
+export default (api: IApi) => {
+ api.onDevCompileDone((opts) => {
+ opts;
+ // console.log('> onDevCompileDone', opts.isFirstCompile);
+ });
+ api.modifyHTML(($) => {
+ $;
+ });
+ api.chainWebpack((memo) => {
+ memo;
+ });
+};
+
+```
+
+### favicon
+
+站点 `favicon` 图标文件。
+
+当存在 `src/favicon.(ico|gif|png|jpg|jpeg|svg|avif|webp)` 文件时，将会自动在产物中添加站点 `favicon` ：
+
+```html
+
+```
+
+若使用外部资源等，可以使用 [favicons](../api/config#favicons) 手动配置站点图标，配置值优先于约定。
diff --git a/docs/docs/guides/env-variables.md b/docs/docs/guides/env-variables.md
index e38b69e054cd..427e3036b685 100644
--- a/docs/docs/guides/env-variables.md
+++ b/docs/docs/guides/env-variables.md
@@ -1,12 +1,12 @@
-# 环境变量
+# Env Variables
-Umi 可以通过环境变量来完成一些特殊的配置和功能。
+Umi can use environment variables to configure specific settings and functionality.
-## 如何设置环境变量
+## How to Set Environment Variables
-### 执行命令时设置
+### Setting in Command Line
-例如需要改变 `umi dev` 开发服务器的端口，进可以通过如下命令实现。
+For example, if you need to change the port of the `umi dev` development server, you can achieve this with the following command:
```bash
# OS X, Linux
@@ -16,16 +16,16 @@ $ PORT=3000 umi dev
$ set PORT=3000&&umi dev
```
-如果需要同时在不同的操作系统中使用环境变量，推荐使用工具 [cross-env](https://github.com/kentcdodds/cross-env)
+If you need to use environment variables across different operating systems, it's recommended to use the tool [cross-env](https://github.com/kentcdodds/cross-env):
```bash
$ pnpm install cross-env -D
$ cross-env PORT=3000 umi dev
```
-### 设置在 .env 文件中
+### Setting in `.env` File
-如果你的环境变量需要在开发者之间共享，推荐你设置在项目根目录的 `.env` 文件中，例如:
+If you want to share environment variables among developers, it's recommended to set them in a `.env` file at the root of your project. For example:
```text
# file .env
@@ -33,24 +33,24 @@ PORT=3000
BABEL_CACHE=none
```
-然后执行，
+Then execute:
```bash
$ umi dev
```
-`umi` 会以 3000 端口启动 dev server，并且禁用 babel 的缓存。
+The `umi` command will start the dev server on port 3000 and disable babel caching.
-如果你有部分环境变量的配置在本地要做特殊配置，可以配置在 `.env.local` 文件中去覆盖 `.env` 的配置。比如在之前的 `.env` 的基础上, 你想本地开发覆盖之前 3000 端口, 而使用 4000 端口，可以做如下定义。
+If you have some environment variable configurations that need to be customized locally, you can configure them in the `.env.local` file to override the configurations in `.env`. For instance, based on the previous `.env` configuration, if you want to use port 4000 for local development instead of the previous 3000, you can define it as follows:
```text
# file .env.local
PORT=4000
```
-`umi` 会以 4000 端口启动 dev server，同时保持禁用 babel 的缓存。
+The `umi` command will start the dev server on port 4000 and still disable babel caching.
-此外 `umi` `.env` 文件中还支持变量的方式来配置环境变量。例如：
+Additionally, you can use variable interpolation to configure environment variables in the `.env` file. For example:
```
# file .env.local
@@ -60,72 +60,71 @@ BAR=bar
CONCAT=$FOO$BAR # CONCAT=foobar
```
-注意：
+Note:
-* 不建议将 `.env.local` 加入版本管理中。
+* It's not recommended to include `.env.local` in version control.
-## 环境变量列表
+## List of Environment Variables
-按字母顺序排列。
+Listed in alphabetical order.
### APP_ROOT
-指定项目根目录。
+Specifies the project root directory.
-注意：
-
-* APP_ROOT 不能配在 .env 中，只能在命令行里添加
+Note:
+* APP_ROOT cannot be configured in `.env`, only in command line.
### ANALYZE
-用于分析 bundle 构成，默认关闭。
+Used for analyzing bundle composition, disabled by default.
-比如：
+For example:
```bash
$ ANALYZE=1 umi dev
-# 或者
+# Or
$ ANALYZE=1 umi build
```
-可以通过 `ANALYZE_PORT` 环境变量自定义端口或 [`analyze`](../api/config#analyze) 选项自定义配置。
+You can customize the port using the `ANALYZE_PORT` environment variable or the [`analyze`](../api/config#analyze) option.
### BABEL_POLYFILL
-默认会根据 targets 配置打目标浏览器的全量补丁，设置为 `none` 禁用内置的补丁方案。
+By default, Babel will apply polyfills based on the targets configuration. Setting this to `none` disables the built-in polyfill.
### COMPRESS
-默认压缩 CSS 和 JS，值为 none 时不压缩，build 时有效。
+By default, CSS and JS are compressed. Setting this to `none` disables compression and is effective during the build process.
### DID_YOU_KNOW
-设置为 `none` 会禁用「你知道吗」提示。
+Setting this to `none` disables "Did You Know" prompts.
### ERROR_OVERLAY
-设置为 `none` 会禁用「Error Overlay」，在调试 Error Boundary 时会有用。
+Setting this to `none` disables the "Error Overlay," which can be useful when debugging error boundaries.
### FS_LOGGER
-默认会开启保存物理日志，值为 none 时不保存，同时针对 webcontainer 场景（比如 stackbliz）暂不保存。
+By default, physical logs are saved. Setting this to `none` disables saving logs. It is also disabled for web container scenarios (e.g., stackblitz).
### HMR
-默认开启 HMR 功能，值为 none 时关闭。
+HMR (Hot Module Replacement) is enabled by default. Setting this to `none` disables HMR.
### HOST
-默认是 `0.0.0.0`。
+The default value is `0.0.0.0`.
### PORT
-指定端口号，默认是 `8000`。
+Specifies the port number. The default is `8000`.
### SOCKET_SERVER
-指定用于 HMR 的 socket 服务器。比如：
+Specifies the socket server used for HMR. For example:
```bash
$ SOCKET_SERVER=http://localhost:8000/ umi dev
@@ -133,7 +132,7 @@ $ SOCKET_SERVER=http://localhost:8000/ umi dev
### SPEED_MEASURE
-分析 Webpack 编译时间，支持 `CONSOLE` 和 `JSON` 两种格式，默认是 `CONSOLE`。
+Analyzes Webpack compilation time. Supports two formats: `CONSOLE` and `JSON`. Default is `CONSOLE`.
```bash
$ SPEED_MEASURE=JSON umi dev
@@ -141,7 +140,7 @@ $ SPEED_MEASURE=JSON umi dev
### UMI_ENV
-当指定 `UMI_ENV` 时，会额外加载指定值的配置文件，优先级为：
+When `UMI_ENV` is specified, it will load an additional configuration file with the specified value. The priority is:
- `config.ts`
@@ -153,13 +152,13 @@ $ SPEED_MEASURE=JSON umi dev
- `config.local.ts`
-若不指定 `UMI_ENV` ，则只会加载当前环境对应的配置文件，越向下的越具体，优先级更高，高优的配置可以往下移动。
+If `UMI_ENV` is not specified, only the configuration file corresponding to the current environment will be loaded. Files that are lower in the list will override those higher up.
-注：根据当前环境的不同，`dev`, `prod`, `test` 配置文件会自动加载，不能将 `UMI_ENV` 的值设定成他们。
+Note: Depending on the current environment, the `dev`, `prod`, and `test` configuration files will be automatically loaded. You should not set `UMI_ENV` to these values.
### UMI_PLUGINS
-指定 `umi` 命令执行时额外加载的插件的路径，使用 `,` 隔开。
+Specifies the paths of additional plugins to load when executing the `umi` command. Use commas to separate paths.
```bash
$ UMI_PLUGINS=./path/to/plugin1,./path/to/plugin2 umi dev
@@ -167,7 +166,7 @@ $ UMI_PLUGINS=./path/to/plugin1,./path/to/plugin2 umi dev
### UMI_PRESETS
-指定 `umi` 命令执行时额外加载插件集的路径，使用 `,` 隔开。
+Specifies the paths of additional plugin sets to load when executing the `umi` command. Use commas to separate paths.
```bash
$ UMI_PRESETS=./path/to/preset1,./path/to/preset2 umi dev
@@ -175,7 +174,7 @@ $ UMI_PRESETS=./path/to/preset1,./path/to/preset2 umi dev
### WEBPACK_FS_CACHE_DEBUG
-开启 webpack 的物理缓存 debug 日志。
+Enables debug logs for Webpack's physical caching.
```bash
$ WEBPACK_FS_CACHE_DEBUG=1 umi dev
diff --git a/docs/docs/guides/env-variables.zh-CN.md b/docs/docs/guides/env-variables.zh-CN.md
new file mode 100644
index 000000000000..e38b69e054cd
--- /dev/null
+++ b/docs/docs/guides/env-variables.zh-CN.md
@@ -0,0 +1,182 @@
+# 环境变量
+
+Umi 可以通过环境变量来完成一些特殊的配置和功能。
+
+## 如何设置环境变量
+
+### 执行命令时设置
+
+例如需要改变 `umi dev` 开发服务器的端口，进可以通过如下命令实现。
+
+```bash
+# OS X, Linux
+$ PORT=3000 umi dev
+
+# Windows (cmd.exe)
+$ set PORT=3000&&umi dev
+```
+
+如果需要同时在不同的操作系统中使用环境变量，推荐使用工具 [cross-env](https://github.com/kentcdodds/cross-env)
+
+```bash
+$ pnpm install cross-env -D
+$ cross-env PORT=3000 umi dev
+```
+
+### 设置在 .env 文件中
+
+如果你的环境变量需要在开发者之间共享，推荐你设置在项目根目录的 `.env` 文件中，例如:
+
+```text
+# file .env
+PORT=3000
+BABEL_CACHE=none
+```
+
+然后执行，
+
+```bash
+$ umi dev
+```
+
+`umi` 会以 3000 端口启动 dev server，并且禁用 babel 的缓存。
+
+如果你有部分环境变量的配置在本地要做特殊配置，可以配置在 `.env.local` 文件中去覆盖 `.env` 的配置。比如在之前的 `.env` 的基础上, 你想本地开发覆盖之前 3000 端口, 而使用 4000 端口，可以做如下定义。
+
+```text
+# file .env.local
+PORT=4000
+```
+
+`umi` 会以 4000 端口启动 dev server，同时保持禁用 babel 的缓存。
+
+此外 `umi` `.env` 文件中还支持变量的方式来配置环境变量。例如：
+
+```
+# file .env.local
+FOO=foo
+BAR=bar
+
+CONCAT=$FOO$BAR # CONCAT=foobar
+```
+
+注意：
+
+* 不建议将 `.env.local` 加入版本管理中。
+
+## 环境变量列表
+
+按字母顺序排列。
+
+### APP_ROOT
+
+指定项目根目录。
+
+注意：
+
+* APP_ROOT 不能配在 .env 中，只能在命令行里添加
+
+
+### ANALYZE
+
+用于分析 bundle 构成，默认关闭。
+
+比如：
+
+```bash
+$ ANALYZE=1 umi dev
+# 或者
+$ ANALYZE=1 umi build
+```
+
+可以通过 `ANALYZE_PORT` 环境变量自定义端口或 [`analyze`](../api/config#analyze) 选项自定义配置。
+
+### BABEL_POLYFILL
+
+默认会根据 targets 配置打目标浏览器的全量补丁，设置为 `none` 禁用内置的补丁方案。
+
+### COMPRESS
+
+默认压缩 CSS 和 JS，值为 none 时不压缩，build 时有效。
+
+### DID_YOU_KNOW
+
+设置为 `none` 会禁用「你知道吗」提示。
+
+### ERROR_OVERLAY
+
+设置为 `none` 会禁用「Error Overlay」，在调试 Error Boundary 时会有用。
+
+### FS_LOGGER
+
+默认会开启保存物理日志，值为 none 时不保存，同时针对 webcontainer 场景（比如 stackbliz）暂不保存。
+
+### HMR
+
+默认开启 HMR 功能，值为 none 时关闭。
+
+### HOST
+
+默认是 `0.0.0.0`。
+
+### PORT
+
+指定端口号，默认是 `8000`。
+
+### SOCKET_SERVER
+
+指定用于 HMR 的 socket 服务器。比如：
+
+```bash
+$ SOCKET_SERVER=http://localhost:8000/ umi dev
+```
+
+### SPEED_MEASURE
+
+分析 Webpack 编译时间，支持 `CONSOLE` 和 `JSON` 两种格式，默认是 `CONSOLE`。
+
+```bash
+$ SPEED_MEASURE=JSON umi dev
+```
+
+### UMI_ENV
+
+当指定 `UMI_ENV` 时，会额外加载指定值的配置文件，优先级为：
+
+ - `config.ts`
+
+ - `config.${UMI_ENV}.ts`
+
+ - `config.${dev | prod | test}.ts`
+
+ - `config.${dev | prod | test}.${UMI_ENV}.ts`
+
+ - `config.local.ts`
+
+若不指定 `UMI_ENV` ，则只会加载当前环境对应的配置文件，越向下的越具体，优先级更高，高优的配置可以往下移动。
+
+注：根据当前环境的不同，`dev`, `prod`, `test` 配置文件会自动加载，不能将 `UMI_ENV` 的值设定成他们。
+
+### UMI_PLUGINS
+
+指定 `umi` 命令执行时额外加载的插件的路径，使用 `,` 隔开。
+
+```bash
+$ UMI_PLUGINS=./path/to/plugin1,./path/to/plugin2 umi dev
+```
+
+### UMI_PRESETS
+
+指定 `umi` 命令执行时额外加载插件集的路径，使用 `,` 隔开。
+
+```bash
+$ UMI_PRESETS=./path/to/preset1,./path/to/preset2 umi dev
+```
+
+### WEBPACK_FS_CACHE_DEBUG
+
+开启 webpack 的物理缓存 debug 日志。
+
+```bash
+$ WEBPACK_FS_CACHE_DEBUG=1 umi dev
+```
diff --git a/docs/docs/guides/errors.zh-CN.md b/docs/docs/guides/errors.zh-CN.md
new file mode 100644
index 000000000000..a27f18e2b9ab
--- /dev/null
+++ b/docs/docs/guides/errors.zh-CN.md
@@ -0,0 +1 @@
+# 错误处理
diff --git a/docs/docs/guides/generator.md b/docs/docs/guides/generator.md
index ab533c953e2d..7eba73e19bdd 100644
--- a/docs/docs/guides/generator.md
+++ b/docs/docs/guides/generator.md
@@ -1,65 +1,65 @@
-# 微生成器
+# Micro Generators
-Umi 中内置了众多微生成器，协助你在开发中快速的完成一些繁琐的工作。
+Umi comes with a variety of micro generators that help you quickly accomplish some tedious tasks during development.
-## 如何使用
+## How to Use
-下面的命令会列出目前所有可用的生成器，可以通过交互式方式来选择你使用的功能，都有详细的提示。
+The following command will list all available generators. You can use interactive prompts to select the desired functionality, and each generator provides detailed prompts.
```bash
$ umi generate
-# 或者
+# Or
$ umi g
```
-你也可以通过 `umi g ` 的形式来使用对应的生成器。
+You can also use the `umi g ` format to use a specific generator.
-## 生成器列表
+## List of Generators
-### 页面生成器
+### Page Generator
-快速生成一个新页面，有以下使用方式。
+Quickly generate a new page in the `src/pages/` directory. Just like the scaffold generator, the page generator has multiple generation methods.
-#### 基本使用
+#### Basic Usage
-交互式输入页面名称和文件生成方式：
+Interactive generation:
```bash
-$umi g page
-? What is the name of page? › mypage
-? How dou you want page files to be created? › - Use arrow-keys. Return to submit.
+$ umi g page
+? What is the name of the page? › mypage
+? How do you want page files to be created? › - Use arrow-keys. Return to submit.
❯ mypage/index.{tsx,less}
mypage.{tsx,less}
```
-直接生成：
+Direct generation:
```bash
-$umi g page foo
+$ umi g page foo
Write: src/pages/foo.tsx
Write: src/pages/foo.less
```
-以目录方式生成页面，目录下为页面的组件和样式文件：
+Generate as a directory:
```bash
-$umi g page bar --dir
+$ umi g page bar --dir
Write: src/pages/bar/index.less
Write: src/pages/bar/index.tsx
```
-嵌套生成页面：
+Nested generation:
```bash
-$umi g page far/far/away/kingdom
+$ umi g page far/far/away/kingdom
Write: src/pages/far/far/away/kingdom.tsx
Write: src/pages/far/far/away/kingdom.less
```
-批量生成多个页面：
+Batch generation of multiple pages:
```bash
-$umi g page page1 page2 a/nested/page3
+$ umi g page page1 page2 a/nested/page3
Write: src/pages/page1.tsx
Write: src/pages/page1.less
Write: src/pages/page2.tsx
@@ -68,17 +68,17 @@ Write: src/pages/a/nested/page3.tsx
Write: src/pages/a/nested/page3.less
```
-#### 对页面模板内容进行自定义
+#### Customizing Template Content
-如果页面生成器使用的默认模板不符合你的需求，你可以对模板内容进行自定义设置。
+If the default template used by the page generator doesn't suit your needs, you can customize the template content.
-执行 `--eject` 命令：
+Run the `--eject` command:
```bash
-$umi g page --eject
+$ umi g page --eject
```
-执行命令后，页面生成器会把它的原始模板写入到项目的 `/templates/page` 目录：
+After running the command, the page generator will write its original template to the `/templates/page` directory in your project:
```
.
@@ -89,9 +89,9 @@ $umi g page --eject
└── index.tsx.tpl
```
-##### 使用模板变量
+##### Using Template Variables
-两个模板文件都支持模板语法，你可以像下面这样插入变量：
+Both template files support template syntax. You can insert variables like this:
```tsx
import React from 'react';
@@ -101,12 +101,13 @@ const message = '{{{msg}}}'
const count = {{{count}}}
```
-可以自定义参数值：
+You can customize parameter values:
```bash
-$umi g page foo --msg "Hello World" --count 10
+$ umi g page foo --msg "Hello World" --count 10
```
-运行命令后，生成的页面内容如下：
+
+After running the command, the generated page content will be as follows:
```tsx
import React from 'react';
@@ -116,25 +117,25 @@ const message = 'Hello World'
const count = 10
```
-如果你不需要使用模板变量，可以省略 `.tpl` 后缀名，将 `index.tsx.tpl` 简写为 `index.tsx`，`index.less.tpl` 简写为 `index.less`。
+If you don't need template variables, you can omit the `.tpl` extension and use `index.tsx` instead of `index.tsx.tpl`, and `index.less` instead of `index.less.tpl`.
-##### 预设变量
+##### Preset Variables
-在上一小节生成的内容中，我们并没有指定 `name`，但它被还是设置值了。这是因为它属于模板中预设的变量，下面是目前页面模板所有的预设变量：
+In the generated content from the previous section, we didn't specify the `name`, but it was still set. This is because it's a preset variable in the template. Here are the preset variables available in the page template:
-|参数|默认值|说明|
+| Variable | Default Value | Description |
|:-:|:-:|:-|
-| `name` | - | 当前文件的名称。如果执行 `pnpm umi g page foo`，会生成 `pages/foo.tsx` 和 `pages/foo.less` 两个文件，其中 `name` 的值为 "foo"。 |
-| `color` | - | 随机生成一个 RGB 颜色。 |
-| `cssExt` | `less` | 样式文件的后缀名。 |
+| `name` | - | The name of the current file. If you execute `pnpm umi g page foo`, it will generate `pages/foo.tsx` and `pages/foo.less` files, where the `name` value is "foo". |
+| `color` | - | A randomly generated RGB color. |
+| `cssExt` | `less` | The file extension for the style files. |
-如果想了解更多模板语法的内容，请查看 [mustache](https://www.npmjs.com/package/mustache)。
+To learn more about template syntax, please refer to [mustache](https://www.npmjs.com/package/mustache).
-##### `dir` 模式
+##### `dir` Mode
-在不使用 `dir` 模式的情况下，如果你的页面模板文件夹只自定义了一个模板文件，缺失的文件会自动选取默认的模板文件。
+Without using the `dir` mode, if your page template folder only customizes one template file, the missing files will automatically use the default template.
-如果使用 `dir` 模式，它的生成内容会和你的页面自定义模板文件夹保持一致，只有在页面自定义模板文件夹为空时才使用默认模板。如果你的页面自定义模板文件夹内容如下：
+If you use the `dir` mode, the generated content will be consistent with your custom template folder for the page. The default template will only be used if the page's custom template folder is empty. If your page's custom template folder content looks like this:
```
.
@@ -142,7 +143,7 @@ const count = 10
└── index.tsx.tpl
```
-生成的目录将是：
+The generated directory will be:
```
.
@@ -150,45 +151,49 @@ const count = 10
└── index.tsx
```
-##### 回退
+##### Rollback
-如果还想继续使用默认的模板，可以指定 `--fallback`，此时不再使用用户自定义的模板：
+If you want to continue using the default template, you can specify `--fallback`, and user-customized templates won't be used:
```bash
-$umi g page foo --fallback
+$ umi g page foo --fallback
```
-### 组件生成器
+### Component Generator
+
+Generates components that your project needs in the `src/components/` directory. Like the page generator, the component generator also has multiple generation methods.
-在 `src/components/` 目录下生成项目需要的组件。和页面生成器一样，组件生成器也有多种生成方式。
+#### Basic Usage
-#### 基本使用
+Interactive generation:
-交互式生成：
```bash
-$umi g component
-✔ Please input you component Name … foo
+$ umi g component
+✔ Please input your component Name … foo
Write: src/components/Foo/index.ts
Write: src/components/Foo/Foo.tsx
```
-直接生成：
+Direct generation:
+
```bash
-$umi g component bar
+$ umi g component bar
Write: src/components/Bar/index.ts
Write: src/components/Bar/Bar.tsx
```
-嵌套生成：
+Nested generation:
+
```bash
-$umi g component group/subgroup/baz
+$ umi g component group/subgroup/baz
Write: src/components/group/subgroup/Baz/index.ts
Write: src/components/group/subgroup/Baz/Baz.tsx
```
-批量生成：
+Batch generation:
+
```bash
-$umi g component apple banana orange
+$ umi g component apple banana orange
Write: src/components/Apple/index.ts
Write: src/components/Apple/Apple.tsx
Write: src/components/Banana/index.ts
@@ -197,118 +202,127 @@ Write: src/components/Orange/index.ts
Write: src/components/Orange/Orange.tsx
```
-#### 对组件模板内容进行自定义
+#### Customizing Template Content
-与[页面生成器](#对页面模板内容进行自定义)相同，组件生成器也支持对模板内容自定义。首先，先将原始模板写入到项目的 `/templates/component` 目录：
+Similar to the [Page Generator](#customizing-template-content) section, the component generator also supports customizing template content. First, write the original template to the `/templates/component` directory in your project:
```bash
-$umi g component --eject
+$ umi g component --eject
```
-##### 使用模板变量
+##### Using Template Variables
```bash
-$umi g component foo --msg "Hello World"
+$ umi g component foo --msg "Hello World"
```
-自定义组件模板可以省略 `.tpl` 后缀名。你可以将 `index.ts.tpl` 简写为 `index.ts`，`component.tsx.tpl` 简写为 `component.tsx`。
+You can omit the `.tpl` extension for custom component templates. You can shorten `index.ts.tpl` to `index.ts` and `component.tsx.tpl` to `component.tsx`.
-组件生成器将生成与你的自定义模板文件夹相一致的内容，你可以根据需要添加更多的自定义模板文件。
+The component generator will generate content consistent with your custom template folder. You can add more custom template files as needed.
-##### 预设变量
+##### Preset Variables
-|参数|默认值|说明|
+| Variable | Default Value | Description |
|:-:|:-:|:-|
-| `compName` | - | 当前组件的名称。如果执行 `pnpm umi g component foo`， `compName` 的值为 `Foo`。 |
+| `compName` | - | The name of the current component. If you execute `pnpm umi g component foo`, the `compName` value is `Foo`. |
-##### 回退
+##### Rollback
```bash
-$umi g component foo --fallback
+$ umi g component foo --fallback
```
-### RouteAPI 生成器
+### RouteAPI Generator
+
+Generates template files for the routeAPI feature.
-生成 routeAPI 功能的模板文件。
+Interactive generation:
-交互式生成：
```bash
-$umi g api
-✔ please input your api name: … starwar/people
+$ umi g api
+
+
+✔ Please input your api name … starwar/people
Write: api/starwar/people.ts
```
-直接生成:
+Direct generation:
+
```bash
-$umi g api films
+$ umi g api films
Write: api/films.ts
```
-嵌套生成器：
+Nested generation:
+
```bash
-$umi g api planets/[id]
+$ umi g api planets/[id]
Write: api/planets/[id].ts
```
-批量生成：
+Batch generation:
+
```bash
-$umi g api spaceships vehicles species
+$ umi g api spaceships vehicles species
Write: api/spaceships.ts
Write: api/vehicles.ts
Write: api/species.ts
```
-### Mock 生成器
+### Mock Generator
-生成 [Mock](./mock) 功能的模板文件，mock 的具体实现参考[文档](./mock)。
+Generates template files for [Mock](./mock) functionality. Mock implementation details can be found in the [documentation](./mock).
+
+Interactive generation:
-交互式生成：
```bash
-$umi g mock
-✔ please input your mock file name … auth
+$ umi g mock
+✔ Please input your mock file name … auth
Write: mock/auth.ts
```
-直接生成:
+Direct generation:
+
```bash
-$umi g mock acl
+$ umi g mock acl
Write: mock/acl.ts
```
-嵌套生成:
+Nested generation:
+
```bash
-$umi g mock users/profile
+$ umi g mock users/profile
Write: mock/users/profile.ts
```
-### Prettier 配置生成器
+### Prettier Configuration Generator
-为项目生成 [prettier](https://prettier.io/) 配置，命令执行后，`umi` 会生成推荐的 prettier 配置和安装相应的依赖。
+Generates a [Prettier](https://prettier.io/) configuration for the project. After running the command, `umi` will generate the recommended Prettier configuration and install the necessary dependencies.
```bash
-$umi g prettier
+$ umi g prettier
info - Write package.json
info - Write .prettierrc
info - Write .prettierignore
```
-### Jest 配置生成器
+### Jest Configuration Generator
-为项目生成 [jest](https://jestjs.io/) 配置，命令执行后，`umi` 会生成 Jest 配置和安装相应的依赖。根据需要选择是否要使用 [@testing-library/react](https://www.npmjs.com/package/@testing-library/react) 做 UI 测试。
+Generates a [Jest](https://jestjs.io/) configuration for the project. After running the command, `umi` will generate the Jest configuration and install the necessary dependencies. Choose whether to use [@testing-library/react](https://www.npmjs.com/package/@testing-library/react) for UI testing based on your needs.
```bash
-$umi g jest
+$ umi g jest
✔ Will you use @testing-library/react for UI testing?! … yes
info - Write package.json
info - Write jest.config.ts
```
-### Tailwind CSS 配置生成器
+### Tailwind CSS Configuration Generator
-为项目开启 [Tailwind CSS](https://tailwindcss.com/) 配置，命令执行后，`umi` 会生成 Tailwind CSS 和安装相应的的依赖。
+Enables [Tailwind CSS](https://tailwindcss.com/) configuration for the project. After running the command, `umi` will generate the Tailwind CSS configuration and install the necessary dependencies.
```bash
-$umi g tailwindcss
+$ umi g tailwindcss
info - Write package.json
set config:tailwindcss on /Users/umi/playground/.umirc.ts
set config:plugins on /Users/umi/playground/.umirc.ts
@@ -317,26 +331,26 @@ info - Write tailwind.config.js
info - Write tailwind.css
```
-### DvaJS 配置生成器
+### DvaJS Configuration Generator
-为项目开启 [Dva](https://dvajs.com/) 配置，命令执行后，`umi` 会生成 Dva
+Enables [Dva](https://dvajs.com/) configuration for the project. After running the command, `umi` will generate Dva configuration and install the necessary dependencies.
```bash
-$umi g dva
+$ umi g dva
set config:dva on /Users/umi/umi-playground/.umirc.ts
set config:plugins on /Users/umi/umi-playground/.umirc.ts
info - Update config file
info - Write example model
```
-### Precommit 配置生成器
+### Precommit Configuration Generator
-为项目生成 [precommit](https://typicode.github.io/husky) 配置，命令执行后，`umi` 会为我们添加 husky 和 Git commit message 格式校验行为，在每次 Git commit 前会将 Git 暂存区的代码默认格式化。
+Generates a [precommit](https://typicode.github.io/husky) configuration for the project. After running the command, `umi` will add Husky and Git commit message format validation behavior. Before each Git commit, the code in the Git staging area will be automatically formatted by default.
-> 注意：如果是初始化出来的 `@umijs/max` 项目，通常不需要该生成器，因为已经配置好 husky 了
+> Note: If you initialize your project with `@umijs/max`, you usually don't need this generator because Husky is already configured.
```bash
-$umi g precommit
+$ umi g precommit
info - Update package.json for devDependencies
info - Update package.json for scripts
info - Write .lintstagedrc
diff --git a/docs/docs/guides/generator.zh-CN.md b/docs/docs/guides/generator.zh-CN.md
new file mode 100644
index 000000000000..ab533c953e2d
--- /dev/null
+++ b/docs/docs/guides/generator.zh-CN.md
@@ -0,0 +1,346 @@
+# 微生成器
+
+Umi 中内置了众多微生成器，协助你在开发中快速的完成一些繁琐的工作。
+
+## 如何使用
+
+下面的命令会列出目前所有可用的生成器，可以通过交互式方式来选择你使用的功能，都有详细的提示。
+
+```bash
+$ umi generate
+# 或者
+$ umi g
+```
+
+你也可以通过 `umi g ` 的形式来使用对应的生成器。
+
+## 生成器列表
+
+### 页面生成器
+
+快速生成一个新页面，有以下使用方式。
+
+#### 基本使用
+
+交互式输入页面名称和文件生成方式：
+
+```bash
+$umi g page
+? What is the name of page? › mypage
+? How dou you want page files to be created? › - Use arrow-keys. Return to submit.
+❯ mypage/index.{tsx,less}
+ mypage.{tsx,less}
+```
+
+直接生成：
+
+```bash
+$umi g page foo
+Write: src/pages/foo.tsx
+Write: src/pages/foo.less
+```
+
+以目录方式生成页面，目录下为页面的组件和样式文件：
+
+```bash
+$umi g page bar --dir
+Write: src/pages/bar/index.less
+Write: src/pages/bar/index.tsx
+```
+
+嵌套生成页面：
+
+```bash
+$umi g page far/far/away/kingdom
+Write: src/pages/far/far/away/kingdom.tsx
+Write: src/pages/far/far/away/kingdom.less
+```
+
+批量生成多个页面：
+
+```bash
+$umi g page page1 page2 a/nested/page3
+Write: src/pages/page1.tsx
+Write: src/pages/page1.less
+Write: src/pages/page2.tsx
+Write: src/pages/page2.less
+Write: src/pages/a/nested/page3.tsx
+Write: src/pages/a/nested/page3.less
+```
+
+#### 对页面模板内容进行自定义
+
+如果页面生成器使用的默认模板不符合你的需求，你可以对模板内容进行自定义设置。
+
+执行 `--eject` 命令：
+
+```bash
+$umi g page --eject
+```
+
+执行命令后，页面生成器会把它的原始模板写入到项目的 `/templates/page` 目录：
+
+```
+.
+├── package.json
+└── templates
+ └── page
+ ├── index.less.tpl
+ └── index.tsx.tpl
+```
+
+##### 使用模板变量
+
+两个模板文件都支持模板语法，你可以像下面这样插入变量：
+
+```tsx
+import React from 'react';
+import './{{{name}}}.less'
+
+const message = '{{{msg}}}'
+const count = {{{count}}}
+```
+
+可以自定义参数值：
+
+```bash
+$umi g page foo --msg "Hello World" --count 10
+```
+运行命令后，生成的页面内容如下：
+
+```tsx
+import React from 'react';
+import './foo.less'
+
+const message = 'Hello World'
+const count = 10
+```
+
+如果你不需要使用模板变量，可以省略 `.tpl` 后缀名，将 `index.tsx.tpl` 简写为 `index.tsx`，`index.less.tpl` 简写为 `index.less`。
+
+##### 预设变量
+
+在上一小节生成的内容中，我们并没有指定 `name`，但它被还是设置值了。这是因为它属于模板中预设的变量，下面是目前页面模板所有的预设变量：
+
+|参数|默认值|说明|
+|:-:|:-:|:-|
+| `name` | - | 当前文件的名称。如果执行 `pnpm umi g page foo`，会生成 `pages/foo.tsx` 和 `pages/foo.less` 两个文件，其中 `name` 的值为 "foo"。 |
+| `color` | - | 随机生成一个 RGB 颜色。 |
+| `cssExt` | `less` | 样式文件的后缀名。 |
+
+如果想了解更多模板语法的内容，请查看 [mustache](https://www.npmjs.com/package/mustache)。
+
+##### `dir` 模式
+
+在不使用 `dir` 模式的情况下，如果你的页面模板文件夹只自定义了一个模板文件，缺失的文件会自动选取默认的模板文件。
+
+如果使用 `dir` 模式，它的生成内容会和你的页面自定义模板文件夹保持一致，只有在页面自定义模板文件夹为空时才使用默认模板。如果你的页面自定义模板文件夹内容如下：
+
+```
+.
+├── a.tsx
+└── index.tsx.tpl
+```
+
+生成的目录将是：
+
+```
+.
+├── a.tsx
+└── index.tsx
+```
+
+##### 回退
+
+如果还想继续使用默认的模板，可以指定 `--fallback`，此时不再使用用户自定义的模板：
+
+```bash
+$umi g page foo --fallback
+```
+
+### 组件生成器
+
+在 `src/components/` 目录下生成项目需要的组件。和页面生成器一样，组件生成器也有多种生成方式。
+
+#### 基本使用
+
+交互式生成：
+```bash
+$umi g component
+✔ Please input you component Name … foo
+Write: src/components/Foo/index.ts
+Write: src/components/Foo/Foo.tsx
+```
+
+直接生成：
+```bash
+$umi g component bar
+Write: src/components/Bar/index.ts
+Write: src/components/Bar/Bar.tsx
+```
+
+嵌套生成：
+```bash
+$umi g component group/subgroup/baz
+Write: src/components/group/subgroup/Baz/index.ts
+Write: src/components/group/subgroup/Baz/Baz.tsx
+```
+
+批量生成：
+```bash
+$umi g component apple banana orange
+Write: src/components/Apple/index.ts
+Write: src/components/Apple/Apple.tsx
+Write: src/components/Banana/index.ts
+Write: src/components/Banana/Banana.tsx
+Write: src/components/Orange/index.ts
+Write: src/components/Orange/Orange.tsx
+```
+
+#### 对组件模板内容进行自定义
+
+与[页面生成器](#对页面模板内容进行自定义)相同，组件生成器也支持对模板内容自定义。首先，先将原始模板写入到项目的 `/templates/component` 目录：
+
+```bash
+$umi g component --eject
+```
+
+##### 使用模板变量
+
+```bash
+$umi g component foo --msg "Hello World"
+```
+
+自定义组件模板可以省略 `.tpl` 后缀名。你可以将 `index.ts.tpl` 简写为 `index.ts`，`component.tsx.tpl` 简写为 `component.tsx`。
+
+组件生成器将生成与你的自定义模板文件夹相一致的内容，你可以根据需要添加更多的自定义模板文件。
+
+##### 预设变量
+
+|参数|默认值|说明|
+|:-:|:-:|:-|
+| `compName` | - | 当前组件的名称。如果执行 `pnpm umi g component foo`， `compName` 的值为 `Foo`。 |
+
+##### 回退
+
+```bash
+$umi g component foo --fallback
+```
+
+### RouteAPI 生成器
+
+生成 routeAPI 功能的模板文件。
+
+交互式生成：
+```bash
+$umi g api
+✔ please input your api name: … starwar/people
+Write: api/starwar/people.ts
+```
+
+直接生成:
+```bash
+$umi g api films
+Write: api/films.ts
+```
+
+嵌套生成器：
+```bash
+$umi g api planets/[id]
+Write: api/planets/[id].ts
+```
+
+批量生成：
+```bash
+$umi g api spaceships vehicles species
+Write: api/spaceships.ts
+Write: api/vehicles.ts
+Write: api/species.ts
+```
+
+### Mock 生成器
+
+生成 [Mock](./mock) 功能的模板文件，mock 的具体实现参考[文档](./mock)。
+
+交互式生成：
+```bash
+$umi g mock
+✔ please input your mock file name … auth
+Write: mock/auth.ts
+```
+
+直接生成:
+```bash
+$umi g mock acl
+Write: mock/acl.ts
+```
+
+嵌套生成:
+```bash
+$umi g mock users/profile
+Write: mock/users/profile.ts
+```
+
+### Prettier 配置生成器
+
+为项目生成 [prettier](https://prettier.io/) 配置，命令执行后，`umi` 会生成推荐的 prettier 配置和安装相应的依赖。
+
+```bash
+$umi g prettier
+info - Write package.json
+info - Write .prettierrc
+info - Write .prettierignore
+```
+
+### Jest 配置生成器
+
+为项目生成 [jest](https://jestjs.io/) 配置，命令执行后，`umi` 会生成 Jest 配置和安装相应的依赖。根据需要选择是否要使用 [@testing-library/react](https://www.npmjs.com/package/@testing-library/react) 做 UI 测试。
+
+```bash
+$umi g jest
+✔ Will you use @testing-library/react for UI testing?! … yes
+info - Write package.json
+info - Write jest.config.ts
+```
+
+### Tailwind CSS 配置生成器
+
+为项目开启 [Tailwind CSS](https://tailwindcss.com/) 配置，命令执行后，`umi` 会生成 Tailwind CSS 和安装相应的的依赖。
+
+```bash
+$umi g tailwindcss
+info - Write package.json
+set config:tailwindcss on /Users/umi/playground/.umirc.ts
+set config:plugins on /Users/umi/playground/.umirc.ts
+info - Update .umirc.ts
+info - Write tailwind.config.js
+info - Write tailwind.css
+```
+
+### DvaJS 配置生成器
+
+为项目开启 [Dva](https://dvajs.com/) 配置，命令执行后，`umi` 会生成 Dva
+
+```bash
+$umi g dva
+set config:dva on /Users/umi/umi-playground/.umirc.ts
+set config:plugins on /Users/umi/umi-playground/.umirc.ts
+info - Update config file
+info - Write example model
+```
+
+### Precommit 配置生成器
+
+为项目生成 [precommit](https://typicode.github.io/husky) 配置，命令执行后，`umi` 会为我们添加 husky 和 Git commit message 格式校验行为，在每次 Git commit 前会将 Git 暂存区的代码默认格式化。
+
+> 注意：如果是初始化出来的 `@umijs/max` 项目，通常不需要该生成器，因为已经配置好 husky 了
+
+```bash
+$umi g precommit
+info - Update package.json for devDependencies
+info - Update package.json for scripts
+info - Write .lintstagedrc
+info - Create .husky
+info - Write commit-msg
+info - Write pre-commit
+```
diff --git a/docs/docs/guides/lint.md b/docs/docs/guides/lint.md
index 74c9ab31fa6d..3b8c5f3fec7b 100644
--- a/docs/docs/guides/lint.md
+++ b/docs/docs/guides/lint.md
@@ -1,23 +1,23 @@
-# 编码规范
+# Coding Standards
-我们通常会在项目中使用 ESLint、Stylelint 来协助我们把控编码质量，为了实现低成本、高性能、更稳定地接入上述工具，Umi 提供了开箱即用的 Lint 能力，包含以下特性：
+In projects, we often use ESLint and Stylelint to help maintain code quality. To make it easy and efficient to integrate these tools while minimizing complexity and enhancing stability, Umi offers an out-of-the-box linting capability. This includes the following features:
-1. **推荐配置**：提供 ESLint 及 Stylelint 推荐配置，可以直接继承使用
-2. **统一的 CLI**：提供 `umi lint` CLI，集成式调用 ESLint 和 Stylelint
-3. **规则稳定**：始终确保规则的稳定性，不会出现上游配置更新导致存量项目 lint 失败的情况
+1. **Recommended Configuration**: Provides recommended configurations for ESLint and Stylelint that you can directly extend.
+2. **Unified CLI**: Provides the `umi lint` CLI, which integrates both ESLint and Stylelint.
+3. **Stable Rules**: Ensures the stability of linting rules, preventing situations where updates to upstream configurations cause existing projects to fail linting.
-其中，ESLint 配置具备如下特点：
+The ESLint configuration has the following characteristics:
-1. **仅质量相关**：我们从数百条规则中筛选出数十条与编码质量相关的规则进行白名单开启，回归 Lint 本质，且不会与 Prettier 的规则冲突
-2. **性能优先**：部分 TypeScript 的规则实用型低但项目全量编译的成本却很高，我们对这些规则进行禁用以提升性能
-3. **内置常用插件**：包含 react、react-hooks、@typescript/eslint、jest，满足日常所需
+1. **Quality-focused**: We have selected a subset of rules from hundreds of available rules that are related to code quality. This approach focuses on the essence of linting while avoiding conflicts with Prettier rules.
+2. **Performance Priority**: We have disabled some TypeScript rules that are not very useful in practice but have a high compilation cost for the whole project.
+3. **Built-in Common Plugins**: It includes presets for react, react-hooks, @typescript/eslint, and jest to cover common needs.
-另外，Stylelint 配置还内置 CSS-in-JS 支持，可以检测出 JS 文件中的样式表语法错误。听起来很有吸引力？来看看如何接入吧。
+Additionally, the Stylelint configuration includes support for CSS-in-JS, enabling detection of syntax errors in style sheets within JavaScript files. Sounds appealing? Let's see how to integrate it.
-## 使用方式
-### 安装
+## Usage
+### Installation
-为了节省安装体积，目前仅在 Umi Max 中内置了 Lint 模块，使用 `max lint` 来执行 lint 过程。**如果你使用的是 Umi，需要先安装 `@umijs/lint`**：
+To save installation size, currently, the lint module is only built into Umi Max. Use `max lint` to run the linting process. **If you are using Umi, you need to install `@umijs/lint` first**:
```bash
$ npm i @umijs/lint -D
@@ -25,7 +25,7 @@ $ npm i @umijs/lint -D
$ pnpm add @umijs/lint -D
```
-然后安装 ESLint 及 Stylelint：
+Then install ESLint and Stylelint:
```bash
$ npm i eslint stylelint -D
@@ -33,62 +33,62 @@ $ npm i eslint stylelint -D
$ pnpm add eslint stylelint -D
```
-### 启用配置
+### Enabling Configurations
-在 `.eslintrc.js` 及 `.stylelintrc.js` 里继承 Umi 提供的配置：
+In `.eslintrc.js` and `.stylelintrc.js`, inherit the provided configurations from Umi:
```js
// .eslintrc.js
module.exports = {
- // Umi 项目
+ // For Umi projects
extends: require.resolve('umi/eslint'),
- // Umi Max 项目
+ // For Umi Max projects
extends: require.resolve('@umijs/max/eslint'),
}
// .stylelintrc.js
module.exports = {
- // Umi 项目
+ // For Umi projects
extends: require.resolve('umi/stylelint'),
- // Umi Max 项目
+ // For Umi Max projects
extends: require.resolve('@umijs/max/stylelint'),
}
```
-在配置文件创建完毕后，我们其实已经可以通过 `eslint`、`stylelint` 命令来执行 lint 了，但我们仍然推荐使用 `umi lint` 命令，以获得更便捷的体验。
+After creating the configuration files, you can use the `eslint` and `stylelint` commands to run linting. However, we still recommend using the `umi lint` command for a more convenient experience.
### CLI
-`umi lint` 命令的用法如下：
+The usage of the `umi lint` command is as follows:
```bash
$ umi lint [glob] [--fix] [--eslint-only] [--stylelint-only] [--cssinjs]
```
-参数说明：
+Parameter explanations:
```bash
- [glob]: 可选，指定要 lint 的文件，默认为 `{src,test}/**/*.{js,jsx,ts,tsx,css,less}`
- --quiet: 可选，禁用 `warn` 规则的报告，仅输出 `error`
- --fix: 可选，自动修复 lint 错误
- --eslint-only: 可选，仅执行 ESLint
- --stylelint-only: 可选，仅执行 Stylelint
- --cssinjs: 可选，为 Stylelint 启用 CSS-in-JS 支持
+ [glob]: Optional, specifies the files to lint. Defaults to `{src,test}/**/*.{js,jsx,ts,tsx,css,less}`
+ --quiet: Optional, disables reporting of `warn` rules, only outputs `error`
+ --fix: Optional, automatically fixes lint errors
+ --eslint-only: Optional, only executes ESLint
+ --stylelint-only: Optional, only executes Stylelint
+ --cssinjs: Optional, enables CSS-in-JS support for Stylelint
```
-通常来说，直接执行 `umi lint` 应该就能满足大部分情况。
+In most cases, simply running `umi lint` should suffice.
-## 与 Git 工作流结合
+## Integrating with Git Workflow
-我们也推荐使用 [lint-staged](https://github.com/okonet/lint-staged#readme) 和 [Husky](https://typicode.github.io/husky/)，将 `umi lint` 与 Git 工作流结合使用，以便在**提交代码时**自动 lint **本次变更**的代码。
+We also recommend using [lint-staged](https://github.com/okonet/lint-staged#readme) and [Husky](https://typicode.github.io/husky/) to automatically lint the code for the changes you're committing using the `umi lint` command.
### lint-staged
-lint-staged 用来驱动 `umi lint` 命令，每次仅将变更的内容交给 `umi lint` 进行检查。
+lint-staged is used to run the `umi lint` command on changed files only, ensuring that only modified files are checked.
-安装方式：
+Install lint-staged:
```bash
$ npm i lint-staged -D
@@ -96,7 +96,7 @@ $ npm i lint-staged -D
$ pnpm add lint-staged -D
```
-在 `package.json` 中配置 lint-staged：
+Configure lint-staged in `package.json`:
```diff
{
@@ -108,13 +108,13 @@ $ pnpm add lint-staged -D
}
```
-此时如果执行 `git add sample.js` 后，再执行 `npx lint-staged`，就能实现仅检查 `sample.js` 本次的变更了。
+Now, running `npx lint-staged` after adding a file (e.g., `git add sample.js`) will lint only the changes made to `sample.js`.
### Husky
-Husky 用来绑定 Git Hooks、在指定时机（例如 `pre-commit`）执行我们想要的命令，安装方式请参考 Husky 文档：https://typicode.github.io/husky/#/?id=automatic-recommended
+Husky is used to bind Git hooks and execute desired commands at specific events (e.g., `pre-commit`). Refer to the Husky documentation for installation: https://typicode.github.io/husky/#/?id=automatic-recommended
-初始化完成后，需要手动修改 `.husky/pre-commit` 文件的内容：
+After installation, manually modify the content of the `.husky/pre-commit` file:
```diff
#!/bin/sh
@@ -124,15 +124,17 @@ Husky 用来绑定 Git Hooks、在指定时机（例如 `pre-commit`）执行我
+ npx lint-staged
```
-至此大功告成，每次执行 `git commit` 命令的时候，`umi lint` 就能自动对本次变更的代码进行检查，在确保编码质量的同时也能确保执行效率。
+With this setup, every time you run `git commit`, the `umi lint`
+
+ command will automatically lint the code changes made in the commit. This ensures code quality and efficiency.
## Prettier
-在启用 `umi lint` 的基础上，我们也建议与 [Prettier](https://prettier.io/docs/en/install.html) 一同使用，以确保团队的代码风格是基本一致的。
+In addition to using `umi lint`, we also recommend using [Prettier](https://prettier.io/docs/en/install.html) to maintain consistent code formatting within the team.
-可参考 Prettier 文档将其配置到 lint-staged 中：https://prettier.io/docs/en/install.html#git-hooks
+You can refer to the Prettier documentation to configure it with lint-staged: https://prettier.io/docs/en/install.html#git-hooks
-## 附录
+## Appendix
-1. Umi 内置的 ESLint 规则列表：https://github.com/umijs/umi/blob/master/packages/lint/src/config/eslint/rules/recommended.ts
-2. Umi 内置的 Stylelint 配置：https://github.com/umijs/umi/blob/master/packages/lint/src/config/stylelint/index.ts
+1. List of built-in ESLint rules in Umi: https://github.com/umijs/umi/blob/master/packages/lint/src/config/eslint/rules/recommended.ts
+2. Built-in Stylelint configuration in Umi: https://github.com/umijs/umi/blob/master/packages/lint/src/config/stylelint/index.ts
diff --git a/docs/docs/guides/lint.zh-CN.md b/docs/docs/guides/lint.zh-CN.md
new file mode 100644
index 000000000000..74c9ab31fa6d
--- /dev/null
+++ b/docs/docs/guides/lint.zh-CN.md
@@ -0,0 +1,138 @@
+# 编码规范
+
+我们通常会在项目中使用 ESLint、Stylelint 来协助我们把控编码质量，为了实现低成本、高性能、更稳定地接入上述工具，Umi 提供了开箱即用的 Lint 能力，包含以下特性：
+
+1. **推荐配置**：提供 ESLint 及 Stylelint 推荐配置，可以直接继承使用
+2. **统一的 CLI**：提供 `umi lint` CLI，集成式调用 ESLint 和 Stylelint
+3. **规则稳定**：始终确保规则的稳定性，不会出现上游配置更新导致存量项目 lint 失败的情况
+
+其中，ESLint 配置具备如下特点：
+
+1. **仅质量相关**：我们从数百条规则中筛选出数十条与编码质量相关的规则进行白名单开启，回归 Lint 本质，且不会与 Prettier 的规则冲突
+2. **性能优先**：部分 TypeScript 的规则实用型低但项目全量编译的成本却很高，我们对这些规则进行禁用以提升性能
+3. **内置常用插件**：包含 react、react-hooks、@typescript/eslint、jest，满足日常所需
+
+另外，Stylelint 配置还内置 CSS-in-JS 支持，可以检测出 JS 文件中的样式表语法错误。听起来很有吸引力？来看看如何接入吧。
+
+## 使用方式
+### 安装
+
+为了节省安装体积，目前仅在 Umi Max 中内置了 Lint 模块，使用 `max lint` 来执行 lint 过程。**如果你使用的是 Umi，需要先安装 `@umijs/lint`**：
+
+```bash
+$ npm i @umijs/lint -D
+# or
+$ pnpm add @umijs/lint -D
+```
+
+然后安装 ESLint 及 Stylelint：
+
+```bash
+$ npm i eslint stylelint -D
+# or
+$ pnpm add eslint stylelint -D
+```
+
+### 启用配置
+
+在 `.eslintrc.js` 及 `.stylelintrc.js` 里继承 Umi 提供的配置：
+
+```js
+// .eslintrc.js
+module.exports = {
+ // Umi 项目
+ extends: require.resolve('umi/eslint'),
+
+ // Umi Max 项目
+ extends: require.resolve('@umijs/max/eslint'),
+}
+
+// .stylelintrc.js
+module.exports = {
+ // Umi 项目
+ extends: require.resolve('umi/stylelint'),
+
+ // Umi Max 项目
+ extends: require.resolve('@umijs/max/stylelint'),
+}
+```
+
+在配置文件创建完毕后，我们其实已经可以通过 `eslint`、`stylelint` 命令来执行 lint 了，但我们仍然推荐使用 `umi lint` 命令，以获得更便捷的体验。
+
+### CLI
+
+`umi lint` 命令的用法如下：
+
+```bash
+$ umi lint [glob] [--fix] [--eslint-only] [--stylelint-only] [--cssinjs]
+```
+
+参数说明：
+
+```bash
+ [glob]: 可选，指定要 lint 的文件，默认为 `{src,test}/**/*.{js,jsx,ts,tsx,css,less}`
+ --quiet: 可选，禁用 `warn` 规则的报告，仅输出 `error`
+ --fix: 可选，自动修复 lint 错误
+ --eslint-only: 可选，仅执行 ESLint
+ --stylelint-only: 可选，仅执行 Stylelint
+ --cssinjs: 可选，为 Stylelint 启用 CSS-in-JS 支持
+```
+
+通常来说，直接执行 `umi lint` 应该就能满足大部分情况。
+
+## 与 Git 工作流结合
+
+我们也推荐使用 [lint-staged](https://github.com/okonet/lint-staged#readme) 和 [Husky](https://typicode.github.io/husky/)，将 `umi lint` 与 Git 工作流结合使用，以便在**提交代码时**自动 lint **本次变更**的代码。
+
+### lint-staged
+
+lint-staged 用来驱动 `umi lint` 命令，每次仅将变更的内容交给 `umi lint` 进行检查。
+
+安装方式：
+
+```bash
+$ npm i lint-staged -D
+#or
+$ pnpm add lint-staged -D
+```
+
+在 `package.json` 中配置 lint-staged：
+
+```diff
+{
++ "lint-staged": {
++ "*.{js,jsx,ts,tsx,css,less}": [
++ "umi lint"
++ ]
++ }
+}
+```
+
+此时如果执行 `git add sample.js` 后，再执行 `npx lint-staged`，就能实现仅检查 `sample.js` 本次的变更了。
+
+### Husky
+
+Husky 用来绑定 Git Hooks、在指定时机（例如 `pre-commit`）执行我们想要的命令，安装方式请参考 Husky 文档：https://typicode.github.io/husky/#/?id=automatic-recommended
+
+初始化完成后，需要手动修改 `.husky/pre-commit` 文件的内容：
+
+```diff
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+- npm test
++ npx lint-staged
+```
+
+至此大功告成，每次执行 `git commit` 命令的时候，`umi lint` 就能自动对本次变更的代码进行检查，在确保编码质量的同时也能确保执行效率。
+
+## Prettier
+
+在启用 `umi lint` 的基础上，我们也建议与 [Prettier](https://prettier.io/docs/en/install.html) 一同使用，以确保团队的代码风格是基本一致的。
+
+可参考 Prettier 文档将其配置到 lint-staged 中：https://prettier.io/docs/en/install.html#git-hooks
+
+## 附录
+
+1. Umi 内置的 ESLint 规则列表：https://github.com/umijs/umi/blob/master/packages/lint/src/config/eslint/rules/recommended.ts
+2. Umi 内置的 Stylelint 配置：https://github.com/umijs/umi/blob/master/packages/lint/src/config/stylelint/index.ts
diff --git a/docs/docs/guides/mfsu.zh-CN.md b/docs/docs/guides/mfsu.zh-CN.md
new file mode 100644
index 000000000000..4bab180de727
--- /dev/null
+++ b/docs/docs/guides/mfsu.zh-CN.md
@@ -0,0 +1,152 @@
+import { Message } from 'umi'
+
+# MFSU
+
+## 什么是 MFSU
+
+MFSU 是一种基于 webpack5 新特性 Module Federation 的打包提速方案。其核心的思路是通过分而治之，将应用源代码的编译和应用依赖的编译分离，将变动较小的应用依赖构建为一个 Module Federation 的 remote 应用，以免去应用热更新时对依赖的编译。
+
+开启 MFSU 可以大幅减少热更新所需的时间了；因此我们在 Umi 的项目中默认开启了 MFSU 功能。当然你也可以通过配置 `mfsu: false` 来关闭它。
+
+## MFSU 的两种策略
+
+MFSU 最关键的一点是如何将应用代码的实际使用的依赖分析出来。根据不同的分析方式 MFSU 有两种工作方式。
+
+### normal 策略 (编译时分析)
+
+采用以下配置启用
+
+```ts {2}
+mfsu: {
+ strategy: 'normal',
+}
+```
+
+现代前端项目中的代码都需要经过转译(transpile)，才会在生产环境中使用。在转译的过程中转译器(比如：babel) 就会在代码中插入新的依赖。这些插入的依赖在项目代码层面是不可见， 但通过转译的插件才收集到。
+
+MFSU 编译时分析的工作方式，先对应用项目源码单独进行编译，编译的同时收集项目的本身依赖和编译引入的依赖。待项目代码编译完成以后，使用收集到的结果继续进行项目依赖部分的代码的构建。
+
+从下图中以 React 引用的构建举例可以看出，整个过程是串行的。
+
+
+
+### eager 策略 (扫描方式)
+
+```ts {2}
+mfsu: {
+ strategy: 'eager',
+}
+```
+
+和编译时分析的方式不同，扫描分析的方式会先读取项目中的所有源代码文件，然后通过静态分析的方式获取项目的依赖。这个过程非常的快，在一个有 17 万行代码，1400 多个文件项目中，分析一次只需要 700ms 左右。如此快速的分析的代价时，收集到的依赖会缺失后面项目代码编译插入的依赖；这部分的依赖最终和项目代码一起编译打包。
+
+分析完项目依赖之后，Umi 会拿着这份依赖信息，并行的去进行项目代码的编译和依赖的编译。
+
+从下图可以看出，编译部分是并行。
+
+
+
+
+## 两种构建工具
+
+MFSU 支持使用 Webpack 或者 esbuild 构建项目的依赖。默认配置使用 Webpack，和 Webpack 生态很好的兼容。
+Esbuild 通过 `mfsu: { esbuild: true }` 来开启，享受 Esbuild 的高效的构建速度。
+
+
+## 如何选择
+
+**编译时分析**的好处是收集的依赖是完整的，项目代码和依赖代码的构建打包完全分离；再项目代码修改以后只需要构建项目代码部分。缺点也很明显，构建的过程是串行的。
+
+**扫描的方式**的优点在于耗时的代码构建都是并行的，对于较大项目的冷启动时间改善非常明显。缺点则是有一部分运行时依赖会和项目代码一起编译。
+
+基于优缺点的分析，给出以下建议
+
+- 如果不使用 Module Federation 的功能的话，项目依赖变动不频繁，建议先尝试 esbuild 构建
+- 如果在 mono repo 项目中, 推荐使用 "normal" 策略; 推荐开启配置 ["monoreporedirect"](../api/config#monoreporedirect)
+- 如果你的项目较大，项目代码基数较大，推荐使用 "eager" 策略
+- 如果项目刚刚启动，会频繁的改动依赖，推荐使用 "eager" 策略
+- 其他类型的项目则随意选择。
+
+## 常见问题
+
+### 依赖缺失
+
+```bash /lodash.capitalize/
+error - [MFSU][eager] build worker failed AssertionError [ERR_ASSERTION]: filePath not found of lodash.capitalize
+```
+
+检查你的依赖确保，对应的依赖已经安装。( 如例子中的 `lodash.capitalize`)
+
+### React 多实例问题
+
+在浏览器中有如下报错
+
+
+
+根因在某些复杂场景下，React 的代码被打包多份，在运行时产出了多个 React 实例。解法通过 Module Federation 的 `shared` 配置来避免多实例的出现。
+如果有其他依赖出现多实例的问题，可以通过类似的方式解决。
+
+```ts {3-5}
+mfsu: {
+ shared: {
+ react: {
+ singleton: true,
+ },
+ },
+},
+```
+
+如果开启了 [MF插件](../max/mf), 需要开启 `shared`，请[参考](../max/mf#和-mfsu-一起使用)。
+
+
+### externals script 兼容问题
+
+如果项目依赖 a，a 依赖 b，而项目配置了 b 的 script 类型的 externals 如下。
+
+```ts
+externals: {
+ b: ['script https://cdn/b.js', b]
+}
+```
+
+在开启 MFSU 时会报错。
+
+```ts
+import * as b from 'b';
+console.log(b);
+```
+
+上述代码的 b 正常应该是 Module 信息，拿到的却是 `Promise`。我理解这是 webpack 的问题，没有处理好 externals script 和 module federation 之间的兼容问题，可能也是因为 externals script 很少有人知道和在使用。
+
+解法是不要和 MFSU 混着用，只在 `process.env.NODE_ENV === 'production'` 时开启。
+
+```ts
+externals: {
+ ...(process.env.NODE_ENV === 'production' ? {b: ['script https://cdn/b.js', b]} : {})
+}
+```
+
+### 依赖环问题
+
+#### 场景 1
+
+在使用 monorepo 时 ，项目依赖了 A 包，A 依赖了 B 包，而 B 包是项目 monorepo 中子包提供。这行就形成项目源码依赖 A ，A 又重新依赖项目源码的情况。
+这种情况建议使用 MFSU 的 exclude 配置。
+
+```ts {2-4}
+mfsu: {
+ exclude: [
+ 'B'
+ ]
+}
+```
+
+#### 场景 2
+
+项目的某个依赖的不合理的实现，项目中依赖了 Bigfish 插件相关的功能（即：引用了 `.umi` 目录下的内容 ）；在开启 MFSU 后项目可能不能正常编译；解法和场景 1 类似配置。将这个包配置进 `mfsu.exclude` 字段中。
+
+
+### worker 兼容问题
+
+如果项目代码需要在 Worker 中使用，那么需要将 Worker 需要的依赖添加到 MFSU 的 [`exclude` 配置中](../api/config#mfsu)。
+Worker 相关依赖只能通过这样方式来绕过，因为 Module Federation 是通过 `window` 对象来共享模块的，所以在 worker 中不能使用 Module Federation 中的模块。
diff --git a/docs/docs/guides/mock.md b/docs/docs/guides/mock.md
index 1a1992fe1a76..0b993fb8336c 100644
--- a/docs/docs/guides/mock.md
+++ b/docs/docs/guides/mock.md
@@ -1,17 +1,16 @@
-import {Message} from 'umi';
+import { Message } from 'umi';
# Mock
-Umi 提供了开箱即用的 Mock 功能，能够用方便简单的方式来完成 Mock 数据的设置。
+Umi provides built-in Mock functionality that allows you to easily set up mock data using a convenient and straightforward approach.
-什么是 Mock 数据：在前后端约定好 API 接口以后，前端可以使用 Mock 数据来在本地模拟出 API 应该要返回的数据，这样一来前后端开发就可以同时进行，不会因为后端 API
-还在开发而导致前端的工作被阻塞。
+What is Mock Data: After defining API interfaces between the frontend and backend, the frontend can use mock data to simulate the data that the API should return. This enables frontend and backend development to proceed simultaneously without blocking each other.
-## 目录约定
+## Directory Convention
-Umi 约定 `/mock` 目录下的所有文件为 [Mock 文件](#mock-文件)，例如这样的目录结构：
+Umi conventionally treats all files under the `/mock` directory as [Mock Files](#mock-files). For example, with the following directory structure:
```text
.
@@ -24,34 +23,34 @@ Umi 约定 `/mock` 目录下的所有文件为 [Mock 文件](#mock-文件)，例
└── index.tsx
```
-则 `/mock` 目录中的 `todos.ts`, `items.ts` 和 `users.ts` 就会被 Umi 视为 [Mock 文件](#mock-文件) 来处理。
+The files `todos.ts`, `items.ts`, and `users.ts` within the `/mock` directory will be recognized by Umi as [Mock Files](#mock-files) to be processed.
-## Mock 文件
+## Mock Files
-Mock 文件默认导出一个对象，而对象的每个 Key 对应了一个 Mock 接口，值则是这个接口所对应的返回数据，例如这样的 Mock 文件：
+Mock files should default export an object, where each key corresponds to a mock API endpoint, and the value represents the data to be returned for that endpoint. For example, in this mock file:
```ts
// ./mock/users.ts
export default {
- // 返回值可以是数组形式
+ // The return value can be an array
'GET /api/users': [
{ id: 1, name: 'foo' },
{ id: 2, name: 'bar' }
],
- // 返回值也可以是对象形式
+ // The return value can also be an object
'GET /api/users/1': { id: 1, name: 'foo' },
}
```
-就声明了两个 Mock 接口，透过 `GET /api/users` 可以拿到一个带有两个用户数据的数组，透过 `GET /api/users/1` 可以拿到某个用户的模拟数据。
+This defines two mock API endpoints. Accessing `GET /api/users` will return an array containing two user data objects, while accessing `GET /api/users/1` will return mock data for a specific user.
-### 请求方法
+### Request Methods
-当 Http 的请求方法是 GET 时，可以省略方法部分，只需要路径即可，例如：
+For HTTP GET requests, you can omit the method part and only provide the path. For example:
```ts
// ./mock/users.ts
@@ -68,7 +67,7 @@ export default {
}
```
-也可以用不同的请求方法，例如 `POST`，`PUT`，`DELETE`：
+You can also use different request methods, such as `POST`, `PUT`, `DELETE`:
```ts
// ./mock/users.ts
@@ -82,15 +81,15 @@ export default {
}
```
-### 自定义函数
+### Custom Functions
-除了直接静态声明返回值，也可以用函数的方式来声明如何计算返回值，例如：
+Instead of directly declaring static return values, you can use functions to determine how to calculate the return values. For example:
```ts
export default {
'POST /api/users/create': (req, res) => {
- // 添加跨域请求头
+ // Add cross-origin request header
res.setHeader('Access-Control-Allow-Origin', '*');
res.end('ok');
}
@@ -98,11 +97,12 @@ export default {
}
```
-关于 `req` 和 `res` 的 API 可参考 [Express@4 官方文档](https://expressjs.com/en/api.html) 来进一步了解。
+You can refer to the [Express@4 official documentation](https://expressjs.com/en/api.html) to learn more about the API for `req` and `res`.
### defineMock
-另外，也可以使用 `defineMock` 类型帮助函数来提供编写 mock 对象的代码提示，如：
+Additionally, you can use the `defineMock` type helper function to provide code hints for writing mock objects, like so:
+
```ts
import { defineMock } from "umi";
@@ -117,10 +117,11 @@ export default defineMock({
},
});
```
-`defineMock` 仅仅提供类型提示，入参与出参完全一致。
-## 关闭 Mock
-Umi 默认开启 Mock 功能，如果不需要的话可以从配置文件关闭：
+`defineMock` only provides type hints; the input and output are identical.
+## Disabling Mock
+
+Umi enables Mock functionality by default. If you don't need it, you can disable it through the configuration file:
```ts
// .umirc.ts
@@ -130,28 +131,27 @@ export default {
};
```
-或是用环境变量的方式关闭：
+Alternatively, you can disable it using environment variables:
```bash
MOCK=none umi dev
```
-## 引入 Mock.js
+## Integrating Mock.js
-在 Mock 中我们经常使用 [Mock.js](http://mockjs.com/) 来帮我们方便的生成随机的模拟数据，如果你使用了 Umi 的 Mock
-功能，建议你搭配这个库来提升模拟数据的真实性：
+In Mock, we often use [Mock.js](http://mockjs.com/) to generate random simulated data conveniently. If you're using Umi's Mock functionality, it's recommended to use this library to enhance the authenticity of your mock data:
```ts
import mockjs from 'mockjs';
export default {
- // 使用 mockjs 等三方库
+ // Use third-party libraries like mockjs
'GET /api/tags': mockjs.mock({
'list|100': [{ name: '@city', 'value|1-100': 50, 'type|0-2': 1 }],
}),
};
```
-## 其他配置
+## Other Configurations
-关于 Mock 功能完整的的其他配置项，请在文档的 [配置](../api/config#mock) 章节中查看。
+For the complete list of other configurations related to Mock functionality, refer to the [Configuration](../api/config#mock) section in the documentation.
\ No newline at end of file
diff --git a/docs/docs/guides/mock.zh-CN.md b/docs/docs/guides/mock.zh-CN.md
new file mode 100644
index 000000000000..1a1992fe1a76
--- /dev/null
+++ b/docs/docs/guides/mock.zh-CN.md
@@ -0,0 +1,157 @@
+import {Message} from 'umi';
+
+# Mock
+
+Umi 提供了开箱即用的 Mock 功能，能够用方便简单的方式来完成 Mock 数据的设置。
+
+
+什么是 Mock 数据：在前后端约定好 API 接口以后，前端可以使用 Mock 数据来在本地模拟出 API 应该要返回的数据，这样一来前后端开发就可以同时进行，不会因为后端 API
+还在开发而导致前端的工作被阻塞。
+
+
+## 目录约定
+
+Umi 约定 `/mock` 目录下的所有文件为 [Mock 文件](#mock-文件)，例如这样的目录结构：
+
+```text
+.
+├── mock
+ ├── todos.ts
+ ├── items.ts
+ └── users.ts
+└── src
+ └── pages
+ └── index.tsx
+```
+
+则 `/mock` 目录中的 `todos.ts`, `items.ts` 和 `users.ts` 就会被 Umi 视为 [Mock 文件](#mock-文件) 来处理。
+
+## Mock 文件
+
+Mock 文件默认导出一个对象，而对象的每个 Key 对应了一个 Mock 接口，值则是这个接口所对应的返回数据，例如这样的 Mock 文件：
+
+```ts
+// ./mock/users.ts
+
+export default {
+
+ // 返回值可以是数组形式
+ 'GET /api/users': [
+ { id: 1, name: 'foo' },
+ { id: 2, name: 'bar' }
+ ],
+
+ // 返回值也可以是对象形式
+ 'GET /api/users/1': { id: 1, name: 'foo' },
+
+}
+```
+
+就声明了两个 Mock 接口，透过 `GET /api/users` 可以拿到一个带有两个用户数据的数组，透过 `GET /api/users/1` 可以拿到某个用户的模拟数据。
+
+### 请求方法
+
+当 Http 的请求方法是 GET 时，可以省略方法部分，只需要路径即可，例如：
+
+```ts
+// ./mock/users.ts
+
+export default {
+
+ '/api/users': [
+ { id: 1, name: 'foo' },
+ { id: 2, name: 'bar' }
+ ],
+
+ '/api/users/1': { id: 1, name: 'foo' },
+
+}
+```
+
+也可以用不同的请求方法，例如 `POST`，`PUT`，`DELETE`：
+
+```ts
+// ./mock/users.ts
+
+export default {
+
+ 'POST /api/users': { result: 'true' },
+
+ 'PUT /api/users/1': { id: 1, name: 'new-foo' },
+
+}
+```
+
+### 自定义函数
+
+除了直接静态声明返回值，也可以用函数的方式来声明如何计算返回值，例如：
+
+```ts
+export default {
+
+ 'POST /api/users/create': (req, res) => {
+ // 添加跨域请求头
+ res.setHeader('Access-Control-Allow-Origin', '*');
+ res.end('ok');
+ }
+
+}
+```
+
+关于 `req` 和 `res` 的 API 可参考 [Express@4 官方文档](https://expressjs.com/en/api.html) 来进一步了解。
+
+### defineMock
+
+另外，也可以使用 `defineMock` 类型帮助函数来提供编写 mock 对象的代码提示，如：
+```ts
+import { defineMock } from "umi";
+
+export default defineMock({
+ "/api/users": [
+ { id: 1, name: "foo" },
+ { id: 2, name: "bar" },
+ ],
+ "/api/users/1": { id: 1, name: "foo" },
+ "GET /api/users/2": (req, res) => {
+ res.status(200).json({ id: 2, name: "bar" });
+ },
+});
+```
+`defineMock` 仅仅提供类型提示，入参与出参完全一致。
+## 关闭 Mock
+
+Umi 默认开启 Mock 功能，如果不需要的话可以从配置文件关闭：
+
+```ts
+// .umirc.ts
+
+export default {
+ mock: false,
+};
+```
+
+或是用环境变量的方式关闭：
+
+```bash
+MOCK=none umi dev
+```
+
+## 引入 Mock.js
+
+在 Mock 中我们经常使用 [Mock.js](http://mockjs.com/) 来帮我们方便的生成随机的模拟数据，如果你使用了 Umi 的 Mock
+功能，建议你搭配这个库来提升模拟数据的真实性：
+
+```ts
+import mockjs from 'mockjs';
+
+export default {
+ // 使用 mockjs 等三方库
+ 'GET /api/tags': mockjs.mock({
+ 'list|100': [{ name: '@city', 'value|1-100': 50, 'type|0-2': 1 }],
+ }),
+};
+```
+
+## 其他配置
+
+关于 Mock 功能完整的的其他配置项，请在文档的 [配置](../api/config#mock) 章节中查看。
diff --git a/docs/docs/guides/mpa.md b/docs/docs/guides/mpa.md
index 00869c834a63..4c1bf08b8658 100644
--- a/docs/docs/guides/mpa.md
+++ b/docs/docs/guides/mpa.md
@@ -1,12 +1,12 @@
-# MPA 模式
+# MPA Mode
-Umi 支持传统 MPA 模式，此模式下，会将 `src/pages` 目录下 `*/index.[jt]sx?` 文件作为 webpack entry 进行打包，无路由，无 history，无 umi.js，满足比如 h5 研发、kitchen 插件研发等场景需要。
+Umi supports the traditional MPA (Multi-Page Application) mode. In this mode, Umi treats the `*/index.[jt]sx?` files under the `src/pages` directory as individual webpack entries for building. There are no routes, no history, and no umi.js in this mode, making it suitable for scenarios like developing H5 projects or creating kitchen plugins.
-注意：此 MPA 模式和 Umi 3 的 MPA 模式的实现不同，Umi 4 是真 MPA，Umi 3 是 Mock 了路由渲染机制。各有利弊，Umi 4 的 MPA 将不能使用大量插件能力，仅适合当构建工具使用。
+Note: This MPA mode in Umi 4 is different from the MPA mode in Umi 3. Umi 4's MPA is a true MPA, whereas Umi 3's MPA mock-routes rendering mechanism. Each has its own advantages and disadvantages. Umi 4's MPA sacrifices some plugin capabilities and is mainly suitable for build tool usage.
-## 使用
+## Usage
-mpa 为内置功能，通过配置即可开启。
+MPA is an built-in feature that can be enabled through configuration.
```js
export default {
@@ -19,20 +19,20 @@ export default {
}
```
-MPA 的目录结构是 `src/pages/${dir}/index.tsx` ，每个文件夹 `${dir}` 会生成一个页面，文件夹内的 `index.tsx` 为页面的入口文件，示例见 [examples/mpa](https://github.com/umijs/umi/tree/master/examples/mpa) 。
+The MPA directory structure is `src/pages/${dir}/index.tsx`, where each `${dir}` directory will generate a separate page. The `index.tsx` file inside each directory is the entry file for that page. See [examples/mpa](https://github.com/umijs/umi/tree/master/examples/mpa) for an example.
-配置项：
+Configuration options:
- - `template` : 产物 HTML 模板，如 `template/index.html` 将使用项目根目录开始寻找，对应路径的 `index.html` 作为产物 HTML 模板。
- - `getConfigFromEntryFile` : 从每个页面的入口文件（`src/*/index.tsx`）中读取页面独立配置。
- - `layout` : 全局默认 layout 。
- - `entry` : 每个入口文件的配置，如 `{ foo: { title: '...' } }` 可以配置 `src/foo/index.tsx` 页面的 `title` 属性。
+- `template`: The HTML template for the output. For example, `template/index.html` will start searching from the root directory and use the corresponding `index.html` as the output HTML template.
+- `getConfigFromEntryFile`: Read page-specific configuration from each page's entry file (`src/*/index.tsx`).
+- `layout`: The default global layout.
+- `entry`: Configuration for each entry file. For example, `{ foo: { title: '...' } }` configures the `title` property for the `src/foo/index.tsx` page.
-## 约定的入口文件
+## Conventional Entry Files
-默认的入口文件是 `src/pages` 目录下 `*/index.[jt]sx?` 文件。
+The default entry files are the `*/index.[jt]sx?` files under the `src/pages` directory.
-比如：
+For example:
```
+ src/pages
@@ -41,7 +41,7 @@ MPA 的目录结构是 `src/pages/${dir}/index.tsx` ，每个文件夹 `${dir}`
- hoo.tsx
```
-那么，`entry` 结构为：
+The `entry` structure would be:
```ts
{
@@ -50,13 +50,13 @@ MPA 的目录结构是 `src/pages/${dir}/index.tsx` ，每个文件夹 `${dir}`
}
```
-构建之后，会同时为每个入口文件生成相应的 HTML 文件，此时产物为 `foo.html` 和 `bar.html` 。
+After building, an HTML file will be generated for each entry file, resulting in `foo.html` and `bar.html`.
-### 页面级配置
+### Page-Level Configuration
### config.json
-约定通过入口文件同层级的 `config.json` 声明配置，比如如下目录结构：
+You can declare configurations by placing a `config.json` file at the same level as the entry file. For example:
```
+ src/pages
@@ -65,7 +65,7 @@ MPA 的目录结构是 `src/pages/${dir}/index.tsx` ，每个文件夹 `${dir}`
- config.json
```
-`foo/config.json` 配置了该页面的独立 `layout` 布局和 `title` 标题：
+In this case, `foo/config.json` configures the page's individual `layout` and `title`:
```json
{
@@ -74,20 +74,16 @@ MPA 的目录结构是 `src/pages/${dir}/index.tsx` ，每个文件夹 `${dir}`
}
```
-目前默认支持的配置项包括：
+The currently supported configuration options include:
-* **template**：模板路径，可参考 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) 的模板写法，通过 lodash template 语法使用变量。
-* **layout**：页面布局，建议以 `@/` 开头引用 src 目录下的文件。
-* **title**：页面标题，默认是入口文件所在的目录名。
-* **mountElementId**：页面渲染时，挂载到节点的 id，默认是 `root` 。
+- **template**: The template path, following the [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) syntax and using lodash template syntax to include variables.
+- **layout**: The page layout, recommended to use `@/` to reference files under the `src` directory.
+- **title**: The page title, defaults to the directory name where the entry file is located.
+- **mountElementId**: The ID of the element where the page will be mounted when rendering, defaults to `root`.
### getConfigFromEntryFile
-Umi 还试验性地支持另一种配置读取方式，通过配置 `mpa: { getConfigFromEntryFile: true }` 开启。
-
-此时，你可以不使用 `config.json` ，而是在入口文件中通过 `export const config` 导出该页面的配置。
-
-比如：
+Umi also experimentally supports an alternative configuration method. You can use `export const config` in the entry file to export the page's configuration. For example:
```ts
// src/pages/foo/index.tsx
@@ -99,7 +95,7 @@ export const config = {
### entry
-在 `.umirc.ts` 中也可以配置每个页面：
+You can also configure each page in `.umirc.ts`:
```ts
mpa: {
@@ -109,19 +105,19 @@ export const config = {
}
```
-### 按需启动
+### On-Demand Startup
-支持通过设置 `env.MPA_FILTER` 来指定需要启动的页面，以提高构建速度
+You can speed up the build process by specifying the pages to be started using the `env.MPA_FILTER` environment variable.
```text
# file .env
-# 只会启动 bar、foo 这两个页面
+# Only start the bar and foo pages
MPA_FILTER=bar,foo
```
-## 渲染
+## Rendering
-默认渲染方式为 react，入口文件只需导出 react 组件，即可进行渲染，无需自行写 `ReactDOM.render` 逻辑。
+The default rendering method is React. You only need to export a React component from the entry file for rendering. There's no need to write the `ReactDOM.render` logic manually.
```tsx
export default function Page() {
@@ -129,15 +125,15 @@ export default function Page() {
}
```
-默认启用 React 18，如果需要 React 17 的渲染方式，请在项目中安装 react 17 的依赖，框架会自动适配 react 版本。
+React 18 is enabled by default. If you need the rendering method of React 17, you can install the dependencies for React 17 in your project. The framework will automatically adapt to the React version.
```bash
$ pnpm i react@17 react-dom@17
```
-## 模板
+## Template
-默认模板如下：
+The default template is as follows:
```html
@@ -151,4 +147,4 @@ $ pnpm i react@17 react-dom@17
```
-通过 `template` 配置自定义全局 HTML 模板 ，也可以进行页面级配置定义不同页面使用不同的模板，请确保变量至少包含 `<%= title %>` 和 `<%= mountElementId %>`。
+You can use the `template` configuration to customize the global HTML template. You can also define different templates for different pages using page-level configuration. Make sure the template variables include at least `<%= title %>` and `<%= mountElementId %>`.
diff --git a/docs/docs/guides/mpa.zh-CN.md b/docs/docs/guides/mpa.zh-CN.md
new file mode 100644
index 000000000000..00869c834a63
--- /dev/null
+++ b/docs/docs/guides/mpa.zh-CN.md
@@ -0,0 +1,154 @@
+# MPA 模式
+
+Umi 支持传统 MPA 模式，此模式下，会将 `src/pages` 目录下 `*/index.[jt]sx?` 文件作为 webpack entry 进行打包，无路由，无 history，无 umi.js，满足比如 h5 研发、kitchen 插件研发等场景需要。
+
+注意：此 MPA 模式和 Umi 3 的 MPA 模式的实现不同，Umi 4 是真 MPA，Umi 3 是 Mock 了路由渲染机制。各有利弊，Umi 4 的 MPA 将不能使用大量插件能力，仅适合当构建工具使用。
+
+## 使用
+
+mpa 为内置功能，通过配置即可开启。
+
+```js
+export default {
+ mpa: {
+ template: string,
+ getConfigFromEntryFile: boolean,
+ layout: string,
+ entry: object,
+ },
+}
+```
+
+MPA 的目录结构是 `src/pages/${dir}/index.tsx` ，每个文件夹 `${dir}` 会生成一个页面，文件夹内的 `index.tsx` 为页面的入口文件，示例见 [examples/mpa](https://github.com/umijs/umi/tree/master/examples/mpa) 。
+
+配置项：
+
+ - `template` : 产物 HTML 模板，如 `template/index.html` 将使用项目根目录开始寻找，对应路径的 `index.html` 作为产物 HTML 模板。
+ - `getConfigFromEntryFile` : 从每个页面的入口文件（`src/*/index.tsx`）中读取页面独立配置。
+ - `layout` : 全局默认 layout 。
+ - `entry` : 每个入口文件的配置，如 `{ foo: { title: '...' } }` 可以配置 `src/foo/index.tsx` 页面的 `title` 属性。
+
+## 约定的入口文件
+
+默认的入口文件是 `src/pages` 目录下 `*/index.[jt]sx?` 文件。
+
+比如：
+
+```
++ src/pages
+ - foo/index.tsx
+ - bar/index.tsx
+ - hoo.tsx
+```
+
+那么，`entry` 结构为：
+
+```ts
+{
+ foo: 'src/pages/foo/index.tsx',
+ bar: 'src/pages/bar/index.tsx'
+}
+```
+
+构建之后，会同时为每个入口文件生成相应的 HTML 文件，此时产物为 `foo.html` 和 `bar.html` 。
+
+### 页面级配置
+
+### config.json
+
+约定通过入口文件同层级的 `config.json` 声明配置，比如如下目录结构：
+
+```
++ src/pages
+ + foo
+ - index.tsx
+ - config.json
+```
+
+`foo/config.json` 配置了该页面的独立 `layout` 布局和 `title` 标题：
+
+```json
+{
+ "layout": "@/layouts/bar.ts",
+ "title": "foooooo"
+}
+```
+
+目前默认支持的配置项包括：
+
+* **template**：模板路径，可参考 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) 的模板写法，通过 lodash template 语法使用变量。
+* **layout**：页面布局，建议以 `@/` 开头引用 src 目录下的文件。
+* **title**：页面标题，默认是入口文件所在的目录名。
+* **mountElementId**：页面渲染时，挂载到节点的 id，默认是 `root` 。
+
+### getConfigFromEntryFile
+
+Umi 还试验性地支持另一种配置读取方式，通过配置 `mpa: { getConfigFromEntryFile: true }` 开启。
+
+此时，你可以不使用 `config.json` ，而是在入口文件中通过 `export const config` 导出该页面的配置。
+
+比如：
+
+```ts
+// src/pages/foo/index.tsx
+export const config = {
+ layout: '@/layouts/bar.ts',
+ title: 'foooooo',
+}
+```
+
+### entry
+
+在 `.umirc.ts` 中也可以配置每个页面：
+
+```ts
+ mpa: {
+ entry: {
+ foo: { title: 'foo title' }
+ }
+ }
+```
+
+### 按需启动
+
+支持通过设置 `env.MPA_FILTER` 来指定需要启动的页面，以提高构建速度
+
+```text
+# file .env
+# 只会启动 bar、foo 这两个页面
+MPA_FILTER=bar,foo
+```
+
+## 渲染
+
+默认渲染方式为 react，入口文件只需导出 react 组件，即可进行渲染，无需自行写 `ReactDOM.render` 逻辑。
+
+```tsx
+export default function Page() {
+ return <%= title %>
+
+
+
+
+
+```
+
+通过 `template` 配置自定义全局 HTML 模板 ，也可以进行页面级配置定义不同页面使用不同的模板，请确保变量至少包含 `<%= title %>` 和 `<%= mountElementId %>`。
diff --git a/docs/docs/guides/performance.zh-CN.md b/docs/docs/guides/performance.zh-CN.md
new file mode 100644
index 000000000000..6f543c6966af
--- /dev/null
+++ b/docs/docs/guides/performance.zh-CN.md
@@ -0,0 +1 @@
+# 产物性能
diff --git a/docs/docs/guides/plugins.md b/docs/docs/guides/plugins.md
index aac4b67e6889..cd4d963d67f1 100644
--- a/docs/docs/guides/plugins.md
+++ b/docs/docs/guides/plugins.md
@@ -1,10 +1,11 @@
-# 开发插件
-Umi 的核心就在于它的插件机制。基于 Umi 的插件机制，你可以获得扩展项目的编译时和运行时的能力。你可以利用我们提供的 [插件API](../api/plugin-api) 来自由编写插件，进而实现修改代码打包配置，修改启动代码，约定目录结构，修改 HTML 等丰富的功能。
+# Developing Plugins
-## 核心概念
-插件的本质就是一个方法，该方法接收了一个参数：api。在插件中，你可以调用 api 提供的方法进行一些 hook 的注册，随后 Umi 会在特定的时机执行这些 hook。
+The core of Umi based on its plugin mechanism. Based on Umi's plugin mechanism, you can extend the capabilities of your project during both compile-time and runtime. You can use the [Plugin API](../api/plugin-api) provided by Umi to freely write plugins and achieve various functionalities such as modifying code bundling configuration, altering startup code, defining directory structures, and modifying HTML content.
-比如：
+## Core Concepts
+A plugin in Umi is essentially a function that receives a parameter: `api`. Within a plugin, you can call methods provided by the `api` to register various hooks, which Umi will execute at specific times.
+
+For example:
```js
import { IApi } from 'umi';
@@ -24,148 +25,148 @@ export default (api: IApi) => {
});
};
```
-这个插件的作用是根据用户配置的 changeFavicon 值来更改配置中的 favicons，（一个很简单且没有实际用途的例子XD）。可以看到插件其实就是一个接收了参数 api 的方法。在这个方法中，我们调用了 `api.modifyConfig` 注册了一个 hook： `(memo)=>{...}`。当你在配置中配置了 `changeFavicon` 之后， Umi 会注册该插件。在 Umi 收集配置的生命周期里，我们在插件里注册的 hook 将被执行，此时配置中的 `favicon` 就会被修改为用户配置中的 `changeFavicon`
+In this example, the plugin's purpose is to change the `favicons` configuration based on the user's `changeFavicon` value (a simple and non-functional example). As you can see, a plugin is essentially a function that accepts the `api` parameter. Within this function, we call `api.modifyConfig` to register a hook `(memo) => {...}`. When you configure `changeFavicon` in your configuration, Umi will register this plugin. During Umi's configuration collection lifecycle, the hooks registered within the plugin will be executed, and the `favicon` configuration will be modified according to the user's `changeFavicon`
-### plugin 和 preset
-preset 的作用是预设一些插件，它通常用来注册一批 presets 和 plugins。在 preset 中，上述提到的接受 api 的方法可以有返回值，该返回值是一个包含 plugins 和 presets 属性的对象，其作用就是注册相应的插件或者插件集。
+### Plugin vs. Preset
+A preset is used to set up a group of plugins. It's typically used to register a set of presets and plugins together. Inside a preset, the method that receives the `api` parameter can return an object containing `plugins` and `presets` properties, which registers the corresponding plugins or plugin sets.
-比如：
+For example:
```js
import { IApi } from 'umi';
export default (api: IApi) => {
return {
- plugins: ['./plugin_foo','./plugin_bar'],
+ plugins: ['./plugin_foo', './plugin_bar'],
presets: ['./preset_foo']
}
};
```
-它们的注册顺序是值得注意的： presets 始终先于 plugins 注册。Umi 维护了两个队列分别用来依次注册 presets 和 plugins，这个例子中的注册的 `preset_foo` 将被置于 presets 队列队首，而 `plugin_foo` 和 `plugin_bar` 将被依次置于 plugins 队列队尾。这里把 preset 放在队首的目的在于保证 presets 之间的顺序和关系是可控的。
+The order of registration matters: presets are always registered before plugins. Umi maintains separate queues for registering presets and plugins. In the example above, the registered `preset_foo` will be placed at the front of the presets queue, while `plugin_foo` and `plugin_bar` will be placed at the end of the plugins queue. Placing presets at the front of the queue ensures that the order and relationship between presets are controlled.
-另外一个值得注意的点是：在 plugin 中，你也可以 return 一些 plugins 或者 presets，但是 Umi 不会对它做任何事情。
+It's important to note that presets registered within a plugin are immediately executed, whereas plugins registered within a preset are executed later.
-### 插件的 id 和 key
-每个插件都对应一个 id 和 key。
+### Plugin id and key
+Each plugin has an id and a key.
-id 是插件所在路径的简写，作为插件的唯一标识；而 key 则是用于插件配置的键名。
+id: The id of a plugin is a shorthand for the plugin's path, serves as a unique identifier for the plugin; key: The key of a plugin is used for configuring the plugin. It's the key under which you configure the plugin in your configuration.
-比如插件 `node_modules/@umijs/plugin-foo/index.js` ，通常来说，它的 id 是 `@umijs/plugin-foo` , key 是 `foo`。此时就允许开发者在配置中来配置键名为 `foo` 的项，用来对插件进行配置。
+For example, a plugin located at `node_modules/@umijs/plugin-foo/index.js` would have an ID of `@umijs/plugin-foo` and a key of `foo`. This allows you to configure the plugin using the key `foo`.
-## 启用插件
-插件有两种启用方式： 环境变量中启用和配置中启用。（与 `umi@3` 不同，我们不再支持对 `package.json` 中依赖项的插件实现自动启用）
+## Enabling Plugins
+There are two ways to enable plugins: using environment variables and using configuration. (Unlike in `umi@3`, plugins in dependencies are no longer automatically enabled.)
-注意：这里的插件指的是第三方插件，Umi 的内置插件统一在配置中通过对其 key 进行配置来启用。
+Note: The term "plugin" here refers to third-party plugins. Umi's built-in plugins are all enabled through configuration by setting their keys.
-### 环境变量
-还可以通过环境变量 `UMI_PRESETS` 和 `UMI_PLUGINS` 注册额外插件。
-比如：
+### Environment Variables
+You can also enable additional plugins using the `UMI_PRESETS` and `UMI_PLUGINS` environment variables.
+For example:
```shell
$ UMI_PRESETS = foo/preset.js umi dev
```
-注意： 项目里不建议使用，通常用于基于 Umi 的框架二次封装。
+Note: It's not recommended to use this in projects; it's usually used for secondary encapsulation of frameworks based on Umi.
-### 配置
-在配置里通过 `presets` 和 `plugins` 配置插件，比如：
+### Configuration
+In the configuration file, you can use the `presets` and `plugins` options to configure plugins. For example:
```js
export default {
presets: ['./preset/foo','bar/presets'],
plugins: ['./plugin', require.resolve('plugin_foo')]
}
```
-配置的内容为插件的路径。
-
-### 插件的顺序
-Umi 插件的注册遵循一定的顺序：
-- 所有的 presets 都先于 plugins 被注册。
-- 内置插件 -> 环境变量中的插件 -> 用户配置中的插件
-- 同时注册（同一个数组里）的插件按顺序依次注册。
-- preset 中注册的 preset 立即执行， 注册的 plugin 最后执行。
-
-## 禁用插件
-有两种方式禁用插件
-### 配置 key 为 false
-比如：
+The values provided in the configuration are the paths to the plugins.
+
+### Plugin Loading Order
+The registration of Umi plugins follows a specific order:
+- All presets are registered before plugins.
+- Built-in plugins -> Environment variable plugins -> User-configured plugins
+- Plugins registered simultaneously (within the same array) are registered in order.
+- Preset-registered presets are executed immediately, while preset-registered plugins are executed last.
+
+## Disabling Plugins
+There are two ways to disable plugins:
+### Setting the Key to `false`
+For example:
```js
export default{
mock: false
}
```
-会禁用 Umi 内置的 mock 插件。
+This will disable the built-in `mock` plugin in Umi.
-### 在插件中禁用其他插件
-可通过 `api.skipPlugins(pluginId[])` 的方式禁用，详见[插件 API](../api/plugin-api)。
+### Disabling Other Plugins Within a Plugin
+It can be disabled by `api.skipPlugins(pluginId[])`, see [Plugin API](../api/plugin-api) for details.
-## 查看插件注册情况
-### 命令行
+## Viewing Plugin Registration
+### Command line
```shell
$ umi plugin list
```
-## 配置插件
-通过配置插件的 key 来配置插件，比如：
+## Configuring Plugins
+You can configure plugins using their keys. For example:
```js
export default{
mock: { exclude: ['./foo'] }
}
```
-这里 mock 就是 Umi 内置插件 mock 的 key。
+Here, `mock` is the key for the built-in mock plugin in Umi.
-再比如我们安装一个插件 `umi-plugin-bar`, 其 key 默认是 `bar`, 就可以配置：
+If you install a plugin named `umi-plugin-bar`, and its key defaults to `bar`, you can configure it like this:
```js
export default{
bar: { ... }
}
```
-### 插件 key 的默认命名规则
-如果插件是一个包的话，key 的默认值将是去除前缀的包名。比如 `@umijs/plugin-foo` 的 key 默认为 `foo`， `@alipay/umi-plugin-bar` 的 key 默认为 `bar`。值得注意的是，该默认规则要求你的包名符合 Umi 插件的命名规范。
+### Default Naming Convention for Plugin Keys
+If a plugin is a package, the default key is the package name without the prefix. For instance, the key for `@umijs/plugin-foo` would be `foo`, and `@alipay/umi-plugin-bar` would have a default key of `bar`. Please note that the default naming convention assumes that your package name follows the Umi plugin naming convention.
-如果插件不是一个包的话，key 的默认值将是插件的文件名。比如 `./plugins/foo.js` 的 key 默认为 `foo`
+If a plugin is not a package, the default key is the plugin's filename. For instance, `./plugins/foo.js` would have a default key of `foo`.
-为了避免不必要的麻烦，我们建议你为自己编写的插件显示地声明其 key。
+To avoid unnecessary complications, it's recommended to explicitly declare the key for your self-written plugins.
-## Umi 插件的机制及其生命周期
+## Umi Plugin Mechanism and Its Lifecycle
-
+
-### 生命周期
+### Lifecycle Stages
-- init stage: 该阶段 Umi 将加载各类配置信息。包括：加载 `.env` 文件； require `package.json` ；加载用户的配置信息； resolve 所有的插件（内置插件、环境变量、用户配置依次进行）。
-- initPresets stage: 该阶段 Umi 将注册 presets。presets 在注册的时候可以通过 `return { presets, plugins }` 来添加额外的插件。其中 presets 将添加到 presets 队列的队首，而 plugins 将被添加到 plugins 队列的队尾。
-- initPlugins stage: 该阶段 Umi 将注册 plugins。这里的 plugins 包括上个阶段由 presets 添加的额外的 plugins， 一个值得注意的点在于： 尽管 plugins 也可以 `return { presets, plugins }` ，但是 Umi 不会对其进行任何操作。插件的 init 其实就是执行插件的代码（但是插件的代码本质其实只是调用 api 进行各种 hook 的注册，而 hook 的执行并非在此阶段执行，因此这里叫插件的注册）。
-- resolveConfig stage: 该阶段 Umi 将整理各个插件中对于 `config schema` 的定义，然后执行插件的 `modifyConfig` 、`modifyDefaultConfig`、 `modifyPaths` 等 hook，进行配置的收集。
-- collectionAppData stage: 该阶段 Umi 执行 `modifyAppData` hook，来维护 App 的元数据。（ `AppData` 是 `umi@4` 新增的 api ）
-- onCheck stage: 该阶段 Umi 执行 `onCheck` hook。
-- onStart stage: 该阶段 Umi 执行 `onStart` hook
-- runCommand stage: 该阶段 Umi 运行当前 cli 要执行的 command，（例如 `umi dev`, 这里就会执行 dev command）Umi 的各种核心功能都在 command 中实现。包括我们的插件调用 api 注册的绝大多数 hook。
+- init stage: In this stage, Umi loads various configuration information, including loading `.env` files, requiring `package.json`, loading user configuration, and resolving plugins (built-in plugins, environment variable plugins, and user-configured plugins).
+- initPresets stage: In this stage, Umi registers presets. Presets can add additional plugins by returning `{ presets, plugins }` in their registration methods. Presets will be added to the front of the presets queue, while plugins will be added to the end of the plugins queue.
+- initPlugins stage: In this stage, Umi registers plugins. This includes additional plugins added by presets in the previous stage. It's important to note that although plugins can also return `{ presets, plugins }`, Umi doesn't do anything with them in this stage. The `init` of a plugin is essentially executing the plugin's code, which mainly involves registering hooks through the `api`. The actual execution of these hooks doesn't happen in this stage, so it's referred to as the registration of the plugin.
+- resolveConfig stage: In this stage, Umi organizes the `config schema` definitions from various plugins and then executes hooks such as `modifyConfig`, `modifyDefaultConfig`, and `modifyPaths` to collect configuration information.
+- collectionAppData stage: In this stage, Umi executes the `modifyAppData` hook to maintain the app's metadata (the `AppData` is a new API introduced in `umi@4`).
+- onCheck stage: In this stage, Umi executes the `onCheck` hook.
+- onStart stage: In this stage, Umi executes the `onStart` hook.
+- runCommand stage: In this stage, Umi runs the current CLI command, such as `umi dev`. Umi's core functionalities are all implemented through commands. The various hooks registered by plugins through API calls are executed within this stage.
-以上就是 Umi 的插件机制的整体流程。
+The above description outlines the entire process of Umi's plugin mechanism.
-### `register()` 、 `registerMethod()` 以及 `applyPlugins()`
+### `register()`, `registerMethod()`, and `applyPlugins()`
-`register()` 接收一个 key 和 一个 hook，它维护了一个 `key-hook[]` 的 map，每当调用 `register()` 的时候，就会为 key 额外注册一个 hook。
+`register()` receives a key and a hook, it maintains a `key-hook[]` map, and whenever `register()` is called, an additional hook will be registered for the key.
-`register()` 注册的 hooks 供 applyPlugins 使用。 这些 hook 的执行顺序参照 [tapable](https://github.com/webpack/tapable)
+`register()` registers hooks for use by applyPlugins. The execution order of these hooks refers to [tapable](https://github.com/webpack/tapable)
-`registerMethod()` 接收一个 key 和 一个 fn，它会在 api 上注册一个方法。如果你没有向 `registerMethod()` 中传入 fn，那么 `registerMethod()` 会在 api 上注册一个"注册器"： 它会将 `register()` 传入 key 并柯里化后的结果作为 fn 注册到 api 上。这样就可以通过调用这个"注册器"，快捷地为 key 注册 hook 了。
+`registerMethod()` takes a key and a fn, it will register a method on the api. If you don't pass fn to `registerMethod()`, then `registerMethod()` will register a "registrar" on the api: it will pass `register()` into the key and curry the result as fn is registered on the api. In this way, the hook can be quickly registered for the key by calling this "registrar".
-关于上述 api 的更具体的使用，请参照[插件 API](../api/plugin-api)
+For more specific use of the above api, please refer to [Plugin API](../api/plugin-api)
-### PluginAPI 的原理
-Umi 会为每个插件赋予一个 PluginAPI 对象，这个对象引用了插件本身和 Umi 的 service。
+### PluginAPI's Underlying Mechanism
+Umi creates a PluginAPI object for each plugin. This object references both the plugin itself and Umi's service.
-Umi 为 PluginAPI 对象的 get() 方法进行了 proxy， 具体规则如下：
-- pluginMethod: 如果 prop 是 Umi 所维护的 `pluginMethods[]` ( `通过 registerMethod()` 注册的方法 ）中的方法，则返回这个方法。
-- service props: 如果 prop 是 serviceProps 数组中的属性（这些属性是 Umi 允许插件直接访问的属性），则返回 service 对应的属性。
-- static props: 如果 prop 是参数 staticProps 数组中的属性（这些属性是静态变量，诸如一些类型定义和常量），则将其返回。
-- 否则返回 api 的属性
+The `get()` method of the PluginAPI object is proxied by Umi and follows these rules:
+- pluginMethod: If the prop is one of Umi's `pluginMethods[]` (methods registered using `registerMethod()`), it returns that method.
+- service props: If the property is in the serviceProps array (these are properties that Umi allows plugins to directly access), it returns the corresponding property from the service.
+- static props: If the property is in the `staticProps` array (these are static variables like type definitions and constants), it returns that property.
+- Otherwise, it returns the corresponding property from the API.
-因此，Umi 提供给插件的 api 绝大多数都是依靠 `registerMethod()` 来实现的，你可以直接使用我们的这些 api 快速地在插件中注册 hook。这也是 Umi 将框架和功能进行解耦的体现： Umi 的 service 只提供插件的管理功能，而 api 都依靠插件来提供。
+This way, Umi provides most of the API to plugins through `registerMethod()`, allowing you to quickly register hooks within plugins. This separation between the framework and functionality is evident: Umi's service only provides plugin management functionality, while the API relies on plugins to provide functionality.
### preset-umi
-`umi-core` 提供了一套插件的注册及管理机制。而 Umi 的核心功能都靠 [preset-umi](https://github.com/umijs/umi/tree/master/packages/preset-umi) 来实现。
+`umi-core` provides a plugin registration and management mechanism. Umi's core functionalities are actually implemented through [preset-umi](https://github.com/umijs/umi/tree/master/packages/preset-umi).
-`preset-umi` 其实就是内置的一个插件集，它提供的插件分为三大类：
-- registerMethods 这类插件注册了一些上述提到的"注册器"，以供开发者快速地注册 hook，这类方法也占据了 PluginAPI 中的大多数。
-- features 这类插件为 Umi 提供了一些特性，例如 appData、lowImport、mock 等。
-- commands 这类插件注册了各类 command， 提供了 Umi CLI 的各种功能。Umi 能够在终端中正常运行，依靠的就是 command 提供的功能。
+`preset-umi` is essentially a built-in plugin set. It provides three types of plugins:
+- registerMethods: These plugins register some of the aforementioned "registerers," which allow developers to quickly register hooks. Most of the methods in `PluginAPI` fall into this category.
+- features: These plugins provide specific features to Umi, such as appData, lowImport, and mock.
+- commands: These plugins register various commands, providing different functionalities to the Umi CLI. Umi's ability to run in the terminal relies on these commands, which provide core functionalities to the CLI.
diff --git a/docs/docs/guides/plugins.zh-CN.md b/docs/docs/guides/plugins.zh-CN.md
new file mode 100644
index 000000000000..aac4b67e6889
--- /dev/null
+++ b/docs/docs/guides/plugins.zh-CN.md
@@ -0,0 +1,171 @@
+# 开发插件
+Umi 的核心就在于它的插件机制。基于 Umi 的插件机制，你可以获得扩展项目的编译时和运行时的能力。你可以利用我们提供的 [插件API](../api/plugin-api) 来自由编写插件，进而实现修改代码打包配置，修改启动代码，约定目录结构，修改 HTML 等丰富的功能。
+
+## 核心概念
+插件的本质就是一个方法，该方法接收了一个参数：api。在插件中，你可以调用 api 提供的方法进行一些 hook 的注册，随后 Umi 会在特定的时机执行这些 hook。
+
+比如：
+```js
+import { IApi } from 'umi';
+
+export default (api: IApi) => {
+ api.describe({
+ key: 'changeFavicon',
+ config: {
+ schema(joi) {
+ return joi.string();
+ },
+ },
+ enableBy: api.EnableBy.config
+ });
+ api.modifyConfig((memo)=>{
+ memo.favicons = api.userConfig.changeFavicon;
+ return memo;
+ });
+};
+```
+这个插件的作用是根据用户配置的 changeFavicon 值来更改配置中的 favicons，（一个很简单且没有实际用途的例子XD）。可以看到插件其实就是一个接收了参数 api 的方法。在这个方法中，我们调用了 `api.modifyConfig` 注册了一个 hook： `(memo)=>{...}`。当你在配置中配置了 `changeFavicon` 之后， Umi 会注册该插件。在 Umi 收集配置的生命周期里，我们在插件里注册的 hook 将被执行，此时配置中的 `favicon` 就会被修改为用户配置中的 `changeFavicon`
+
+### plugin 和 preset
+preset 的作用是预设一些插件，它通常用来注册一批 presets 和 plugins。在 preset 中，上述提到的接受 api 的方法可以有返回值，该返回值是一个包含 plugins 和 presets 属性的对象，其作用就是注册相应的插件或者插件集。
+
+比如：
+```js
+import { IApi } from 'umi';
+
+export default (api: IApi) => {
+ return {
+ plugins: ['./plugin_foo','./plugin_bar'],
+ presets: ['./preset_foo']
+ }
+};
+```
+它们的注册顺序是值得注意的： presets 始终先于 plugins 注册。Umi 维护了两个队列分别用来依次注册 presets 和 plugins，这个例子中的注册的 `preset_foo` 将被置于 presets 队列队首，而 `plugin_foo` 和 `plugin_bar` 将被依次置于 plugins 队列队尾。这里把 preset 放在队首的目的在于保证 presets 之间的顺序和关系是可控的。
+
+另外一个值得注意的点是：在 plugin 中，你也可以 return 一些 plugins 或者 presets，但是 Umi 不会对它做任何事情。
+
+### 插件的 id 和 key
+每个插件都对应一个 id 和 key。
+
+id 是插件所在路径的简写，作为插件的唯一标识；而 key 则是用于插件配置的键名。
+
+比如插件 `node_modules/@umijs/plugin-foo/index.js` ，通常来说，它的 id 是 `@umijs/plugin-foo` , key 是 `foo`。此时就允许开发者在配置中来配置键名为 `foo` 的项，用来对插件进行配置。
+
+## 启用插件
+插件有两种启用方式： 环境变量中启用和配置中启用。（与 `umi@3` 不同，我们不再支持对 `package.json` 中依赖项的插件实现自动启用）
+
+注意：这里的插件指的是第三方插件，Umi 的内置插件统一在配置中通过对其 key 进行配置来启用。
+
+### 环境变量
+还可以通过环境变量 `UMI_PRESETS` 和 `UMI_PLUGINS` 注册额外插件。
+比如：
+```shell
+$ UMI_PRESETS = foo/preset.js umi dev
+```
+注意： 项目里不建议使用，通常用于基于 Umi 的框架二次封装。
+
+### 配置
+在配置里通过 `presets` 和 `plugins` 配置插件，比如：
+```js
+export default {
+ presets: ['./preset/foo','bar/presets'],
+ plugins: ['./plugin', require.resolve('plugin_foo')]
+}
+```
+配置的内容为插件的路径。
+
+### 插件的顺序
+Umi 插件的注册遵循一定的顺序：
+- 所有的 presets 都先于 plugins 被注册。
+- 内置插件 -> 环境变量中的插件 -> 用户配置中的插件
+- 同时注册（同一个数组里）的插件按顺序依次注册。
+- preset 中注册的 preset 立即执行， 注册的 plugin 最后执行。
+
+## 禁用插件
+有两种方式禁用插件
+### 配置 key 为 false
+比如：
+```js
+export default{
+ mock: false
+}
+```
+会禁用 Umi 内置的 mock 插件。
+
+### 在插件中禁用其他插件
+可通过 `api.skipPlugins(pluginId[])` 的方式禁用，详见[插件 API](../api/plugin-api)。
+
+## 查看插件注册情况
+### 命令行
+```shell
+$ umi plugin list
+```
+
+## 配置插件
+通过配置插件的 key 来配置插件，比如：
+```js
+export default{
+ mock: { exclude: ['./foo'] }
+}
+```
+这里 mock 就是 Umi 内置插件 mock 的 key。
+
+再比如我们安装一个插件 `umi-plugin-bar`, 其 key 默认是 `bar`, 就可以配置：
+```js
+export default{
+ bar: { ... }
+}
+```
+
+### 插件 key 的默认命名规则
+如果插件是一个包的话，key 的默认值将是去除前缀的包名。比如 `@umijs/plugin-foo` 的 key 默认为 `foo`， `@alipay/umi-plugin-bar` 的 key 默认为 `bar`。值得注意的是，该默认规则要求你的包名符合 Umi 插件的命名规范。
+
+如果插件不是一个包的话，key 的默认值将是插件的文件名。比如 `./plugins/foo.js` 的 key 默认为 `foo`
+
+为了避免不必要的麻烦，我们建议你为自己编写的插件显示地声明其 key。
+
+## Umi 插件的机制及其生命周期
+
+
+
+### 生命周期
+
+- init stage: 该阶段 Umi 将加载各类配置信息。包括：加载 `.env` 文件； require `package.json` ；加载用户的配置信息； resolve 所有的插件（内置插件、环境变量、用户配置依次进行）。
+- initPresets stage: 该阶段 Umi 将注册 presets。presets 在注册的时候可以通过 `return { presets, plugins }` 来添加额外的插件。其中 presets 将添加到 presets 队列的队首，而 plugins 将被添加到 plugins 队列的队尾。
+- initPlugins stage: 该阶段 Umi 将注册 plugins。这里的 plugins 包括上个阶段由 presets 添加的额外的 plugins， 一个值得注意的点在于： 尽管 plugins 也可以 `return { presets, plugins }` ，但是 Umi 不会对其进行任何操作。插件的 init 其实就是执行插件的代码（但是插件的代码本质其实只是调用 api 进行各种 hook 的注册，而 hook 的执行并非在此阶段执行，因此这里叫插件的注册）。
+- resolveConfig stage: 该阶段 Umi 将整理各个插件中对于 `config schema` 的定义，然后执行插件的 `modifyConfig` 、`modifyDefaultConfig`、 `modifyPaths` 等 hook，进行配置的收集。
+- collectionAppData stage: 该阶段 Umi 执行 `modifyAppData` hook，来维护 App 的元数据。（ `AppData` 是 `umi@4` 新增的 api ）
+- onCheck stage: 该阶段 Umi 执行 `onCheck` hook。
+- onStart stage: 该阶段 Umi 执行 `onStart` hook
+- runCommand stage: 该阶段 Umi 运行当前 cli 要执行的 command，（例如 `umi dev`, 这里就会执行 dev command）Umi 的各种核心功能都在 command 中实现。包括我们的插件调用 api 注册的绝大多数 hook。
+
+以上就是 Umi 的插件机制的整体流程。
+
+### `register()` 、 `registerMethod()` 以及 `applyPlugins()`
+
+`register()` 接收一个 key 和 一个 hook，它维护了一个 `key-hook[]` 的 map，每当调用 `register()` 的时候，就会为 key 额外注册一个 hook。
+
+`register()` 注册的 hooks 供 applyPlugins 使用。 这些 hook 的执行顺序参照 [tapable](https://github.com/webpack/tapable)
+
+`registerMethod()` 接收一个 key 和 一个 fn，它会在 api 上注册一个方法。如果你没有向 `registerMethod()` 中传入 fn，那么 `registerMethod()` 会在 api 上注册一个"注册器"： 它会将 `register()` 传入 key 并柯里化后的结果作为 fn 注册到 api 上。这样就可以通过调用这个"注册器"，快捷地为 key 注册 hook 了。
+
+关于上述 api 的更具体的使用，请参照[插件 API](../api/plugin-api)
+
+### PluginAPI 的原理
+Umi 会为每个插件赋予一个 PluginAPI 对象，这个对象引用了插件本身和 Umi 的 service。
+
+Umi 为 PluginAPI 对象的 get() 方法进行了 proxy， 具体规则如下：
+- pluginMethod: 如果 prop 是 Umi 所维护的 `pluginMethods[]` ( `通过 registerMethod()` 注册的方法 ）中的方法，则返回这个方法。
+- service props: 如果 prop 是 serviceProps 数组中的属性（这些属性是 Umi 允许插件直接访问的属性），则返回 service 对应的属性。
+- static props: 如果 prop 是参数 staticProps 数组中的属性（这些属性是静态变量，诸如一些类型定义和常量），则将其返回。
+- 否则返回 api 的属性
+
+因此，Umi 提供给插件的 api 绝大多数都是依靠 `registerMethod()` 来实现的，你可以直接使用我们的这些 api 快速地在插件中注册 hook。这也是 Umi 将框架和功能进行解耦的体现： Umi 的 service 只提供插件的管理功能，而 api 都依靠插件来提供。
+
+### preset-umi
+`umi-core` 提供了一套插件的注册及管理机制。而 Umi 的核心功能都靠 [preset-umi](https://github.com/umijs/umi/tree/master/packages/preset-umi) 来实现。
+
+`preset-umi` 其实就是内置的一个插件集，它提供的插件分为三大类：
+- registerMethods 这类插件注册了一些上述提到的"注册器"，以供开发者快速地注册 hook，这类方法也占据了 PluginAPI 中的大多数。
+- features 这类插件为 Umi 提供了一些特性，例如 appData、lowImport、mock 等。
+- commands 这类插件注册了各类 command， 提供了 Umi CLI 的各种功能。Umi 能够在终端中正常运行，依靠的就是 command 提供的功能。
diff --git a/docs/docs/guides/prepare.md b/docs/docs/guides/prepare.md
index 097e204cb97c..0fa399b4d472 100644
--- a/docs/docs/guides/prepare.md
+++ b/docs/docs/guides/prepare.md
@@ -1,19 +1,19 @@
import { Message } from 'umi';
-# 开发环境
+# Dev Environment
-本文将带领你从零开始在本地搭建一个 Umi.js 项目的开发环境。
+This article will guide you through setting up a local development environment for a Umi.js project from scratch.
-## Nodejs
+## Node.js
-Umi.js 需要使用 [Node.js](https://nodejs.org/zh-cn/) 来进行开发，因此请先确保电脑已经安装了 Node.js 且版本在 14 以上。
+Umi.js requires [Node.js](https://nodejs.org/) for development, so please make sure you have Node.js installed on your computer with a version of 14 or above.
-如果你是 macOS 用户，建议使用 [nvm](https://github.com/nvm-sh/nvm) 来管理 Node.js 的版本；
-Windows 用户建议使用 [nvm-windows](https://github.com/coreybutler/nvm-windows) 。
+If you are a macOS user, it's recommended to use [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions.
+For Windows users, it's recommended to use [nvm-windows](https://github.com/coreybutler/nvm-windows).
-本文将以 macOS 或 Linux 环境下使用 [nvm](https://github.com/nvm-sh/nvm) 的方式安装 [Node.js](https://nodejs.org/zh-cn/) ：
+This article assumes you're using macOS or Linux and will show you how to install [Node.js](https://nodejs.org/) using [nvm](https://github.com/nvm-sh/nvm):
```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
@@ -22,14 +22,14 @@ nvm -v
0.39.1
```
-安装完成 [nvm](https://github.com/nvm-sh/nvm) 之后，使用以下命令来安装 [Node.js](https://nodejs.org/zh-cn/) ：
+After installing [nvm](https://github.com/nvm-sh/nvm), use the following commands to install [Node.js](https://nodejs.org/):
```bash
nvm install 16
nvm use 16
```
-安装完成后，使用以下命令来检查是否安装成功并且安装了正确的版本：
+After installation, use the following command to check if the installation was successful and if the correct version is installed:
```bash
node -v
@@ -37,15 +37,15 @@ node -v
v16.14.0
```
-## 依赖管理
+## Dependency Management
-Node 安装完成后会自带 [npm](https://www.npmjs.com/) 依赖管理工具，但 Umi.js 推荐使用 [pnpm](https://pnpm.io/) 来管理依赖：
+After installing Node, you'll have the [npm](https://www.npmjs.com/) dependency management tool. However, Umi.js recommends using [pnpm](https://pnpm.io/) to manage dependencies:
```bash
curl -fsSL https://get.pnpm.io/install.sh | sh -
```
-安装完成后，可以用以下命令检查是否安装成功：
+After installation, you can use the following command to check if the installation was successful:
```bash
pnpm -v
@@ -55,14 +55,14 @@ pnpm -v
## IDE
-安装完 [Node.js](https://nodejs.org/zh-cn/) 及 [pnpm](https://pnpm.io/) (或其他依赖管理工具) 后，你需要一个自己习惯的 IDE 或文本编辑器来编写代码。如果你还没有习惯的 IDE，可以从下方挑选一个：
+Once you've installed [Node.js](https://nodejs.org/) and [pnpm](https://pnpm.io/) (or other dependency management tools), you'll need an IDE or text editor to write your code. If you don't have a preferred IDE, you can choose one from the list below:
-1. [Visual Studio Code](https://code.visualstudio.com/) (推荐)
-2. [WebStorm](https://www.jetbrains.com/webstorm/) (推荐)
+1. [Visual Studio Code](https://code.visualstudio.com/) (recommended)
+2. [WebStorm](https://www.jetbrains.com/webstorm/) (recommended)
3. [IntelliJ IDEA](https://www.jetbrains.com/idea/)
4. [Sublime Text](https://www.sublimetext.com/)
5. [Atom](https://atom.io/)
-## 下一步
+## Next Steps
-恭喜你！你的本地环境已经准备好开始开发 Umi.js 项目了，马上前往 [脚手架](boilerplate) 学习如何使用 Umi.js 脚手架快速启动一个项目吧 🎉
+Congratulations! Your local environment is ready to start developing Umi.js projects. Head over to [Boilerplate](boilerplate) to learn how to quickly start a project using the Umi.js scaffold 🎉
\ No newline at end of file
diff --git a/docs/docs/guides/prepare.zh-CN.md b/docs/docs/guides/prepare.zh-CN.md
new file mode 100644
index 000000000000..097e204cb97c
--- /dev/null
+++ b/docs/docs/guides/prepare.zh-CN.md
@@ -0,0 +1,68 @@
+import { Message } from 'umi';
+
+# 开发环境
+
+本文将带领你从零开始在本地搭建一个 Umi.js 项目的开发环境。
+
+## Nodejs
+
+Umi.js 需要使用 [Node.js](https://nodejs.org/zh-cn/) 来进行开发，因此请先确保电脑已经安装了 Node.js 且版本在 14 以上。
+
+
+如果你是 macOS 用户，建议使用 [nvm](https://github.com/nvm-sh/nvm) 来管理 Node.js 的版本；
+Windows 用户建议使用 [nvm-windows](https://github.com/coreybutler/nvm-windows) 。
+
+
+本文将以 macOS 或 Linux 环境下使用 [nvm](https://github.com/nvm-sh/nvm) 的方式安装 [Node.js](https://nodejs.org/zh-cn/) ：
+
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
+nvm -v
+
+0.39.1
+```
+
+安装完成 [nvm](https://github.com/nvm-sh/nvm) 之后，使用以下命令来安装 [Node.js](https://nodejs.org/zh-cn/) ：
+
+```bash
+nvm install 16
+nvm use 16
+```
+
+安装完成后，使用以下命令来检查是否安装成功并且安装了正确的版本：
+
+```bash
+node -v
+
+v16.14.0
+```
+
+## 依赖管理
+
+Node 安装完成后会自带 [npm](https://www.npmjs.com/) 依赖管理工具，但 Umi.js 推荐使用 [pnpm](https://pnpm.io/) 来管理依赖：
+
+```bash
+curl -fsSL https://get.pnpm.io/install.sh | sh -
+```
+
+安装完成后，可以用以下命令检查是否安装成功：
+
+```bash
+pnpm -v
+
+7.3.0
+```
+
+## IDE
+
+安装完 [Node.js](https://nodejs.org/zh-cn/) 及 [pnpm](https://pnpm.io/) (或其他依赖管理工具) 后，你需要一个自己习惯的 IDE 或文本编辑器来编写代码。如果你还没有习惯的 IDE，可以从下方挑选一个：
+
+1. [Visual Studio Code](https://code.visualstudio.com/) (推荐)
+2. [WebStorm](https://www.jetbrains.com/webstorm/) (推荐)
+3. [IntelliJ IDEA](https://www.jetbrains.com/idea/)
+4. [Sublime Text](https://www.sublimetext.com/)
+5. [Atom](https://atom.io/)
+
+## 下一步
+
+恭喜你！你的本地环境已经准备好开始开发 Umi.js 项目了，马上前往 [脚手架](boilerplate) 学习如何使用 Umi.js 脚手架快速启动一个项目吧 🎉
diff --git a/docs/docs/guides/proxy.md b/docs/docs/guides/proxy.md
index 8e15932e0fe7..ab0c22ba2f41 100644
--- a/docs/docs/guides/proxy.md
+++ b/docs/docs/guides/proxy.md
@@ -1,10 +1,10 @@
-# 代理
+# Proxy
-> 代理也称网络代理，是一种特殊的网络服务，允许一个终端（一般为客户端）通过这个服务与另一个终端（一般为服务器）进行非直接的连接。- [维基百科](https://zh.wikipedia.org/wiki/%E4%BB%A3%E7%90%86%E6%9C%8D%E5%8A%A1%E5%99%A8)
+> A proxy, also known as a network proxy, is a special kind of network service that allows one endpoint (usually a client) to establish a non-direct connection with another endpoint (usually a server). - [Wikipedia](https://en.wikipedia.org/wiki/Proxy_server)
-在项目开发（dev）中，所有的网络请求（包括资源请求）都会通过本地的 server 做响应分发，我们通过使用 [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware) 中间件，来代理指定的请求到另一个目标服务器上。如请求 `fetch('/api')` 来取到远程 `http://jsonplaceholder.typicode.com/` 的数据。
+During project development (dev), all network requests (including resource requests) are dispatched through a local server, which uses the [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware) middleware to proxy specified requests to another target server. For example, sending a request `fetch('/api')` retrieves data from the remote `http://jsonplaceholder.typicode.com/`.
-要实现上述的需求我们只需要在配置文件中使用 proxy 配置：
+To achieve this requirement, you only need to use the proxy configuration in your configuration file:
```ts
export default {
@@ -18,15 +18,13 @@ export default {
}
```
-上述配置表示，将 `/api` 前缀的请求，代理到 `http://jsonplaceholder.typicode.com/`，替换请求地址中的 `/api` 为 `''`，并且将请求来源修改为目标url。如请求 `/api/a`，实际上是请求 `http://jsonplaceholder.typicode.com/a`。
+In the above configuration, requests with the `/api` prefix are proxied to `http://jsonplaceholder.typicode.com/`. The `/api` part in the request address is replaced with `''`, and the source of the request is changed to the target URL. For example, a request to `/api/a` actually makes a request to `http://jsonplaceholder.typicode.com/a`.
-一般我们使用这个能力来解开发中的跨域访问问题。由于浏览器（或者 webview）存在同源策略，之前我们会让服务端配合使用 Cross-Origin Resource Sharing (CORS) 策略来绕过跨域访问问题。现在有了本地的 node 服务，我们就可以使用代理来解决这个问题。
+Generally, we use this capability to address cross-origin access issues during development. Due to the same-origin policy enforced by browsers (or webviews), we used to require server-side cooperation using Cross-Origin Resource Sharing (CORS) policies to bypass cross-origin access issues. Now, with a local Node.js server, we can use proxy to solve this problem.
> XMLHttpRequest cannot load https://api.example.com. No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://localhost:8000' is therefore not allowed access.
-原理其实很简单，就是浏览器上有跨域问题，但是服务端没有跨域问题。我们请求同源的本地服务，然后让本地服务去请求非同源的远程服务。需要注意的是，请求代理，代理的是请求的服务，不会直接修改发起的请求 url。它只是将目标服务器返回的数据传递到前端。所以你在浏览器上看到的请求地址还是 `http://localhost:8000/api/a`。
-
-值得注意的是 proxy 暂时只能解开发时（dev）的跨域访问问题，可以在部署时使用同源部署。如果在生产上（build）的发生跨域问题的话，可以将类似的配置转移到 Nginx 容器上。
+The principle is quite simple: there is a cross-origin issue in the browser, but not on the server. We send requests to our local same-origin server, which then requests the remote non-same-origin server. It's important to note that request proxying affects the server being requested and doesn't directly modify the request URL being initiated. It simply forwards the data returned by the target server to the frontend. Therefore, the request address you see in your browser will still be `http://localhost:8000/api/a`.
diff --git a/docs/docs/guides/proxy.zh-CN.md b/docs/docs/guides/proxy.zh-CN.md
new file mode 100644
index 000000000000..8e15932e0fe7
--- /dev/null
+++ b/docs/docs/guides/proxy.zh-CN.md
@@ -0,0 +1,32 @@
+# 代理
+
+> 代理也称网络代理，是一种特殊的网络服务，允许一个终端（一般为客户端）通过这个服务与另一个终端（一般为服务器）进行非直接的连接。- [维基百科](https://zh.wikipedia.org/wiki/%E4%BB%A3%E7%90%86%E6%9C%8D%E5%8A%A1%E5%99%A8)
+
+在项目开发（dev）中，所有的网络请求（包括资源请求）都会通过本地的 server 做响应分发，我们通过使用 [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware) 中间件，来代理指定的请求到另一个目标服务器上。如请求 `fetch('/api')` 来取到远程 `http://jsonplaceholder.typicode.com/` 的数据。
+
+要实现上述的需求我们只需要在配置文件中使用 proxy 配置：
+
+```ts
+export default {
+ proxy: {
+ '/api': {
+ 'target': 'http://jsonplaceholder.typicode.com/',
+ 'changeOrigin': true,
+ 'pathRewrite': { '^/api' : '' },
+ },
+ },
+}
+```
+
+上述配置表示，将 `/api` 前缀的请求，代理到 `http://jsonplaceholder.typicode.com/`，替换请求地址中的 `/api` 为 `''`，并且将请求来源修改为目标url。如请求 `/api/a`，实际上是请求 `http://jsonplaceholder.typicode.com/a`。
+
+一般我们使用这个能力来解开发中的跨域访问问题。由于浏览器（或者 webview）存在同源策略，之前我们会让服务端配合使用 Cross-Origin Resource Sharing (CORS) 策略来绕过跨域访问问题。现在有了本地的 node 服务，我们就可以使用代理来解决这个问题。
+
+> XMLHttpRequest cannot load https://api.example.com. No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://localhost:8000' is therefore not allowed access.
+
+原理其实很简单，就是浏览器上有跨域问题，但是服务端没有跨域问题。我们请求同源的本地服务，然后让本地服务去请求非同源的远程服务。需要注意的是，请求代理，代理的是请求的服务，不会直接修改发起的请求 url。它只是将目标服务器返回的数据传递到前端。所以你在浏览器上看到的请求地址还是 `http://localhost:8000/api/a`。
+
+值得注意的是 proxy 暂时只能解开发时（dev）的跨域访问问题，可以在部署时使用同源部署。如果在生产上（build）的发生跨域问题的话，可以将类似的配置转移到 Nginx 容器上。
+
+
+
diff --git a/docs/docs/guides/routes.md b/docs/docs/guides/routes.md
index f56b0dcd1ac1..0116b51b2ff6 100644
--- a/docs/docs/guides/routes.md
+++ b/docs/docs/guides/routes.md
@@ -1,18 +1,18 @@
import { Message } from 'umi';
-# 路由
+# Routing
-在 Umi 应用是[单页应用](https://en.wikipedia.org/wiki/Single-page_application)，页面地址的跳转都是在浏览器端完成的，不会重新请求服务端获取 html，html 只在应用初始化时加载一次。所有页面由不同的组件构成，页面的切换其实就是不同组件的切换，你只需要在配置中把不同的路由路径和对应的组件关联上。
+In Umi applications, which are [single-page applications](https://en.wikipedia.org/wiki/Single-page_application), page navigation occurs on the client-side within the browser. This means that the server isn't re-requested to fetch HTML content, and the HTML is loaded only once during the application initialization. Different pages are composed of various components, and switching between pages involves changing the active component associated with the corresponding route path.
-## 路由类型配置
+## Route Type Configuration
-请参考 [history](../api/config#history) 配置。
+Please refer to the [history](../api/config#history) configuration.
-## 配置路由
+## Configuring Routes
-在配置文件中通过 `routes` 进行配置，格式为路由信息的数组。
+Routes are configured in the configuration file using the `routes` field, which is an array containing route information.
-比如：
+For example:
```ts
// .umirc.ts
@@ -24,19 +24,19 @@ export default {
}
```
-Umi 4 默认按页拆包，从而有更快的页面加载速度，由于加载过程是异步的，所以往往你需要编写 [`loading.tsx`](./directory-structure#loadingtsxjsx) 来给项目添加加载样式，提升体验。
+Umi 4 by default splits pages into separate bundles, resulting in faster page loading times. Since the loading process is asynchronous, you often need to create a [`loading.tsx`](./directory-structure#loadingtsxjsx) file to add loading styles and enhance the user experience.
-你可以在 Chrome Devtools > 网络 Tab 中将网络设置成低速，然后切换路由查看加载组件是否生效。
+You can use Chrome Devtools > Network Tab to simulate a slow network speed. This can help you verify whether loading components are effective when switching routes.
### path
* Type: `string`
-`path` 只支持两种占位符配置，第一种是动态参数 `:id` 的形式，第二种是 `*` 通配符，通配符只能出现路由字符串的最后。
+The `path` supports two types of placeholders. The first type is dynamic parameters in the form of `:id`, and the second type is the `*` wildcard, which can only appear at the end of the route string.
-✅ 以下是目前***支持***的路由路径配置形式：
+✅ Here are the currently ***supported*** route path configurations:
```txt
/groups
@@ -47,7 +47,7 @@ Umi 4 默认按页拆包，从而有更快的页面加载速度，由于加载
/files/:id/*
```
-❌ 以下是目前***不支持***的路由路径配置形式：
+❌ Here are the currently ***unsupported*** route path configurations:
```txt
/users/:id?
/tweets/:id(\d+)
@@ -59,15 +59,15 @@ Umi 4 默认按页拆包，从而有更快的页面加载速度，由于加载
* Type: `string`
-配置 location 和 path 匹配后用于渲染的 React 组件路径。可以是绝对路径，也可以是相对路径，如果是相对路径，会从 `src/pages` 开始寻找。
+This field configures the React component path used for rendering when `location` matches `path`. The component path can be either an absolute or relative path. If it's a relative path, it will start searching from `src/pages`.
-如果指向 `src` 目录的文件，可以用 `@`，比如 `component: '@/layouts/basic'`，推荐使用 `@` 组织路由文件位置。
+You can use `@` to reference files within the `src` directory, for example: `component: '@/layouts/basic'`. Using `@` is recommended for organizing your route file locations.
### routes
-配置子路由，通常在需要为多个路径增加 layout 组件时使用。
+This field configures child routes and is typically used when you want to associate multiple paths with a layout component.
-比如：
+For example:
```js
export default {
@@ -85,7 +85,7 @@ export default {
}
```
-在全局布局 `src/layouts/index` 中，通过 `
-`wrappers` 中的每个组件会给当前的路由组件增加一层嵌套路由，如果你希望路由结构不发生变化，推荐使用高阶组件。先在高阶组件中实现 wrapper 中的逻辑，然后使用该高阶组件装饰对应的路由组件。
+Each component in the `wrappers` array adds a nested route layer to the current route component. If you want to keep the route structure unchanged, it's recommended to use higher-order components. First, implement the logic from the wrapper in the higher-order component, then use the higher-order component to decorate the corresponding route component.
-举例：
+For example:
```jsx
// src/hocs/withAuth.tsx
import { Navigate } from 'umi'
-const withAuth = (Component) => ()=>{
+const withAuth = (Component) => () => {
const { isLogin } = useAuth();
if (isLogin) {
return
-推荐使用 `useLocation`, 而不是直接访问 `history.location`. 两者的区别是 `pathname` 的部分。
-`history.location.pathname` 是完整的浏览器的路径名；而 `useLocation` 中返回的 `pathname` 是相对项目配置的`base`的路径。
+It's recommended to use `useLocation` instead of directly accessing `history.location`. The main difference is in the `pathname` part.
+`history.location.pathname` provides the full browser pathname, whereas `useLocation().pathname` returns a pathname relative to the project's `base` configuration.
-举例：项目如果配置 `base: '/testbase'`, 当前浏览器地址为 `https://localhost:8000/testbase/page/apple`
+For example: If the project has a `base: '/testbase'` configuration and the current browser address is `https://localhost:8000/testbase/page/apple`:
-`history.location.pathname` 为 `/testbase/page/apple`
+`history.location.pathname` is `/testbase/page/apple`.
-`useLocation().pathname` 为 `/page/apple`
+`useLocation().pathname` is `/page/apple`.
-### 路由动态参数
+### Route Dynamic Parameters
[useParams](https://reactrouter.com/docs/en/v6/api#useparams)
```jsx
-// 路由配置 /comp/:id
-// 当前 location /comp/paramId
+// Route configuration: /comp/:id
+// Current location: /comp/paramId
const params = useParams();
// params
@@ -457,18 +457,17 @@ const params = useParams();
}
```
-### query 信息
+### Query Information
[useSearchParams](https://reactrouter.com/docs/en/v6/api#usesearchparams)
```jsx
-// 当前 location /comp?a=b;
+// Current location: /comp?a=b;
const [searchParams, setSearchParams] = useSearchParams();
searchParams.get('a') // b
searchParams.toString() // a=b
-setSearchParams({a:'c',d:'e'}) // location 变成 /comp?a=c&d=e
+setSearchParams({a:'c',d:'e'}) // Location changes to /comp?a=c&d=e
```
-`searchParams`的 api [参考](https://developer.mozilla.org/zh-CN/docs/Web/API/URL/searchParams)
-
+For the `searchParams` API, you can [refer to this link](https://developer.mozilla.org/zh-CN/docs/Web/API/URL/searchParams).
\ No newline at end of file
diff --git a/docs/docs/guides/routes.zh-CN.md b/docs/docs/guides/routes.zh-CN.md
new file mode 100644
index 000000000000..f56b0dcd1ac1
--- /dev/null
+++ b/docs/docs/guides/routes.zh-CN.md
@@ -0,0 +1,474 @@
+import { Message } from 'umi';
+
+# 路由
+
+在 Umi 应用是[单页应用](https://en.wikipedia.org/wiki/Single-page_application)，页面地址的跳转都是在浏览器端完成的，不会重新请求服务端获取 html，html 只在应用初始化时加载一次。所有页面由不同的组件构成，页面的切换其实就是不同组件的切换，你只需要在配置中把不同的路由路径和对应的组件关联上。
+
+## 路由类型配置
+
+请参考 [history](../api/config#history) 配置。
+
+## 配置路由
+
+在配置文件中通过 `routes` 进行配置，格式为路由信息的数组。
+
+比如：
+
+```ts
+// .umirc.ts
+export default {
+ routes: [
+ { path: '/', component: 'index' },
+ { path: '/user', component: 'user' },
+ ],
+}
+```
+
+Umi 4 默认按页拆包，从而有更快的页面加载速度，由于加载过程是异步的，所以往往你需要编写 [`loading.tsx`](./directory-structure#loadingtsxjsx) 来给项目添加加载样式，提升体验。
+
+
+你可以在 Chrome Devtools > 网络 Tab 中将网络设置成低速，然后切换路由查看加载组件是否生效。
+
+
+### path
+
+* Type: `string`
+
+`path` 只支持两种占位符配置，第一种是动态参数 `:id` 的形式，第二种是 `*` 通配符，通配符只能出现路由字符串的最后。
+
+✅ 以下是目前***支持***的路由路径配置形式：
+
+```txt
+/groups
+/groups/admin
+/users/:id
+/users/:id/messages
+/files/*
+/files/:id/*
+```
+
+❌ 以下是目前***不支持***的路由路径配置形式：
+```txt
+/users/:id?
+/tweets/:id(\d+)
+/files/*/cat.jpg
+/files-*
+```
+
+### component
+
+* Type: `string`
+
+配置 location 和 path 匹配后用于渲染的 React 组件路径。可以是绝对路径，也可以是相对路径，如果是相对路径，会从 `src/pages` 开始寻找。
+
+如果指向 `src` 目录的文件，可以用 `@`，比如 `component: '@/layouts/basic'`，推荐使用 `@` 组织路由文件位置。
+
+### routes
+
+配置子路由，通常在需要为多个路径增加 layout 组件时使用。
+
+比如：
+
+```js
+export default {
+ routes: [
+ { path: '/login', component: 'login' },
+ {
+ path: '/',
+ component: '@/layouts/index',
+ routes: [
+ { path: '/list', component: 'list' },
+ { path: '/admin', component: 'admin' },
+ ],
+ },
+ ],
+}
+```
+
+在全局布局 `src/layouts/index` 中，通过 `
+`wrappers` 中的每个组件会给当前的路由组件增加一层嵌套路由，如果你希望路由结构不发生变化，推荐使用高阶组件。先在高阶组件中实现 wrapper 中的逻辑，然后使用该高阶组件装饰对应的路由组件。
+
+
+举例：
+
+```jsx
+// src/hocs/withAuth.tsx
+import { Navigate } from 'umi'
+
+const withAuth = (Component) => ()=>{
+ const { isLogin } = useAuth();
+ if (isLogin) {
+ return
+推荐使用 `useLocation`, 而不是直接访问 `history.location`. 两者的区别是 `pathname` 的部分。
+`history.location.pathname` 是完整的浏览器的路径名；而 `useLocation` 中返回的 `pathname` 是相对项目配置的`base`的路径。
+
+举例：项目如果配置 `base: '/testbase'`, 当前浏览器地址为 `https://localhost:8000/testbase/page/apple`
+
+`history.location.pathname` 为 `/testbase/page/apple`
+
+`useLocation().pathname` 为 `/page/apple`
+
+
+### 路由动态参数
+
+[useParams](https://reactrouter.com/docs/en/v6/api#useparams)
+
+```jsx
+// 路由配置 /comp/:id
+// 当前 location /comp/paramId
+
+const params = useParams();
+// params
+{
+ "id": "paramId"
+}
+```
+
+### query 信息
+
+[useSearchParams](https://reactrouter.com/docs/en/v6/api#usesearchparams)
+
+```jsx
+// 当前 location /comp?a=b;
+const [searchParams, setSearchParams] = useSearchParams();
+searchParams.get('a') // b
+searchParams.toString() // a=b
+
+setSearchParams({a:'c',d:'e'}) // location 变成 /comp?a=c&d=e
+```
+
+`searchParams`的 api [参考](https://developer.mozilla.org/zh-CN/docs/Web/API/URL/searchParams)
+
diff --git a/docs/docs/guides/styling.md b/docs/docs/guides/styling.md
index dac57469c98f..c109c97d7813 100644
--- a/docs/docs/guides/styling.md
+++ b/docs/docs/guides/styling.md
@@ -1,14 +1,14 @@
import { Message } from 'umi';
-# 样式
+# Styling
-本文介绍各种在 Umi 项目中使用样式的方式。
+This article introduces various ways to use styles in Umi projects.
-## 使用 CSS 样式
+## Using CSS Styles
-你可以在 Umi 项目中使用 `.css` 文件声明各种样式，然后在 `.js` 文件中引入即可生效。
+You can declare various styles in `.css` files in your Umi project and then import them in `.js` files to make them effective.
-例如，在 `src/pages/index.css` 文件按照以下代码声明 `.title` 类的样式为红色：
+For example, in the `src/pages/index.css` file, declare the `.title` class's style to be red:
```css
.title {
@@ -16,7 +16,7 @@ import { Message } from 'umi';
}
```
-然后在 `src/pages/index.tsx` 文件中引入即可生效。
+Then, import it in the `src/pages/index.tsx` file to apply the style:
```jsx
// src/pages/index.tsx
@@ -28,12 +28,11 @@ export default function () {
}
```
-按照此种引入方式的样式会在整个 Umi 项目中生效，即无论你从哪个 `.js`
-文件引入，他声明的样式可以在任何页面和组件中使用。如果你想要避免这种情况，可以使用 [CSS Modules](#使用-css-modules) 的功能来限制样式的作用域。
+Using this import method, the style will be applied throughout the entire Umi project. It means that the styles declared in one `.js` file can be used in any page or component. If you want to avoid this behavior, you can use the [CSS Modules](#using-css-modules) feature to limit the scope of the styles.
-## 使用 CSS Modules
+## Using CSS Modules
-在 `js` 文件中引入样式时，如果赋予他一个变量名，就可以将样式以 CSS Module 的形式引入。
+When importing styles in `js` files, you can import them as CSS Modules by assigning them a variable name.
```jsx
// src/pages/index.tsx
@@ -47,14 +46,14 @@ export default function () {
}
```
-上面的示例中，`index.css` 文件中声明的样式不会对全局样式造成影响，只会对从 `styles` 变量中使用的样式生效。
+In the example above, the styles declared in the `index.css` file will not affect global styles; they will only be applied to the styles used from the `styles` variable.
-## 使用 CSS 预处理器
+## Using CSS Preprocessors
-Umi 默认支持 LESS (推荐)，SASS 和 SCSS 样式的导入，你可以直接按照引入 CSS 文件的方式引入并使用这些由 CSS 预处理器处理的样式。
+Umi supports importing styles processed by CSS preprocessors like LESS (recommended), SASS, and SCSS. You can import and use these styles just like importing CSS files.
-
-在 Umi 中使用 Sass(Scss) 需要额外安装预处理依赖 如: `npm add -D sass`
+
+To use Sass(Scss) in Umi, you need to install the preprocessor dependencies additionally, such as `npm add -D sass`.
```jsx
@@ -69,7 +68,7 @@ export default function () {
}
```
-同样也支持 CSS Module 的用法：
+CSS Modules usage is also supported:
```jsx
// src/pages/index.tsx
@@ -87,28 +86,26 @@ export default function () {
}
```
-## 进阶设置
+## Advanced Settings
-如果你需要使用除了常见的 LESS, SASS 或 SCSS 以外的其他样式预处理器，你可以透过 Umi
-插件提供的 [chainWebpack 接口](../api/config#chainwebpack)来加入自己需要的 Loader。
+If you need to use a CSS preprocessor other than the commonly used LESS, SASS, or SCSS, you can add the necessary loaders using the [chainWebpack interface](../api/config#chainwebpack) provided by Umi plugins.
-## 使用 Tailwindcss
+## Using Tailwind CSS
-Umi 提供了内置的 [Tailwindcss](https://tailwindcss.com/)
-插件，并且可以直接方便地使用 [微生成器](./generator#tailwind-css-配置生成器) 来启用。
+Umi provides a built-in [Tailwind CSS](https://tailwindcss.com/) plugin, and you can easily enable it using the [scaffolding generator](./generator#tailwind-css-配置生成器).
-## 使用 UnoCSS
+## Using UnoCSS
-与 Tailwindcss 相同，Umi 也提供了内置的 [UnoCSS](https://github.com/unocss/unocss) 插件，可以按照相同方式开启。
+Similar to Tailwind CSS, Umi also offers a built-in [UnoCSS](https://github.com/unocss/unocss) plugin, which can be enabled in the same manner.
-1. 安装 `plugin-unocss`
-2. 安装 `unocss` 及 `@unocss/cli`
+1. Install the `plugin-unocss` plugin.
+2. Install `unocss` and `@unocss/cli`.
```bash
pnpm i unocss @unocss/cli
```
-3. 在 Umi 设置中启用插件，并声明会用到 `unocss` 的文件目录
+3. Enable the plugin in the Umi configuration and specify the directory where `unocss` will be used.
```js
// .umirc.ts
@@ -118,27 +115,27 @@ export default {
require.resolve('@umijs/plugins/dist/unocss')
],
unocss: {
- // 检测 className 的文件范围，若项目不包含 src 目录，可使用 `pages/**/*.tsx`
+ // Specify the file scope to check className. If your project doesn't contain the src directory, you can use `pages/**/*.tsx`.
watch: ['src/**/*.tsx']
},
};
```
-4. 在项目目录下加入 `unocss.config.ts`
- 配置文件，并加入项目需要的 [UnoCSS Presets](https://github.com/unocss/unocss#presets)
+4. Add the `unocss.config.ts` configuration file to your project directory and include the necessary [UnoCSS Presets](https://github.com/unocss/unocss#presets).
```js
// unocss.config.ts
-import {defineConfig, presetAttributify, presetUno} from 'unocss';
+import { defineConfig, presetAttributify, presetUno } from 'unocss';
-export function createConfig({strict = true, dev = true} = {}) {
+export function createConfig({ strict = true, dev = true } = {}) {
return defineConfig({
- envMode: dev ? 'dev' : 'build', presets: [presetAttributify({strict}), presetUno()],
+ envMode: dev ? 'dev' : 'build',
+ presets: [presetAttributify({ strict }), presetUno()],
});
}
-export default createConfig();
+export default createConfig();
```
-5. 启动项目进行开发，插件会监听设置文件中的 `unocss.watch` 字段，动态生成样式文件并自动套用
+5. Start your project for development, and the plugin will monitor the `unocss.watch` field in the settings file, dynamically generate style files, and apply them automatically.
\ No newline at end of file
diff --git a/docs/docs/guides/styling.zh-CN.md b/docs/docs/guides/styling.zh-CN.md
new file mode 100644
index 000000000000..dac57469c98f
--- /dev/null
+++ b/docs/docs/guides/styling.zh-CN.md
@@ -0,0 +1,144 @@
+import { Message } from 'umi';
+
+# 样式
+
+本文介绍各种在 Umi 项目中使用样式的方式。
+
+## 使用 CSS 样式
+
+你可以在 Umi 项目中使用 `.css` 文件声明各种样式，然后在 `.js` 文件中引入即可生效。
+
+例如，在 `src/pages/index.css` 文件按照以下代码声明 `.title` 类的样式为红色：
+
+```css
+.title {
+ color: red;
+}
+```
+
+然后在 `src/pages/index.tsx` 文件中引入即可生效。
+
+```jsx
+// src/pages/index.tsx
+
+import './index.css';
+
+export default function () {
+ return
+在 Umi 中使用 Sass(Scss) 需要额外安装预处理依赖 如: `npm add -D sass`
+
+
+```jsx
+// src/pages/index.tsx
+
+import './index.less';
+import './index.sass';
+import './index.scss';
+
+export default function () {
+ return
-umi 项目
+For a Umi project:
```ts
import { Config, configUmiAlias, createConfig } from 'umi/test';
@@ -22,13 +20,13 @@ export default async () => {
jsTransformer: 'esbuild',
jsTransformerOpts: { jsx: 'automatic' },
}),
- // 覆盖 umi 的默认 jest 配置, 如
+ // Override Umi's default Jest configuration, such as
// displayName: "Umi jest",
})) as Config.InitialOptions;
};
```
-@umijs/max 项目
+For a @umijs/max project:
```ts
import { Config, configUmiAlias, createConfig } from '@umijs/max/test';
@@ -40,7 +38,7 @@ export default async () => {
jsTransformer: 'esbuild',
jsTransformerOpts: { jsx: 'automatic' },
}),
- // 覆盖 umi 的默认 jest 配置, 如
+ // Override Umi's default Jest configuration, such as
// displayName: "Umi jest",
})) as Config.InitialOptions;
};
@@ -48,21 +46,23 @@ export default async () => {
-配置完后，就可以开始编写单元测试了。
+After configuration, you can start writing unit tests.
-## 与 UI 无关的测试
+## Testing UI-Independent Logic
-假设我们需要测试一个 utils 函数 `reverseApiData`, 它将 api 请求的结果 `data` 对象的 key 和 value 互换。
+Suppose we need to test a utility function called `reverseApiData`, which swaps the keys and values of an `data` object obtained from an API request.
-我们推荐将测试文件被测模块放在同一级目录，这样可以方便查看测试文件以便理解模块的功能。
+We recommend placing the test file in the same directory as the module being tested. This makes it easier to understand the module's functionality by viewing the test file.
```txt
.
└── utils
- ├── reverseApiData.test.tss
+ ├── reverseApiData.test.ts
└── reverseApiData.ts
```
+Here's the implementation of the utility function:
+
```ts
// utils/reverseApiData.ts
export async function reverseApiData(url: string, fetcher = fetch) {
@@ -79,32 +79,29 @@ export async function reverseApiData(url: string, fetcher = fetch) {
}
```
-先来写我们第一个测试用例, 确保 `fetcher` 使用传入的 `url` 请求 api 的数据
+Let's start by writing our first test case to ensure that the `fetcher` uses the provided `url` to request API data:
```ts
import { reverseApiData } from './reverseApiData';
-// 测试用例名字表明测试的目的
test('reverseApiData use fetcher to request url', async () => {
- // 测试用例以 3A 的结构来写
-
- // Arrange 准备阶段，准备 mock 函数或者数据
+ // Arrange (Setup) phase: Prepare mock functions or data
const fetcher = jest.fn().mockResolvedValue({
json: () => Promise.resolve(),
});
- // Act 执行被测对象
+ // Act phase: Execute the function being tested
await reverseApiData('https://api.end/point', fetcher);
- // Assert 断言测试结果
+ // Assert phase: Assert the test result
expect(fetcher).toBeCalledWith('https://api.end/point');
});
```
-执行测试
+Run the test:
```bash
-$npx jest
+$ npx jest
info - generate files
PASS src/utils/reverseApiData.test.ts
@@ -116,10 +113,10 @@ Ran all test suites.
```
-可以使用`npx jest --watch` 让 jest 进程不退出，这样能省去启动重新 jest 的等待时间。
+You can use `npx jest --watch` to keep the Jest process running, eliminating the need to restart Jest every time.
-我们再写一个用例来测试这个工具函数完成了键值的对换功能。
+Let's write another test case to test the functionality of this utility function: swapping key-value pairs.
```ts
test('reverseApiData reverse simple object', async () => {
@@ -133,15 +130,15 @@ test('reverseApiData reverse simple object', async () => {
});
```
-让每个测试用例只关注一个功能点，可以让用例在重构的时候给我们更准确的反馈，改动破坏了什么功能。更多的用例请 [参考](https://github.com/umijs/umi/tree/master/examples/test-test/utils/reverseApiData.test.ts)
+Remember to focus each test case on a specific aspect of functionality. This makes it easier to get precise feedback during refactoring, indicating which functionality might have been affected by changes. For more test cases, you can refer to the [example](https://github.com/umijs/umi/tree/master/examples/test-test/utils/reverseApiData.test.ts).
-## UI 测试
+## UI Testing
-组件和 UI 相关的测试推荐使用 `@testing-library/react`。
+For testing components and UI-related code, we recommend using `@testing-library/react`.
-### 渲染结果判断
+### Rendering Result Assertion
-- 使用 jest 的 snapshot
+- Using Jest snapshots
```tsx
// examples/test-test/components/Greet/Greet.test.tsx
@@ -155,9 +152,9 @@ test('renders Greet without name by snapshot', () => {
});
```
-执行 `npx jest` 后会在测试用例同级目录会生成 `__snapshots__` 文件夹和用例的 snapshot，请加入到版本管理中。
+After running `npx jest`, a `__snapshots__` folder will be generated in the same directory as the test case, along with the snapshots. Include these snapshots in version control.
-- 使用 jest 的 inline snapshot
+- Using Jest inline snapshots
```tsx
// examples/test-test/components/Greet/Greet.test.tsx
@@ -168,9 +165,9 @@ test('renders Greet without name by inline snapshot', () => {
});
```
-执行 `npx jest` 后会在 `toMatchInlineSnapshot` 函数的参数中填入 snapshot 字符串；这种方式适合渲染结果比较短的内容。
+After running `npx jest`, the snapshot string will be filled into the argument of the `toMatchInlineSnapshot` function. This method is suitable for rendering results with shorter content.
-- 使用 @testing-library/jest-dom 断言
+- Using @testing-library/jest-dom assertions
```tsx
// examples/test-test/components/Greet/Greet.test.tsx
@@ -184,9 +181,9 @@ test('renders Greet without name assert by testing-library', () => {
});
```
-更多[断言 API](https://github.com/testing-library/jest-dom)
+For more assertion APIs, refer to the [Jest DOM](https://github.com/testing-library/jest-dom) documentation.
-### 组件行为判断
+### Component Behavior Assertion
```tsx
// examples/test-test/components/Greet/Greet.test.tsx
diff --git a/docs/docs/guides/test.zh-CN.md b/docs/docs/guides/test.zh-CN.md
new file mode 100644
index 000000000000..c3cde837cff9
--- /dev/null
+++ b/docs/docs/guides/test.zh-CN.md
@@ -0,0 +1,203 @@
+import { Message, Tabbed } from 'umi';
+
+# 测试
+
+自动化测试是保障质量的有效手段，Umi 4 提供单元测试的脚手架。Umi 4 推荐使用 [Jest](https://jestjs.io/) 和 [@testing-library/react](https://github.com/testing-library/react-testing-library) 来完成项目中的单元测试。
+
+## 配置
+
+使用 Umi 4 的微生成器快速的配置好 Jest [参考](./generator#jest-配置生成器), 如果你需要修改 jest 相关的配置，可以在 `jest.config.ts` 修改。
+
+
+
+umi 项目
+
+```ts
+import { Config, configUmiAlias, createConfig } from 'umi/test';
+
+export default async () => {
+ return (await configUmiAlias({
+ ...createConfig({
+ target: 'browser',
+ jsTransformer: 'esbuild',
+ jsTransformerOpts: { jsx: 'automatic' },
+ }),
+ // 覆盖 umi 的默认 jest 配置, 如
+ // displayName: "Umi jest",
+ })) as Config.InitialOptions;
+};
+```
+
+@umijs/max 项目
+
+```ts
+import { Config, configUmiAlias, createConfig } from '@umijs/max/test';
+
+export default async () => {
+ return (await configUmiAlias({
+ ...createConfig({
+ target: 'browser',
+ jsTransformer: 'esbuild',
+ jsTransformerOpts: { jsx: 'automatic' },
+ }),
+ // 覆盖 umi 的默认 jest 配置, 如
+ // displayName: "Umi jest",
+ })) as Config.InitialOptions;
+};
+```
+
+
+
+配置完后，就可以开始编写单元测试了。
+
+## 与 UI 无关的测试
+
+假设我们需要测试一个 utils 函数 `reverseApiData`, 它将 api 请求的结果 `data` 对象的 key 和 value 互换。
+
+我们推荐将测试文件被测模块放在同一级目录，这样可以方便查看测试文件以便理解模块的功能。
+
+```txt
+.
+└── utils
+ ├── reverseApiData.test.tss
+ └── reverseApiData.ts
+```
+
+```ts
+// utils/reverseApiData.ts
+export async function reverseApiData(url: string, fetcher = fetch) {
+ const res = await fetcher(url);
+ const json = await res.json();
+
+ const { data = {} } = json;
+ const reversed: Record = {};
+ for (const key of Object.keys(data)) {
+ const val = data[key];
+ reversed[val] = key;
+ }
+ return reversed;
+}
+```
+
+先来写我们第一个测试用例, 确保 `fetcher` 使用传入的 `url` 请求 api 的数据
+
+```ts
+import { reverseApiData } from './reverseApiData';
+
+// 测试用例名字表明测试的目的
+test('reverseApiData use fetcher to request url', async () => {
+ // 测试用例以 3A 的结构来写
+
+ // Arrange 准备阶段，准备 mock 函数或者数据
+ const fetcher = jest.fn().mockResolvedValue({
+ json: () => Promise.resolve(),
+ });
+
+ // Act 执行被测对象
+ await reverseApiData('https://api.end/point', fetcher);
+
+ // Assert 断言测试结果
+ expect(fetcher).toBeCalledWith('https://api.end/point');
+});
+```
+
+执行测试
+
+```bash
+$npx jest
+info - generate files
+ PASS src/utils/reverseApiData.test.ts
+
+Test Suites: 1 passed, 1 total
+Tests: 1 passed, 1 total
+Snapshots: 0 total
+Time: 0.894 s, estimated 1 s
+Ran all test suites.
+```
+
+
+可以使用`npx jest --watch` 让 jest 进程不退出，这样能省去启动重新 jest 的等待时间。
+
+
+我们再写一个用例来测试这个工具函数完成了键值的对换功能。
+
+```ts
+test('reverseApiData reverse simple object', async () => {
+ const fetcher = jest.fn().mockResolvedValue({
+ json: () => Promise.resolve({ data: { a: 'b' } }),
+ });
+
+ const reversed = await reverseApiData('url', fetcher);
+
+ expect(reversed).toEqual({ b: 'a' });
+});
+```
+
+让每个测试用例只关注一个功能点，可以让用例在重构的时候给我们更准确的反馈，改动破坏了什么功能。更多的用例请 [参考](https://github.com/umijs/umi/tree/master/examples/test-test/utils/reverseApiData.test.ts)
+
+## UI 测试
+
+组件和 UI 相关的测试推荐使用 `@testing-library/react`。
+
+### 渲染结果判断
+
+- 使用 jest 的 snapshot
+
+```tsx
+// examples/test-test/components/Greet/Greet.test.tsx
+import { render } from '@testing-library/react';
+import React from 'react';
+import Greet from './Greet';
+
+test('renders Greet without name by snapshot', () => {
+ const { container } = render(
-**我是否应该选择 Max ？**
-使用 Max 并不代表需要使用全部 Max 的功能，可以根据需求关闭插件，所以当你需要使用 Max 的功能时，可以总是选择创建 Max 项目。 +**Should I choose Max?**
+Using Max doesn't mean you have to utilize all of its features. You can choose to disable plugins based on your needs. So, when you want to use Max's features, you can always choose to create a Max project.
-## 项目级插件
-
-若你想在项目中快速使用插件的功能（如 [修改产物的 html](../introduce/faq#documentejs-去哪了如何自定义-html-模板) ），可以在项目的根目录创建 `plugin.ts` 编写一个项目级插件，该文件将被自动作为插件加载。
-
-有关更详细的目录结构说明请参阅 [目录结构](./directory-structure) 章节。
-
-## 开发插件
-
-请参阅 [开发插件](./plugins) 章节。
+## Project-Level Plugins
+If you want to quickly use plugin features within your project (e.g., [modifying the generated HTML](../introduce/faq#documentejs-where-is-it-how-do-i-customize-the-html-template)), you can create a `plugin.ts` file in the root directory of your project to write a project-level plugin. This file will be automatically loaded as a plugin.
+For more detailed information about directory structure, please refer to the [Directory Structure](./directory-structure) section.
+## Developing Plugins
+Please refer to the [Developing Plugins](./plugins) section.
diff --git a/docs/docs/guides/use-plugins.zh-CN.md b/docs/docs/guides/use-plugins.zh-CN.md
new file mode 100644
index 000000000000..5e994476f2a7
--- /dev/null
+++ b/docs/docs/guides/use-plugins.zh-CN.md
@@ -0,0 +1,45 @@
+import { Message } from 'umi';
+
+# 插件
+
+## 使用插件
+
+在普通的 Umi 应用中，默认 **不附带任何插件** ，如需使用 Max 的功能（如 数据流、antd 等），需要手动安装插件并开启他们：
+
+```bash
+ pnpm add -D @umijs/plugins
+```
+
+如开启 antd 插件：
+
+```ts
+// .umirc.ts
+export default {
+ plugins: ['@umijs/plugins/dist/antd'],
+ antd: {}
+}
+```
+
+Umi 与 Max 的区别是 Max 已经内置了大部分插件，如 数据流（ `initial-state` 、 `model` ）、`antd` 等，这些插件都可以在 `@umijs/plugins/dist/*` 加载并且开启。
+
+如需进一步了解 Max 具备的功能和配置说明，请参阅 [Umi Max](../max/introduce) 章节。
+
+
+
+**我是否应该选择 Max ？**
+使用 Max 并不代表需要使用全部 Max 的功能，可以根据需求关闭插件，所以当你需要使用 Max 的功能时，可以总是选择创建 Max 项目。 +
+
+## 项目级插件
+
+若你想在项目中快速使用插件的功能（如 [修改产物的 html](../introduce/faq#documentejs-去哪了如何自定义-html-模板) ），可以在项目的根目录创建 `plugin.ts` 编写一个项目级插件，该文件将被自动作为插件加载。
+
+有关更详细的目录结构说明请参阅 [目录结构](./directory-structure) 章节。
+
+## 开发插件
+
+请参阅 [开发插件](./plugins) 章节。
+
+
+
+
diff --git a/docs/docs/guides/use-vue.md b/docs/docs/guides/use-vue.md
index 352b7edda2c8..be8e9c4a0569 100644
--- a/docs/docs/guides/use-vue.md
+++ b/docs/docs/guides/use-vue.md
@@ -1,40 +1,40 @@
import { Message } from 'umi';
-# 使用 Vue
+# Using Vue
-本文介绍如何在 Umi 使用 Vue , Umi Vue 大部分配置和 React 相同，这里只列出一些 Vue 独有的配置
+This document explains how to use Vue with Umi. Most of the Umi Vue configuration is similar to React, so we will focus on Vue-specific configurations.
-## 启动方式
+## Getting Started
-### 安装
+### Installation
```bash
pnpm add @umijs/preset-vue -D
```
-### 配置预设
+### Configuring the Preset
```ts
-// .umirc.ts or config/config.ts 中
+// .umirc.ts or config/config.ts
export default {
presets: [require.resolve('@umijs/preset-vue')],
};
```
-## 路由
+## Routing
-### 配置式路由
+### Configuration-Based Routing
-这里仅列出和 React 路由配置差异部分
+Here, we only list the differences in routing configuration compared to React.
-#### name
+#### Name
-命名路由
+Named Routes
-除了 `path` 之外，你还可以为任何路由提供 `name`
+In addition to `path`, you can provide a `name` for any route:
```ts
export default {
@@ -42,13 +42,13 @@ export default {
{
path: '/user/:username',
name: 'user',
- component: 'index'
- }
- ]
-}
+ component: 'index',
+ },
+ ],
+};
```
-要链接到一个命名的路由，可以向 `router-link` 组件的 to 属性传递一个对象：
+To link to a named route, you can pass an object to the `to` prop of the `router-link` component:
```html
@@ -56,30 +56,30 @@ export default {
```
-效果和命令式地调用 `router.push` 一致：
+This is equivalent to programmatically calling `router.push`:
```ts
-router.push({ name: 'user', params: { username: 'erina' } })
+router.push({ name: 'user', params: { username: 'erina' } });
```
-在这方法都能导航到路径 `/user/erina`。
+Both methods will navigate to the path `/user/erina`.
-#### redirect
+#### Redirect
-重定向也是通过 `routes` 配置来完成，下面例子是从 `/home` 重定向到 `/`：
+Redirects are also achieved through the `routes` configuration. The following example redirects from `/home` to `/`:
```ts
export default {
routes: [
{
path: '/home',
- redirect: '/'
- }
- ]
-}
+ redirect: '/',
+ },
+ ],
+};
```
-重定向的目标也可以是一个命名的路由：
+The target of the redirect can also be a named route:
```ts
export default {
@@ -87,33 +87,34 @@ export default {
{
path: '/home',
redirect: {
- name: 'homepage'
- }
- }
- ]
-}
+ name: 'homepage',
+ },
+ },
+ ],
+};
```
-#### alias
+#### Alias
+
+A redirect means that when a user visits `/home`, the URL is replaced with `/`, which is then matched as `/`. So, what is an alias?
-重定向是指当用户访问 `/home` 时，URL 会被 `/` 替换，然后匹配成 `/`。那么什么是别名呢？
+Alias `/` as `/home`. This means that when a user visits `/home`, the URL remains `/home`, but it's matched as if the user is visiting `/`.
-将 `/` 别名为 `/home`，意味着当用户访问 `/home` 时，URL 仍然是 `/home`，但会被匹配为用户正在访问 `/`。
+The corresponding route configuration is as follows:
-上面对应的路由配置为：
```ts
export default {
routes: [
{
path: '/',
component: 'index',
- alias: '/home'
- }
- ]
-}
+ alias: '/home',
+ },
+ ],
+};
```
-通过别名，你可以自由地将 UI 结构映射到一个任意的 URL，而不受配置的嵌套结构的限制。使别名以 `/` 开头，以使嵌套路径中的路径成为绝对路径。你甚至可以将两者结合起来，用一个数组提供多个别名：
+With aliases, you can freely map UI structures to arbitrary URLs, regardless of the configured nested structure. Prefix the alias with `/` to make nested paths absolute. You can even combine the two by providing multiple aliases in an array:
```ts
export default {
@@ -122,18 +123,18 @@ export default {
path: '/users',
component: 'users',
routes: [
- // 为这 3 个 URL 呈现 UserList
+ // Render UserList for these 3 URLs
// - /users
// - /users/list
// - /people
{ path: '', component: '/users/UserList', alias: ['/people', 'list'] },
- ]
- }
- ]
-}
+ ],
+ },
+ ],
+};
```
-### 页面跳转
+### Page Navigation
```html
```
-更多[详见](https://router.vuejs.org/guide/advanced/composition-api.html#accessing-the-router-and-current-route-inside-setup)
+For more details, see the [Vue Router documentation on composition API](https://router.vuejs.org/guide/advanced/composition-api.html#accessing-the-router-and-current-route-inside-setup).
### router-link
-[详见](https://router.vuejs.org/guide/#router-link)
+[See Vue Router documentation on router-link](https://router.vuejs.org/guide/#router-link).
### router-view
-[详见](https://router.vuejs.org/guide/#router-view)
+[See Vue Router documentation on router-view](https://router.vuejs.org/guide/#router-view).
-## 运行时配置
+## Runtime Configuration
-可以通过在约定的 `src/app.tsx` 通过 export 配置来控制 vue vue-router 相关的配置
+You can control Vue and Vue Router-related configurations by exporting configuration from `src/app.tsx` using the `export` syntax.
### router
-配置路由配置
+Configure routing behavior:
```ts
// src/app.tsx
@@ -183,7 +184,7 @@ export const router: RouterConfig = {
### onMounted(\{app, router\})
-Vue app mount 成功回调, 这里可以拿到 app 的实例及 router 的实例, 可以进行全局组件注册, 路由拦截器等。
+Callback function called when the Vue app is mounted. You can get the app instance and router instance here, allowing you to register global components and set up router interceptors, among other things.
```ts
export function onMounted({ app, router }: any) {
@@ -197,9 +198,9 @@ export function onMounted({ app, router }: any) {
### rootContainer(container)
-修改交给 vue-router 渲染时的根组件。
+Modify the root component that vue-router renders.
-比如用于在外面包一个父组件
+For example, you can wrap it with a parent component:
```ts
import { h } from 'vue'
@@ -209,9 +210,9 @@ export function rootContainer(container) {
}
```
-## examples
+## Examples
-更多详见 demo
+For more examples, refer to the demos:
* [boilerplate-vue](https://github.com/umijs/umi/tree/master/examples/boilerplate-vue)
* [with-vue-pinia](https://github.com/umijs/umi/tree/master/examples/with-vue-pinia)
diff --git a/docs/docs/guides/use-vue.zh-CN.md b/docs/docs/guides/use-vue.zh-CN.md
new file mode 100644
index 000000000000..352b7edda2c8
--- /dev/null
+++ b/docs/docs/guides/use-vue.zh-CN.md
@@ -0,0 +1,218 @@
+import { Message } from 'umi';
+
+# 使用 Vue
+
+本文介绍如何在 Umi 使用 Vue , Umi Vue 大部分配置和 React 相同，这里只列出一些 Vue 独有的配置
+
+## 启动方式
+
+### 安装
+
+```bash
+pnpm add @umijs/preset-vue -D
+```
+
+### 配置预设
+
+```ts
+// .umirc.ts or config/config.ts 中
+export default {
+ presets: [require.resolve('@umijs/preset-vue')],
+};
+
+```
+
+## 路由
+
+### 配置式路由
+
+
+这里仅列出和 React 路由配置差异部分
+
+
+#### name
+
+命名路由
+
+除了 `path` 之外，你还可以为任何路由提供 `name`
+
+```ts
+export default {
+ routes: [
+ {
+ path: '/user/:username',
+ name: 'user',
+ component: 'index'
+ }
+ ]
+}
+```
+
+要链接到一个命名的路由，可以向 `router-link` 组件的 to 属性传递一个对象：
+
+```html
+
+ User
+
+```
+
+效果和命令式地调用 `router.push` 一致：
+
+```ts
+router.push({ name: 'user', params: { username: 'erina' } })
+```
+
+在这方法都能导航到路径 `/user/erina`。
+
+#### redirect
+
+重定向也是通过 `routes` 配置来完成，下面例子是从 `/home` 重定向到 `/`：
+
+```ts
+export default {
+ routes: [
+ {
+ path: '/home',
+ redirect: '/'
+ }
+ ]
+}
+```
+
+重定向的目标也可以是一个命名的路由：
+
+```ts
+export default {
+ routes: [
+ {
+ path: '/home',
+ redirect: {
+ name: 'homepage'
+ }
+ }
+ ]
+}
+```
+
+#### alias
+
+重定向是指当用户访问 `/home` 时，URL 会被 `/` 替换，然后匹配成 `/`。那么什么是别名呢？
+
+将 `/` 别名为 `/home`，意味着当用户访问 `/home` 时，URL 仍然是 `/home`，但会被匹配为用户正在访问 `/`。
+
+上面对应的路由配置为：
+```ts
+export default {
+ routes: [
+ {
+ path: '/',
+ component: 'index',
+ alias: '/home'
+ }
+ ]
+}
+```
+
+通过别名，你可以自由地将 UI 结构映射到一个任意的 URL，而不受配置的嵌套结构的限制。使别名以 `/` 开头，以使嵌套路径中的路径成为绝对路径。你甚至可以将两者结合起来，用一个数组提供多个别名：
+
+```ts
+export default {
+ routes: [
+ {
+ path: '/users',
+ component: 'users',
+ routes: [
+ // 为这 3 个 URL 呈现 UserList
+ // - /users
+ // - /users/list
+ // - /people
+ { path: '', component: '/users/UserList', alias: ['/people', 'list'] },
+ ]
+ }
+ ]
+}
+```
+
+### 页面跳转
+
+```html
+
+```
+
+更多[详见](https://router.vuejs.org/guide/advanced/composition-api.html#accessing-the-router-and-current-route-inside-setup)
+
+### router-link
+
+[详见](https://router.vuejs.org/guide/#router-link)
+
+### router-view
+
+[详见](https://router.vuejs.org/guide/#router-view)
+
+## 运行时配置
+
+可以通过在约定的 `src/app.tsx` 通过 export 配置来控制 vue vue-router 相关的配置
+
+### router
+
+配置路由配置
+
+```ts
+// src/app.tsx
+export const router: RouterConfig = {
+ // @ts-ignore
+ scrollBehavior(to, from) {
+ console.log('scrollBehavior', to, from);
+ },
+};
+```
+
+### onMounted(\{app, router\})
+
+Vue app mount 成功回调, 这里可以拿到 app 的实例及 router 的实例, 可以进行全局组件注册, 路由拦截器等。
+
+```ts
+export function onMounted({ app, router }: any) {
+ console.log('onMounted', app, router);
+ app.provide('umi-hello', {
+ h: 'hello',
+ w: 'word',
+ });
+}
+```
+
+### rootContainer(container)
+
+修改交给 vue-router 渲染时的根组件。
+
+比如用于在外面包一个父组件
+
+```ts
+import { h } from 'vue'
+
+export function rootContainer(container) {
+ return h(ThemeProvider, null, container);
+}
+```
+
+## examples
+
+更多详见 demo
+
+* [boilerplate-vue](https://github.com/umijs/umi/tree/master/examples/boilerplate-vue)
+* [with-vue-pinia](https://github.com/umijs/umi/tree/master/examples/with-vue-pinia)
+* [with-vue-element-plus](https://github.com/umijs/umi/tree/master/examples/with-vue-element-plus)
diff --git a/docs/docs/introduce/contributing.md b/docs/docs/introduce/contributing.md
index ec1af2e3f868..9ba4a947ccfc 100644
--- a/docs/docs/introduce/contributing.md
+++ b/docs/docs/introduce/contributing.md
@@ -1,67 +1,67 @@
import { Message } from 'umi';
-# 参与贡献
+# Contributing to Umi
-❤️ Loving Umi and want to get involved? Thanks!
+❤️ Love Umi and want to get involved? Thank you!
-## 环境准备
+## Environment Setup
-### Node.js 和 pnpm
+### Node.js and pnpm
-开发 Umi 需要 Node.js 16+ 和 `pnpm` v8。
+Developing Umi requires Node.js 16+ and `pnpm` v8.
-推荐使用 [`nvm`](https://github.com/nvm-sh/nvm) 管理 Node.js，避免权限问题的同时，还能够随时切换当前使用的 Node.js 的版本。在 Windows 系统下的开发者可以使用 [`nvm-windows`](https://github.com/coreybutler/nvm-windows)。
+It's recommended to use [`nvm`](https://github.com/nvm-sh/nvm) to manage Node.js to avoid permission issues and switch between different Node.js versions. Windows users can use [`nvm-windows`](https://github.com/coreybutler/nvm-windows).
-在 `pnpm` 的[官网](https://pnpm.io/installation)选择一种方式安装即可。
+You can install `pnpm` following the instructions on the [official website](https://pnpm.io/installation).
-### Clone 项目
+### Clone the Project
```bash
$ git clone git@github.com:umijs/umi.git
$ cd umi
```
-### 安装依赖并构建
+### Install Dependencies and Build
```bash
$ pnpm i && pnpm build
```
-## 开发 Umi
+## Developing Umi
-### 启动 dev 命令
+### Start the dev Command
-本地开发 Umi 必开命令，用于编译 `src` 下的 TypeScript 文件到 `dist` 目录，同时监听文件变更，有变更时增量编译。
+The `dev` command is essential for local Umi development. It compiles TypeScript files under the `src` directory into the `dist` directory and watches for file changes, performing incremental compilation.
```bash
$ pnpm dev
```
-如果觉得比较慢，也可以只跑特定 package 的 `pnpm dev` 命令，比如。
+If you find it slow, you can also run the `pnpm dev` command for specific packages, for example:
```bash
$ cd packages/umi
$ pnpm dev
```
-### 跑 Example
+### Running Examples
-`examples` 目录下保存了各种用于测试的例子，跑 example 是开发 Umi 时确认功能正常的常用方式。每个 example 都配了 dev 脚本，所以进入 example 然后执行 `pnpm dev` 即可。
+The `examples` directory contains various examples used for testing. Running examples is a common way to confirm that Umi's features are working correctly during development. Each example has a `dev` script, so you can enter the example directory and run `pnpm dev`.
```bash
$ cd examples/boilerplate
$ pnpm dev
```
-如果要用 vite 模式跑，加 `--vite` 参数，
+For running in Vite mode, add the `--vite` parameter:
```bash
$ pnpm dev --vite
```
-### 测试
+### Testing
-目前跑测试很快，10s+ 就完成了。推荐本地跑一遍再提 PR，减少 Round Trip。
+Currently, running tests is quite fast, taking around 10 seconds to complete. It's recommended to run tests locally before making a pull request to reduce the round trip time.
```bash
$ pnpm test
@@ -73,114 +73,114 @@ Time: 13.658 s
Ran all test suites.
```
-如果需要只跑部分文件的用例，用 `pnpm jest`，因为 `pnpm test` 只开了 turborepo 功能的。
+If you only want to run specific test files, use `pnpm jest`, as `pnpm test` only enables the TurboRepo feature.
-比如，
+For example:
```bash
$ pnpm jest packages/plugin-docs/src/compiler.test.ts
```
-## 贡献 Umi 文档
+## Contributing to Umi Documentation
-Umi 的文档由 Umi@4 和 `@umijs/plugin-docs` 插件实现，本质上就是一个 Umi 项目。在根目录执行如下命令即可开始 Umi 文档的开发：
+Umi's documentation is built using Umi@4 and the `@umijs/plugin-docs` plugin. Essentially, it's a Umi project itself. Run the following command in the root directory to start developing Umi documentation:
```bash
-# 安装 Umi 文档依赖
+# Install Umi documentation dependencies
$ pnpm doc:deps
-# 启用 Umi 文档开发
-# 首次启动时编译耗时较长，请耐心等待
+# Start developing Umi documentation
+# The initial start may take a while due to compilation. Please be patient.
$ pnpm doc:dev
```
-打开指定的端口号，即可实时查看文档更新的内容，以及 `@umijs/plugin-docs` 插件开发的成果。
+Open the specified port to view the updated documentation content and the results of `@umijs/plugin-docs` plugin development.
-### 撰写 Umi 文档
+### Writing Umi Documentation
-Umi 文档的编写基于 MDX 格式。MDX 是 Markdown 格式的拓展，允许您在撰写 Umi 文档时插入 JSX 组件。
+Umi documentation is written in MDX format. MDX is an extension of Markdown that allows you to include JSX components when writing Umi documentation.
-撰写 **文档（Document）** 时，可用的组件可以在 `packages/plugin-docs/client/theme-doc/components` 目录下找到。撰写 **博客（Blog）** 时，可用的组件可以在 `packages/plugin-docs/client/theme-blog/components` 目录下找到。
+When writing **document** content, you can find available components in the `packages/plugin-docs/client/theme-doc/components` directory. When writing **blog** content, available components can be found in the `packages/plugin-docs/client/theme-blog/components` directory.
-Umi 文档的代码高亮基于 [`Rehype Pretty Code`](https://github.com/atomiks/rehype-pretty-code)，完整的能力和使用说明请移步它的[官方文档](https://rehype-pretty-code.netlify.app)。
+Umi documentation's code highlighting is based on [`Rehype Pretty Code`](https://github.com/atomiks/rehype-pretty-code). For complete capabilities and usage instructions, refer to its [official documentation](https://rehype-pretty-code.netlify.app).
-在根目录执行如下命令可以格式化仓库中已有的 Umi 文档：
+You can format existing Umi documentation in the repository using the following command:
```bash
$ pnpm format:docs
```
-格式化文档后，建议**仅提交您撰写或修改的 Umi 文档**。不同文档贡献者的写作风格有一定的差异，格式化以后不一定能保留原来期望的样式。
+After formatting, it's recommended to **only commit the Umi documentation you've written or modified**. Different document contributors have different writing styles, and formatting might not preserve the originally intended style.
-### 参与 Umi 文档插件开发
+### Contributing to Umi Documentation Plugin Development
-新建一个终端，执行如下命令：
+Open a new terminal and run the following command:
```bash
$ cd packages/plugin-docs
$ pnpm dev:css
```
-现在，当您修改了 `tailwind.css` 文件或在开发时修改了 TailwindCSS 样式类时，会自动编译并生成 `tailwind.out.css` 样式表文件。
+Now, when you modify the `tailwind.css` file or modify TailwindCSS styles during development, it will automatically compile and generate the `tailwind.out.css` stylesheet file.
-Umi 会监听 `docs` 和 `packages/plugin-docs/client` 目录下文件的变化，而不会监听 `packages/plugin-docs/src` 目录。
+Umi will watch for changes in files under the `docs` and `packages/plugin-docs/client` directories, but not in the `packages/plugin-docs/src` directory.
-如果您需要编译 `packages/plugin-docs/src` 中的文件，请移动到 `packages/plugin-docs` 目录下执行 `pnpm build` 命令，然后重启开发。
+If you need to compile files in `packages/plugin-docs/src`, move to the `packages/plugin-docs` directory and execute the `pnpm build` command, then restart the development process.
-在根目录执行如下命令可以格式化 Umi 文档插件的代码：
+You can format the code of Umi documentation plugin using the following command:
```bash
$ pnpm format:plugin-docs
```
-在根目录执行如下命令可以构建 Umi 文档：
+You can build Umi documentation using the following command:
```bash
$ pnpm doc:build
```
-## 新增 package
+## Adding a New Package
-新增 package 有封装脚本，无需手动复制 `package.json` 等文件：
+Adding a new package has a script that encapsulates the process. You don't need to manually copy `package.json` and other files:
```bash
-# 创建 package 目录
+# Create a package directory
$ mkdir packages/foo
-# 初始化 package 开发
+# Initialize package development
$ pnpm bootstrap
```
-## 更新依赖
+## Updating Dependencies
-> 不推荐非 Core Maintainer 做大量依赖更新。因为涉及依赖预打包，有较多需注意的点。
+> It's not recommended for non-Core Maintainers to perform extensive dependency updates, as it involves dependency pre-bundling and there are several important points to consider.
-执行 `pnpm dep:update` 可更新依赖。
+You can update dependencies by running `pnpm dep:update`:
```bash
$ pnpm dep:update
```
-由于 Umi 有针对依赖做预打包处理，更新依赖后还需检查更新的依赖是否为 devDependencies 并且有对此做依赖预打包。如果有，需要在对应 package 下执行 `pnpm build:deps` 并指定依赖，用于更新预打包的依赖文件。
+Since Umi pre-bundles dependencies, you need to check if the updated dependencies are `devDependencies` and whether they require pre-bundling. If they do, execute `pnpm build:deps` under the corresponding package and specify the dependency to update the pre-bundled dependency files.
```bash
$ pnpm build:deps --dep webpack-manifest-plugin
```
-## 发布
+## Publishing
-只有 Core Maintainer 才能执行发布。
+Only Core Maintainers can perform releases.
```bash
$ pnpm release
```
-## 加入 Contributor 群
+## Join the Contributor Group
-提交过 Bugfix 或 Feature 类 PR 的同学，如果有兴趣一起参与维护 Umi，可先用钉钉扫下方二维码（注明 github id）加我钉钉，然后我会拉到群里。
+If you've submitted Bugfix or Feature PRs and are interested in contributing to Umi's maintenance, you can scan the QR code below using DingTalk (mentioning your GitHub ID) to contact me. I'll add you to the contributor group.
-如果你不知道可以贡献什么，可以到源码里搜 TODO 或 FIXME 找找。
+If you're unsure about what to contribute, you can search for TODO or FIXME in the source code.
\ No newline at end of file
diff --git a/docs/docs/introduce/contributing.zh-CN.md b/docs/docs/introduce/contributing.zh-CN.md
new file mode 100644
index 000000000000..ec1af2e3f868
--- /dev/null
+++ b/docs/docs/introduce/contributing.zh-CN.md
@@ -0,0 +1,186 @@
+import { Message } from 'umi';
+
+# 参与贡献
+
+❤️ Loving Umi and want to get involved? Thanks!
+
+## 环境准备
+
+### Node.js 和 pnpm
+
+开发 Umi 需要 Node.js 16+ 和 `pnpm` v8。
+
+推荐使用 [`nvm`](https://github.com/nvm-sh/nvm) 管理 Node.js，避免权限问题的同时，还能够随时切换当前使用的 Node.js 的版本。在 Windows 系统下的开发者可以使用 [`nvm-windows`](https://github.com/coreybutler/nvm-windows)。
+
+在 `pnpm` 的[官网](https://pnpm.io/installation)选择一种方式安装即可。
+
+### Clone 项目
+
+```bash
+$ git clone git@github.com:umijs/umi.git
+$ cd umi
+```
+
+### 安装依赖并构建
+
+```bash
+$ pnpm i && pnpm build
+```
+
+## 开发 Umi
+
+### 启动 dev 命令
+
+本地开发 Umi 必开命令，用于编译 `src` 下的 TypeScript 文件到 `dist` 目录，同时监听文件变更，有变更时增量编译。
+
+```bash
+$ pnpm dev
+```
+
+如果觉得比较慢，也可以只跑特定 package 的 `pnpm dev` 命令，比如。
+
+```bash
+$ cd packages/umi
+$ pnpm dev
+```
+
+### 跑 Example
+
+`examples` 目录下保存了各种用于测试的例子，跑 example 是开发 Umi 时确认功能正常的常用方式。每个 example 都配了 dev 脚本，所以进入 example 然后执行 `pnpm dev` 即可。
+
+```bash
+$ cd examples/boilerplate
+$ pnpm dev
+```
+
+如果要用 vite 模式跑，加 `--vite` 参数，
+
+```bash
+$ pnpm dev --vite
+```
+
+### 测试
+
+目前跑测试很快，10s+ 就完成了。推荐本地跑一遍再提 PR，减少 Round Trip。
+
+```bash
+$ pnpm test
+...
+Test Suites: 1 skipped, 43 passed, 43 of 44 total
+Tests: 6 skipped, 167 passed, 173 total
+Snapshots: 0 total
+Time: 13.658 s
+Ran all test suites.
+```
+
+如果需要只跑部分文件的用例，用 `pnpm jest`，因为 `pnpm test` 只开了 turborepo 功能的。
+
+比如，
+
+```bash
+$ pnpm jest packages/plugin-docs/src/compiler.test.ts
+```
+
+## 贡献 Umi 文档
+
+Umi 的文档由 Umi@4 和 `@umijs/plugin-docs` 插件实现，本质上就是一个 Umi 项目。在根目录执行如下命令即可开始 Umi 文档的开发：
+
+```bash
+# 安装 Umi 文档依赖
+$ pnpm doc:deps
+# 启用 Umi 文档开发
+# 首次启动时编译耗时较长，请耐心等待
+$ pnpm doc:dev
+```
+
+打开指定的端口号，即可实时查看文档更新的内容，以及 `@umijs/plugin-docs` 插件开发的成果。
+
+### 撰写 Umi 文档
+
+Umi 文档的编写基于 MDX 格式。MDX 是 Markdown 格式的拓展，允许您在撰写 Umi 文档时插入 JSX 组件。
+
+
+撰写 **文档（Document）** 时，可用的组件可以在 `packages/plugin-docs/client/theme-doc/components` 目录下找到。撰写 **博客（Blog）** 时，可用的组件可以在 `packages/plugin-docs/client/theme-blog/components` 目录下找到。
+
+
+Umi 文档的代码高亮基于 [`Rehype Pretty Code`](https://github.com/atomiks/rehype-pretty-code)，完整的能力和使用说明请移步它的[官方文档](https://rehype-pretty-code.netlify.app)。
+
+在根目录执行如下命令可以格式化仓库中已有的 Umi 文档：
+
+```bash
+$ pnpm format:docs
+```
+
+格式化文档后，建议**仅提交您撰写或修改的 Umi 文档**。不同文档贡献者的写作风格有一定的差异，格式化以后不一定能保留原来期望的样式。
+
+### 参与 Umi 文档插件开发
+
+新建一个终端，执行如下命令：
+
+```bash
+$ cd packages/plugin-docs
+$ pnpm dev:css
+```
+
+现在，当您修改了 `tailwind.css` 文件或在开发时修改了 TailwindCSS 样式类时，会自动编译并生成 `tailwind.out.css` 样式表文件。
+
+Umi 会监听 `docs` 和 `packages/plugin-docs/client` 目录下文件的变化，而不会监听 `packages/plugin-docs/src` 目录。
+
+
+如果您需要编译 `packages/plugin-docs/src` 中的文件，请移动到 `packages/plugin-docs` 目录下执行 `pnpm build` 命令，然后重启开发。
+
+
+在根目录执行如下命令可以格式化 Umi 文档插件的代码：
+
+```bash
+$ pnpm format:plugin-docs
+```
+
+在根目录执行如下命令可以构建 Umi 文档：
+
+```bash
+$ pnpm doc:build
+```
+
+## 新增 package
+
+新增 package 有封装脚本，无需手动复制 `package.json` 等文件：
+
+```bash
+# 创建 package 目录
+$ mkdir packages/foo
+# 初始化 package 开发
+$ pnpm bootstrap
+```
+
+## 更新依赖
+
+> 不推荐非 Core Maintainer 做大量依赖更新。因为涉及依赖预打包，有较多需注意的点。
+
+执行 `pnpm dep:update` 可更新依赖。
+
+```bash
+$ pnpm dep:update
+```
+
+由于 Umi 有针对依赖做预打包处理，更新依赖后还需检查更新的依赖是否为 devDependencies 并且有对此做依赖预打包。如果有，需要在对应 package 下执行 `pnpm build:deps` 并指定依赖，用于更新预打包的依赖文件。
+
+```bash
+$ pnpm build:deps --dep webpack-manifest-plugin
+```
+
+## 发布
+
+只有 Core Maintainer 才能执行发布。
+
+```bash
+$ pnpm release
+```
+
+## 加入 Contributor 群
+
+提交过 Bugfix 或 Feature 类 PR 的同学，如果有兴趣一起参与维护 Umi，可先用钉钉扫下方二维码（注明 github id）加我钉钉，然后我会拉到群里。
+
+
+
+如果你不知道可以贡献什么，可以到源码里搜 TODO 或 FIXME 找找。
diff --git a/docs/docs/introduce/faq.md b/docs/docs/introduce/faq.md
index d13c78377500..b891dd3b42d2 100644
--- a/docs/docs/introduce/faq.md
+++ b/docs/docs/introduce/faq.md
@@ -1,16 +1,16 @@
-# FAQ
+## FAQ
-## 可以关闭 dynamicImport 吗？
+### Can I disable `dynamicImport`?
-可以，但不建议关闭。
+Yes, you can disable it, but it's not recommended.
-1、安装依赖
+1. Install the dependency:
```bash
- pnpm i babel-plugin-dynamic-import-node -D
+pnpm i babel-plugin-dynamic-import-node -D
```
-2、配置里加上 `extraBabelPlugins` ，但只针对 production 开启
+2. Add the `extraBabelPlugins` configuration in your `.umirc.ts` to apply the plugin only in production:
```ts
// .umirc.ts
@@ -21,68 +21,67 @@ export default {
}
```
-## 没有 dynamicImport 怎么配置它的 loading ？
+### How do I configure the loading when using `dynamicImport`?
-定义 `src/loading.tsx` :
+Define a `src/loading.tsx` file:
-参考 [目录结构 > loading.tsx](../guides/directory-structure#loadingtsxjsx)
+Refer to [Directory Structure > loading.tsx](../guides/directory-structure#loadingtsxjsx).
-## 可以用 react 17 吗？
+### Can I use React 17?
-由于 umi v4 升级了默认的 react 版本到 v18，使用 umi4 时注意下依赖库和 react 18 的兼容情况，如果还需要使用 react 17，请执行以下命令并重启。
+Umi v4 upgrades the default React version to v18. If you want to use React 17, execute the following command and restart:
```bash
- pnpm add react@^17 react-dom@^17
+pnpm add react@^17 react-dom@^17
```
-## 代理静态资源到本地后，一直 restart 刷新页面
+### After proxying static resources to my local server, the page keeps restarting when refreshed.
})
-解法：配置 `SOCKET_SERVER=127.0.0.1:${port}` 启动项目
+Solution: Configure `SOCKET_SERVER=127.0.0.1:${port}` when starting the project:
```bash
- SOCKET_SERVER=http://127.0.0.1:8000 pnpm dev
+SOCKET_SERVER=http://127.0.0.1:8000 pnpm dev
```
-## Error evaluating function `round`: argument must be a number
+### Error evaluating function `round`: argument must be a number
})
-解法：新版 less 中 `/` 默认被识别为属性简写，通过配置 `lessLoader: { math: 'always' }` 恢复旧版行为（默认将 `/` 用作计算符号）。
+Solution: In the new version of Less, `/` is recognized as an attribute shorthand. To revert to the old behavior (treating `/` as a calculation symbol), configure `lessLoader: { math: 'always' }`.
-## routes 里的 layout 配置选项不生效
+### The `layout` configuration option in `routes` doesn't work.
-layout 配置被移动到了 `app.ts` ，详见 [runtime-config > layout](https://umijs.org/docs/api/runtime-config#layout)
+The `layout` configuration has been moved to `app.ts`. Refer to [Runtime Configuration > layout](https://umijs.org/docs/api/runtime-config#layout).
+### Where is `document.ejs`, and how do I customize the HTML template?
-## document.ejs 去哪了，如何自定义 HTML 模板
+In addition to injecting external [scripts](https://umijs.org/docs/api/config#scripts) and [styles](https://umijs.org/docs/api/config#styles) through configuration, you can use project-level plugins to modify the HTML output more flexibly. See [issuecomment-1151088426](https://github.com/umijs/umi-next/issues/868#issuecomment-1151088426).
-除了可以通过 配置项 注入外部 [script](https://umijs.org/docs/api/config#scripts) 、[css](https://umijs.org/docs/api/config#styles) 外，还可以使用项目级插件更灵活的修改 HTML 产物，参见：[issuecomment-1151088426](https://github.com/umijs/umi-next/issues/868#issuecomment-1151088426)
+### The external JavaScript file configured in `scripts` is inserted after `umi.js`. Why is that?
-## scripts 里配置的外部 js 文件为什么默认插入到 umi.js 的后面
+React only starts running after the page has loaded completely, so inserting it after `umi.js` doesn't affect the project.
-react 只有在页面加载完毕后才会开始运行，所以插到 `umi.js` 后面不会影响项目。
+If you need to insert it before `umi.js`, refer to [issuecomment-1176960539](https://github.com/umijs/umi/issues/8442#issuecomment-1176960539).
-若需要插到 `umi.js` 前面，可参见 [issuecomment-1176960539](https://github.com/umijs/umi/issues/8442#issuecomment-1176960539)
+### How do I bundle packages in Umi 4?
-## umi4 我怎么分包
+Umi 4 by default splits bundles by page. If you feel the need for further optimization, you can use code splitting strategies or manually split bundles. Refer to [Code Splitting Guide](../../blog/code-splitting).
-Umi 4 默认按页拆包，如果你觉得还需要优化，可以使用分包策略或手动拆包，详见：[代码拆分指南](../../blog/code-splitting)
+If you have a requirement to bundle all JavaScript artifacts into a single `umi.js` file, you need to disable [dynamicImport](#can-i-disable-dynamicimport).
-如果你有将所有 js 产物打包成单 `umi.js` 文件的需求，请关闭 [dynamicImport](#可以关闭-dynamicimport-吗) 。
+### Where is `_layout.tsx`, and how do I implement nested routing?
-## _layout.tsx 去哪了，我怎么嵌套路由
+Umi 4 uses React Router v6. Use the `
-## Umi 是什么？
+## What is Umi?
-Umi，中文发音为「乌米」，是可扩展的企业级前端应用框架。Umi 以路由为基础的，同时支持配置式路由和约定式路由，保证路由的功能完备，并以此进行功能扩展。然后配以生命周期完善的插件体系，覆盖从源码到构建产物的每个生命周期，支持各种功能扩展和业务需求。
+Umi, from the Chinese word 乌米 "woo-mee" (wū mǐ), is a scalable enterprise-class front-end application framework. Umi is based on routing, and supports both configuration routing and convention routing to ensure complete routing function experience. It is also complemented with a complete life cycle plug-in system, covering every use case from source code to build products, and supports many function extensions and business requirements.
-Umi 是蚂蚁集团的底层前端框架，已直接或间接地服务了 10000+ 应用，包括 Java、Node、H5 无线、离线（Hybrid）应用、纯前端 assets 应用、CMS 应用、Electron 应用、Serverless 应用等。他已经很好地服务了我们的内部用户，同时也服务了不少外部用户，包括淘系、飞猪、阿里云、字节、腾讯、口碑、美团等。在 2021 年字节的[调研报告](https://zhuanlan.zhihu.com/p/403206195)中，Umi 是其中 25.33% 开发者的选择。
+Umi is the underlying front-end framework of Ant Group, and has directly or indirectly served 10,000 applications, including Java, Node.js, mobile (H5), offline (Hybrid) apps, pure frontend asset applications, CMS applications, Electron apps, and Serverless applications. It has effectively served internal users within Ant Group and a significant number of external users from various companies such as Taobao, Fliggy, Alibaba Cloud, ByteDance, Tencent, Koubei, and Meituan. In ByteDance's [2021 developer survey report](https://zhuanlan.zhihu.com/p/403206195), Umi was the choice of 25.33% of developers.
-Umi 有很多非常有意思的特性，比如。
+Umi boasts several interesting features:
-1、**企业级**，在安全性、稳定性、最佳实践、约束能力方面会考虑更多
-2、**插件化**，啥都能改，Umi 本身也是由插件构成
-3、**MFSU**，比 Vite 还快的 Webpack 打包方案
-4、基于 React Router 6 的完备路由
-5、默认最快的请求
-6、SSR & SSG
-7、稳定白盒性能好的 ESLint 和 Jest
-8、React 18 的框架级接入
-9、Monorepo 最佳实践
+1. **Enterprise-Grade**: Focused on security, stability, best practices, and constraint capabilities. +2. **Plugin-Based**: Highly customizable with Umi itself built upon a plugin architecture. +3. **MFSU**: A Webpack bundling solution faster than Vite. +4. Complete routing based on React Router 6. +5. Fastest default request setup. +6. SSR & SSG capabilities. +7. Stable and performant ESLint and Jest integration. +8. Framework-level integration with React 18. +9. Monorepo best practices. ... +## When Not to Use Umi? -## 什么时候不用 Umi？ +Umi might not be suitable for your project if: -如果你的项目， - -1、需要支持 IE 8 或更低版本的浏览器
-2、需要支持 React 16.8.0 以下的 React
-3、需要跑在 Node 14 以下的环境中
-4、有很强的 webpack 自定义需求和主观意愿
-5、需要选择不同的路由方案
+1. You need to support browsers, including IE 8 or lower. +2. You need to support React versions earlier than 16.8.0. +3. Your project needs to run in an environment with Node.js versions lower than 14. +4. You have specific and strong Webpack customization requirements and preferences. +5. You need to choose a different routing solution. ... -Umi 可能不适合你。 - - -## 为什么不是？ +## Why Not? ### create-react-app -create-react-app 是脚手架，和 Umi、next.js、remix、ice、modern.js 等元框架不是同一类型。脚手架可以让我们快速启动项目，对于单一的项目够用，但对于团队而言却不够。因为使用脚手架像泼出去的水，一旦启动，无法迭代。同时脚手架所能做的封装和抽象都非常有限。 +create-react-app is a scaffolding tool and is not in the same category as Umi, next.js, remix, ice, modern.js, and similar frameworks. Scaffolding tools allow quick project setup, suitable for individual projects but insufficient for team use. Once a scaffolding is set up, it becomes difficult to iterate. Additionally, the encapsulation and abstraction provided by scaffolding tools are limited. ### next.js -如果要做 SSR，next.js 是非常好的选择（当然，Umi 也支持 SSR）；而如果只做 CSR，Umi 会是更好的选择。相比之下，Umi 的扩展性会更好；并且 Umi 做了很多更贴地气的功能，比如配置式路由、补丁方案、antd 的接入、微前端、国际化、权限等；同时 Umi 会更稳定，因为他锁了能锁的全部依赖，定期主动更新，某一个子版本的 Umi，不会因为重装依赖之后而跑不起来。 +For SSR (Server-Side Rendering), next.js is an excellent choice (though Umi also supports SSR). If you're only doing CSR (Client-Side Rendering), Umi might be a better option. Umi offers better extensibility, more user-friendly features such as configuration-based routing, patching solutions, integration with antd, micro-frontends, internationalization, permissions, and more. Umi is also more stable, as it locks all possible dependencies, updates them periodically, and won't break after reinstalling dependencies. -### remix +### Remix -Remix 是我非常喜欢的框架，Umi 4 从中抄（学）了不少东西。但 Remix 是 Server 框架，其内置的 loader 和 action 都是跑在 server 端的，所以会对部署环境会有一定要求。Umi 将 loader、action 以及 remix 的请求机制同时运用到 client 和 server 侧，不仅 server 请求快，纯 CSR 的项目请求也可达到理论的最快值。同时 Remix 基于 esbuild 做打包，可能不适用于对兼容性有要求或者依赖尺寸特别大的项目。
+I like Remix a lot, and Umi 4 has learned quite a bit from it. However, Remix is primarily a server framework, with its built-in loaders and actions running on the server side, which makes specific deployment environments necessary. Umi utilizes loaders, actions, and Remix's request mechanisms on both the client and server sides, achieving fast server requests and even faster requests for purely CSR projects. Additionally, Remix uses esbuild for bundling, which might not be suitable for projects with strict compatibility requirements or large dependency sizes.
\ No newline at end of file
diff --git a/docs/docs/introduce/introduce.zh-CN.md b/docs/docs/introduce/introduce.zh-CN.md
new file mode 100644
index 000000000000..5016f275c31f
--- /dev/null
+++ b/docs/docs/introduce/introduce.zh-CN.md
@@ -0,0 +1,52 @@
+# Umi 介绍
+
+
+
+
+## Umi 是什么？
+
+Umi，中文发音为「乌米」，是可扩展的企业级前端应用框架。Umi 以路由为基础的，同时支持配置式路由和约定式路由，保证路由的功能完备，并以此进行功能扩展。然后配以生命周期完善的插件体系，覆盖从源码到构建产物的每个生命周期，支持各种功能扩展和业务需求。
+
+Umi 是蚂蚁集团的底层前端框架，已直接或间接地服务了 10000+ 应用，包括 Java、Node、H5 无线、离线（Hybrid）应用、纯前端 assets 应用、CMS 应用、Electron 应用、Serverless 应用等。他已经很好地服务了我们的内部用户，同时也服务了不少外部用户，包括淘系、飞猪、阿里云、字节、腾讯、口碑、美团等。在 2021 年字节的[调研报告](https://zhuanlan.zhihu.com/p/403206195)中，Umi 是其中 25.33% 开发者的选择。
+
+Umi 有很多非常有意思的特性，比如。
+
+1、**企业级**，在安全性、稳定性、最佳实践、约束能力方面会考虑更多
+2、**插件化**，啥都能改，Umi 本身也是由插件构成
+3、**MFSU**，比 Vite 还快的 Webpack 打包方案
+4、基于 React Router 6 的完备路由
+5、默认最快的请求
+6、SSR & SSG
+7、稳定白盒性能好的 ESLint 和 Jest
+8、React 18 的框架级接入
+9、Monorepo 最佳实践
+... + + +## 什么时候不用 Umi？ + +如果你的项目， + +1、需要支持 IE 8 或更低版本的浏览器
+2、需要支持 React 16.8.0 以下的 React
+3、需要跑在 Node 14 以下的环境中
+4、有很强的 webpack 自定义需求和主观意愿
+5、需要选择不同的路由方案
+... + +Umi 可能不适合你。 + + +## 为什么不是？ + +### create-react-app + +create-react-app 是脚手架，和 Umi、next.js、remix、ice、modern.js 等元框架不是同一类型。脚手架可以让我们快速启动项目，对于单一的项目够用，但对于团队而言却不够。因为使用脚手架像泼出去的水，一旦启动，无法迭代。同时脚手架所能做的封装和抽象都非常有限。 + +### next.js + +如果要做 SSR，next.js 是非常好的选择（当然，Umi 也支持 SSR）；而如果只做 CSR，Umi 会是更好的选择。相比之下，Umi 的扩展性会更好；并且 Umi 做了很多更贴地气的功能，比如配置式路由、补丁方案、antd 的接入、微前端、国际化、权限等；同时 Umi 会更稳定，因为他锁了能锁的全部依赖，定期主动更新，某一个子版本的 Umi，不会因为重装依赖之后而跑不起来。 + +### remix + +Remix 是我非常喜欢的框架，Umi 4 从中抄（学）了不少东西。但 Remix 是 Server 框架，其内置的 loader 和 action 都是跑在 server 端的，所以会对部署环境会有一定要求。Umi 将 loader、action 以及 remix 的请求机制同时运用到 client 和 server 侧，不仅 server 请求快，纯 CSR 的项目请求也可达到理论的最快值。同时 Remix 基于 esbuild 做打包，可能不适用于对兼容性有要求或者依赖尺寸特别大的项目。
diff --git a/docs/docs/introduce/philosophy.md b/docs/docs/introduce/philosophy.md
index cf7acaff377e..7ec312b0107f 100644
--- a/docs/docs/introduce/philosophy.md
+++ b/docs/docs/introduce/philosophy.md
@@ -1,62 +1,58 @@
-# 设计思路
+# Design Philosophy
-Umi 从 1 做到 4，试错了很多东西，也试对了不少。这些试对的点我们逐渐沉淀下来，就成为指引我们如何做好企业级框架的思路。
+Umi has gone through iterations from version 1 to 4, trying out various ideas and approaches, both successful and unsuccessful. These successful elements have gradually been refined into guiding principles for creating a high-quality enterprise-level framework.
-设计思路包括，
+The design philosophy encompasses:
-1、技术收敛
-2、插件和插件集
-3、最佳实践
-4、企业级
-5、import all from umi
-6、编译时框架
-7、依赖预打包
-8、默认快
-9、约束与开放
+1. **Technology Convergence** +2. **Plugins and Plugin Collections** +3. **Best Practices** +4. **Enterprise-Grade** +5. **import all from umi** -下面仅介绍 1-5 的 5 点，剩下 6-9 的 4 点在 2022.1.8 的 SEE Conf 中有过详细分享，详见[《SEE Conf: Umi 4 设计思路文字稿》](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ%3D%3D&mid=2247484533&idx=1&sn=9b15a67b88ebc95476fce1798eb49146)。 +The following will cover points 1 to 5, while points 6 to 9 were elaborated in detail during the SEE Conf on January 8, 2022, and can be found in the article [SEE Conf: Umi 4 Design Philosophy Transcript](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ%3D%3D&mid=2247484533&idx=1&sn=9b15a67b88ebc95476fce1798eb49146). -## 技术收敛 +## Technology Convergence
-技术收敛对团队而言尤其重要，他包含两层含义，1）技术栈收敛 2）依赖收敛。技术栈收敛指社区那么多技术栈，每个技术方向都有非常多选择，比如数据流应该就不下 100 种，开发者应该如何选择；收敛了技术栈之后还需要收敛依赖，团队中，开发者的项目不应该有很多细碎的依赖，每一个依赖都附带着升级成本。 +Technology convergence is especially crucial for teams. It involves two aspects: 1) Technology stack convergence and 2) Dependency convergence. Technology stack convergence addresses the multitude of choices within various technology domains. For instance, there are over 100 choices for data flow, making it challenging for developers to choose the best option. After converging on a technology stack, it's necessary to converge on dependencies. In a team, projects should avoid having too many fragmented dependencies, as each one incurs upgrading costs. -我们希望开发者依赖 Umi 之后就无需关心 babel、webpack、postcss、react、react-router 等依赖，而依赖 @umijs/max 之后无需再关心开发中台项目的依赖和技术栈。 +The goal is for developers who depend on Umi to not worry about dependencies like babel, webpack, postcss, react, react-router, etc. Similarly, by depending on `@umijs/max`, developers need not concern themselves with dependencies and technology stacks when developing mid-tier projects. -## 插件和插件集 +## Plugins and Plugin Collections
-Umi 通过提供插件和插件集的机制来满足不同场景和业务的需求。插件是为了扩展一个功能，而插件集是为了扩展一类业务。比如要支持 vue，我们可以有 `@umijs/preset-vue`，包含 vue 相关的构建和运行时；比如要支持 h5 的应用类型，可以有 `@umijs/preset-h5`，把 h5 相关的功能集合到一起。 +Umi provides a mechanism of plugins and plugin collections to cater to different scenarios and business requirements. Plugins extend specific functionalities, while plugin collections extend categories of business requirements. For instance, to support Vue, there could be `@umijs/preset-vue`, including build and runtime functionalities for Vue. Similarly, `@umijs/preset-h5` could bundle h5-related features together for supporting h5 applications. -如果要类比，插件集和 babel 的 preset，以及 eslint 的 config 都类似。 +Analogously, plugin collections resemble babel presets and eslint configs. -## 最佳实践 +## Best Practices -最佳实践是我们认为做某件事当下最好的方式，主语是我们，所以会相对比较主观。比如路由、补丁方案、数据流、请求、权限、国际化、微前端、icons 使用、编辑器使用、图表、表单等方面，Umi 都会给出我们的最佳实践。这些最佳实践大部分来自蚂蚁集团内部的实践和讨论，也有部分来自社区。他们是主观和时间敏感的，所以可能会有相对比较频繁的迭代。 +Best practices reflect our current understanding of the best way to do something. Since the subject is "we," best practices are relatively subjective. Umi provides best practices for aspects like routing, patching solutions, data flow, requests, permissions, internationalization, micro-frontends, icon usage, editor usage, charts, forms, etc. Many of these practices are derived from practices and discussions within Ant Group, as well as from the community. These practices are subjective and time-sensitive, leading to frequent iterations. -之所以需要最佳实践，1）是社区太多方案选择，2）是很多人没有选择的精力和经验甚至意愿。尤其是针对非专业的前端，有选择比没选择好，不管这个选择如何。 +Best practices are essential due to the overwhelming number of choices in the community and the lack of time, experience, or willingness of many developers to choose. Especially for non-professional developers, having a choice is better than not having one, regardless of the choice itself. -## 企业级 +## Enterprise-Grade -npm 社区「世风日下」，涉政包、恶意包、广告求职包频出，所以如何确保不会「睡一觉醒来项目挂了」是面对企业生成提供服务的框架绕不开的一个点。 +The npm ecosystem is somewhat chaotic, with issues like politically sensitive packages, malicious packages, and job advertisement packages cropping up frequently. Ensuring that projects won't "break overnight" is an essential aspect of creating a framework meant to serve enterprises. -Umi 通过写死版本、依赖预打包、通过 eslint hack 锁定 eslint 依赖，通过配置锁定 babel 补丁依赖等方式，让 Umi 不会在你重装 node_modules 之后就挂掉，并以此来实现「十年后依旧可用」。 +Umi tackles this by fixing versions, pre-bundling dependencies, locking eslint dependencies using eslint hacks, and locking babel patch dependencies through configuration. These strategies ensure that Umi won't break after reinstalling node_modules, contributing to its longevity. ## import all from umi -很多人可能都第一次听到。import all from umi 意思是所有 import 都来自 `umi`。比如 dva 不是 `import { connect } from 'dva'`，而是 `import { connect } from 'umi'`，从 umi 中导出。导出的方法不仅来自 umi 自身，还来自 umi 插件。 +This feature might be unfamiliar to many. "import all from umi" means that all imports come from `umi`. For example, instead of `import { connect } from 'dva'`, it's `import { connect } from 'umi'`. The exported methods not only come from Umi itself but also from Umi plugins. -这是两年前 Umi 3 加的功能，最近发现 Remix、prisma、vitekit 等框架和工具都有类似实现。 +This feature was introduced in Umi 3 two years ago. Recently, similar implementations have been adopted by frameworks and tools like Remix, prisma, and vitekit. ```ts -// 大量插件为 umi 提供额外导出内容 +// Many plugins provide additional exports from umi import { connect, useModel, useIntl, useRequest, MicroApp, ... } from 'umi'; ``` -这带来的好处是。通过 Umi 将大量依赖管理起来，用户无需手动安装；同时开发者在代码中也会少很多 import 语句。 +The benefit is that many dependencies are managed through Umi, reducing the need for manual installations. Additionally, developers will have fewer import statements in their code. \ No newline at end of file diff --git a/docs/docs/introduce/philosophy.zh-CN.md b/docs/docs/introduce/philosophy.zh-CN.md new file mode 100644 index 000000000000..cf7acaff377e --- /dev/null +++ b/docs/docs/introduce/philosophy.zh-CN.md @@ -0,0 +1,62 @@ +# 设计思路 + +Umi 从 1 做到 4，试错了很多东西，也试对了不少。这些试对的点我们逐渐沉淀下来，就成为指引我们如何做好企业级框架的思路。 + +设计思路包括， + +1、技术收敛
+2、插件和插件集
+3、最佳实践
+4、企业级
+5、import all from umi
+6、编译时框架
+7、依赖预打包
+8、默认快
+9、约束与开放
+ +下面仅介绍 1-5 的 5 点，剩下 6-9 的 4 点在 2022.1.8 的 SEE Conf 中有过详细分享，详见[《SEE Conf: Umi 4 设计思路文字稿》](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ%3D%3D&mid=2247484533&idx=1&sn=9b15a67b88ebc95476fce1798eb49146)。 + +## 技术收敛 + +
+
+
+ +技术收敛对团队而言尤其重要，他包含两层含义，1）技术栈收敛 2）依赖收敛。技术栈收敛指社区那么多技术栈，每个技术方向都有非常多选择，比如数据流应该就不下 100 种，开发者应该如何选择；收敛了技术栈之后还需要收敛依赖，团队中，开发者的项目不应该有很多细碎的依赖，每一个依赖都附带着升级成本。 + +我们希望开发者依赖 Umi 之后就无需关心 babel、webpack、postcss、react、react-router 等依赖，而依赖 @umijs/max 之后无需再关心开发中台项目的依赖和技术栈。 + +## 插件和插件集 + +
+
+
+ +Umi 通过提供插件和插件集的机制来满足不同场景和业务的需求。插件是为了扩展一个功能，而插件集是为了扩展一类业务。比如要支持 vue，我们可以有 `@umijs/preset-vue`，包含 vue 相关的构建和运行时；比如要支持 h5 的应用类型，可以有 `@umijs/preset-h5`，把 h5 相关的功能集合到一起。 + +如果要类比，插件集和 babel 的 preset，以及 eslint 的 config 都类似。 + +## 最佳实践 + +最佳实践是我们认为做某件事当下最好的方式，主语是我们，所以会相对比较主观。比如路由、补丁方案、数据流、请求、权限、国际化、微前端、icons 使用、编辑器使用、图表、表单等方面，Umi 都会给出我们的最佳实践。这些最佳实践大部分来自蚂蚁集团内部的实践和讨论，也有部分来自社区。他们是主观和时间敏感的，所以可能会有相对比较频繁的迭代。 + +之所以需要最佳实践，1）是社区太多方案选择，2）是很多人没有选择的精力和经验甚至意愿。尤其是针对非专业的前端，有选择比没选择好，不管这个选择如何。 + +## 企业级 + +npm 社区「世风日下」，涉政包、恶意包、广告求职包频出，所以如何确保不会「睡一觉醒来项目挂了」是面对企业生成提供服务的框架绕不开的一个点。 + +Umi 通过写死版本、依赖预打包、通过 eslint hack 锁定 eslint 依赖，通过配置锁定 babel 补丁依赖等方式，让 Umi 不会在你重装 node_modules 之后就挂掉，并以此来实现「十年后依旧可用」。 + +## import all from umi + +很多人可能都第一次听到。import all from umi 意思是所有 import 都来自 `umi`。比如 dva 不是 `import { connect } from 'dva'`，而是 `import { connect } from 'umi'`，从 umi 中导出。导出的方法不仅来自 umi 自身，还来自 umi 插件。 + +这是两年前 Umi 3 加的功能，最近发现 Remix、prisma、vitekit 等框架和工具都有类似实现。 + +```ts +// 大量插件为 umi 提供额外导出内容 +import { connect, useModel, useIntl, useRequest, MicroApp, ... } from 'umi'; +``` + +这带来的好处是。通过 Umi 将大量依赖管理起来，用户无需手动安装；同时开发者在代码中也会少很多 import 语句。 diff --git a/docs/docs/introduce/upgrade-to-umi-4.md b/docs/docs/introduce/upgrade-to-umi-4.md index d955a54c01ee..bc1ed2aa7d60 100644 --- a/docs/docs/introduce/upgrade-to-umi-4.md +++ b/docs/docs/introduce/upgrade-to-umi-4.md @@ -1,20 +1,20 @@ -# 升级到 Umi 4 +# Upgrading to Umi 4 -## 升级步骤 +## Upgrade Steps -升级到 Umi 4 只需要简单的几步操作就能完成，简单的描述整个过程就是 - “重装依赖，修改配置”： +Upgrading to Umi 4 can be completed with just a few simple steps, which can be summarized as "reinstall dependencies, modify configurations": -1. **依赖处理** -2. **启动命令** -3. **非官方插件升级** -4. **配置层迁移** -5. **代码层修改** +1. **Dependency Management** +2. **Update Commands** +3. **Unofficial Plugin Upgrades** +4. **Configuration Migration** +5. **Code-Level Changes** -### 依赖处理 +### Dependency Management -项目的 `package.json` 需要升级 Umi，并替换掉对应的 Umi 插件。 +In your project's `package.json`, you need to upgrade Umi and replace corresponding Umi plugins. -如果 `umi@3` 中是使用 `umi` + `@umijs/preset-react` 的组合进行开发的，那可以直接使用新版的 `max` 直接升级。 +If your project was developed using the combination of `umi` + `@umijs/preset-react` in `umi@3`, you can directly upgrade to the new version using `@umijs/max`. ```diff { @@ -26,13 +26,13 @@ } ``` -删除 `node_module`，执行下 `npm install` 重装依赖。 +Delete your `node_modules` folder and then run `npm install` to reinstall the dependencies. -### 启动命令 +### Update Commands -如果使用了 `@umijs/max` 可以使用 `max` 命令来替换 `umi`，`max dev`，`max build` 等 +If you are using `@umijs/max`, you can replace the `umi` commands with `max` commands, such as `max dev`, `max build`, etc. -`umi@4` 将一些项目前置操作放到了 `setup` 命令中，如 umi@3 中的 `umi g tmp` 等命令，需要使用 `umi setup` 替换 +`umi@4` has moved some project initialization operations to the `setup` command, similar to the `umi g tmp` command in `umi@3`, which should be replaced with `umi setup`. `package.json` @@ -49,68 +49,55 @@ } ``` -### 非官方插件升级 +### Unofficial Plugin Upgrades -在项目中用到的一些非 Umi 官方提供的 Umi 插件，请联系相关作者及时根据[插件 api 变动](../api/plugin-api)。 +For some unofficial Umi plugins used in your project, please contact the respective authors to update them based on the [plugin API changes](../api/plugin-api). -项目迁移时可先关闭对相应插件包的引用，如临时注释配置中的 `plugins`，移除 package.json 中以 `umi-plugin-`，`@umijs/plugin-` 和 `@umijs/preset-` 开头的所有依赖。 +During project migration, you can temporarily comment out the references to the corresponding plugin packages in your configurations. Remove dependencies starting with `umi-plugin-`, `@umijs/plugin-`, and `@umijs/preset-` from your `package.json`. -### 配置层迁移 +### Configuration Migration -**max 提供的的配置项**如下 `config/config.ts` ： +**max's provided configuration items** in `config/config.ts`: -> 需要注意的是，之前的一些插件约定开启的规则，在 `umi@4` 中几乎都要通过显式的配置开启，因为希望在 `umi@4` 中有更少的“黑盒”。 +> Note that some previously implicitly enabled rules in certain plugins must now be explicitly configured in `umi@4`, as there is a desire for fewer "black boxes" in `umi@4`. ```typescript -import { defineConfig, utils } from 'umi'; +import { defineConfig } from 'umi'; export default defineConfig({ - model: {}, - antd: {}, - request: {}, - initialState: {}, + fastRefresh: true, + dva: {}, mock: { include: ['src/pages/**/_mock.ts'], }, - dva: {}, layout: { - // https://umijs.org/docs/max/layout-menu#构建时配置 title: 'UmiJS', locale: true, }, - // https://umijs.org/zh-CN/plugins/plugin-locale locale: { - // default zh-CN default: 'zh-CN', antd: true, - // default true, when it is true, will use `navigator.language` overwrite default baseNavigator: true, }, }); ``` -**存在差异的配置项**如下 `config/config.ts` ： +**Configuration items with differences** in `config/config.ts`: ```typescript -import { defineConfig, utils } from 'umi'; +import { defineConfig } from 'umi'; export default defineConfig({ -- fastRefresh: {}, -+ fastRefresh: true, - dva: { - // 不再支持 hmr 这个参数 -- hmr: true, - }, -// 默认 webpack5 -- webpack5: {}, -}) + fastRefresh: true, // Previously: fastRefresh: {} + dva: {}, // Previous hmr parameter is no longer supported +}); ``` -### 代码层修改 +### Code-Level Changes -Umi 4 中将 `react-router@5` 升级到 `react-router@6`，所以路由相关的一些 api 存在着使用上的差异。 +Umi 4 upgrades `react-router@5` to `react-router@6`, so there are some usage differences in the routing-related APIs. -props 默认为空对象，以下属性都不能直接从 props 中取出  +Props are now empty objects, and the following properties cannot be directly accessed from props:  #### children @@ -119,9 +106,9 @@ import { Outlet } from 'umi';` 组件拥有 `accessible` 和 `fallback` 两个属性，当 `accessible` 为 `true` 时会渲染子组件，当 `accessible` 为 `false` 会渲染 `fallback` 属性对应的 `ReactNode`。
+- The `` component has two attributes: `accessible` and `fallback`. When `accessible` is `true`, the child component will be rendered. When `accessible` is `false`, the `ReactNode` corresponding to the `fallback` attribute will be rendered.
diff --git a/docs/docs/max/access.zh-CN.md b/docs/docs/max/access.zh-CN.md
new file mode 100644
index 000000000000..3d949dcc988b
--- /dev/null
+++ b/docs/docs/max/access.zh-CN.md
@@ -0,0 +1,162 @@
+# 权限
+
+## 启用方式
+
+配置开启。同时需要 `src/access.ts` 提供权限配置。
+
+```ts
+export default {
+ access: {},
+ // access 插件依赖 initial State 所以需要同时开启
+ initialState: {},
+};
+```
+
+## 介绍
+
+我们约定了 `src/access.ts` 为我们的权限定义文件，该文件需要默认导出一个方法，导出的方法会在项目初始化时被执行。该方法需要返回一个对象，对象的每一个值就对应定义了一条权限。如下所示：
+
+```js
+// src/access.ts
+export default function (initialState) {
+ const { userId, role } = initialState;
+
+ return {
+ canReadFoo: true,
+ canUpdateFoo: role === 'admin',
+ canDeleteFoo: (foo) => {
+ return foo.ownerId === userId;
+ },
+ };
+}
+```
+
+其中 `initialState` 是通过初始化状态插件 `initial-state` 提供的数据，你可以使用该数据来初始化你的用户权限。
+
+## 配置
+
+### 扩展的路由配置
+
+配合 [layout](./layout-menu) 插件你可以很简单的实现针对某些页面的权限控制。如下所示，只有拥有了 canReadPageA （在 `src/access.ts` 中定义）权限，用户才可以访问该页面。否则会默认渲染 Layout 插件内置的权限错误页面。
+
+```ts
+export const routes = [
+ {
+ path: '/pageA',
+ component: 'PageA',
+ access: 'canReadPageA', // 权限定义返回值的某个 key
+ },
+];
+```
+
+### 自定义权限页面配置
+
+上面说到默认渲染 Layout 插件内置的权限错误页面，如果想配置自定义权限页面需要在 `src/app.tsx` 中定义。
+
+```tsx
+export const layout: RunTimeLayoutConfig = () => {
+ return {
+ // 自定义 403 页面
+ unAccessible:
+ Can not update foo.
}
+ >
+ Update foo.
+
+
+ { location.pathname }
+ { location.search }
+ { location.hash }
+
+ );
+}
+```
+
+如果在 React 组件和 Hooks 之外获取当前路由信息。
+
+```ts
+// location 对象，包含 pathname、search 和 hash
+window.location.pathname;
+window.location.search;
+window.location.hash;
+```
+
+命令式路由跳转。
+
+```ts
+import { history } from 'umi';
+
+// 跳转到指定路由
+history.push('/list');
+
+// 带参数跳转到指定路由
+history.push('/list?a=b&c=d#anchor', state);
+history.push({
+ pathname: '/list',
+ search: '?a=b&c=d',
+ hash: 'anchor',
+ },
+ {
+ some: 'state-data',
+ }
+);
+
+// 跳转当前路径，并刷新 state
+history.push({}, state)
+
+// 跳转到上一个路由
+history.back();
+history.go(-1);
+```
+
+-
+
+
+ );
+}
+
+function DashboardWithContext() {
+ return (
+ Dashboard
+
+
+ );
+}
+```
+
+`Outlet` 组件的 `context` 可以使用 API `useOutletContext` 在子组件中获取。
+
+### resolvePath
+
+用于在客户端解析前端路由跳转路径。
+
+类型定义如下：
+
+```ts
+declare function resolvePath(
+ to: PartialDashboard
+
+ {outlet}
+
+}
+```
+
+### useOutletContext
+
+`useOutletContext` 用于返回 `Outlet` 组件上挂载的 `context` 。
+
+类型定义如下：
+```ts
+declare function useOutletContext
+
+}
+
+const SomeRouteComponentUnderLayout = () => {
+ const layoutContext = useOutletContext();
+
+ return JSON.stringify(layoutContext) // {"prop":"from Layout"}
+}
+```
+
+### useParams
+
+`useParams` 钩子函数返回动态路由的匹配参数键值对对象；子路由中会集成父路由的动态参数。
+
+类型定义如下：
+```ts
+declare function useParams<
+ K extends string = string
+>(): Readonly1 :
+ }
+
+ if (lastRoute?.extraProp) {
+ return 2 :
+ }
+
+ return
+ Hello World {this.props.location.pathname}
+
+ );
+ }
+}
+
+export default withRouter(HelloWorld);
+```
diff --git a/docs/docs/api/commands.md b/docs/docs/api/commands.md
index 61ea8ceddabf..732f2f0d5a09 100644
--- a/docs/docs/api/commands.md
+++ b/docs/docs/api/commands.md
@@ -1,14 +1,16 @@
-# 命令行
+Sure, here's the translated markdown with the Chinese words replaced:
-umi 提供了很多内置的命令行用于启动，构建项目，另外还有一些辅助开发的命令，如生成器等。
+# Command Line
-要获取可用的命令列表，你可以在项目目录中运行 help 命令：
+Umi provides many built-in command-line tools for project startup, building, and various development aids such as generators.
+
+To get a list of available commands, you can run the `help` command in your project directory:
```bash
umi help
```
-你应该能看到类似如下的日志：
+You should see logs similar to the following:
```bash
Usage: umi params: {JSON.stringify(this.props.match.params)}
+ +{data}
;
+}
+
+export async function clientLoader() {
+ const data = await fetch('/api/data');
+ return data;
+}
+```
+
+如上代码，在 `clientLoader` 函数返回的数据，可以在组件内调用 `useClientLoaderData` 获取。
+
+## 优化效果
+
+考虑一个三层嵌套路由的场景：
+
+1. 我们需要先等第一层路由的组件加载完成，然后第一层路由的组件发起数据请求
+2. 第一层路由的数据请求完成后，开始请求第二层路由的组件，第二层路由的组件加载好以后请求第二层路由需要的数据
+3. 第二层路由的数据请求完成后，开始请求第三层路由的组件，第三层路由的组件加载好以后请求第三层路由需要的数据
+4. 第三层路由的数据请求完成后，整个页面才完成渲染
+
+这样的瀑布流请求会严重影响用户的体验，如下图所示：
+
+
+
+如果将组件请求数据的程序提取到 `clientLoader` 中，则 Umi 可以并行地请求这些数据：
+
+
diff --git a/docs/docs/guides/compile-speed.zh-CN.md b/docs/docs/guides/compile-speed.zh-CN.md
new file mode 100644
index 000000000000..550d9c4e5763
--- /dev/null
+++ b/docs/docs/guides/compile-speed.zh-CN.md
@@ -0,0 +1 @@
+# 编译速度
diff --git a/docs/docs/guides/config-convention.zh-CN.md b/docs/docs/guides/config-convention.zh-CN.md
new file mode 100644
index 000000000000..96a631860844
--- /dev/null
+++ b/docs/docs/guides/config-convention.zh-CN.md
@@ -0,0 +1,53 @@
+# 配置文件格式约定
+
+为了方便 Umi 通过 CLI 来修改项目的配置，项目配置文件需要采用下面两种方式来书写。
+
+## 导出默认配置对象
+
+推荐这样的方式：
+
+```ts
+// ✅
+export default {
+ dva: {},
+}
+```
+
+而不是这样的方式：
+
+```ts
+// ❌
+const config = { dva: {} }
+export default config
+```
+
+## 默认导出配置函数结果
+
+推荐这样的方式：
+```ts
+// ✅
+import { defineConfig } from 'umi';
+
+export default defineConfig({
+ dva: {}
+})
+```
+
+而不是这样的方式：
+```ts
+// ❌
+import { defineConfig } from 'umi';
+
+const config = { dva: {} }
+export default defineConfig(config)
+```
+
+也不是这样的方式：
+
+```ts
+// ❌
+import { defineConfig } from 'umi';
+
+const config = defineConfig({ dva: {}})
+export default config;
+```
diff --git a/docs/docs/guides/debug.md b/docs/docs/guides/debug.md
index 655d439c0f7e..6a58509b1ccc 100644
--- a/docs/docs/guides/debug.md
+++ b/docs/docs/guides/debug.md
@@ -1,58 +1,58 @@
-import { Message } from 'umi';
+# Debugging
-# 调试
+In addition to using browser debugging tools for development, Umi recommends the following debugging approaches to assist in project debugging.
-除了使用浏览器的调试工具来完成开发中的调试外，Umi 还推荐以下调试方式来协助项目的调试。
+## Debugging the Development Build
-## 调试 dev 产物
+If you need to debug the built artifacts during the development phase, such as `umi.js`, you can follow these steps. Let's take `umi.js` as an example. First, download the original `umi.js` file to the root directory of your project. Make any necessary edits for debugging purposes, and then refresh the browser. The project will use the modified `umi.js` file in the root directory. Once debugging is complete, you can simply delete the `umi.js` file from the root directory to revert to the original state.
-如果你需要在 dev 阶段调试项目的构建产物，以 `umi.js` 举例。先将原来的 `umi.js` 下载到当前项目根目录下。根据调试需要进行编辑后，刷新浏览器，项目使用的 `umi.js` 就替换成了根目录下的 `umi.js` 文件。调试完毕需要恢复就直接删除根目录的 `umi.js` 即可。
+Here's an example of how to do this:
-举例：
```bash
-# 下载当前项目的 umi.js
-$curl http://127.0.0.1:8000/umi.js -O
+# Download the umi.js file from the current project
+$ curl http://127.0.0.1:8000/umi.js -O
-# 增加想调试的内容，举例增加 "debug!!!" 弹窗
+# Make edits for debugging, for example, add an "debug!!!" alert
$ echo -e '\n;alert("debug!!!");\n' >> umi.js
-# 打开浏览器就能看到 alert 弹窗
-# 退出调试，恢复到正常状态
-$rm umi.js
+# Open the browser to see the alert popup
+
+# To exit debugging and revert to the normal state
+$ rm umi.js
```
-以此类推即可调试其他的 JavaScript 文件。
+You can follow similar steps to debug other JavaScript files.
## XSwitch
-如果需要在特定的域名环境调试或者验证当前的修改的代码，推荐使用 Chrome 插件 [XSwitch](https://chrome.google.com/webstore/detail/xswitch/idkjhjggpffolpidfkikidcokdkdaogg)。
-
+If you need to debug or validate your code changes on a specific domain, consider using the Chrome extension [XSwitch](https://chrome.google.com/webstore/detail/xswitch/idkjhjggpffolpidfkikidcokdkdaogg).
+Suppose you want to debug your local code on the production project URL `https://www.myproject.com`. The project uses `https://www.myproject.com/umi.hash.js`. To validate your local project, you need to replace it with your local development environment's `http://127.0.0.1:8000/umi.js`.
-假设我们想在线上项目地址 `https://www.myproject.com` 上调试本地代码。项目使用 `https://www.myproject.com/umi.hash.js`，为了验证本地的项目，需要将它替换成本地开发环境的 `http://127.0.0.1:000/umi.js`
+Start your local environment using the `SOCKET_SERVER` environment variable to avoid continuous page refreshes due to connection issues with the socket server:
-首先使用环境变量 `SOCKET_SERVER` 启动本地环境（防止因为连接不上 socket server 导致页面不断刷新）。
```bash
-$SOCKET_SERVER=http://127.0.0.1:8000/ npx umi dev
+$ SOCKET_SERVER=http://127.0.0.1:8000/ npx umi dev
```
-然后，在 XSwitch 中配置资源转发规则。
+Next, configure resource forwarding rules in XSwitch:
+
```json
{
"proxy": [
- // 数组的第 0 项的资源会被第 1 项目替换
+ // The resource at index 0 of the array will be replaced with the resource at index 1
[
"https://www.myproject.com/umi.2c8a01df.js",
"http://127.0.0.1:8000/umi.js"
],
- // 使用正则可以方便处理分包情况下 js 资源的加载
+ // Using regex to handle loading of JS resources in split chunks
[
"https://www.myproject.com/(.*\.js)",
- "http://127.0.0.1:8000/$1",
+ "http://127.0.0.1:8000/$1"
],
- // 如果需要验证视觉表现，不要忘记替换 css 资源
+ // Don't forget to replace CSS resources if you need to validate visual appearance
[
"https://www.myproject.com/umi.ae8b10e0.css",
"http://127.0.0.1:8000/umi.css"
@@ -61,14 +61,14 @@ $SOCKET_SERVER=http://127.0.0.1:8000/ npx umi dev
}
```
-刷新页面，正式域名下的内容就被替换了，这个时候就能方便的指定环境下调试了。
+After refreshing the page, the content from the production domain will be replaced. This way, you can easily debug in a specific environment.
-如果要退出调试，关闭 XSwitch 插件功能即可。
+To exit debugging, simply disable the XSwitch extension.
>
+ //
```
-### `src` 目录
+### `src` Directory
-#### .umi 目录
+#### .umi Directory
>
+ ```
+
+### `src` 目录
+
+#### .umi 目录
+
+Hello
+}
+```
+
+默认启用 React 18，如果需要 React 17 的渲染方式，请在项目中安装 react 17 的依赖，框架会自动适配 react 版本。
+
+```bash
+$ pnpm i react@17 react-dom@17
+```
+
+## 模板
+
+默认模板如下：
+
+```html
+
+
+
+
+
+ )
+}
+```
+
+这样，访问 `/list` 和 `/admin` 就会带上 `src/layouts/index` 这个 layout 组件。
+
+### redirect
+
+* Type: `string`
+
+配置路由跳转。
+
+比如：
+
+```js
+export default {
+ routes: [
+ { path: '/', redirect: '/list' },
+ { path: '/list', component: 'list' },
+ ],
+}
+```
+
+访问 `/` 会跳转到 `/list`，并由 `src/pages/list` 文件进行渲染。
+
+### wrappers
+
+* Type: `string[]`
+
+配置路由组件的包装组件，通过包装组件可以为当前的路由组件组合进更多的功能。
+比如，可以用于路由级别的权限校验：
+
+```js
+export default {
+ routes: [
+ { path: '/user', component: 'user',
+ wrappers: [
+ '@/wrappers/auth',
+ ],
+ },
+ { path: '/login', component: 'login' },
+ ]
+}
+```
+
+然后在 `src/wrappers/auth` 中，
+
+```jsx
+import { Navigate, Outlet } from 'umi'
+
+export default (props) => {
+ const { isLogin } = useAuth();
+ if (isLogin) {
+ return
+ Users Page
+
+ )
+}
+```
+
+然后点击 `Users Page` 就会跳转到 `/users` 地址。
+
+注意：
+
+* `Link` 只用于单页应用的内部跳转，如果是外部地址跳转请使用 `a` 标签
+
+## 路由组件参数
+
+Umi 4 使用 [react-router@6](https://reactrouter.com/docs/en/v6/api) 作为路由组件，路由参数的获取使其 hooks。
+
+### match 信息
+
+[useMatch](https://reactrouter.com/docs/en/v6/api#usematch)
+
+```jsx
+const match = useMatch('/comp/:id')
+// match
+{
+ "params": {
+ "id": "paramId"
+ },
+ "pathname": "/comp/paramId/",
+ "pathnameBase": "/comp/paramId",
+ "pattern": {
+ "path": "/comp/:id",
+ "caseSensitive": false,
+ "end": true
+ }
+}
+```
+
+### location 信息
+
+[useLocation](https://reactrouter.com/docs/en/v6/api#uselocation)
+
+```jsx
+const location = useLocation();
+// location
+{
+ "pathname": "/path/",
+ "search": "",
+ "hash": "",
+ "state": null,
+ "key": "default"
+}
+```
+
+Hello World
;
+}
+```
+
+按照此种引入方式的样式会在整个 Umi 项目中生效，即无论你从哪个 `.js`
+文件引入，他声明的样式可以在任何页面和组件中使用。如果你想要避免这种情况，可以使用 [CSS Modules](#使用-css-modules) 的功能来限制样式的作用域。
+
+## 使用 CSS Modules
+
+在 `js` 文件中引入样式时，如果赋予他一个变量名，就可以将样式以 CSS Module 的形式引入。
+
+```jsx
+// src/pages/index.tsx
+
+import styles from './index.css';
+
+export default function () {
+ return
+ Hello World
+
;
+}
+```
+
+上面的示例中，`index.css` 文件中声明的样式不会对全局样式造成影响，只会对从 `styles` 变量中使用的样式生效。
+
+## 使用 CSS 预处理器
+
+Umi 默认支持 LESS (推荐)，SASS 和 SCSS 样式的导入，你可以直接按照引入 CSS 文件的方式引入并使用这些由 CSS 预处理器处理的样式。
+
+Hello World
;
+}
+```
+
+同样也支持 CSS Module 的用法：
+
+```jsx
+// src/pages/index.tsx
+
+import lessStyles from './index.less';
+import sassStyles from './index.sass';
+import scssStyles from './index.scss';
+
+export default function () {
+ return
+ Hello World
+
;
+}
+```
+
+## 进阶设置
+
+如果你需要使用除了常见的 LESS, SASS 或 SCSS 以外的其他样式预处理器，你可以透过 Umi
+插件提供的 [chainWebpack 接口](../api/config#chainwebpack)来加入自己需要的 Loader。
+
+## 使用 Tailwindcss
+
+Umi 提供了内置的 [Tailwindcss](https://tailwindcss.com/)
+插件，并且可以直接方便地使用 [微生成器](./generator#tailwind-css-配置生成器) 来启用。
+
+## 使用 UnoCSS
+
+与 Tailwindcss 相同，Umi 也提供了内置的 [UnoCSS](https://github.com/unocss/unocss) 插件，可以按照相同方式开启。
+
+1. 安装 `plugin-unocss`
+2. 安装 `unocss` 及 `@unocss/cli`
+
+```bash
+pnpm i unocss @unocss/cli
+```
+
+3. 在 Umi 设置中启用插件，并声明会用到 `unocss` 的文件目录
+
+```js
+// .umirc.ts
+
+export default {
+ plugins: [
+ require.resolve('@umijs/plugins/dist/unocss')
+ ],
+ unocss: {
+ // 检测 className 的文件范围，若项目不包含 src 目录，可使用 `pages/**/*.tsx`
+ watch: ['src/**/*.tsx']
+ },
+};
+```
+
+4. 在项目目录下加入 `unocss.config.ts`
+ 配置文件，并加入项目需要的 [UnoCSS Presets](https://github.com/unocss/unocss#presets)
+
+```js
+// unocss.config.ts
+
+import {defineConfig, presetAttributify, presetUno} from 'unocss';
+
+export function createConfig({strict = true, dev = true} = {}) {
+ return defineConfig({
+ envMode: dev ? 'dev' : 'build', presets: [presetAttributify({strict}), presetUno()],
+ });
+}
+
+export default createConfig();
+```
+
+5. 启动项目进行开发，插件会监听设置文件中的 `unocss.watch` 字段，动态生成样式文件并自动套用
diff --git a/docs/docs/guides/test.md b/docs/docs/guides/test.md
index c3cde837cff9..8b964331bb71 100644
--- a/docs/docs/guides/test.md
+++ b/docs/docs/guides/test.md
@@ -1,16 +1,14 @@
-import { Message, Tabbed } from 'umi';
+# Testing
-# 测试
+Automated testing is an effective means of ensuring quality, and Umi 4 provides a scaffolding for unit testing. Umi 4 recommends using [Jest](https://jestjs.io/) and [@testing-library/react](https://github.com/testing-library/react-testing-library) for unit testing in your project.
-自动化测试是保障质量的有效手段，Umi 4 提供单元测试的脚手架。Umi 4 推荐使用 [Jest](https://jestjs.io/) 和 [@testing-library/react](https://github.com/testing-library/react-testing-library) 来完成项目中的单元测试。
+## Configuration
-## 配置
-
-使用 Umi 4 的微生成器快速的配置好 Jest [参考](./generator#jest-配置生成器), 如果你需要修改 jest 相关的配置，可以在 `jest.config.ts` 修改。
+Use the micro generator in Umi 4 to quickly set up Jest [reference](./generator#jest-configuration-generator). If you need to modify the Jest-related configuration, you can do so in the `jest.config.ts` file.
I am blue
+I am red
+-使用 Max 并不代表需要使用全部 Max 的功能，可以根据需求关闭插件，所以当你需要使用 Max 的功能时，可以总是选择创建 Max 项目。 +**Should I choose Max?**
+Using Max doesn't mean you have to utilize all of its features. You can choose to disable plugins based on your needs. So, when you want to use Max's features, you can always choose to create a Max project.
+使用 Max 并不代表需要使用全部 Max 的功能，可以根据需求关闭插件，所以当你需要使用 Max 的功能时，可以总是选择创建 Max 项目。 +
-如果你不知道可以贡献什么，可以到源码里搜 TODO 或 FIXME 找找。
+If you're unsure about what to contribute, you can search for TODO or FIXME in the source code.
\ No newline at end of file
diff --git a/docs/docs/introduce/contributing.zh-CN.md b/docs/docs/introduce/contributing.zh-CN.md
new file mode 100644
index 000000000000..ec1af2e3f868
--- /dev/null
+++ b/docs/docs/introduce/contributing.zh-CN.md
@@ -0,0 +1,186 @@
+import { Message } from 'umi';
+
+# 参与贡献
+
+❤️ Loving Umi and want to get involved? Thanks!
+
+## 环境准备
+
+### Node.js 和 pnpm
+
+开发 Umi 需要 Node.js 16+ 和 `pnpm` v8。
+
+推荐使用 [`nvm`](https://github.com/nvm-sh/nvm) 管理 Node.js，避免权限问题的同时，还能够随时切换当前使用的 Node.js 的版本。在 Windows 系统下的开发者可以使用 [`nvm-windows`](https://github.com/coreybutler/nvm-windows)。
+
+在 `pnpm` 的[官网](https://pnpm.io/installation)选择一种方式安装即可。
+
+### Clone 项目
+
+```bash
+$ git clone git@github.com:umijs/umi.git
+$ cd umi
+```
+
+### 安装依赖并构建
+
+```bash
+$ pnpm i && pnpm build
+```
+
+## 开发 Umi
+
+### 启动 dev 命令
+
+本地开发 Umi 必开命令，用于编译 `src` 下的 TypeScript 文件到 `dist` 目录，同时监听文件变更，有变更时增量编译。
+
+```bash
+$ pnpm dev
+```
+
+如果觉得比较慢，也可以只跑特定 package 的 `pnpm dev` 命令，比如。
+
+```bash
+$ cd packages/umi
+$ pnpm dev
+```
+
+### 跑 Example
+
+`examples` 目录下保存了各种用于测试的例子，跑 example 是开发 Umi 时确认功能正常的常用方式。每个 example 都配了 dev 脚本，所以进入 example 然后执行 `pnpm dev` 即可。
+
+```bash
+$ cd examples/boilerplate
+$ pnpm dev
+```
+
+如果要用 vite 模式跑，加 `--vite` 参数，
+
+```bash
+$ pnpm dev --vite
+```
+
+### 测试
+
+目前跑测试很快，10s+ 就完成了。推荐本地跑一遍再提 PR，减少 Round Trip。
+
+```bash
+$ pnpm test
+...
+Test Suites: 1 skipped, 43 passed, 43 of 44 total
+Tests: 6 skipped, 167 passed, 173 total
+Snapshots: 0 total
+Time: 13.658 s
+Ran all test suites.
+```
+
+如果需要只跑部分文件的用例，用 `pnpm jest`，因为 `pnpm test` 只开了 turborepo 功能的。
+
+比如，
+
+```bash
+$ pnpm jest packages/plugin-docs/src/compiler.test.ts
+```
+
+## 贡献 Umi 文档
+
+Umi 的文档由 Umi@4 和 `@umijs/plugin-docs` 插件实现，本质上就是一个 Umi 项目。在根目录执行如下命令即可开始 Umi 文档的开发：
+
+```bash
+# 安装 Umi 文档依赖
+$ pnpm doc:deps
+# 启用 Umi 文档开发
+# 首次启动时编译耗时较长，请耐心等待
+$ pnpm doc:dev
+```
+
+打开指定的端口号，即可实时查看文档更新的内容，以及 `@umijs/plugin-docs` 插件开发的成果。
+
+### 撰写 Umi 文档
+
+Umi 文档的编写基于 MDX 格式。MDX 是 Markdown 格式的拓展，允许您在撰写 Umi 文档时插入 JSX 组件。
+
+
+
+如果你不知道可以贡献什么，可以到源码里搜 TODO 或 FIXME 找找。
diff --git a/docs/docs/introduce/faq.md b/docs/docs/introduce/faq.md
index d13c78377500..b891dd3b42d2 100644
--- a/docs/docs/introduce/faq.md
+++ b/docs/docs/introduce/faq.md
@@ -1,16 +1,16 @@
-# FAQ
+## FAQ
-## 可以关闭 dynamicImport 吗？
+### Can I disable `dynamicImport`?
-可以，但不建议关闭。
+Yes, you can disable it, but it's not recommended.
-1、安装依赖
+1. Install the dependency:
```bash
- pnpm i babel-plugin-dynamic-import-node -D
+pnpm i babel-plugin-dynamic-import-node -D
```
-2、配置里加上 `extraBabelPlugins` ，但只针对 production 开启
+2. Add the `extraBabelPlugins` configuration in your `.umirc.ts` to apply the plugin only in production:
```ts
// .umirc.ts
@@ -21,68 +21,67 @@ export default {
}
```
-## 没有 dynamicImport 怎么配置它的 loading ？
+### How do I configure the loading when using `dynamicImport`?
-定义 `src/loading.tsx` :
+Define a `src/loading.tsx` file:
-参考 [目录结构 > loading.tsx](../guides/directory-structure#loadingtsxjsx)
+Refer to [Directory Structure > loading.tsx](../guides/directory-structure#loadingtsxjsx).
-## 可以用 react 17 吗？
+### Can I use React 17?
-由于 umi v4 升级了默认的 react 版本到 v18，使用 umi4 时注意下依赖库和 react 18 的兼容情况，如果还需要使用 react 17，请执行以下命令并重启。
+Umi v4 upgrades the default React version to v18. If you want to use React 17, execute the following command and restart:
```bash
- pnpm add react@^17 react-dom@^17
+pnpm add react@^17 react-dom@^17
```
-## 代理静态资源到本地后，一直 restart 刷新页面
+### After proxying static resources to my local server, the page keeps restarting when refreshed.
-解法：配置 `SOCKET_SERVER=127.0.0.1:${port}` 启动项目
+Solution: Configure `SOCKET_SERVER=127.0.0.1:${port}` when starting the project:
```bash
- SOCKET_SERVER=http://127.0.0.1:8000 pnpm dev
+SOCKET_SERVER=http://127.0.0.1:8000 pnpm dev
```
-## Error evaluating function `round`: argument must be a number
+### Error evaluating function `round`: argument must be a number
-解法：新版 less 中 `/` 默认被识别为属性简写，通过配置 `lessLoader: { math: 'always' }` 恢复旧版行为（默认将 `/` 用作计算符号）。
+Solution: In the new version of Less, `/` is recognized as an attribute shorthand. To revert to the old behavior (treating `/` as a calculation symbol), configure `lessLoader: { math: 'always' }`.
-## routes 里的 layout 配置选项不生效
+### The `layout` configuration option in `routes` doesn't work.
-layout 配置被移动到了 `app.ts` ，详见 [runtime-config > layout](https://umijs.org/docs/api/runtime-config#layout)
+The `layout` configuration has been moved to `app.ts`. Refer to [Runtime Configuration > layout](https://umijs.org/docs/api/runtime-config#layout).
+### Where is `document.ejs`, and how do I customize the HTML template?
-## document.ejs 去哪了，如何自定义 HTML 模板
+In addition to injecting external [scripts](https://umijs.org/docs/api/config#scripts) and [styles](https://umijs.org/docs/api/config#styles) through configuration, you can use project-level plugins to modify the HTML output more flexibly. See [issuecomment-1151088426](https://github.com/umijs/umi-next/issues/868#issuecomment-1151088426).
-除了可以通过 配置项 注入外部 [script](https://umijs.org/docs/api/config#scripts) 、[css](https://umijs.org/docs/api/config#styles) 外，还可以使用项目级插件更灵活的修改 HTML 产物，参见：[issuecomment-1151088426](https://github.com/umijs/umi-next/issues/868#issuecomment-1151088426)
+### The external JavaScript file configured in `scripts` is inserted after `umi.js`. Why is that?
-## scripts 里配置的外部 js 文件为什么默认插入到 umi.js 的后面
+React only starts running after the page has loaded completely, so inserting it after `umi.js` doesn't affect the project.
-react 只有在页面加载完毕后才会开始运行，所以插到 `umi.js` 后面不会影响项目。
+If you need to insert it before `umi.js`, refer to [issuecomment-1176960539](https://github.com/umijs/umi/issues/8442#issuecomment-1176960539).
-若需要插到 `umi.js` 前面，可参见 [issuecomment-1176960539](https://github.com/umijs/umi/issues/8442#issuecomment-1176960539)
+### How do I bundle packages in Umi 4?
-## umi4 我怎么分包
+Umi 4 by default splits bundles by page. If you feel the need for further optimization, you can use code splitting strategies or manually split bundles. Refer to [Code Splitting Guide](../../blog/code-splitting).
-Umi 4 默认按页拆包，如果你觉得还需要优化，可以使用分包策略或手动拆包，详见：[代码拆分指南](../../blog/code-splitting)
+If you have a requirement to bundle all JavaScript artifacts into a single `umi.js` file, you need to disable [dynamicImport](#can-i-disable-dynamicimport).
-如果你有将所有 js 产物打包成单 `umi.js` 文件的需求，请关闭 [dynamicImport](#可以关闭-dynamicimport-吗) 。
+### Where is `_layout.tsx`, and how do I implement nested routing?
-## _layout.tsx 去哪了，我怎么嵌套路由
+Umi 4 uses React Router v6. Use the `
+
+解法：配置 `SOCKET_SERVER=127.0.0.1:${port}` 启动项目
+
+```bash
+ SOCKET_SERVER=http://127.0.0.1:8000 pnpm dev
+```
+
+## Error evaluating function `round`: argument must be a number
+
+
+
+解法：新版 less 中 `/` 默认被识别为属性简写，通过配置 `lessLoader: { math: 'always' }` 恢复旧版行为（默认将 `/` 用作计算符号）。
+
+## routes 里的 layout 配置选项不生效
+
+layout 配置被移动到了 `app.ts` ，详见 [runtime-config > layout](https://umijs.org/docs/api/runtime-config#layout)
+
+
+## document.ejs 去哪了，如何自定义 HTML 模板
+
+除了可以通过 配置项 注入外部 [script](https://umijs.org/docs/api/config#scripts) 、[css](https://umijs.org/docs/api/config#styles) 外，还可以使用项目级插件更灵活的修改 HTML 产物，参见：[issuecomment-1151088426](https://github.com/umijs/umi-next/issues/868#issuecomment-1151088426)
+
+## scripts 里配置的外部 js 文件为什么默认插入到 umi.js 的后面
+
+react 只有在页面加载完毕后才会开始运行，所以插到 `umi.js` 后面不会影响项目。
+
+若需要插到 `umi.js` 前面，可参见 [issuecomment-1176960539](https://github.com/umijs/umi/issues/8442#issuecomment-1176960539)
+
+## umi4 我怎么分包
+
+Umi 4 默认按页拆包，如果你觉得还需要优化，可以使用分包策略或手动拆包，详见：[代码拆分指南](../../blog/code-splitting)
+
+如果你有将所有 js 产物打包成单 `umi.js` 文件的需求，请关闭 [dynamicImport](#可以关闭-dynamicimport-吗) 。
+
+## _layout.tsx 去哪了，我怎么嵌套路由
+
+Umi 4 使用 react-router v6 ，通过 `
-## Umi 是什么？
+## What is Umi?
-Umi，中文发音为「乌米」，是可扩展的企业级前端应用框架。Umi 以路由为基础的，同时支持配置式路由和约定式路由，保证路由的功能完备，并以此进行功能扩展。然后配以生命周期完善的插件体系，覆盖从源码到构建产物的每个生命周期，支持各种功能扩展和业务需求。
+Umi, from the Chinese word 乌米 "woo-mee" (wū mǐ), is a scalable enterprise-class front-end application framework. Umi is based on routing, and supports both configuration routing and convention routing to ensure complete routing function experience. It is also complemented with a complete life cycle plug-in system, covering every use case from source code to build products, and supports many function extensions and business requirements.
-Umi 是蚂蚁集团的底层前端框架，已直接或间接地服务了 10000+ 应用，包括 Java、Node、H5 无线、离线（Hybrid）应用、纯前端 assets 应用、CMS 应用、Electron 应用、Serverless 应用等。他已经很好地服务了我们的内部用户，同时也服务了不少外部用户，包括淘系、飞猪、阿里云、字节、腾讯、口碑、美团等。在 2021 年字节的[调研报告](https://zhuanlan.zhihu.com/p/403206195)中，Umi 是其中 25.33% 开发者的选择。
+Umi is the underlying front-end framework of Ant Group, and has directly or indirectly served 10,000 applications, including Java, Node.js, mobile (H5), offline (Hybrid) apps, pure frontend asset applications, CMS applications, Electron apps, and Serverless applications. It has effectively served internal users within Ant Group and a significant number of external users from various companies such as Taobao, Fliggy, Alibaba Cloud, ByteDance, Tencent, Koubei, and Meituan. In ByteDance's [2021 developer survey report](https://zhuanlan.zhihu.com/p/403206195), Umi was the choice of 25.33% of developers.
-Umi 有很多非常有意思的特性，比如。
+Umi boasts several interesting features:
-1、**企业级**，在安全性、稳定性、最佳实践、约束能力方面会考虑更多-2、**插件化**，啥都能改，Umi 本身也是由插件构成
-3、**MFSU**，比 Vite 还快的 Webpack 打包方案
-4、基于 React Router 6 的完备路由
-5、默认最快的请求
-6、SSR & SSG
-7、稳定白盒性能好的 ESLint 和 Jest
-8、React 18 的框架级接入
-9、Monorepo 最佳实践
+1. **Enterprise-Grade**: Focused on security, stability, best practices, and constraint capabilities. +2. **Plugin-Based**: Highly customizable with Umi itself built upon a plugin architecture. +3. **MFSU**: A Webpack bundling solution faster than Vite. +4. Complete routing based on React Router 6. +5. Fastest default request setup. +6. SSR & SSG capabilities. +7. Stable and performant ESLint and Jest integration. +8. Framework-level integration with React 18. +9. Monorepo best practices. ... +## When Not to Use Umi? -## 什么时候不用 Umi？ +Umi might not be suitable for your project if: -如果你的项目， - -1、需要支持 IE 8 或更低版本的浏览器
-2、需要支持 React 16.8.0 以下的 React
-3、需要跑在 Node 14 以下的环境中
-4、有很强的 webpack 自定义需求和主观意愿
-5、需要选择不同的路由方案
+1. You need to support browsers, including IE 8 or lower. +2. You need to support React versions earlier than 16.8.0. +3. Your project needs to run in an environment with Node.js versions lower than 14. +4. You have specific and strong Webpack customization requirements and preferences. +5. You need to choose a different routing solution. ... -Umi 可能不适合你。 - - -## 为什么不是？ +## Why Not? ### create-react-app -create-react-app 是脚手架，和 Umi、next.js、remix、ice、modern.js 等元框架不是同一类型。脚手架可以让我们快速启动项目，对于单一的项目够用，但对于团队而言却不够。因为使用脚手架像泼出去的水，一旦启动，无法迭代。同时脚手架所能做的封装和抽象都非常有限。 +create-react-app is a scaffolding tool and is not in the same category as Umi, next.js, remix, ice, modern.js, and similar frameworks. Scaffolding tools allow quick project setup, suitable for individual projects but insufficient for team use. Once a scaffolding is set up, it becomes difficult to iterate. Additionally, the encapsulation and abstraction provided by scaffolding tools are limited. ### next.js -如果要做 SSR，next.js 是非常好的选择（当然，Umi 也支持 SSR）；而如果只做 CSR，Umi 会是更好的选择。相比之下，Umi 的扩展性会更好；并且 Umi 做了很多更贴地气的功能，比如配置式路由、补丁方案、antd 的接入、微前端、国际化、权限等；同时 Umi 会更稳定，因为他锁了能锁的全部依赖，定期主动更新，某一个子版本的 Umi，不会因为重装依赖之后而跑不起来。 +For SSR (Server-Side Rendering), next.js is an excellent choice (though Umi also supports SSR). If you're only doing CSR (Client-Side Rendering), Umi might be a better option. Umi offers better extensibility, more user-friendly features such as configuration-based routing, patching solutions, integration with antd, micro-frontends, internationalization, permissions, and more. Umi is also more stable, as it locks all possible dependencies, updates them periodically, and won't break after reinstalling dependencies. -### remix +### Remix -Remix 是我非常喜欢的框架，Umi 4 从中
+
+
+## Umi 是什么？
+
+Umi，中文发音为「乌米」，是可扩展的企业级前端应用框架。Umi 以路由为基础的，同时支持配置式路由和约定式路由，保证路由的功能完备，并以此进行功能扩展。然后配以生命周期完善的插件体系，覆盖从源码到构建产物的每个生命周期，支持各种功能扩展和业务需求。
+
+Umi 是蚂蚁集团的底层前端框架，已直接或间接地服务了 10000+ 应用，包括 Java、Node、H5 无线、离线（Hybrid）应用、纯前端 assets 应用、CMS 应用、Electron 应用、Serverless 应用等。他已经很好地服务了我们的内部用户，同时也服务了不少外部用户，包括淘系、飞猪、阿里云、字节、腾讯、口碑、美团等。在 2021 年字节的[调研报告](https://zhuanlan.zhihu.com/p/403206195)中，Umi 是其中 25.33% 开发者的选择。
+
+Umi 有很多非常有意思的特性，比如。
+
+1、**企业级**，在安全性、稳定性、最佳实践、约束能力方面会考虑更多+2、**插件化**，啥都能改，Umi 本身也是由插件构成
+3、**MFSU**，比 Vite 还快的 Webpack 打包方案
+4、基于 React Router 6 的完备路由
+5、默认最快的请求
+6、SSR & SSG
+7、稳定白盒性能好的 ESLint 和 Jest
+8、React 18 的框架级接入
+9、Monorepo 最佳实践
+... + + +## 什么时候不用 Umi？ + +如果你的项目， + +1、需要支持 IE 8 或更低版本的浏览器
+2、需要支持 React 16.8.0 以下的 React
+3、需要跑在 Node 14 以下的环境中
+4、有很强的 webpack 自定义需求和主观意愿
+5、需要选择不同的路由方案
+... + +Umi 可能不适合你。 + + +## 为什么不是？ + +### create-react-app + +create-react-app 是脚手架，和 Umi、next.js、remix、ice、modern.js 等元框架不是同一类型。脚手架可以让我们快速启动项目，对于单一的项目够用，但对于团队而言却不够。因为使用脚手架像泼出去的水，一旦启动，无法迭代。同时脚手架所能做的封装和抽象都非常有限。 + +### next.js + +如果要做 SSR，next.js 是非常好的选择（当然，Umi 也支持 SSR）；而如果只做 CSR，Umi 会是更好的选择。相比之下，Umi 的扩展性会更好；并且 Umi 做了很多更贴地气的功能，比如配置式路由、补丁方案、antd 的接入、微前端、国际化、权限等；同时 Umi 会更稳定，因为他锁了能锁的全部依赖，定期主动更新，某一个子版本的 Umi，不会因为重装依赖之后而跑不起来。 + +### remix + +Remix 是我非常喜欢的框架，Umi 4 从中
-2、插件和插件集
-3、最佳实践
-4、企业级
-5、import all from umi
-6、编译时框架
-7、依赖预打包
-8、默认快
-9、约束与开放
+1. **Technology Convergence** +2. **Plugins and Plugin Collections** +3. **Best Practices** +4. **Enterprise-Grade** +5. **import all from umi** -下面仅介绍 1-5 的 5 点，剩下 6-9 的 4 点在 2022.1.8 的 SEE Conf 中有过详细分享，详见[《SEE Conf: Umi 4 设计思路文字稿》](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ%3D%3D&mid=2247484533&idx=1&sn=9b15a67b88ebc95476fce1798eb49146)。 +The following will cover points 1 to 5, while points 6 to 9 were elaborated in detail during the SEE Conf on January 8, 2022, and can be found in the article [SEE Conf: Umi 4 Design Philosophy Transcript](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ%3D%3D&mid=2247484533&idx=1&sn=9b15a67b88ebc95476fce1798eb49146). -## 技术收敛 +## Technology Convergence
-技术收敛对团队而言尤其重要，他包含两层含义，1）技术栈收敛 2）依赖收敛。技术栈收敛指社区那么多技术栈，每个技术方向都有非常多选择，比如数据流应该就不下 100 种，开发者应该如何选择；收敛了技术栈之后还需要收敛依赖，团队中，开发者的项目不应该有很多细碎的依赖，每一个依赖都附带着升级成本。 +Technology convergence is especially crucial for teams. It involves two aspects: 1) Technology stack convergence and 2) Dependency convergence. Technology stack convergence addresses the multitude of choices within various technology domains. For instance, there are over 100 choices for data flow, making it challenging for developers to choose the best option. After converging on a technology stack, it's necessary to converge on dependencies. In a team, projects should avoid having too many fragmented dependencies, as each one incurs upgrading costs. -我们希望开发者依赖 Umi 之后就无需关心 babel、webpack、postcss、react、react-router 等依赖，而依赖 @umijs/max 之后无需再关心开发中台项目的依赖和技术栈。 +The goal is for developers who depend on Umi to not worry about dependencies like babel, webpack, postcss, react, react-router, etc. Similarly, by depending on `@umijs/max`, developers need not concern themselves with dependencies and technology stacks when developing mid-tier projects. -## 插件和插件集 +## Plugins and Plugin Collections
-Umi 通过提供插件和插件集的机制来满足不同场景和业务的需求。插件是为了扩展一个功能，而插件集是为了扩展一类业务。比如要支持 vue，我们可以有 `@umijs/preset-vue`，包含 vue 相关的构建和运行时；比如要支持 h5 的应用类型，可以有 `@umijs/preset-h5`，把 h5 相关的功能集合到一起。 +Umi provides a mechanism of plugins and plugin collections to cater to different scenarios and business requirements. Plugins extend specific functionalities, while plugin collections extend categories of business requirements. For instance, to support Vue, there could be `@umijs/preset-vue`, including build and runtime functionalities for Vue. Similarly, `@umijs/preset-h5` could bundle h5-related features together for supporting h5 applications. -如果要类比，插件集和 babel 的 preset，以及 eslint 的 config 都类似。 +Analogously, plugin collections resemble babel presets and eslint configs. -## 最佳实践 +## Best Practices -最佳实践是我们认为做某件事当下最好的方式，主语是我们，所以会相对比较主观。比如路由、补丁方案、数据流、请求、权限、国际化、微前端、icons 使用、编辑器使用、图表、表单等方面，Umi 都会给出我们的最佳实践。这些最佳实践大部分来自蚂蚁集团内部的实践和讨论，也有部分来自社区。他们是主观和时间敏感的，所以可能会有相对比较频繁的迭代。 +Best practices reflect our current understanding of the best way to do something. Since the subject is "we," best practices are relatively subjective. Umi provides best practices for aspects like routing, patching solutions, data flow, requests, permissions, internationalization, micro-frontends, icon usage, editor usage, charts, forms, etc. Many of these practices are derived from practices and discussions within Ant Group, as well as from the community. These practices are subjective and time-sensitive, leading to frequent iterations. -之所以需要最佳实践，1）是社区太多方案选择，2）是很多人没有选择的精力和经验甚至意愿。尤其是针对非专业的前端，有选择比没选择好，不管这个选择如何。 +Best practices are essential due to the overwhelming number of choices in the community and the lack of time, experience, or willingness of many developers to choose. Especially for non-professional developers, having a choice is better than not having one, regardless of the choice itself. -## 企业级 +## Enterprise-Grade -npm 社区「世风日下」，涉政包、恶意包、广告求职包频出，所以如何确保不会「睡一觉醒来项目挂了」是面对企业生成提供服务的框架绕不开的一个点。 +The npm ecosystem is somewhat chaotic, with issues like politically sensitive packages, malicious packages, and job advertisement packages cropping up frequently. Ensuring that projects won't "break overnight" is an essential aspect of creating a framework meant to serve enterprises. -Umi 通过写死版本、依赖预打包、通过 eslint hack 锁定 eslint 依赖，通过配置锁定 babel 补丁依赖等方式，让 Umi 不会在你重装 node_modules 之后就挂掉，并以此来实现「十年后依旧可用」。 +Umi tackles this by fixing versions, pre-bundling dependencies, locking eslint dependencies using eslint hacks, and locking babel patch dependencies through configuration. These strategies ensure that Umi won't break after reinstalling node_modules, contributing to its longevity. ## import all from umi -很多人可能都第一次听到。import all from umi 意思是所有 import 都来自 `umi`。比如 dva 不是 `import { connect } from 'dva'`，而是 `import { connect } from 'umi'`，从 umi 中导出。导出的方法不仅来自 umi 自身，还来自 umi 插件。 +This feature might be unfamiliar to many. "import all from umi" means that all imports come from `umi`. For example, instead of `import { connect } from 'dva'`, it's `import { connect } from 'umi'`. The exported methods not only come from Umi itself but also from Umi plugins. -这是两年前 Umi 3 加的功能，最近发现 Remix、prisma、vitekit 等框架和工具都有类似实现。 +This feature was introduced in Umi 3 two years ago. Recently, similar implementations have been adopted by frameworks and tools like Remix, prisma, and vitekit. ```ts -// 大量插件为 umi 提供额外导出内容 +// Many plugins provide additional exports from umi import { connect, useModel, useIntl, useRequest, MicroApp, ... } from 'umi'; ``` -这带来的好处是。通过 Umi 将大量依赖管理起来，用户无需手动安装；同时开发者在代码中也会少很多 import 语句。 +The benefit is that many dependencies are managed through Umi, reducing the need for manual installations. Additionally, developers will have fewer import statements in their code. \ No newline at end of file diff --git a/docs/docs/introduce/philosophy.zh-CN.md b/docs/docs/introduce/philosophy.zh-CN.md new file mode 100644 index 000000000000..cf7acaff377e --- /dev/null +++ b/docs/docs/introduce/philosophy.zh-CN.md @@ -0,0 +1,62 @@ +# 设计思路 + +Umi 从 1 做到 4，试错了很多东西，也试对了不少。这些试对的点我们逐渐沉淀下来，就成为指引我们如何做好企业级框架的思路。 + +设计思路包括， + +1、技术收敛
+2、插件和插件集
+3、最佳实践
+4、企业级
+5、import all from umi
+6、编译时框架
+7、依赖预打包
+8、默认快
+9、约束与开放
+ +下面仅介绍 1-5 的 5 点，剩下 6-9 的 4 点在 2022.1.8 的 SEE Conf 中有过详细分享，详见[《SEE Conf: Umi 4 设计思路文字稿》](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ%3D%3D&mid=2247484533&idx=1&sn=9b15a67b88ebc95476fce1798eb49146)。 + +## 技术收敛 + +
+
++ +技术收敛对团队而言尤其重要，他包含两层含义，1）技术栈收敛 2）依赖收敛。技术栈收敛指社区那么多技术栈，每个技术方向都有非常多选择，比如数据流应该就不下 100 种，开发者应该如何选择；收敛了技术栈之后还需要收敛依赖，团队中，开发者的项目不应该有很多细碎的依赖，每一个依赖都附带着升级成本。 + +我们希望开发者依赖 Umi 之后就无需关心 babel、webpack、postcss、react、react-router 等依赖，而依赖 @umijs/max 之后无需再关心开发中台项目的依赖和技术栈。 + +## 插件和插件集 + +
+
++ +Umi 通过提供插件和插件集的机制来满足不同场景和业务的需求。插件是为了扩展一个功能，而插件集是为了扩展一类业务。比如要支持 vue，我们可以有 `@umijs/preset-vue`，包含 vue 相关的构建和运行时；比如要支持 h5 的应用类型，可以有 `@umijs/preset-h5`，把 h5 相关的功能集合到一起。 + +如果要类比，插件集和 babel 的 preset，以及 eslint 的 config 都类似。 + +## 最佳实践 + +最佳实践是我们认为做某件事当下最好的方式，主语是我们，所以会相对比较主观。比如路由、补丁方案、数据流、请求、权限、国际化、微前端、icons 使用、编辑器使用、图表、表单等方面，Umi 都会给出我们的最佳实践。这些最佳实践大部分来自蚂蚁集团内部的实践和讨论，也有部分来自社区。他们是主观和时间敏感的，所以可能会有相对比较频繁的迭代。 + +之所以需要最佳实践，1）是社区太多方案选择，2）是很多人没有选择的精力和经验甚至意愿。尤其是针对非专业的前端，有选择比没选择好，不管这个选择如何。 + +## 企业级 + +npm 社区「世风日下」，涉政包、恶意包、广告求职包频出，所以如何确保不会「睡一觉醒来项目挂了」是面对企业生成提供服务的框架绕不开的一个点。 + +Umi 通过写死版本、依赖预打包、通过 eslint hack 锁定 eslint 依赖，通过配置锁定 babel 补丁依赖等方式，让 Umi 不会在你重装 node_modules 之后就挂掉，并以此来实现「十年后依旧可用」。 + +## import all from umi + +很多人可能都第一次听到。import all from umi 意思是所有 import 都来自 `umi`。比如 dva 不是 `import { connect } from 'dva'`，而是 `import { connect } from 'umi'`，从 umi 中导出。导出的方法不仅来自 umi 自身，还来自 umi 插件。 + +这是两年前 Umi 3 加的功能，最近发现 Remix、prisma、vitekit 等框架和工具都有类似实现。 + +```ts +// 大量插件为 umi 提供额外导出内容 +import { connect, useModel, useIntl, useRequest, MicroApp, ... } from 'umi'; +``` + +这带来的好处是。通过 Umi 将大量依赖管理起来，用户无需手动安装；同时开发者在代码中也会少很多 import 语句。 diff --git a/docs/docs/introduce/upgrade-to-umi-4.md b/docs/docs/introduce/upgrade-to-umi-4.md index d955a54c01ee..bc1ed2aa7d60 100644 --- a/docs/docs/introduce/upgrade-to-umi-4.md +++ b/docs/docs/introduce/upgrade-to-umi-4.md @@ -1,20 +1,20 @@ -# 升级到 Umi 4 +# Upgrading to Umi 4 -## 升级步骤 +## Upgrade Steps -升级到 Umi 4 只需要简单的几步操作就能完成，简单的描述整个过程就是 - “重装依赖，修改配置”： +Upgrading to Umi 4 can be completed with just a few simple steps, which can be summarized as "reinstall dependencies, modify configurations": -1. **依赖处理** -2. **启动命令** -3. **非官方插件升级** -4. **配置层迁移** -5. **代码层修改** +1. **Dependency Management** +2. **Update Commands** +3. **Unofficial Plugin Upgrades** +4. **Configuration Migration** +5. **Code-Level Changes** -### 依赖处理 +### Dependency Management -项目的 `package.json` 需要升级 Umi，并替换掉对应的 Umi 插件。 +In your project's `package.json`, you need to upgrade Umi and replace corresponding Umi plugins. -如果 `umi@3` 中是使用 `umi` + `@umijs/preset-react` 的组合进行开发的，那可以直接使用新版的 `max` 直接升级。 +If your project was developed using the combination of `umi` + `@umijs/preset-react` in `umi@3`, you can directly upgrade to the new version using `@umijs/max`. ```diff { @@ -26,13 +26,13 @@ } ``` -删除 `node_module`，执行下 `npm install` 重装依赖。 +Delete your `node_modules` folder and then run `npm install` to reinstall the dependencies. -### 启动命令 +### Update Commands -如果使用了 `@umijs/max` 可以使用 `max` 命令来替换 `umi`，`max dev`，`max build` 等 +If you are using `@umijs/max`, you can replace the `umi` commands with `max` commands, such as `max dev`, `max build`, etc. -`umi@4` 将一些项目前置操作放到了 `setup` 命令中，如 umi@3 中的 `umi g tmp` 等命令，需要使用 `umi setup` 替换 +`umi@4` has moved some project initialization operations to the `setup` command, similar to the `umi g tmp` command in `umi@3`, which should be replaced with `umi setup`. `package.json` @@ -49,68 +49,55 @@ } ``` -### 非官方插件升级 +### Unofficial Plugin Upgrades -在项目中用到的一些非 Umi 官方提供的 Umi 插件，请联系相关作者及时根据[插件 api 变动](../api/plugin-api)。 +For some unofficial Umi plugins used in your project, please contact the respective authors to update them based on the [plugin API changes](../api/plugin-api). -项目迁移时可先关闭对相应插件包的引用，如临时注释配置中的 `plugins`，移除 package.json 中以 `umi-plugin-`，`@umijs/plugin-` 和 `@umijs/preset-` 开头的所有依赖。 +During project migration, you can temporarily comment out the references to the corresponding plugin packages in your configurations. Remove dependencies starting with `umi-plugin-`, `@umijs/plugin-`, and `@umijs/preset-` from your `package.json`. -### 配置层迁移 +### Configuration Migration -**max 提供的的配置项**如下 `config/config.ts` ： +**max's provided configuration items** in `config/config.ts`: -> 需要注意的是，之前的一些插件约定开启的规则，在 `umi@4` 中几乎都要通过显式的配置开启，因为希望在 `umi@4` 中有更少的“黑盒”。 +> Note that some previously implicitly enabled rules in certain plugins must now be explicitly configured in `umi@4`, as there is a desire for fewer "black boxes" in `umi@4`. ```typescript -import { defineConfig, utils } from 'umi'; +import { defineConfig } from 'umi'; export default defineConfig({ - model: {}, - antd: {}, - request: {}, - initialState: {}, + fastRefresh: true, + dva: {}, mock: { include: ['src/pages/**/_mock.ts'], }, - dva: {}, layout: { - // https://umijs.org/docs/max/layout-menu#构建时配置 title: 'UmiJS', locale: true, }, - // https://umijs.org/zh-CN/plugins/plugin-locale locale: { - // default zh-CN default: 'zh-CN', antd: true, - // default true, when it is true, will use `navigator.language` overwrite default baseNavigator: true, }, }); ``` -**存在差异的配置项**如下 `config/config.ts` ： +**Configuration items with differences** in `config/config.ts`: ```typescript -import { defineConfig, utils } from 'umi'; +import { defineConfig } from 'umi'; export default defineConfig({ -- fastRefresh: {}, -+ fastRefresh: true, - dva: { - // 不再支持 hmr 这个参数 -- hmr: true, - }, -// 默认 webpack5 -- webpack5: {}, -}) + fastRefresh: true, // Previously: fastRefresh: {} + dva: {}, // Previous hmr parameter is no longer supported +}); ``` -### 代码层修改 +### Code-Level Changes -Umi 4 中将 `react-router@5` 升级到 `react-router@6`，所以路由相关的一些 api 存在着使用上的差异。 +Umi 4 upgrades `react-router@5` to `react-router@6`, so there are some usage differences in the routing-related APIs. -props 默认为空对象，以下属性都不能直接从 props 中取出  +Props are now empty objects, and the following properties cannot be directly accessed from props:  #### children @@ -119,9 +106,9 @@ import { Outlet } from 'umi';
+- { props.children }
++
+ );
+}
+```
+
+使用了 `React.cloneElement` 方式渲染的路由组件改造，示例
+
+```diff
+import React from 'react';
++ import { Outlet } from 'umi';
+
+export default function RouteComponent(props) {
+ return (
+
+- { React.cloneElement(props.children, { someProp: 'p1' }) }
++
+ );
+}
+```
+
+组件改成从 `useOutletContext` 取值
+
+```diff
+import React from 'react';
++ import { useOutletContext } from 'umi';
+
+- export function Comp(props){
++ export function Comp() {
++ const props = useOutletContext();
+
+ return props.someProp;
+}
+```
+
+#### history
+
+```diff
++ import { history } from 'umi';
+export default function Page(props) {
+ return (
+ {
+- props.history.push('list');
++ history.push('list');
+ }}>
+
+ );
+}
+```
+
+#### location
+
+> 建议组件或 hooks 里用 useLocation 取，其他地方就用 window.location 获取。
+
+```diff
+export default function Page(props) {
++ const { location } = window;
+ return (
+
+- { props.location }
++ { location }
+
+ );
+}
+```
+
+或者
+
+```diff
++ import { useLocation } from 'umi';
+export default function Page(props) {
++ let location = useLocation();
+ return (
+
+- { props.location }
++ { location }
+
+ );
+}
+```
+
+#### match
+
+```diff
++ import { useMatch } from 'umi';
+export default function Page(props) {
++ const match = useMatch({ path: 'list/search/:type' });
+ return (
+
+- { props.match }
++ { match }
+
+ );
+}
+```
+
+在 class component 组件中的使用方式:
+
+```diff
+import { matchPath } from 'umi';
+class Page extends Component {
++ match = matchPath({ path: 'list/search/:type' }, window.location.pathname);
+ state = {}
+ render() {
+ return (
+
+- {this.props.match.type}
++ {this.match.type}
+
+ )
+ }
+}
+```
+更多 `Umi` 相关 [api](https://umijs.org/docs/api/api)
+
+需要注意 match 数据的差异：
+
+```
+// match v5
+isExact: true
+params: {}
+path: "/users/abc"
+url: "/users/abc"
+
+// match v6
+params:{ }
+pathname: "/list/search/articles"
+pathnameBase: "/list/search/articles"
+pattern: {path: 'list/search/:type'}
+```
+
+更多改动和 api 变更，请查阅 [react-router@6](https://reactrouter.com/docs/en/v6/api#uselocation)
+
+完成以上操作后，执行下 `max dev`，访问 [http://localhost:8000](http://localhost:8000)，请验证所有功能都符合预期。
+
+如果你的项目无法正常启动，你可能还需要做如下操作：
+
+## 配置变更
+
+TODO
+
+## FAQ
+
+### location 中的 query 找不到？
+
+location 中的 query 不再支持了，后续推荐用 [search](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
+
+```diff
+- const { query } = history.location;
++ import { parse } from 'query-string';
++ const query = parse(history.location.search);
+```
+
+### \*.d 文件找不到，或者它的引用找不到
+
+在 `umi@3` 中通过 `import` 会自动找到同名的 `.d.ts` 文件，如：
+
+`import { ButtonType } from './button';`
+
+如果存在 `.button.d.ts` 文件，在 `umi@3` 中会正确执行，但是在 umi@4 中会发生报错，你可能需要更加规范的引用类型。
+
+```diff
+- import { ButtonType } from './button';
++ import type { ButtonType } from './button.d';
+```
diff --git a/docs/docs/max/access.md b/docs/docs/max/access.md
index 3d949dcc988b..4dd8dbab85c9 100644
--- a/docs/docs/max/access.md
+++ b/docs/docs/max/access.md
@@ -1,20 +1,20 @@
-# 权限
+# Permissions
-## 启用方式
+## Activation Method
-配置开启。同时需要 `src/access.ts` 提供权限配置。
+Enable configuration. Also, `src/access.ts` needs to provide permission configuration.
```ts
export default {
access: {},
- // access 插件依赖 initial State 所以需要同时开启
+ // The access plugin depends on initial State so both need to be enabled simultaneously
initialState: {},
};
```
-## 介绍
+## Introduction
-我们约定了 `src/access.ts` 为我们的权限定义文件，该文件需要默认导出一个方法，导出的方法会在项目初始化时被执行。该方法需要返回一个对象，对象的每一个值就对应定义了一条权限。如下所示：
+We have designated `src/access.ts` as our permission definition file. This file needs to export a default function, and the exported function will be executed during project initialization. This function needs to return an object, where each value corresponds to a defined permission. Here's how it looks:
```js
// src/access.ts
@@ -31,34 +31,34 @@ export default function (initialState) {
}
```
-其中 `initialState` 是通过初始化状态插件 `initial-state` 提供的数据，你可以使用该数据来初始化你的用户权限。
+Here, `initialState` is the data provided by the initialization state plugin `initial-state`. You can use this data to initialize user permissions.
-## 配置
+## Configuration
-### 扩展的路由配置
+### Extended Route Configuration
-配合 [layout](./layout-menu) 插件你可以很简单的实现针对某些页面的权限控制。如下所示，只有拥有了 canReadPageA （在 `src/access.ts` 中定义）权限，用户才可以访问该页面。否则会默认渲染 Layout 插件内置的权限错误页面。
+In conjunction with the [layout](./layout-menu) plugin, you can easily implement permission control for certain pages. As shown below, only users with the `canReadPageA` permission (defined in `src/access.ts`) can access this page. Otherwise, the built-in permission error page from the Layout plugin will be rendered by default.
```ts
export const routes = [
{
path: '/pageA',
component: 'PageA',
- access: 'canReadPageA', // 权限定义返回值的某个 key
+ access: 'canReadPageA', // The key corresponding to a value returned by the permission definition
},
];
```
-### 自定义权限页面配置
+### Custom Permission Page Configuration
-上面说到默认渲染 Layout 插件内置的权限错误页面，如果想配置自定义权限页面需要在 `src/app.tsx` 中定义。
+As mentioned earlier, by default, the built-in permission error page from the Layout plugin will be rendered. If you want to configure a custom permission page, you need to define it in `src/app.tsx`.
```tsx
export const layout: RunTimeLayoutConfig = () => {
return {
- // 自定义 403 页面
+ // Custom 403 page
unAccessible: 'unAccessible'
,
- // 自定义 404 页面
+ // Custom 404 page
noFound: 'noFound'
,
};
};
@@ -68,13 +68,13 @@ export const layout: RunTimeLayoutConfig = () => {
- Type: `string`
-对应的权限名称。
+Corresponds to the permission name.
## API
### useAccess
-我们提供了一个 Hooks 用于在组件中获取权限相关信息，如下所示：
+We provide a hook for components to access permission-related information, as shown below:
```js
import React from 'react';
@@ -85,7 +85,7 @@ const PageA = (props) => {
const access = useAccess();
if (access.canReadFoo) {
- // 如果可以读取 Foo，则...
+ // If can read Foo, then...
}
return <>TODO;
@@ -94,31 +94,31 @@ const PageA = (props) => {
export default PageA;
```
-配合 `Access` 组件可以很简单的实现页面内的元素的权限控制。
+Combined with the `Access` component, you can easily control the permissions of elements within a page.
### Access
-可以在业务组件中使用插件提供的 React hook `useAccess` 以及组件 `'unAccessible'
,
+ // 自定义 404 页面
+ noFound: 'noFound'
,
+ };
+};
+```
+
+#### access
+
+- Type: `string`
+
+对应的权限名称。
+
+## API
+
+### useAccess
+
+我们提供了一个 Hooks 用于在组件中获取权限相关信息，如下所示：
+
+```js
+import React from 'react';
+import { useAccess } from 'umi';
+
+const PageA = (props) => {
+ const { foo } = props;
+ const access = useAccess();
+
+ if (access.canReadFoo) {
+ // 如果可以读取 Foo，则...
+ }
+
+ return <>TODO;
+};
+
+export default PageA;
+```
+
+配合 `Access` 组件可以很简单的实现页面内的元素的权限控制。
+
+### Access
+
+可以在业务组件中使用插件提供的 React hook `useAccess` 以及组件 `
+ Can not read foo content.
}
+ >
+ Foo content.
+ {user.username}
}
+ {loading ? <> : {user.username}
}
);
}
```
-其中，`useModel()` 方法传入的参数为 Model 的**命名空间**。
+In the `useModel()` method, the parameter provided is the Model's **namespace**.
{user.username}
}
+ );
+}
+```
+
+其中，`useModel()` 方法传入的参数为 Model 的**命名空间**。
+
+
+
+
+
+ );
+};
+```
+
+上面的组件并不关心计数器 Model 中的 `counter` 值，只需要使用 Model 提供的 `increment()` 和 `decrement()` 方法。于是我们传入了一个函数作为 `useModel()` 方法的第二个参数，该函数的返回值将作为 `useModel()` 方法的返回值。
+
+这样，我们过滤掉了 `counter` 这一频繁变化的值，避免了组件重复渲染带来的性能损失。
+
+## 全局初始状态
+
+`@umi/max` 内置了**全局初始状态管理**[插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/initial-state.ts)，允许您快速构建并在组件内获取 Umi 项目全局的初始状态。
+
+全局初始状态是一种特殊的 Model。
+
+全局初始状态在整个 Umi 项目的最开始创建。编写 `src/app.ts` 的导出方法 `getInitialState()`，其返回值将成为全局初始状态。例如：
+
+```ts
+// src/app.ts
+import { fetchInitialData } from '@/services/initial';
+
+export async function getInitialState() {
+ const initialData = await fetchInitialData();
+ return initialData;
+}
+```
+
+现在，各种插件和您定义的组件都可以通过 `useModel('@@initialState')` 直接获取到这份全局的初始状态，如下所示：
+
+```tsx
+import { useModel } from 'umi';
+
+export default function Page() {
+ const { initialState, loading, error, refresh, setInitialState } =
+ useModel('@@initialState');
+ return <>{initialState};
+};
+```
+
+| 对象属性 | 类型 | 介绍 |
+| --- | --- | --- |
+| `initialState` | `any` | 导出的 `getInitialState()` 方法的返回值 |
+| `loading` | `boolean` | `getInitialState()` 或 `refresh()` 方法是否正在进行中。在首次获取到初始状态前，页面其他部分的渲染都会**被阻止** |
+| `error` | `Error` | 如果导出的 `getInitialState()` 方法运行时报错，报错的错误信息 |
+| `refresh` | `() => void` | 重新执行 `getInitialState` 方法，并获取新的全局初始状态 |
+| `setInitialState` | `(state: any) => void` | 手动设置 `initialState` 的值，手动设置完毕会将 `loading` 置为 `false` |
+
+## Qiankun 父子应用间通信
+
+`@umi/max` 内置了 **Qiankun 微前端**[插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/qiankun.ts)，当使用数据流插件时，它允许微应用通过 `useModel('@@qiankunStateFromMaster')` 方法获取父应用传递给子应用的数据 Model，进而实现父子应用间的通信。
+
+具体的使用方法请查阅[微前端的父子应用通信章节](./micro-frontend#父子应用通信)。
+
+## API
+
+### `useModel`
+
+`useModel()` 是一个钩子函数，提供了使用 Model 的能力。它接受两个参数：
+
+| 参数 | 类型 | 介绍 |
+| --- | --- | --- |
+| `namespace` | `String` | Model 文件的命名空间 |
+| `updater` | `(model: any) => any` | 可选参数。传入一个函数，函数的返回值为当前组件中需要使用到的 Model 状态或数据，并作为 `useModel()` 方法的返回值。对优化组件性能具有重要意义。 |
+
+```tsx
+// src/components/AdminInfo/index.tsx
+import { useModel } from 'umi';
+
+export default function Page() {
+ const { user, fetchUser } = useModel('adminModel', (model) => ({
+ user: model.admin,
+ fetchUser: model.fetchAdmin,
+ }));
+
+ return <>hello;
+};
+```
diff --git a/docs/docs/max/dva.md b/docs/docs/max/dva.md
index 53dda60b92d9..8b3be0fe6e5f 100644
--- a/docs/docs/max/dva.md
+++ b/docs/docs/max/dva.md
@@ -1,34 +1,34 @@
# dva
-## 为什么需要状态管理
+## Why State Management is Needed
-React 的组件只是通过 jsx 以及样式按照 state 构建最终的 UI，真正将页面动态化的实际上是 state 的变化实现的。对于简单的前端应用，在组件中通过组件自身的 state 加上父组件通过 props 状态的传递就能够满足应用数据管理的需求。但是当应用膨胀到一定程度后就会导致组件内维护的状态非常的复杂，加上组件之间状态的传递，很容易导致数据管理混乱。很小的修改都可能导致难以预料的副作用。
+React components construct the final UI based on the state using JSX and styles. The dynamic behavior of the page is achieved through changes in the state. For simple frontend applications, managing application data with the component's own state along with state passing through props from parent components might suffice. However, as the application grows, maintaining complex state within components, along with state passing between components, can lead to data management issues. Even small modifications can result in unforeseen side effects.
-所以我们需要纯净的 UI 组件，除了渲染逻辑，不再杂糅其他（比如网络请求）。这样我们就要想办法把与渲染无关的业务逻辑抽离出来，形成独立的层（在 Umi 中就是 `src/models` 文件夹中所管理的 model ）去管理。让所有组件降级为`无状态组件`，仅仅依赖 props 渲染。这样 UI 层面就不需关心渲染无关的逻辑，专注做 UI 渲染。（注：这里说的组件主要是指 page 下面的页面组件，对于 component 下的组件本身就应该是比较通用的组件，更应该仅仅依赖 props 渲染，它们也不应该有 model，数据应该通过在页面组件中通过 props 传递过去）。
+Thus, we need pure UI components. Apart from rendering logic, they shouldn't include other concerns (like network requests). Therefore, we need to extract business logic unrelated to rendering and form independent layers (such as the `src/models` folder managed by Umi) to manage it. This approach reduces components to "stateless components," relying solely on props for rendering. As a result, the UI layer doesn't need to deal with non-rendering logic, focusing solely on UI rendering. (Note: The term "component" mainly refers to page components under the `src/pages` directory. For components under the `src/components` directory, they should be general-purpose components, relying solely on props for rendering. They shouldn't have models, and data should be passed through props from page components.)
-## 简单的数据共享
+## Simple Data Sharing
-对于简单的应用，不需要复杂的数据流，只需要一些简单的数据共享。我们推荐使用 [中台最佳实践简易数据流](./data-flow) 。
+For simple applications that don't require complex data flows, we recommend using the [best practice for simple data flow in the middle-end](./data-flow).
-## Umi 如何管理状态
+## How Umi Manages State
-如下图所示，Umi 内置了 [Dva](https://dvajs.com) 提供了一套状态管理方案：
+As shown in the diagram below, Umi includes [Dva](https://dvajs.com) as an integrated state management solution:
-
+
-数据统一在 `src/models` 中的 model 管理，组件内尽可能的不去维护数据，而是通过 connect 去关联 model 中的数据。页面有操作的时候则触发一个 action 去请求后端接口以及修改 model 中的数据，将业务逻辑分离到一个环形的闭环中，使得数据在其中单向流动。让应用更好维护。这样的思想最初来源于 Facebook 的 [flux](http://facebook.github.io/flux/)。接下来我们来具体看看如何在 Umi 中实现这样的逻辑。
+Data is managed centrally in models defined in the `src/models` directory. Components ideally don't need to manage data; instead, they can use the `connect` function to access data from the model. When actions are triggered on pages, they request backend APIs and modify the data in the model, creating a circular and closed data flow. This approach is inspired by Facebook's [Flux](http://facebook.github.io/flux/) architecture. Let's see how to implement this logic in Umi.
-### 配置 dva
+### Configuring Dva
-首先你需要配置 `dva: {}` 打开 Umi 内置的 dva 插件。
+First, you need to configure `dva: {}` to enable Umi's built-in Dva plugin.
-### 添加 model
+### Adding Models
-Umi 会默认将 `src/models` 下的 model 定义自动挂载，你只需要在 model 文件夹中新建文件即可新增一个 model 用来管理组件状态。
+Umi automatically mounts models defined under `src/models`. You only need to create files in the `models` folder to add new models for managing component states.
-在 2.0 后，为了更好的支持移动端的 H5 项目的按需加载和大型项目的 model 组织，对于某个 page 文件夹下面的 model 我们也会默认挂载，具体结构可以参考[目录结构说明](../guides/directory-structure)。但是需要注意的是 model 的 namespace 是全局的，你仍然需要保证你的 namesapce 唯一（默认是文件名）。对于大部分的项目，我们推荐统一放到 model 中进行管理即可，不需要使用该功能。
+Starting from Umi 2.0, to better support on-demand loading in mobile H5 projects and organize models for large projects, models under a specific page folder will also be automatically mounted. You can refer to the [directory structure guide](../guides/directory-structure) for the specific structure. However, note that the namespace of the model is global, so you still need to ensure that your namespace is unique (by default, it's the same as the filename). For most projects, we recommend managing models centrally in the `models` folder, and you don't need to use this feature.
-model 的写法参考如下示例：
+Here's an example of a model:
```js
import { queryUsers, queryUser } from '../../services/user';
@@ -61,11 +61,11 @@ export default {
};
```
-### 把组件和 model connect 在一起
+### Connecting Components and Models
-新建完成 model 之后你就可以在组件中通过 ES6 的 [Decorator](http://es6.ruanyifeng.com/#docs/decorator) 方便的把 model 和组件 connect 到一起。然后你就可以在组件中通过`this.props.[modelName]`的方式来访问 model 中的数据了。（在对应的 model 中，默认 namespace 即为文件名）
+After creating a model, you can use ES6 decorators to conveniently connect the model to a component. Then, you can access data from the model through `this.props.[modelName]` (where modelName corresponds to the model's namespace, by default, it's the filename).
-组件如下示例：
+Here's an example component:
```javascript
import React, { Component } from 'react';
@@ -78,6 +78,7 @@ class UserInfo extends Component {
constructor(props) {
super(props);
}
+
render() {
return {this.props.user.name}
;
}
@@ -86,9 +87,9 @@ class UserInfo extends Component {
export default UserInfo;
```
-### 在组件中 dispatch 事件
+### Dispatching Events in Components
-connect 方法同时也会添加 `dispatch` 到 `this.props` 上，你可以在用户触发某个事件的时候调用它来触发 model 中的 effects 或者 reducer 来修改 model 中的数据。如下所示：
+The `connect` function adds the `dispatch` method to `this.props`, which you can use to trigger actions in the model. For instance:
```javascript
import React, { Component } from 'react';
@@ -119,26 +120,26 @@ class UserInfo extends Component {
export default UserInfo;
```
-### 修改数据
+### Modifying Data
-dispatch 一个 action 之后会按照 action 中的 type 找到定义在 model 中的一个 effect 或者 reducer。
+After dispatching an action, the corresponding effect or reducer defined in the model will be executed based on the action's type.
-如果是 effect，那么可以去请求后端数据，然后再触发一个 reducer 来修改数据。通过 reducer 修改数据之后组件便会按照最新的数据更新，至此，一次数据的流动就结束了。
+If it's an effect, you can make backend requests and then trigger a reducer to modify data in the model. After data is modified through a reducer, the component updates based on the latest data. This completes the unidirectional data flow.
-## 文档
+## Documentation
-### model 定义
+### Model Definition
-一个 model 中可以定义如下几个部分：
+A model can have the following parts:
-- namespace # model 的命名空间，唯一标识一个 model，如果与文件名相同可以省略不写
-- state # model 中的数据
-- effects # 异步 action，用来发送异步请求
-- reducers # 同步 action，用来修改 state
+- `namespace`: The model's namespace, a unique identifier for the model. It's often the same as the filename and can be omitted if they match.
+- `state`: The data within the model.
+- `effects`: Asynchronous actions used to communicate with the backend.
+- `reducers`: Synchronous actions used to modify the state.
-### connect
+### Connect
-`connect` 的是用来将 model 和组件关联在一起的，它会将相关数据和 `dispatch` 添加到组件的 `props` 中。如下所示：
+The `connect` function establishes the connection between a model and a component. It adds relevant data and the `dispatch` method to the component's props. Here's an example:
```jsx
import React, { Component } from 'react';
@@ -147,7 +148,7 @@ import { connect } from 'umi';
const mapModelToProps = allModels => {
return {
test: 'hello world',
- // props you want connect to Component
+ // props you want to connect to the Component
};
};
@@ -161,19 +162,19 @@ class UserInfo extends Component {
export default UserInfo;
```
-推荐通过注解的方式调用 connect，它等同于 `export default connect(mapModelToProps)(UserInfo);`。connect 接收一个参数，是一个方法，在该方法中你接收到所有的 model 信息，需要返回要添加到 props 上的对象。在上面的例子中你就可以通过 `this.props.test` 得到 `hello world` 的字符串了。
+It is recommended to call connect via annotation, which is equivalent to `export default connect(mapModelToProps)(UserInfo);`. connect receives a parameter, which is a method in which you receive all model information and need to return the object to be added to props. In the above example, you can get the string of `hello world` through `this.props.test`.
-### dispatch
+### Dispatch
-在使用 `connect` 将组件和 model 关联在一起的同时框架也会添加一个 `this.props.dispatch` 的方法，通过该方法你可以触发一个 action 到 model 中。如下所示：
+The `connect` function not only connects the model to the component but also adds the `this.props.dispatch` method. This method allows you to trigger an action in the model. For example:
```jsx
-render () {
+render() {
return {
- this.props.dispacth({
+ this.props.dispatch({
type: 'modelnamespace/actionname',
sometestdata: 'xxx',
- othertestata: {},
+ othertestdata: {},
}).then(() => {
// it will return a promise
// action success
@@ -182,15 +183,15 @@ render () {
}
```
-通过 `this.props.dispatch` 触发的 action 分为 effect 和 reducer 两类，下面是对他们的更多细节说明。
+Actions triggered using `this.props.dispatch` can be effects or reducers. Let's explore more about them.
### Reducer
-reducer 是一个函数，用来处理修改数据的逻辑（同步，不能请求后端）。接受 state 和 action，返回老的或新的 state 。即：`(state, action) => state`。
+A reducer is a function responsible for modifying data (synchronously, without backend requests). It takes `state` and `action` as arguments and returns the modified state: `(state, action) => state`.
-#### 增删改
+#### Adding, Removing, and Updating
-以 todos 为例。
+Consider the example of managing todos:
```javascript
exports default {
@@ -216,9 +217,9 @@ exports default {
};
```
-#### 嵌套数据的增删改
+#### Modifying Nested Data
-建议最多一层嵌套，以保持 state 的扁平化，深层嵌套会让 reducer 很难写和难以维护。
+It's recommended to have at most one level of nesting to keep the state flat. Deep nesting can lead to complex reducer logic and maintenance challenges.
```javascript
app.model({
@@ -236,7 +237,7 @@ app.model({
});
```
-下面是深层嵌套的例子，应尽量避免。
+The following example involves deep nesting, which should be avoided as much as possible:
```javascript
app.model({
@@ -262,9 +263,9 @@ app.model({
### Effect
-effects 是定义在 model 中的。它也是一种类型的 action，主要用于和后端的异步通讯。通过 effects 请求后端发送和接收必要的数据之后可以通过 put 方法再次发送一个 reducer 来修改数据。
+Effects are defined within models and represent a type of action primarily used for asynchronous communication with the backend. After triggering an effect and handling asynchronous logic, you can use the `put` method to trigger a reducer and modify the model's data.
-effect 通过 ES6 中 [Generator 函数](http://es6.ruanyifeng.com/#docs/generator) 来支持通过顺序的代码实现异步的请求，示例如下：
+Effects use ES6 generator functions to facilitate asynchronous logic. Here's an example:
```javascript
export default {
@@ -278,13 +279,13 @@ export default {
};
```
-effects 中定义的 action 都必须是通过 `*` 定义的 Generator 函数，然后在函数中通过关键字 `yield` 来触发异步逻辑。
+Actions defined in the `effects` section must be generator functions declared with `*`, where asynchronous logic is handled using the `yield` keyword.
#### Effects
##### put
-用于触发 action 。
+Used to trigger an action.
```javascript
yield put({ type: 'todos/add', payload: 'Learn Dva' });
@@ -292,7 +293,7 @@ yield put({ type: 'todos/add', payload: 'Learn Dva' });
##### call
-用于调用异步逻辑，支持 promise 。
+Used to invoke asynchronous logic, supports promises.
```javascript
const result = yield call(fetch, '/todos');
@@ -300,38 +301,38 @@ const result = yield call(fetch, '/todos');
##### select
-用于从 state 里获取数据。
+Used to fetch data from the state.
```javascript
const todos = yield select(state => state.todos);
```
-### loading
+### Loading
-框架会默认添加一个命名空间为 loading 的 model，该 model 包含 effects 异步加载 loading 的相关信息，它的 state 格式如下：
+Umi automatically adds a global `loading` namespace model that contains information about loading states related to effects. Its state structure is as follows:
```js
{
- global: Boolean, // 是否真正有异步请求发送中
+ global: Boolean, // Whether any asynchronous requests are being sent
models: {
- [modelnamespace]: Boolean, // 具体每个 model 的加载情况
+ [modelnamespace]: Boolean, // Loading status for specific models
},
effects: {
- [modelnamespace/effectname]: Boolean, // 具体每个 effect 的加载情况
+ [modelnamespace/effectname]: Boolean, // Loading status for specific effects
},
}
```
-你可以使用该 model 实现在组件中添加 loading 动画。
+You can use this model to implement loading animations in your components.
-## 调试
+## Debugging
-### redux
+### Redux
-dva 的底层是基于 redux，所以你可以安装 redux 的[开发者工具](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=zh-CN)用来查看 model 中的数据和变化的记录。
+Since dva is built on top of Redux, you can install the [Redux DevTools extension](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en) to inspect model data and record state changes.
-
+
-## 参考文章
+## References
-- [dva 官网](https://dvajs.com/)
+- [Dva Official Website](https://dvajs.com/)
diff --git a/docs/docs/max/dva.zh-CN.md b/docs/docs/max/dva.zh-CN.md
new file mode 100644
index 000000000000..fe8e7fa77dd5
--- /dev/null
+++ b/docs/docs/max/dva.zh-CN.md
@@ -0,0 +1,337 @@
+# dva
+
+## 为什么需要状态管理
+
+React 的组件只是通过 jsx 以及样式按照 state 构建最终的 UI，真正将页面动态化的实际上是 state 的变化实现的。对于简单的前端应用，在组件中通过组件自身的 state 加上父组件通过 props 状态的传递就能够满足应用数据管理的需求。但是当应用膨胀到一定程度后就会导致组件内维护的状态非常的复杂，加上组件之间状态的传递，很容易导致数据管理混乱。很小的修改都可能导致难以预料的副作用。
+
+所以我们需要纯净的 UI 组件，除了渲染逻辑，不再杂糅其他（比如网络请求）。这样我们就要想办法把与渲染无关的业务逻辑抽离出来，形成独立的层（在 Umi 中就是 `src/models` 文件夹中所管理的 model ）去管理。让所有组件降级为`无状态组件`，仅仅依赖 props 渲染。这样 UI 层面就不需关心渲染无关的逻辑，专注做 UI 渲染。（注：这里说的组件主要是指 page 下面的页面组件，对于 component 下的组件本身就应该是比较通用的组件，更应该仅仅依赖 props 渲染，它们也不应该有 model，数据应该通过在页面组件中通过 props 传递过去）。
+
+## 简单的数据共享
+
+对于简单的应用，不需要复杂的数据流，只需要一些简单的数据共享。我们推荐使用 [中台最佳实践简易数据流](./data-flow) 。
+
+## Umi 如何管理状态
+
+如下图所示，Umi 内置了 [Dva](https://dvajs.com) 提供了一套状态管理方案：
+
+
+
+数据统一在 `src/models` 中的 model 管理，组件内尽可能的不去维护数据，而是通过 connect 去关联 model 中的数据。页面有操作的时候则触发一个 action 去请求后端接口以及修改 model 中的数据，将业务逻辑分离到一个环形的闭环中，使得数据在其中单向流动。让应用更好维护。这样的思想最初来源于 Facebook 的 [flux](http://facebook.github.io/flux/)。接下来我们来具体看看如何在 Umi 中实现这样的逻辑。
+
+### 配置 dva
+
+首先你需要配置 `dva: {}` 打开 Umi 内置的 dva 插件。
+
+### 添加 model
+
+Umi 会默认将 `src/models` 下的 model 定义自动挂载，你只需要在 model 文件夹中新建文件即可新增一个 model 用来管理组件状态。
+
+在 2.0 后，为了更好的支持移动端的 H5 项目的按需加载和大型项目的 model 组织，对于某个 page 文件夹下面的 model 我们也会默认挂载，具体结构可以参考[目录结构说明](../guides/directory-structure)。但是需要注意的是 model 的 namespace 是全局的，你仍然需要保证你的 namesapce 唯一（默认是文件名）。对于大部分的项目，我们推荐统一放到 model 中进行管理即可，不需要使用该功能。
+
+model 的写法参考如下示例：
+
+```js
+import { queryUsers, queryUser } from '../../services/user';
+
+export default {
+ state: {
+ user: {},
+ },
+
+ effects: {
+ *queryUser({ payload }, { call, put }) {
+ const { data } = yield call(queryUser, payload);
+ yield put({ type: 'queryUserSuccess', payload: data });
+ },
+ },
+
+ reducers: {
+ queryUserSuccess(state, { payload }) {
+ return {
+ ...state,
+ user: payload,
+ };
+ },
+ },
+
+ test(state) {
+ console.log('test');
+ return state;
+ },
+};
+```
+
+### 把组件和 model connect 在一起
+
+新建完成 model 之后你就可以在组件中通过 ES6 的 [Decorator](http://es6.ruanyifeng.com/#docs/decorator) 方便的把 model 和组件 connect 到一起。然后你就可以在组件中通过`this.props.[modelName]`的方式来访问 model 中的数据了。（在对应的 model 中，默认 namespace 即为文件名）
+
+组件如下示例：
+
+```javascript
+import React, { Component } from 'react';
+import { connect } from 'umi';
+
+@connect(({ user }) => ({
+ user,
+}))
+class UserInfo extends Component {
+ constructor(props) {
+ super(props);
+ }
+ render() {
+ return .(js|json|ts)`。其中，`` 为分隔符，默认为 `-`，可以通过 `baseSeparator` 项配置。
+Language files should be named according to this convention: `.(js|json|ts)`. Here, `` is a separator character, which is `-` by default but can be configured using the `baseSeparator` option.
-例如，如果您需要在项目中引入简体中文和英文的多语言支持，可以在 `src/locales` 目录下创建 `zh-CN.ts` 和 `en-US.ts` 两个文件：
+For example, if you need to introduce language support for Simplified Chinese and English in your project, you can create two files, `zh-CN.ts` and `en-US.ts`, under the `src/locales` directory:
```diff
src
@@ -20,21 +20,21 @@ src
pages
```
-在 `.umirc.ts` 中配置国际化插件：
+Configure the internationalization plugin in `.umirc.ts`:
```ts
export default {
locale: {
- // 默认使用 src/locales/zh-CN.ts 作为多语言文件
+ // Use src/locales/zh-CN.ts as the default language file
default: 'zh-CN',
baseSeparator: '-',
},
};
```
-关于配置的更多介绍可参见[配置插件](#配置插件)章节。
+For more detailed configuration, see the [Configuration Plugin](#configuration-plugin) section.
-现在，添加您的第一条多语言内容：
+Now, add your first piece of localized content:
```ts
// src/locales/zh-CN.ts
@@ -50,21 +50,21 @@ export default {
};
```
-您也可以使用 `.json` 文件来存放多语言的内容：
+You can also use `.json` files to store language content:
```json
// src/locales/zh-CN.json
{
- "welcome": "欢迎光临 Umi 的世界！",
+ "welcome": "欢迎光临 Umi 的世界！"
}
// src/locales/en-US.json
{
- "welcome": "Welcome to Umi's world!",
+ "welcome": "Welcome to Umi's world!"
}
```
-一切就绪，现在您可以在 Umi 中使用多语言内容。交给我们的 ` | Record
- // defaultLocale: string
- // defaultFormats: CustomFormats
- // timeZone?: string
- // textComponent?: React.ComponentType | keyof React.ReactHTML
- // wrapRichTextChunksInFragment?: boolean
- // defaultRichTextElements?: Record>
- // onError(err: string): void
-}
-
+ // ... other react-intl options
+};
```
## FAQ
-### 为什么不直接使用 `formatMessage` 这个语法糖？
+### Why not use the `formatMessage` shorthand directly?
-虽然 `formatMessage` 直接使用起来会非常方便，但是它脱离了 React 的生命周期，最严重的问题就是切换语言时无法触发 DOM 的重新渲染。为了解决这个问题，我们切换语言时就需要刷新一下浏览器，用户体验很差。所以推荐大家使用 `useIntl` 或者 `injectIntl`，可以实现同样的功能。
+While using the `formatMessage` shorthand is convenient, it operates outside of the React lifecycle. The most significant issue is that it can't trigger DOM re-rendering when switching languages. To address this issue, you would need to refresh the browser when switching languages, which results in poor user experience. Therefore, it's recommended to use `useIntl` or `injectIntl` to achieve the same functionality.
diff --git a/docs/docs/max/i18n.zh-CN.md b/docs/docs/max/i18n.zh-CN.md
new file mode 100644
index 000000000000..dc8c2271758e
--- /dev/null
+++ b/docs/docs/max/i18n.zh-CN.md
@@ -0,0 +1,525 @@
+import { Message } from 'umi';
+
+# 国际化
+
+`@umi/max` 内置了[国际化插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/locale.ts)，它可以轻松地将国际化功能集成到你的 Umi 应用程序之中。
+
+## 开始使用
+
+国际化插件采用约定式目录结构，我们约定在 `src/locales` 目录下引入多语言文件。
+
+多语言文件的命名需遵循此规范：`.(js|json|ts)`。其中，`` 为分隔符，默认为 `-`，可以通过 `baseSeparator` 项配置。
+
+例如，如果您需要在项目中引入简体中文和英文的多语言支持，可以在 `src/locales` 目录下创建 `zh-CN.ts` 和 `en-US.ts` 两个文件：
+
+```diff
+src
+ + locales
+ + zh-CN.ts
+ + en-US.ts
+ pages
+```
+
+在 `.umirc.ts` 中配置国际化插件：
+
+```ts
+export default {
+ locale: {
+ // 默认使用 src/locales/zh-CN.ts 作为多语言文件
+ default: 'zh-CN',
+ baseSeparator: '-',
+ },
+};
+```
+
+关于配置的更多介绍可参见[配置插件](#配置插件)章节。
+
+现在，添加您的第一条多语言内容：
+
+```ts
+// src/locales/zh-CN.ts
+export default {
+ welcome: '欢迎光临 Umi 的世界！',
+};
+```
+
+```ts
+// src/locales/en-US.ts
+export default {
+ welcome: "Welcome to Umi's world!",
+};
+```
+
+您也可以使用 `.json` 文件来存放多语言的内容：
+
+```json
+// src/locales/zh-CN.json
+{
+ "welcome": "欢迎光临 Umi 的世界！",
+}
+
+// src/locales/en-US.json
+{
+ "welcome": "Welcome to Umi's world!",
+}
+```
+
+一切就绪，现在您可以在 Umi 中使用多语言内容。交给我们的 ` | Record
+ // defaultLocale: string
+ // defaultFormats: CustomFormats
+ // timeZone?: string
+ // textComponent?: React.ComponentType | keyof React.ReactHTML
+ // wrapRichTextChunksInFragment?: boolean
+ // defaultRichTextElements?: Record>
+ // onError(err: string): void
+}
+
+```
+## FAQ
+
+### 为什么不直接使用 `formatMessage` 这个语法糖？
+
+虽然 `formatMessage` 直接使用起来会非常方便，但是它脱离了 React 的生命周期，最严重的问题就是切换语言时无法触发 DOM 的重新渲染。为了解决这个问题，我们切换语言时就需要刷新一下浏览器，用户体验很差。所以推荐大家使用 `useIntl` 或者 `injectIntl`，可以实现同样的功能。
diff --git a/docs/docs/max/introduce.md b/docs/docs/max/introduce.md
index afebd0526630..02a773e549c9 100644
--- a/docs/docs/max/introduce.md
+++ b/docs/docs/max/introduce.md
@@ -1,12 +1,12 @@
import { Message } from 'umi'
-# Umi Max 简介
+# Introduction
-Umi 作为一个可扩展的企业级前端应用框架，在蚂蚁集团内部已经已直接或间接地服务了 10000+ 应用。在工程实践的过程中，解决大量前端开发中开发中遇到的常见问题，这些经验累积成 Umi 各个插件。为了方便开发者更加方便的使用这些插件，在我们这些插件开源的基础上，直接将他们集成到一起，打造了 `@umijs/max`。 让开发者直接可以通过脚手架马上获得和蚂蚁集团开发 Umi 应用一样的开发体检。
+As an extensible enterprise-level frontend application framework, Umi has directly or indirectly served over 10,000 applications within Ant Group. Through practical engineering, it addresses a multitude of common issues encountered in frontend development. These accumulated experiences have given rise to various Umi plugins. To facilitate developers in using these plugins more conveniently, we've integrated them together on the basis of open sourcing our plugins, resulting in `@umijs/max`. This allows developers to immediately obtain the same development experience as Ant Group when developing Umi applications.
-## 如何使用
+## How to use
-在使用 `create-umi` 选择 `Ant Design Pro` 模板，就能使用 `@umijs/max` 来创建项目了。
+To create a project using `@umijs/max`, choose the `Ant Design Pro` template with the `create-umi` command.
```bash {4}
$ npx create-umi@latest
@@ -17,29 +17,29 @@ $ npx create-umi@latest
```
-在 Umi Max 项目中命令行请使用 `max{:bash}`，而不是原来的 `umi{:bash}`，示例如下
+In a Umi Max project, use `max{:bash}` in the command line instead of the original `umi{:bash}` command. An example is shown below.
```bash /max/
$ npx max g jest
```
-新建的项目默认安装以下插件, 可以按需开启：
+By default, newly created projects come with the following plugins installed, which can be selectively enabled:
-- [权限](./access)
-- [站点统计](./analytics)
-- [Antd](./antd)
-- [图表](./charts)
+- [Permissions](./access)
+- [Site Analytics](./analytics)
+- [Ant Design (Antd)](./antd)
+- [Charts](./charts)
- [dva](./dva)
-- [initial-state](./data-flow#全局初始状态)
-- [数据流](./data-flow)
-- [布局和菜单](./layout-menu)
-- [国际化(多语言)](./i18n)
+- [Initial State](./data-flow#global-initial-state)
+- [Data Flow](./data-flow)
+- [Layout and Menu](./layout-menu)
+- [Internationalization (i18n)](./i18n)
- [model](./data-flow)
-- [乾坤微前端](./micro-frontend)
-- [请求库](./request)
+- [Qiankun Micro Frontends](./micro-frontend)
+- [Request Library](./request)
- [Tailwind CSS](./tailwindcss)
- [CSS-IN-JS](./styled-components)
-- [请求方案](./react-query)
-- [全局数据存储方案](./valtio)
+- [Request Strategies](./react-query)
+- [Global Data Storage Solution](./valtio)
- [Module Federation](./mf)
diff --git a/docs/docs/max/introduce.zh-CN.md b/docs/docs/max/introduce.zh-CN.md
new file mode 100644
index 000000000000..afebd0526630
--- /dev/null
+++ b/docs/docs/max/introduce.zh-CN.md
@@ -0,0 +1,45 @@
+import { Message } from 'umi'
+
+# Umi Max 简介
+
+Umi 作为一个可扩展的企业级前端应用框架，在蚂蚁集团内部已经已直接或间接地服务了 10000+ 应用。在工程实践的过程中，解决大量前端开发中开发中遇到的常见问题，这些经验累积成 Umi 各个插件。为了方便开发者更加方便的使用这些插件，在我们这些插件开源的基础上，直接将他们集成到一起，打造了 `@umijs/max`。 让开发者直接可以通过脚手架马上获得和蚂蚁集团开发 Umi 应用一样的开发体检。
+
+## 如何使用
+
+在使用 `create-umi` 选择 `Ant Design Pro` 模板，就能使用 `@umijs/max` 来创建项目了。
+
+```bash {4}
+$ npx create-umi@latest
+? Pick Umi App Template › - Use arrow-keys. Return to submit.
+ Simple App
+❯ Ant Design Pro
+ Vue Simple App
+```
+
+
+在 Umi Max 项目中命令行请使用 `max{:bash}`，而不是原来的 `umi{:bash}`，示例如下
+
+
+```bash /max/
+$ npx max g jest
+```
+
+新建的项目默认安装以下插件, 可以按需开启：
+
+- [权限](./access)
+- [站点统计](./analytics)
+- [Antd](./antd)
+- [图表](./charts)
+- [dva](./dva)
+- [initial-state](./data-flow#全局初始状态)
+- [数据流](./data-flow)
+- [布局和菜单](./layout-menu)
+- [国际化(多语言)](./i18n)
+- [model](./data-flow)
+- [乾坤微前端](./micro-frontend)
+- [请求库](./request)
+- [Tailwind CSS](./tailwindcss)
+- [CSS-IN-JS](./styled-components)
+- [请求方案](./react-query)
+- [全局数据存储方案](./valtio)
+- [Module Federation](./mf)
diff --git a/docs/docs/max/layout-menu.md b/docs/docs/max/layout-menu.md
index f6f7e2bcd819..a283ad31a073 100644
--- a/docs/docs/max/layout-menu.md
+++ b/docs/docs/max/layout-menu.md
@@ -1,8 +1,8 @@
-# 布局与菜单
+# Layout and Menu
-## 启用方式
+## Activation
-配置开启。
+Configure the activation in the following way.
```ts
// config/config.ts
@@ -13,23 +13,23 @@ export default {
};
```
-## 介绍
+## Introduction
-为了进一步降低研发成本，我们将布局通过 Umi 插件的方式内置，只需通过简单的配置即可拥有 Ant Design 的 Layout（[ProLayout](https://procomponents.ant.design/components/layout)），包括导航以及侧边栏。从而做到用户无需关心布局。
+To further reduce development costs, we've integrated the layout through Umi plugins, allowing you to easily possess Ant Design's Layout ([ProLayout](https://procomponents.ant.design/components/layout)) with simple configuration. This includes navigation and sidebars. As a result, users do not need to concern themselves with the layout.
-- 默认为 Ant Design 的 Layout [@ant-design/pro-layout](https://www.npmjs.com/package/@ant-design/pro-layout)，支持它全部配置项。
-- 顶部导航/侧边栏菜单根据路由中的配置自动生成。
-- 默认支持对路由的 403/404 处理和 Error Boundary。
-- 搭配 `access` [插件](./access)一起使用，可以完成对路由权限的控制。
-- 搭配 `initial-state` [插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/initial-state.ts) 和 [数据流](./data-flow) 插件一起使用，可以拥有默认用户登陆信息的展示。
+- Defaults to Ant Design's Layout [@ant-design/pro-layout](https://www.npmjs.com/package/@ant-design/pro-layout), supporting all of its configuration options.
+- Top navigation/sidebar menus are automatically generated based on route configurations.
+- Default support for 403/404 handling and Error Boundary for routes.
+- When used together with the `access` [plugin](./access), it can complete route permission control.
+- When used together with the `initial-state` [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/initial-state.ts) and [data flow](./data-flow) plugin, it can display default user login information.
-> 想要动态菜单？查看这里 [菜单的高级用法](https://beta-pro.ant.design/docs/advanced-menu-cn)
+> Need dynamic menus? Check out the [advanced menu usage](https://beta-pro.ant.design/docs/advanced-menu-cn) here.
-## 配置
+## Configuration
-### 构建时配置
+### Build-time Configuration
-可以通过配置文件 `config/config.ts` 中的 `layout` 属性开启插件。
+You can enable the plugin by configuring the `layout` property in the `config/config.ts` file.
```ts
import { defineConfig } from 'umi';
@@ -37,7 +37,7 @@ import { defineConfig } from 'umi';
export default defineConfig({
layout: {
title: 'Ant Design',
- locale: false, // 默认开启，如无需菜单国际化可关闭
+ locale: false, // Enable by default, can be turned off if menu internationalization is not needed
},
});
```
@@ -47,92 +47,92 @@ export default defineConfig({
- Type: `string`
- Default: `name` in package.json
-显示在布局左上角的产品名，默认值为包名。
+The product name displayed in the upper left corner of the layout, with the default value being the package name.
#### locale
- Type: `boolean`
- Default: `false`
-是否开始国际化配置。开启后路由里配置的菜单名会被当作菜单名国际化的 key，插件会去 locales 文件中查找 `menu.[key]`对应的文案，默认值为该 key，路由配置的 name 字段的值就是对应的 key 值。如果菜单是多级路由假设是二级路由菜单，那么插件就会去 locales 文件中查找 `menu.[key].[key]`对应的文案，该功能需要配置 [`i18n`](./i18n) 使用。如无需菜单国际化可配置 `false` 关闭。
+Whether to enable internationalization configuration. When enabled, the menu name configured in the route will be treated as the key for menu internationalization. The plugin will look up the corresponding text of `menu.[key]` in the locales file. The default value is the same as the key. The value of the `name` field in the route configuration is the corresponding key value. If the menu is a multi-level route, assuming it is a second-level route menu, the plugin will look up the corresponding text of `menu.[key].[key]` in the locales file. This feature requires configuration with [`i18n`](./i18n). If menu internationalization is not needed, it can be configured as `false`.
-### 运行时配置
+### Runtime Configuration
-运行时配置写在 `src/app.tsx` 中，key 为 `layout`。
+Runtime configuration is written in `src/app.tsx`, with the key being `layout`.
```tsx
import { RunTimeLayoutConfig } from '@umijs/max';
export const layout: RunTimeLayoutConfig = (initialState) => {
return {
- // 常用属性
+ // Common properties
title: 'Ant Design',
logo: 'https://img.alicdn.com/tfs/TB1YHEpwUT1gK0jSZFhXXaAtVXa-28-27.svg',
- // 默认布局调整
+ // Default layout adjustments
rightContentRender: () => ;`
-- Default: Ant Design Pro 的错误页。
+- Default: Ant Design Pro's error page.
-发生错误后展示的组件。
+The component displayed after an error occurs.
-### 扩展的路由配置
+### Extended Route Configuration
-Layout 插件会基于 Umi 的路由，封装了更多的配置项，支持更多配置式的能力。新增：
+The Layout plugin encapsulates more configuration options based on Umi's routes, supporting more configurative capabilities. New additions include:
-- 侧边栏菜单配置。
-- 布局路由级别展示/隐藏相关配置。
-- 与权限插件结合，配置式实现权限路由的功能。
+- Sidebar menu configuration.
+- Layout-level display/hide configurations for routes.
+- Combining with the permission plugin to achieve functionality for permission routes.
-示例如下：
+An example is as follows:
```typescript
// config/route.ts
@@ -140,30 +140,30 @@ export const routes: IBestAFSRoute[] = [
{
path: '/welcome',
component: 'IndexPage',
- name: '欢迎', // 兼容此写法
+ name: 'Welcome', // Also compatible with this writing style
icon: 'testicon',
- // 更多功能查看
+ // More functionality can be found at
// https://beta-pro.ant.design/docs/advanced-menu
// ---
- // 新页面打开
+ // Open in a new page
target: '_blank',
- // 不展示顶栏
+ // Do not display the top bar
headerRender: false,
- // 不展示页脚
+ // Do not display the footer
footerRender: false,
- // 不展示菜单
+ // Do not display the menu
menuRender: false,
- // 不展示菜单顶栏
+ // Do not display the menu title and logo
menuHeaderRender: false,
- // 权限配置，需要与 plugin-access 插件配合使用
+ // Permission configuration, needs to be used in conjunction with the plugin-access plugin
access: 'canRead',
- // 隐藏子菜单
+ // Hide child menu
hideChildrenInMenu: true,
- // 隐藏自己和子菜单
+ // Hide itself and child menu
hideInMenu: true,
- // 在面包屑中隐藏
+ // Hide in breadcrumbs
hideInBreadcrumb: true,
- // 子项往上提，仍旧展示,
+ // Lift children up and display themselves,
flatMenu: true,
},
];
@@ -173,23 +173,23 @@ export const routes: IBestAFSRoute[] = [
- Type: `string`
-菜单上显示的名称，没有则不展示该菜单。
+The name displayed on the menu. If not provided, the menu will not be displayed.
#### icon
- Type: `string`
-菜单上显示的 antd 的 icon，为了按需加载 layout 插件会帮你自动转化为 Antd icon 的 dom。支持类型可以在 [antd icon](https://ant.design/components/icon-cn/) 中找到。示例：
+The Antd icon displayed on the menu. To enable on-demand loading, the layout plugin will automatically convert it to the Antd icon's DOM element. Supported types can be found in [antd icon](https://ant.design/components/icon-cn/). Examples:
```ts
-// ;`
+- Default: Ant Design Pro 的错误页。
+
+发生错误后展示的组件。
+
+### 扩展的路由配置
+
+Layout 插件会基于 Umi 的路由，封装了更多的配置项，支持更多配置式的能力。新增：
+
+- 侧边栏菜单配置。
+- 布局路由级别展示/隐藏相关配置。
+- 与权限插件结合，配置式实现权限路由的功能。
+
+示例如下：
+
+```typescript
+// config/route.ts
+export const routes: IBestAFSRoute[] = [
+ {
+ path: '/welcome',
+ component: 'IndexPage',
+ name: '欢迎', // 兼容此写法
+ icon: 'testicon',
+ // 更多功能查看
+ // https://beta-pro.ant.design/docs/advanced-menu
+ // ---
+ // 新页面打开
+ target: '_blank',
+ // 不展示顶栏
+ headerRender: false,
+ // 不展示页脚
+ footerRender: false,
+ // 不展示菜单
+ menuRender: false,
+ // 不展示菜单顶栏
+ menuHeaderRender: false,
+ // 权限配置，需要与 plugin-access 插件配合使用
+ access: 'canRead',
+ // 隐藏子菜单
+ hideChildrenInMenu: true,
+ // 隐藏自己和子菜单
+ hideInMenu: true,
+ // 在面包屑中隐藏
+ hideInBreadcrumb: true,
+ // 子项往上提，仍旧展示,
+ flatMenu: true,
+ },
+];
+```
+
+#### name
+
+- Type: `string`
+
+菜单上显示的名称，没有则不展示该菜单。
+
+#### icon
+
+- Type: `string`
+
+菜单上显示的 antd 的 icon，为了按需加载 layout 插件会帮你自动转化为 Antd icon 的 dom。支持类型可以在 [antd icon](https://ant.design/components/icon-cn/) 中找到。示例：
+
+```ts
+//
+Module Federation 功能需要浏览器支持 `Top Level Await` 特性。在生产环境中使用请注意浏览器是否支持([浏览器支持情况](https://caniuse.com/?search=top%20level%20await))。
+
+
+## 配置
+
+### 使用远端模块配置
+
+
+
+@umijs/max 项目
+
+```ts
+// .umirc.ts
+import { defineConfig } from '@umijs/max';
+
+const shared = {
+ react: {
+ singleton: true,
+ eager: true,
+ },
+ 'react-dom': {
+ singleton: true,
+ eager: true,
+ },
+};
+
+export default defineConfig({
+ // 已经内置 Module Federation 插件, 直接开启配置即可
+ mf: {
+ remotes: [
+ {
+ // 可选，未配置则使用当前 remotes[].name 字段
+ aliasName: 'mfNameAlias',
+ name: 'theMfName',
+ entry: 'https://to.the.remote.com/remote.js',
+ },
+ ],
+
+ // 配置 MF 共享的模块
+ shared,
+ },
+});
+```
+
+普通 Umi 项目
+
+```ts
+// .umirc.ts
+import { defineConfig } from 'umi';
+
+const shared = {
+ react: {
+ singleton: true,
+ eager: true,
+ },
+ 'react-dom': {
+ singleton: true,
+ eager: true,
+ },
+};
+
+export default defineConfig({
+ plugins: ['@umijs/plugins/dist/mf'], // 引入插件
+ mf: {
+ remotes: [
+ {
+ // 可选，未配置则使用当前 remotes[].name 字段
+ aliasName: 'mfNameAlias',
+ name: 'theMfName',
+ entry: 'https://to.the.remote.com/remote.js',
+ },
+ ],
+
+ // 配置 MF 共享的模块
+ shared,
+ },
+});
+```
+
+
+
+在项目中就可以使用 `import XXX from 'mfNameAlias/XXXX'` 来使用远端模块的内容了。
+
+#### 运行时远端模块加载
+
+如果需要在运行时（根据运行的环境）决定加载远端模块的地址，可以采用如下方式配置：
+
+```ts
+// .umirc.ts
+defineConfig({
+ mf: {
+ remotes: [
+ {
+ name: 'theMfName',
+ keyResolver: `(function(){
+ try {
+ return window.injectInfo.env || 'PROD'
+ } catch(e) {
+ return 'PROD'}
+ })()`,
+ entries: {
+ PRE: 'http://pre.mf.com/remote.js',
+ PROD: 'http://produ.mf.com/remote.js',
+ TEST: 'http://test.dev.mf.com/remote.js',
+ DEV: 'http://127.0.0.1:8000/remote.js',
+ },
+ },
+ ],
+ shared,
+ },
+});
+```
+
+- 使用运行时远端模块加载逻辑时，不要配置 `remotes[]#entry` , 插件会优先使用该字段。
+- `keyResolver` 用于在运行时决定使用 `entries` 哪个 key; 推荐使用 _立即调用函数表达式_ 的形式，可以在函数中实现较复杂的功能。不支持异步的函数。
+- `keyResolver` 也可以使用静态的值，配置形式 `keyResolver: '"PROD"'`
+
+### 导出远端模块配置
+
+当前项目对外提供远端模块，模块名使用如下配置字段
+
+```ts
+// .umirc.ts
+// 提取变量是为了和 MFSU 配合使用保持配置一致
+const remoteMFName = 'remoteMFName';
+
+defineConfig({
+ mf: {
+ name: remoteMFName,
+
+ // 可选，远端模块库类型, 如果模块需要在乾坤子应用中使用建议配置示例的值，
+ // 注意这里的 name 必须和最终 MF 模块的 name 一致
+ // library: { type: "window", name: "exportMFName" },
+ },
+});
+```
+
+
+配置的模块名必须为一个合法的 Javascript 变量名！
+
+
+导出的模块按照约定，将源代码目录下的 `exposes` 一级子目录名作为导出项，导出文件为该目录下的 index 文件，举例
+
+```txt
+src/exposes/
+├── Button
+│ └── index.jsx
+├── Head
+│ └── index.ts
+└── Form
+ └── index.tsx
+```
+
+对应的 Module Federation 的 exposes 为
+
+```js
+{
+ './Button': 'src/exposes/Button/index.jsx',
+ './Button': 'src/exposes/Head/index.ts',
+ './Form' : 'src/exposes/Form/index.tsx',
+}
+```
+
+## 运行时 API
+
+### 何时需要使用运行时 API ？
+
+采用配置的方式结合`import()`已经可以方便的使用 Module Federation 功能。如果你有以下需求就应该考虑使用运行时 API。
+
+- 远端模块的加载失败时，页面需要使用兜底组件
+- 远端模块的加载的地址无法通过同步函数来确定（需要异步调用）
+- 远端模块的加载的地址和模块名需要在运行时才能确定
+
+### safeMfImport
+
+有兜底的远端模块加载函数，接口定义如下：
+
+```ts
+safeMfImport(moduleSpecifier: string, fallback: any): Promise
+```
+
+结合 `React.lazy` 可以实现远端模块的懒加载
+
+```ts
+import { safeMfImport } from '@umijs/max';
+import React, { Suspense } from 'react';
+
+const RemoteCounter = React.lazy(() => {
+ return safeMfImport('remoteCounter/Counter', { default: () => 'Fallback' });
+});
+
+export default function Page() {
+ return (
+
+
+ );
+};
+```
+
+
+- 注意这里需要将兜底的***组件***包装到对象的`default`字段上来模拟一个模块。
+- `remoteCounter/Counter` 需要和配置对应。
+
+
+[实例代码](https://github.com/umijs/umi/blob/master/examples/mf-host/src/pages/safe-import.tsx)
+
+### safeRemoteComponent
+
+该 API 为封装了 `safeMfImport` 的高阶组件, 接口定义如下：
+
+```ts
+safeRemoteComponent>
+ (opts: {
+ moduleSpecifier:string;
+ fallbackComponent: React.ComponentType; // 远端组件加载失败的兜底组件
+ loadingElement: React.ReactNode ; // 组件加载中的 loading 展示
+ } ): T
+```
+
+示例:
+
+```ts
+const RemoteCounter = safeRemoteComponent>({
+ moduleSpecifier: 'remoteCounter/Counter',
+ fallbackComponent: () => 'fallbacked',
+ loadingElement: 'Loading',
+});
+
+export default function Page() {
+ return (
+
+```
+
+示例
+
+```ts
+const RemoteCounter = React.lazy(() => {
+ return rawMfImport({
+ entry: 'http://localhost:8001/remote.js',
+ moduleName: 'Counter',
+ remoteName: 'remoteCounter',
+ });
+});
+```
+
+[示例代码](https://github.com/umijs/umi/blob/master/examples/mf-host/src/pages/raw-mf-import.tsx)
+
+### safeRemoteComponentWithMfConfig
+
+封装了`rawMfImport`的 高阶组件：
+
+```ts
+type RawRemoteComponentOpts ={
+ mfConfig:{
+ entry:string;
+ remoteName: string;
+ moduleName: string;
+ };
+ fallbackComponent: ComponentType;
+ loadingElement: ReactNode;
+}
+safeRemoteComponentWithMfConfig>(opts: RawRemoteComponentOpts): T
+```
+
+示例
+
+```ts
+const RemoteCounter = safeRemoteComponentWithMfConfig<
+ React.FC<{ init?: number }>
+>({
+ mfConfig: {
+ entry: 'http://localhost:8001/remote.js',
+ moduleName: 'Counter',
+ remoteName: 'remoteCounter',
+ },
+ fallbackComponent: () => 'raw Fallback',
+ loadingElement: 'raw Loading',
+});
+
+export default function Page() {
+ return
-本教程假设您对什么是微前端，什么是 Qiankun 微应用，以及如何使用 Qiankun 微应用已经有了基本的了解。
+This tutorial assumes that you have a basic understanding of what micro frontends are, what Qiankun micro apps are, and how to use Qiankun micro apps.
-### 配置父应用
+### Configuring the Parent App
-首先需要配置父应用，注册子应用的相关信息，这样父应用才能识别子应用并在内部引入。
+First, you need to configure the parent app to register information about the child apps. This way, the parent app can recognize and incorporate the child apps internally.
-注册子应用的方式主要有两种：
+There are two main ways to register child apps:
-- 插件注册子应用。
-- 运行时注册子应用。
+- Registering child apps using plugins.
+- Registering child apps at runtime.
-#### 插件注册子应用
+#### Registering Child Apps Using Plugins
-修改父应用的 Umi 配置文件，添加如下内容：
+Modify the Umi configuration file of the parent app and add the following content:
```ts
// .umirc.ts
@@ -55,11 +55,11 @@ export default {
};
```
-其中，`name` 为子应用的名称，在引入子应用时需要使用到它；`entry` 为子应用运行的 HTTP 地址；`master` 对象的完整 API 可[见此](#masteroptions)。
+Here, `name` is the name of the child app, which you'll use when importing the child app. `entry` is the HTTP address where the child app is hosted. For the complete API of the `master` object, refer to [this](#masteroptions).
-#### 运行时注册子应用
+#### Registering Child Apps at Runtime
-修改父应用的 Umi 配置文件，添加如下内容：
+Modify the Umi configuration file of the parent app and add the following content:
```ts
// .umirc.ts
@@ -70,7 +70,7 @@ export default {
};
```
-修改父应用的 `src/app.ts` 文件，导出 `qiankun` 对象：
+Modify the `src/app.ts` file of the parent app and export the `qiankun` object:
```ts
// src/app.ts
@@ -88,13 +88,13 @@ export const qiankun = {
};
```
-### 配置子应用
+### Configuring Child Apps
-子应用需要导出必要的生命周期钩子，供父应用在适当的时机调用。
+Child apps need to export the necessary lifecycle hooks for the parent app to call at appropriate times.
-假设您的子应用项目**基于 Umi 开发**且**引入了 `qiankun` [插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/qiankun.ts)**。如果没有，可以按照[此教程](https://qiankun.umijs.org/zh/guide/getting-started#%E5%BE%AE%E5%BA%94%E7%94%A8)进行配置。
+Assuming your child app project is **based on Umi** and has imported the `qiankun` [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/qiankun.ts)**. If not, you can configure it following [this tutorial](https://qiankun.umijs.org/zh/guide/getting-started#%E5%BE%AE%E5%BA%94%E7%94%A8).
-修改子应用的 Umi 的配置文件，添加如下内容：
+Modify the Umi configuration file of the child app and add the following content:
```ts
// .umirc.ts
@@ -105,24 +105,24 @@ export default {
};
```
-这样，微前端插件会自动在项目中创建好 Qiankun 子应用所需的生命周期钩子和方法，Easy as a cake！
+This way, the micro frontend plugin will automatically create the necessary lifecycle hooks and methods for Qiankun child apps in the project. Easy as a cake!
-### 引入子应用
+### Importing Child Apps
-在父应用中引入子应用，插件提供了三种不同实现的方式：
+You can import child apps into the parent app using three different methods provided by the plugin:
-- 路由绑定引入子应用。
-- `
@@ -230,16 +230,16 @@ export default function Page() {
}
```
-在上面的例子中，点击按钮后，父应用的路由变为 `/app2/home`，渲染子应用 `app2` 内部路由为 `/home` 的页面。同理，如果想要从子应用 app2 回到子应用 app1，可以编写代码如下：
+In the example above, clicking the button changes the parent app's route to `/app2/home` and renders the page with route `/home` within the `app2` child app. Similarly, if you want to navigate from the `app2` child app to the `app1` child app, you can write the code like this:
```tsx
-// 在 app2 中
+// In app2
import { MicroAppLink } from 'umi';
export default function Page() {
return (
<>
- {/* 跳转链接为 /app1/project/home */}
+ {/* Navigating link is /app1/project/home */}
@@ -248,16 +248,16 @@ export default function Page() {
}
```
-您也可以从子应用跳转到父应用的指定路由：
+You can also navigate from a child app to a specific route in the parent app:
```tsx
-// 在子应用中
+// In the child app
import { MicroAppLink } from 'umi';
export default function Page() {
return (
<>
- {/* 跳转链接为 /table */}
+ {/* Navigating link is /table */}
@@ -266,24 +266,24 @@ export default function Page() {
}
```
-## 子应用生命周期
+## Child App Lifecycle
-Qiankun 在 single-spa 的基础上实现了一些额外的生命钩子。按照微应用的生命周期顺序，Qiankun 支持的完整的生命钩子列表如下：
+Qiankun builds on top of single-spa and provides additional lifecycle hooks. According to the order of micro app lifecycles, Qiankun supports the following complete list of lifecycle hooks:
-- `beforeLoad`，微应用**开始获取前**调用。最初，微应用为 `NOT_LOADED` 状态。
-- [`load`](https://single-spa.js.org/docs/building-applications/#load)，微应用**获取完成时**调用。开始获取微应用时，微应用变成 `LOADING_SOURCE_CODE` 状态。若获取成功，微应用变成 `NOT_BOOTSTRAPPED` 状态；若获取失败，微应用变成 `LOAD_ERROR` 状态。
-- [`bootstrap`](https://single-spa.js.org/docs/building-applications/#bootstrap)，微应用**初始化完成时**调用。开始初始化微应用时，微应用变成 `BOOTSTRAPPING` 状态。初始化完成时，微应用变成 `NOT_MOUNTED` 状态。
-- `beforeMount`，微应用每次**开始挂载前**调用。
-- [`mount`](https://single-spa.js.org/docs/building-applications/#mount)，微应用每次**开始挂载时**调用。微应用变成 `MOUNTING` 状态。
-- `afterMount`，微应用每次**挂载完成时**调用。微应用变成 `MOUNTED` 状态。
-- `beforeUnmount`，微应用每次**开始卸载前**调用。
-- [`unmount`](https://single-spa.js.org/docs/building-applications/#unmount)，微应用每次**开始卸载时**调用。微应用变成 `UNMOUNTING` 状态。
-- `afterUnmount`，微应用每次**卸载完成时**调用。微应用变成 `NOT_MOUNTED` 状态。
-- [`unload`](https://single-spa.js.org/docs/building-applications/#unload)，微应用**卸载完成时**调用。微应用变成 `NOT_LOADED` 状态。
+- `beforeLoad`: Called **before the micro app starts loading**. Initially, the micro app is in the `NOT_LOADED` state.
+- [`load`](https://single-spa.js.org/docs/building-applications/#load): Called when the micro app **finishes loading**. When the micro app starts loading, it transitions to the `LOADING_SOURCE_CODE` state. If loading is successful, the micro app transitions to the `NOT_BOOTSTRAPPED` state; if loading fails, it transitions to the `LOAD_ERROR` state.
+- [`bootstrap`](https://single-spa.js.org/docs/building-applications/#bootstrap): Called when the micro app **finishes initializing**. When the micro app starts initialization, it transitions to the `BOOTSTRAPPING` state. After initialization is complete, it transitions to the `NOT_MOUNTED` state.
+- `beforeMount`: Called **before each mounting of the micro app**.
+- [`mount`](https://single-spa.js.org/docs/building-applications/#mount): Called when the micro app **starts mounting**. The micro app transitions to the `MOUNTING` state.
+- `afterMount`: Called when each mounting of the micro app **finishes mounting**. The micro app transitions to the `MOUNTED` state.
+- `beforeUnmount`: Called **before each unmounting of the micro app**.
+- [`unmount`](https://single-spa.js.org/docs/building-applications/#unmount): Called when the micro app **starts unmounting**. The micro app transitions to the `UNMOUNTING` state.
+- `afterUnmount`: Called when each unmounting of the micro app **finishes unmounting**. The micro app transitions to the `NOT_MOUNTED` state.
+- [`unload`](https://single-spa.js.org/docs/building-applications/#unload): Called when the micro app **finishes unloading**. The micro app transitions to the `NOT_LOADED` state.
-此外，还存在一个特殊的生命钩子 `update`，仅在使用 `
+本教程假设您对什么是微前端，什么是 Qiankun 微应用，以及如何使用 Qiankun 微应用已经有了基本的了解。
+
+
+### 配置父应用
+
+首先需要配置父应用，注册子应用的相关信息，这样父应用才能识别子应用并在内部引入。
+
+注册子应用的方式主要有两种：
+
+- 插件注册子应用。
+- 运行时注册子应用。
+
+#### 插件注册子应用
+
+修改父应用的 Umi 配置文件，添加如下内容：
+
+```ts
+// .umirc.ts
+export default {
+ qiankun: {
+ master: {
+ apps: [
+ {
+ name: 'app1',
+ entry: '//localhost:7001',
+ },
+ {
+ name: 'app2',
+ entry: '//localhost:7002',
+ },
+ ],
+ },
+ },
+};
+```
+
+其中，`name` 为子应用的名称，在引入子应用时需要使用到它；`entry` 为子应用运行的 HTTP 地址；`master` 对象的完整 API 可[见此](#masteroptions)。
+
+#### 运行时注册子应用
+
+修改父应用的 Umi 配置文件，添加如下内容：
+
+```ts
+// .umirc.ts
+export default {
+ qiankun: {
+ master: {},
+ },
+};
+```
+
+修改父应用的 `src/app.ts` 文件，导出 `qiankun` 对象：
+
+```ts
+// src/app.ts
+export const qiankun = {
+ apps: [
+ {
+ name: 'app1',
+ entry: '//localhost:7001',
+ },
+ {
+ name: 'app2',
+ entry: '//localhost:7002',
+ },
+ ],
+};
+```
+
+### 配置子应用
+
+子应用需要导出必要的生命周期钩子，供父应用在适当的时机调用。
+
+假设您的子应用项目**基于 Umi 开发**且**引入了 `qiankun` [插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/qiankun.ts)**。如果没有，可以按照[此教程](https://qiankun.umijs.org/zh/guide/getting-started#%E5%BE%AE%E5%BA%94%E7%94%A8)进行配置。
+
+修改子应用的 Umi 的配置文件，添加如下内容：
+
+```ts
+// .umirc.ts
+export default {
+ qiankun: {
+ slave: {},
+ },
+};
+```
+
+这样，微前端插件会自动在项目中创建好 Qiankun 子应用所需的生命周期钩子和方法，Easy as a cake！
+
+### 引入子应用
+
+在父应用中引入子应用，插件提供了三种不同实现的方式：
+
+- 路由绑定引入子应用。
+- `
+
+
+
+ );
+}
+```
+
+在上面的例子中，点击按钮后，父应用的路由变为 `/app2/home`，渲染子应用 `app2` 内部路由为 `/home` 的页面。同理，如果想要从子应用 app2 回到子应用 app1，可以编写代码如下：
+
+```tsx
+// 在 app2 中
+import { MicroAppLink } from 'umi';
+
+export default function Page() {
+ return (
+ <>
+ {/* 跳转链接为 /app1/project/home */}
+
+
+
+
+ );
+}
+```
+
+您也可以从子应用跳转到父应用的指定路由：
+
+```tsx
+// 在子应用中
+import { MicroAppLink } from 'umi';
+
+export default function Page() {
+ return (
+ <>
+ {/* 跳转链接为 /table */}
+
+
+
+
+ );
+}
+```
+
+## 子应用生命周期
+
+Qiankun 在 single-spa 的基础上实现了一些额外的生命钩子。按照微应用的生命周期顺序，Qiankun 支持的完整的生命钩子列表如下：
+
+- `beforeLoad`，微应用**开始获取前**调用。最初，微应用为 `NOT_LOADED` 状态。
+- [`load`](https://single-spa.js.org/docs/building-applications/#load)，微应用**获取完成时**调用。开始获取微应用时，微应用变成 `LOADING_SOURCE_CODE` 状态。若获取成功，微应用变成 `NOT_BOOTSTRAPPED` 状态；若获取失败，微应用变成 `LOAD_ERROR` 状态。
+- [`bootstrap`](https://single-spa.js.org/docs/building-applications/#bootstrap)，微应用**初始化完成时**调用。开始初始化微应用时，微应用变成 `BOOTSTRAPPING` 状态。初始化完成时，微应用变成 `NOT_MOUNTED` 状态。
+- `beforeMount`，微应用每次**开始挂载前**调用。
+- [`mount`](https://single-spa.js.org/docs/building-applications/#mount)，微应用每次**开始挂载时**调用。微应用变成 `MOUNTING` 状态。
+- `afterMount`，微应用每次**挂载完成时**调用。微应用变成 `MOUNTED` 状态。
+- `beforeUnmount`，微应用每次**开始卸载前**调用。
+- [`unmount`](https://single-spa.js.org/docs/building-applications/#unmount)，微应用每次**开始卸载时**调用。微应用变成 `UNMOUNTING` 状态。
+- `afterUnmount`，微应用每次**卸载完成时**调用。微应用变成 `NOT_MOUNTED` 状态。
+- [`unload`](https://single-spa.js.org/docs/building-applications/#unload)，微应用**卸载完成时**调用。微应用变成 `NOT_LOADED` 状态。
+
+此外，还存在一个特殊的生命钩子 `update`，仅在使用 `({
+ slogan: 'Hello MicroFrontend',
+ });
+
+ return {
+ globalState,
+ setGlobalState,
+ };
+}
+```
+
+如果通过组件的模式引入子应用，直接将数据以组件参数的形式传递给子应用即可：
+
+```tsx
+import React, { useState } from 'react';
+import { MicroApp } from 'umi';
+
+export default function Page() {
+ const [globalState, setGlobalState] = useState({
+ slogan: 'Hello MicroFrontend',
+ });
+
+ return (
+
+
+Max 项目
+
+```ts
+// .umirc.ts
+moment2dayjs: {
+ preset: 'antd',
+ plugins: ['duration'],
+}
+```
+
+Umi 项目
+
+```ts
+// .umirc.ts
+plugins: [ '@umijs/plugins/dist/moment2dayjs' ],
+moment2dayjs: {
+ preset: 'antd' ,
+ plugins: ['duration'],
+}
+```
+
+
+
+## preset
+
+preset 可配置的值：`antd|antdv3|none`
+
+preset 为 `antd` dayjs 扩展以下插件：
+
+- isSameOrBefore
+- isSameOrAfter
+- advancedFormat
+- customParseFormat
+- weekday
+- weekYear
+- weekOfYear
+- isMoment
+- localeData
+- localizedFormat
+
+preset 为 `antdv3` dayjs 扩展以下插件：
+
+- isSameOrBefore
+- isSameOrAfter
+- advancedFormat
+- customParseFormat
+- weekday
+- weekYear
+- weekOfYear
+- isMoment
+- localeData
+- localizedFormat
+- badMutable
+
+preset 为 `none` 不扩展任何插件。
+
+## plugins
+
+手动配置的 `dayjs` 插件名列表。
+
+
+preset 的插件和 plugins 配置的插件会合并后配置到 dayjs
+
+
+
+开启该插件后，需要自行安装 `dayjs` 依赖
+
diff --git a/docs/docs/max/react-query.md b/docs/docs/max/react-query.md
index fcfddc375b7e..944a64118af5 100644
--- a/docs/docs/max/react-query.md
+++ b/docs/docs/max/react-query.md
@@ -1,10 +1,10 @@
# react-query
-@umijs/max 内置了 [react-query](https://tanstack.com/query/)（和 @tanstack/react-query 是同一个）请求方案。
+@umijs/max comes with the [react-query](https://tanstack.com/query/) (same as @tanstack/react-query) data fetching solution.
-## 启用方式
+## Activation
-如果是 @umijs/max，配置开启。
+For @umijs/max, enable it through configuration.
```ts
export default {
@@ -12,7 +12,7 @@ export default {
}
```
-如果是 umi，先安装 `@umijs/plugins` 依赖，再通过配置开启。
+If you are using Umi, first install the `@umijs/plugins` dependency and then activate it through configuration.
```bash
$ pnpm i @umijs/plugins -D
@@ -25,24 +25,24 @@ export default {
}
```
-## 特性
+## Features
-插件帮你做了几件事，
+The plugin handles several tasks for you:
-1、dev 模式下开启 react query 的 devtool，可通过 `reactQuery: { devtool: false }` 关闭，选项在 app.ts 里通过 `export const reactQuery = { devtool }` 配置。
+1. It enables the react-query devtool in development mode. You can disable it using `reactQuery: { devtool: false }`, and configure this option in `app.ts` using `export const reactQuery = { devtool }`.
-2、注册全局的 QueryClient，可通过 `reactQuery: { queryClient: false }` 关闭，选项在 app.ts 里通过 `export const reactQuery = { queryClient }` 配置。
+2. It registers a global QueryClient. You can disable it using `reactQuery: { queryClient: false }`, and configure this option in `app.ts` using `export const reactQuery = { queryClient }`.
-3、大部分 react-query 的导出可以从 `umi` 或 `@umijs/max` 里 import 使用。
+3. Most of the react-query exports can be imported and used from `umi` or `@umijs/max`.
-## 配置项
+## Configuration Options
-可以在 `reactQuery` 中做以下配置。
+You can configure the following options within `reactQuery`:
-- `devtool`: boolean，是否开启 react query 官方 devtool 工具，默认 `true`
-- `queryClient`: boolean, 是否注册全局的 QueryClient 和 QueryClientProvier，默认 `true`
+- `devtool`: boolean, whether to enable the official react-query devtool. Default is `true`.
+- `queryClient`: boolean, whether to register the global QueryClient and QueryClientProvier. Default is `true`.
-比如：
+For example:
```ts
export default {
@@ -53,16 +53,16 @@ export default {
}
```
-注：以上两个配置的运行时配置需在 `app.ts` 里进行配置。
+Note: The runtime configurations for these two options should be done in `app.ts`.
-## 运行时配置项
+## Runtime Configuration Options
-包含以下配置。
+Includes the following configurations:
-- `devtool`：object
+- `devtool`: object
- `queryClient`: object
-比如：
+For example:
```ts
const API_SERVER = '/path/to/api/server';
diff --git a/docs/docs/max/react-query.zh-CN.md b/docs/docs/max/react-query.zh-CN.md
new file mode 100644
index 000000000000..fcfddc375b7e
--- /dev/null
+++ b/docs/docs/max/react-query.zh-CN.md
@@ -0,0 +1,88 @@
+# react-query
+
+@umijs/max 内置了 [react-query](https://tanstack.com/query/)（和 @tanstack/react-query 是同一个）请求方案。
+
+## 启用方式
+
+如果是 @umijs/max，配置开启。
+
+```ts
+export default {
+ reactQuery: {},
+}
+```
+
+如果是 umi，先安装 `@umijs/plugins` 依赖，再通过配置开启。
+
+```bash
+$ pnpm i @umijs/plugins -D
+```
+
+```ts
+export default {
+ plugins: ['@umijs/plugins/dist/react-query'],
+ reactQuery: {},
+}
+```
+
+## 特性
+
+插件帮你做了几件事，
+
+1、dev 模式下开启 react query 的 devtool，可通过 `reactQuery: { devtool: false }` 关闭，选项在 app.ts 里通过 `export const reactQuery = { devtool }` 配置。
+
+2、注册全局的 QueryClient，可通过 `reactQuery: { queryClient: false }` 关闭，选项在 app.ts 里通过 `export const reactQuery = { queryClient }` 配置。
+
+3、大部分 react-query 的导出可以从 `umi` 或 `@umijs/max` 里 import 使用。
+
+## 配置项
+
+可以在 `reactQuery` 中做以下配置。
+
+- `devtool`: boolean，是否开启 react query 官方 devtool 工具，默认 `true`
+- `queryClient`: boolean, 是否注册全局的 QueryClient 和 QueryClientProvier，默认 `true`
+
+比如：
+
+```ts
+export default {
+ reactQuery: {
+ devtool: false,
+ queryClient: false,
+ },
+}
+```
+
+注：以上两个配置的运行时配置需在 `app.ts` 里进行配置。
+
+## 运行时配置项
+
+包含以下配置。
+
+- `devtool`：object
+- `queryClient`: object
+
+比如：
+
+```ts
+const API_SERVER = '/path/to/api/server';
+export const reactQuery = {
+ devtool: {
+ initialIsOpen: true,
+ },
+ queryClient: {
+ defaultOptions: {
+ queries: {
+ queryFn: async ({ queryKey }) => {
+ const res = await fetch(`${API_SERVER}/${queryKey.join('/')}`);
+ if (res.status !== 200) {
+ throw new Error(res.statusText);
+ }
+ return res.json();
+ }
+ }
+ }
+ },
+};
+```
+
diff --git a/docs/docs/max/request.md b/docs/docs/max/request.md
index e3143b5653da..406c022d583a 100644
--- a/docs/docs/max/request.md
+++ b/docs/docs/max/request.md
@@ -1,8 +1,8 @@
import { Message } from 'umi';
-# 请求
+# Requests
-`@umijs/max` 内置了插件方案。它基于 [axios](https://axios-http.com/) 和 [ahooks](https://ahooks-v2.surge.sh) 的 `useRequest` 提供了一套统一的网络请求和错误处理方案。
+`@umijs/max` comes with built-in plugins. It provides a unified network request and error handling solution based on [axios](https://axios-http.com/) and [ahooks](https://ahooks-v2.surge.sh)'s `useRequest`.
```js
import { request, useRequest } from 'umi';
@@ -11,8 +11,9 @@ request;
useRequest;
```
-## 配置
-### 构建时配置
+## Configuration
+
+### Build-time Configuration
```js
export default {
request: {
@@ -21,9 +22,9 @@ export default {
};
```
-构建时配置可以为 useRequest 配置 `dataField` ，该配置的默认值是 `data`。该配置的主要目的是方便 useRequest 直接消费数据。如果你想要在消费数据时拿到后端的原始数据，需要在这里配置 `dataField` 为 `''` 。
+Build-time configuration can set the `dataField` for useRequest. The default value is `data`. The primary purpose of this configuration is to allow useRequest to consume data directly. If you want to access the original backend data when consuming data, you need to configure `dataField` as `''` here.
-比如你的后端返回的数据格式如下。
+For example, if your backend returns data in the following format:
```js
{
@@ -33,11 +34,11 @@ export default {
}
```
-那么 useRequest 就可以直接消费 `data`。其值为 123，而不是 `{ success, data, code }` 。
+Then useRequest can directly consume `data`. Its value will be 123, rather than `{ success, data, code }`.
-### 运行时配置
+### Runtime Configuration
-在 `src/app.ts` 中你可以通过配置 request 项，来为你的项目进行统一的个性化的请求设定。
+In `src/app.ts`, you can configure the `request` item to provide consistent personalized request settings for your project.
```ts
import type { RequestConfig } from 'umi';
@@ -46,9 +47,9 @@ export const request: RequestConfig = {
timeout: 1000,
// other axios options you want
errorConfig: {
- errorHandler(){
+ errorHandler() {
},
- errorThrower(){
+ errorThrower() {
}
},
requestInterceptors: [],
@@ -56,86 +57,87 @@ export const request: RequestConfig = {
};
```
-除了 `errorConfig`, `requestInterceptors`, `responseInterceptors` 以外其它配置都直接透传 [axios](https://axios-http.com/docs/req_config) 的 request 配置。**在这里配置的规则将应用于所有的** `request` 和 `useRequest` **方法**。
+Except for `errorConfig`, `requestInterceptors`, and `responseInterceptors`, other configurations are directly passed through to axios's request configuration. The rules configured here will apply to all `request` and `useRequest` methods.
-下面分别介绍 `plugin-request` 的运行时配置项。本节的末尾，我们会给出一个完整的运行时配置示例，并且对它的功能进行一个详细的描述。
+Below, we'll discuss the runtime configuration options for the `plugin-request`. At the end of this section, we'll provide a complete runtime configuration example and provide a detailed explanation of its functionality.
#### errorConfig
-如果你想要为自己的请求设定统一的错误处理方案，可以在这里进行配置。
+If you want to establish a unified error handling solution for your requests, you can configure it here.
-其中 `errorThrower` 接收你后端返回的数据并且需要抛出一个你自己设定的 error， 你可以在这里根据后端的数据进行一定的处理。
+The `errorThrower` takes the data returned by your backend and should throw an error that you define. You can process the backend data accordingly.
-我们的 `request` 会 catch `errorThrower` 抛出的错误，并且执行你的 `errorHandler` 方法，该方法接收两个参数，第一个参数是 catch 到的 error，第二个参数则是 request 的 opts。
+Our `request` will catch errors thrown by the `errorThrower` and execute your `errorHandler` function. This function receives two parameters: the caught error and the `opts` of the request.
-这里面的 `errorHandler` 和 `errorThrower` 需要配套使用。文档的末尾有一个完整的例子。
+The `errorHandler` and `errorThrower` need to be used together. A complete example is provided at the end of the documentation.
-如果你觉得这种方式进行错误处理过于繁琐，可以直接在拦截器中实现自己的错误处理。
+If you find this error handling method too cumbersome, you can directly implement your own error handling in interceptors.
-`errorThrower` 是利用 `responseInterceptors` 实现的，它的触发条件是: 当 `data.success` 为 `false` 时。
+`errorThrower` is implemented using `responseInterceptors`, and it is triggered when `data.success` is `false`.
#### requestInterceptors
-为 request 方法添加请求阶段的拦截器。
+Add request interceptors for the `request` method.
-传入一个数组，每个元素都是一个拦截器，它们会被按顺序依次注册到 axios 实例上。拦截器的写法同 axios request interceptor 一致，它需要接收 request config 作为参数，并且将它返回。
+Pass an array where each element is an interceptor. They will be registered on the axios instance in order. The format of interceptors is the same as axios request interceptors. They should accept the request config as a parameter and return it.
-我们建议你使用 `RequestConfig`，它能帮助你规范地书写你的拦截器。
+We recommend using `RequestConfig` to write your interceptors properly.
e.g.
```ts
const request: RequestConfig = {
requestInterceptors: [
- // 直接写一个 function，作为拦截器
+ // Write a function directly as an interceptor
(url, options) =>
{
// do something
return { url, options }
},
- // 一个二元组，第一个元素是 request 拦截器，第二个元素是错误处理
+ // A tuple where the first element is the request interceptor and the second is an error handler
[(url, options) => {return { url, options }}, (error) => {return Promise.reject(error)}],
- // 数组，省略错误处理
+ // Array, omitting the error handler
[(url, options) => {return { url, options }}]
]
}
```
-另外，为了更好的兼容 umi-request，我们允许 umi-request 的拦截器写法，尽管它不能够通过 typescript 的语法检查。
+Additionally, for better compatibility with umi-request, we allow the umi-request interceptor syntax here, even though it may not pass TypeScript's syntax check.
#### responseInterceptors
-为 request 方法添加响应阶段的拦截器。
+Add response interceptors for the `request` method.
-传入一个数组，每个元素都是一个拦截器，它们会被按顺序依次注册到 axios 实例上。拦截器的写法同 axios response interceptor一致。接收 axios 的 response 作为参数，并且将它返回。
+Pass an array where each element is an interceptor. They will be registered on the axios instance in order. The format of interceptors is the same as axios response interceptors. They should accept axios's response as a parameter and return it.
-我们建议你使用 `RequestConfig`，它能帮助你规范地书写你的拦截器。
+We recommend using `RequestConfig` to write your interceptors properly.
e.g.
```ts
const request: RequestConfig = {
responseInterceptors: [
- // 直接写一个 function，作为拦截器
+ // Write a function directly as an interceptor
(response) =>
{
- // 不再需要异步处理读取返回体内容，可直接在data中读出，部分字段可在 config 中找到
+ // You no longer need to asynchronously process the response body, you can directly read it from `data`, and some fields can be found in `config`
const { data = {} as any, config } = response;
// do something
return response
},
- // 一个二元组，第一个元素是 request 拦截器，第二个元素是错误处理
+ // A tuple where the first element is the response interceptor and the second is an error handler
[(response) => {return response}, (error) => {return Promise.reject(error)}],
- // 数组，省略错误处理
+ // Array, omitting the error handler
[(response) => {return response}]
]
}
```
-**注意： 我们会按照你的数组顺序依次注册拦截器，但是其执行顺序参考 axios，request 是后添加的在前，response 是后添加的在后**
+**Note: We will register interceptors in the order of your array, but their execution order follows axios's behavior – request interceptors added later will be executed first, while response interceptors added later will be executed last.**
## API
### useRequest
-插件内置了 [@ahooksjs/useRequest](https://ahooks-v2.js.org/hooks/async) ，你可以在组件内通过该 Hook 简单便捷的消费数据。示例如下：
+The plugin includes [@ahooksjs/useRequest](https://ahooks-v2.js.org/hooks/async). You can easily consume data in components using this hook. Here's an example:
+
```typescript
import { useRequest } from 'umi';
@@ -152,75 +154,80 @@ export default function Page() {
return
+`errorThrower` 是利用 `responseInterceptors` 实现的，它的触发条件是: 当 `data.success` 为 `false` 时。
+
+
+#### requestInterceptors
+为 request 方法添加请求阶段的拦截器。
+
+传入一个数组，每个元素都是一个拦截器，它们会被按顺序依次注册到 axios 实例上。拦截器的写法同 axios request interceptor 一致，它需要接收 request config 作为参数，并且将它返回。
+
+我们建议你使用 `RequestConfig`，它能帮助你规范地书写你的拦截器。
+
+e.g.
+```ts
+const request: RequestConfig = {
+ requestInterceptors: [
+ // 直接写一个 function，作为拦截器
+ (url, options) =>
+ {
+ // do something
+ return { url, options }
+ },
+ // 一个二元组，第一个元素是 request 拦截器，第二个元素是错误处理
+ [(url, options) => {return { url, options }}, (error) => {return Promise.reject(error)}],
+ // 数组，省略错误处理
+ [(url, options) => {return { url, options }}]
+ ]
+
+}
+```
+
+另外，为了更好的兼容 umi-request，我们允许 umi-request 的拦截器写法，尽管它不能够通过 typescript 的语法检查。
+
+#### responseInterceptors
+为 request 方法添加响应阶段的拦截器。
+
+传入一个数组，每个元素都是一个拦截器，它们会被按顺序依次注册到 axios 实例上。拦截器的写法同 axios response interceptor一致。接收 axios 的 response 作为参数，并且将它返回。
+
+我们建议你使用 `RequestConfig`，它能帮助你规范地书写你的拦截器。
+
+e.g.
+```ts
+const request: RequestConfig = {
+ responseInterceptors: [
+ // 直接写一个 function，作为拦截器
+ (response) =>
+ {
+ // 不再需要异步处理读取返回体内容，可直接在data中读出，部分字段可在 config 中找到
+ const { data = {} as any, config } = response;
+ // do something
+ return response
+ },
+ // 一个二元组，第一个元素是 request 拦截器，第二个元素是错误处理
+ [(response) => {return response}, (error) => {return Promise.reject(error)}],
+ // 数组，省略错误处理
+ [(response) => {return response}]
+ ]
+
+}
+```
+
+**注意： 我们会按照你的数组顺序依次注册拦截器，但是其执行顺序参考 axios，request 是后添加的在前，response 是后添加的在后**
+
+## API
+### useRequest
+插件内置了 [@ahooksjs/useRequest](https://ahooks-v2.js.org/hooks/async) ，你可以在组件内通过该 Hook 简单便捷的消费数据。示例如下：
+```typescript
+import { useRequest } from 'umi';
+
+export default function Page() {
+ const { data, error, loading } = useRequest(() => {
+ return services.getUserList('/api/test');
+ });
+ if (loading) {
+ return
+
+Max 项目
+
+```bash
+npx max g tailwindcss
+info - Update package.json for devDependencies
+set config:tailwindcss on /project/max-playground/.umirc.ts
+info - Update .umirc.ts
+info - Write tailwind.config.js
+info - Write tailwind.css
+```
+
+Umi 项目
+
+```bash
+npx umi g tailwindcss
+info - Update package.json for devDependencies
+set config:tailwindcss on /project/max-playground/.umirc.ts
+info - Update .umirc.ts
+info - Write tailwind.config.js
+info - Write tailwind.css
+```
+
+
+
+至此就可以在项目中使用 Tailwind CSS 的样式；项目根目录的 `tailwind.config.js` 和 `tailwind.css` 根据需要修改配置。
diff --git a/docs/docs/max/valtio.md b/docs/docs/max/valtio.md
index 0c3496e4594d..2831321ed3e8 100644
--- a/docs/docs/max/valtio.md
+++ b/docs/docs/max/valtio.md
@@ -1,38 +1,38 @@
# valtio
-@umijs/max 内置了 valtio 数据流方案。
+@umijs/max comes with the valtio state management solution.
-## 启用 valtio
+## Activation
-配置开启。
+Enable it through configuration.
```ts
export default {
valtio: {},
-}
+};
```
-## 开始使用
+## Getting Started
-### 基本用法
+### Basic Usage
-极其简单。
+It's incredibly simple.
```ts
import { proxy, useSnapshot } from 'umi';
-// 1、定义数据
+// 1. Define data
const state = proxy({ count: 0 });
-// 2、使用数据
+// 2. Use data
const snap = useSnapshot(state);
snap.count;
-// 3、更新数据
+// 3. Update data
state.count += 1;
```
-### React 外访问
+### Access Outside React
-天然支持。
+Natively supported.
```ts
import { proxy } from 'umi';
@@ -42,83 +42,86 @@ state.count;
state.count += 1;
```
-### 数据推导
+### Computed Data
```ts
import { proxyWithComputed } from 'umi';
-const state = proxyWithComputed({
- count: 0,
-}, {
- double: snap => snap.count * 2,
-});
+const state = proxyWithComputed(
+ {
+ count: 0,
+ },
+ {
+ double: snap => snap.count * 2,
+ }
+);
```
-### Action 和异步 Action
+### Actions and Async Actions
-两种用法，可以和 state 放一起，也可以分开。
+There are two ways to define actions: you can define them within the same object as the state, or separate them.
```ts
import { proxy } from 'umi';
-// 方法一：放一起
+// Method 1: Define together
const state = proxy({
count: 0,
actions: {
- add() {
- // 注意这里别用 this.count，基于 snap 调用时会报错
- state.count += 1;
- },
- }
+ add() {
+ // Note: Don't use this.count here, as calling this in relation to snap will cause an error
+ state.count += 1;
+ },
+ },
});
-// 方法二：分开放
+// Method 2: Define separately
const state = proxy({ count: 0 });
const actions = {
add() {
state.count += 1;
},
- // 异步 action
+ // Async action
async addAsync() {
state.count += await fetch('/api/add');
},
};
```
-### 数据结构的拆分与组合
+### Splitting and Combining Data Structures
```ts
import { proxy } from 'umi';
-// 比如如下定义
-// state.foo 和 state.bar 都是 proxy，可拆分使用
+// For example, defining as follows:
+// Both state.foo and state.bar are proxies and can be used separately
const state = proxy({
foo: { a: 1 },
bar: { b: 1 },
});
-// 组合
+// Combining
const foo = proxy({ a: 1 });
const bar = proxy({ b: 1 });
const state = proxy({ foo, bar });
```
-### 组件封装
+### Component Encapsulation
-如果 props 内容和 state 无关，可以不处理；如果有关，按以下方式用 context 包一下，同时做 props 到 state 的数据同步即可。
+If props are unrelated to state, they can be left as they are. If they are related, use the following method to wrap them in a context. Also, synchronize the data from props to state.
```ts
import { proxy } from 'umi';
-// 1、createContext
+// 1. Create Context
const MyContext = createContext();
-// 2、Provider
+// 2. Provider
const value = useRef(proxy({ count: 0 })).current;
-(val: V, opts: {
@@ -174,9 +180,11 @@ export function proxyWithPersist(val: V, opts: {
}
```
-### 兼容性
+### Compatibility
-1）需要 React 16.8 或以上，2）不支持 IE 11，3）map 和 set 不能直接用，需改用 valtio 提供的 proxyMap 和 proxySet。
+1. Requires React 16.8 or above.
+2. Does not support IE 11.
+3. Cannot directly use `map` and `set`, use `proxyMap` and `proxySet` provided by valtio.
```ts
import { proxy, proxyMap } from 'umi';
@@ -187,7 +195,6 @@ const state = proxy({
});
```
-### 测试
-
-可以直接测 store，也可以测基于 store 的 React 组件。正常写用例即可，后者推荐用 @testing-library/react。
+### Testing
+You can directly test the store or test React components based on the store. Write your test cases as usual. For the latter, it's recommended to use `@testing-library/react`.
\ No newline at end of file
diff --git a/docs/docs/max/valtio.zh-CN.md b/docs/docs/max/valtio.zh-CN.md
new file mode 100644
index 000000000000..0c3496e4594d
--- /dev/null
+++ b/docs/docs/max/valtio.zh-CN.md
@@ -0,0 +1,193 @@
+# valtio
+
+@umijs/max 内置了 valtio 数据流方案。
+
+## 启用 valtio
+
+配置开启。
+
+```ts
+export default {
+ valtio: {},
+}
+```
+
+## 开始使用
+
+### 基本用法
+
+极其简单。
+
+```ts
+import { proxy, useSnapshot } from 'umi';
+
+// 1、定义数据
+const state = proxy({ count: 0 });
+// 2、使用数据
+const snap = useSnapshot(state);
+snap.count;
+// 3、更新数据
+state.count += 1;
+```
+
+### React 外访问
+
+天然支持。
+
+```ts
+import { proxy } from 'umi';
+
+const state = proxy({ count: 0 });
+state.count;
+state.count += 1;
+```
+
+### 数据推导
+
+```ts
+import { proxyWithComputed } from 'umi';
+
+const state = proxyWithComputed({
+ count: 0,
+}, {
+ double: snap => snap.count * 2,
+});
+```
+
+### Action 和异步 Action
+
+两种用法，可以和 state 放一起，也可以分开。
+
+```ts
+import { proxy } from 'umi';
+
+// 方法一：放一起
+const state = proxy({
+ count: 0,
+ actions: {
+ add() {
+ // 注意这里别用 this.count，基于 snap 调用时会报错
+ state.count += 1;
+ },
+ }
+});
+// 方法二：分开放
+const state = proxy({ count: 0 });
+const actions = {
+ add() {
+ state.count += 1;
+ },
+ // 异步 action
+ async addAsync() {
+ state.count += await fetch('/api/add');
+ },
+};
+```
+
+### 数据结构的拆分与组合
+
+```ts
+import { proxy } from 'umi';
+
+// 比如如下定义
+// state.foo 和 state.bar 都是 proxy，可拆分使用
+const state = proxy({
+ foo: { a: 1 },
+ bar: { b: 1 },
+});
+
+// 组合
+const foo = proxy({ a: 1 });
+const bar = proxy({ b: 1 });
+const state = proxy({ foo, bar });
+```
+
+### 组件封装
+
+如果 props 内容和 state 无关，可以不处理；如果有关，按以下方式用 context 包一下，同时做 props 到 state 的数据同步即可。
+
+```ts
+import { proxy } from 'umi';
+
+// 1、createContext
+const MyContext = createContext();
+// 2、Provider
+const value = useRef(proxy({ count: 0 })).current;
+(val: V, opts: {
+ key: string;
+}) {
+ const local = localStorage.getItem(opts.key);
+ const state = proxy(local ? JSON.parse(local) : val);
+ subscribe(state, () => {
+ localStorage.setItem(opts.key, JSON.stringify(snapshot(state)));
+ });
+ return state;
+}
+```
+
+### 兼容性
+
+1）需要 React 16.8 或以上，2）不支持 IE 11，3）map 和 set 不能直接用，需改用 valtio 提供的 proxyMap 和 proxySet。
+
+```ts
+import { proxy, proxyMap } from 'umi';
+
+const state = proxy({
+ todos: proxyMap([[1, {id:1,text:'Learn Umi'}]]),
+ filter: 'all',
+});
+```
+
+### 测试
+
+可以直接测 store，也可以测基于 store 的 React 组件。正常写用例即可，后者推荐用 @testing-library/react。
+
diff --git a/docs/docs/tutorials/getting-started.md b/docs/docs/tutorials/getting-started.md
index 9fc51165ec48..87dc9aeb0333 100644
--- a/docs/docs/tutorials/getting-started.md
+++ b/docs/docs/tutorials/getting-started.md
@@ -1,12 +1,12 @@
import { Tabbed } from 'umi';
-# 快速上手
+# Getting Started
-## 环境准备
+## Environment Setup
-首先得有 node，并确保 node 版本是 14 或以上。（推荐用 [nvm](https://github.com/nvm-sh/nvm) 来管理 node 版本，windows 下推荐用 [nvm-windows](https://github.com/coreybutler/nvm-windows)）
+First, you need to have Node.js installed, and make sure the Node.js version is 14 or above. (It's recommended to use [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions. For Windows, you can use [nvm-windows](https://github.com/coreybutler/nvm-windows))
-mac 或 linux 下安装 nvm。
+Install nvm on macOS or Linux:
```bash
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
@@ -14,21 +14,21 @@ $ nvm -v
0.39.1
```
-安装 node。
+Install Node.js:
-```
+```bash
$ nvm install 16
$ nvm use 16
$ node -v
v16.10.0
```
-然后需要包管理工具。node 默认包含 npm，但也可以选择其他方案，
+Next, you need a package management tool. Node.js comes with npm by default, but you can also choose other options:
-* [pnpm](https://pnpm.io/installation), umi 团队推荐
+* [pnpm](https://pnpm.io/installation) (recommended by the Umi team)
* [Yarn](https://yarnpkg.com/getting-started/install)
-安装 pnpm。
+Install pnpm:
```bash
curl -fsSL https://get.pnpm.io/install.sh | sh -
@@ -36,14 +36,14 @@ $ pnpm -v
7.3.0
```
-## 创建项目
+## Create a Project
-先找个地方建个空目录。
+Start by creating an empty directory:
```bash
$ mkdir myapp && cd myapp
```
-通过官方工具创建项目，
+Create a project using the official tool:
@@ -137,29 +137,29 @@ info - generate files
```
-注：使用 bun 初始化项目会更快，需要 bun >= `0.4.0` 版本。
+Note: Using Bun to initialize the project will be faster, and you need bun version >= `0.4.0`.
-国内建议选 **pnpm + taobao 源**，速度提升明显。这一步会自动安装依赖，同时安装成功后会自动执行 `umi setup` 做一些文件预处理等工作。
+For users in China, it's recommended to choose **pnpm + taobao registry** for faster speed. This step will automatically install dependencies and execute `umi setup` after successful installation for some file preprocessing and other tasks.
-### 从模板创建项目
+### Create project from a template
```bash
- # 从 @umijs/electron-template 创建一个 electron 模板
+ # Create an Electron template from @umijs/electron-template
pnpm create umi --template electron
```
-### 参数选项
+### Parameter Options
-使用 `create-umi` 创建项目时，可用的参数如下：
+When creating a project using `create-umi`, you can use the following options:
option|description
:-:|:-
-`--no-git`|创建项目，但不初始化 Git
-`--no-install`|创建项目，但不自动安装依赖
+`--no-git`|Create the project, but don't initialize Git
+`--no-install`|Create the project, but don't automatically install dependencies
-## 启动项目
+## Start the Project
-执行 `pnpm dev` 命令，
+Execute the `pnpm dev` command:
```bash
$ pnpm dev
@@ -174,13 +174,13 @@ event - compiled successfully in 1121 ms (388 modules)
event - MFSU compiled successfully in 1308 ms (875 modules)
```
-在浏览器里打开 [http://localhost:8000/](http://localhost:8000/)，能看到以下界面，
+Open your browser and navigate to [http://localhost:8000/](http://localhost:8000/). You should see the following page:
-## 启用 Prettier（可选）
+## Enable Prettier (Optional)
-如果需要用 prettier 做项目代码的自动格式化，执行 `pnpm umi g`，
+If you want to use Prettier for automatic code formatting, execute `pnpm umi g`:
```bash
$ pnpm umi g
@@ -191,9 +191,9 @@ info - Write .prettierignore
info - Install dependencies with pnpm
```
-## 部署发布
+## Deploy and Publish
-执行 `pnpm build` 命令，
+Execute the `pnpm build` command:
```bash
> umi build
@@ -201,7 +201,7 @@ event - compiled successfully in 1179 ms (567 modules)
event - build index.html
```
-产物默认会生成到 `./dist` 目录下，
+The build output will be generated in the `./dist` directory:
```
./dist
@@ -210,4 +210,4 @@ event - build index.html
└── umi.js
```
-完成构建后，就可以把 dist 目录部署到服务器上了。
+After completing the build, you can deploy the `dist` directory to your server.
\ No newline at end of file
diff --git a/docs/docs/tutorials/getting-started.zh-CN.md b/docs/docs/tutorials/getting-started.zh-CN.md
new file mode 100644
index 000000000000..9fc51165ec48
--- /dev/null
+++ b/docs/docs/tutorials/getting-started.zh-CN.md
@@ -0,0 +1,213 @@
+import { Tabbed } from 'umi';
+
+# 快速上手
+
+## 环境准备
+
+首先得有 node，并确保 node 版本是 14 或以上。（推荐用 [nvm](https://github.com/nvm-sh/nvm) 来管理 node 版本，windows 下推荐用 [nvm-windows](https://github.com/coreybutler/nvm-windows)）
+
+mac 或 linux 下安装 nvm。
+
+```bash
+$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
+$ nvm -v
+0.39.1
+```
+
+安装 node。
+
+```
+$ nvm install 16
+$ nvm use 16
+$ node -v
+v16.10.0
+```
+
+然后需要包管理工具。node 默认包含 npm，但也可以选择其他方案，
+
+* [pnpm](https://pnpm.io/installation), umi 团队推荐
+* [Yarn](https://yarnpkg.com/getting-started/install)
+
+安装 pnpm。
+
+```bash
+curl -fsSL https://get.pnpm.io/install.sh | sh -
+$ pnpm -v
+7.3.0
+```
+
+## 创建项目
+
+先找个地方建个空目录。
+
+```bash
+$ mkdir myapp && cd myapp
+```
+通过官方工具创建项目，
+
+
+
+PNPM
+```bash
+$ pnpm dlx create-umi@latest
+✔ Install the following package: create-umi? (Y/n) · true
+✔ Pick Npm Client › pnpm
+✔ Pick Npm Registry › taobao
+Write: .gitignore
+Write: .npmrc
+Write: .umirc.ts
+Copy: layouts/index.tsx
+Write: package.json
+Copy: pages/index.tsx
+Copy: pages/users.tsx
+Copy: pages/users/foo.tsx
+> @ postinstall /private/tmp/sorrycc-vylwuW
+> umi setup
+info - generate files
+```
+
+BUN
+```bash
+$ bunx create-umi
+✔ Pick Umi App Template › Simple App
+✔ Pick Npm Client › pnpm
+✔ Pick Npm Registry › npm
+Write: .gitignore
+Write: .npmrc
+Write: .umirc.ts
+Write: package.json
+Copy: src/assets/yay.jpg
+Copy: src/layouts/index.less
+Write: src/layouts/index.tsx
+Copy: src/pages/docs.tsx
+Copy: src/pages/index.tsx
+Write: tsconfig.json
+Copy: typings.d.ts
+ready - Git initialized successfully
+```
+
+NPM
+```bash
+$ npx create-umi@latest
+Need to install the following packages:
+ create-umi@latest
+Ok to proceed? (y) y
+✔ Pick Umi App Template › Simple App
+✔ Pick Npm Client › npm
+✔ Pick Npm Registry › taobao
+Write: .gitignore
+Write: .npmrc
+Write: .umirc.ts
+Write: package.json
+Copy: src/assets/yay.jpg
+Copy: src/layouts/index.less
+Write: src/layouts/index.tsx
+Copy: src/pages/docs.tsx
+Copy: src/pages/index.tsx
+Write: tsconfig.json
+Copy: typings.d.ts
+
+> postinstall
+> umi setup
+```
+
+YARN
+```bash
+$ yarn create umi
+success Installed "create-umi@4.0.6" with binaries:
+ - create-umi
+✔ Pick Umi App Template › Simple App
+✔ Pick Npm Client › yarn
+✔ Pick Npm Registry › taobao
+Write: .gitignore
+Write: .npmrc
+Write: .umirc.ts
+Write: package.json
+Copy: src/assets/yay.jpg
+Copy: src/layouts/index.less
+Write: src/layouts/index.tsx
+Copy: src/pages/docs.tsx
+Copy: src/pages/index.tsx
+Write: tsconfig.json
+Copy: typings.d.ts
+yarn install v1.22.18
+success Saved lockfile.
+$ umi setup
+info - generate files
+```
+
+
+注：使用 bun 初始化项目会更快，需要 bun >= `0.4.0` 版本。
+
+国内建议选 **pnpm + taobao 源**，速度提升明显。这一步会自动安装依赖，同时安装成功后会自动执行 `umi setup` 做一些文件预处理等工作。
+
+### 从模板创建项目
+
+```bash
+ # 从 @umijs/electron-template 创建一个 electron 模板
+ pnpm create umi --template electron
+```
+
+### 参数选项
+
+使用 `create-umi` 创建项目时，可用的参数如下：
+
+option|description
+:-:|:-
+`--no-git`|创建项目，但不初始化 Git
+`--no-install`|创建项目，但不自动安装依赖
+
+## 启动项目
+
+执行 `pnpm dev` 命令，
+
+```bash
+$ pnpm dev
+ ╔═════════════════════════════════════════════════════╗
+ ║ App listening at: ║
+ ║ > Local: https://127.0.0.1:8000 ║
+ready - ║ > Network: https://192.168.1.1:8000 ║
+ ║ ║
+ ║ Now you can open browser with the above addresses👆 ║
+ ╚═════════════════════════════════════════════════════╝
+event - compiled successfully in 1121 ms (388 modules)
+event - MFSU compiled successfully in 1308 ms (875 modules)
+```
+
+在浏览器里打开 [http://localhost:8000/](http://localhost:8000/)，能看到以下界面，
+
+
+
+## 启用 Prettier（可选）
+
+如果需要用 prettier 做项目代码的自动格式化，执行 `pnpm umi g`，
+
+```bash
+$ pnpm umi g
+✔ Pick generator type › Enable Prettier -- Enable Prettier
+info - Write package.json
+info - Write .prettierrc
+info - Write .prettierignore
+info - Install dependencies with pnpm
+```
+
+## 部署发布
+
+执行 `pnpm build` 命令，
+
+```bash
+> umi build
+event - compiled successfully in 1179 ms (567 modules)
+event - build index.html
+```
+
+产物默认会生成到 `./dist` 目录下，
+
+```
+./dist
+├── index.html
+├── umi.css
+└── umi.js
+```
+
+完成构建后，就可以把 dist 目录部署到服务器上了。
diff --git a/docs/locales/en-US.json b/docs/locales/en-US.json
new file mode 100644
index 000000000000..a0a59d08c8d7
--- /dev/null
+++ b/docs/locales/en-US.json
@@ -0,0 +1,6 @@
+{
+ "Search anything ...": "Search anything ...",
+ "Docs": "Docs",
+ "Blog": "Blog",
+ "No result for": "No result for"
+}
diff --git a/theme.config.ts b/theme.config.ts
index 0b48af194974..e4958793f8d3 100644
--- a/theme.config.ts
+++ b/theme.config.ts
@@ -2,13 +2,14 @@ import UmiLogo from './packages/plugin-docs/client/theme-doc/icons/umi.png';
export default {
title: 'UmiJS',
- description: '插件化的企业级前端应用框架',
+ description: 'Plug-in enterprise-level front-end application framework',
+ 'description.zh-CN': '插件化的企业级前端应用框架',
logo: UmiLogo,
github: 'https://github.com/umijs/umi',
- // i18n: [
- // { locale: 'en-US', text: 'English' },
- // { locale: 'zh-CN', text: '简体中文' },
- // ],
+ i18n: [
+ { locale: 'en-US', text: 'English' },
+ { locale: 'zh-CN', text: '简体中文' },
+ ],
searchHotKey: {
macos: '⌘+K',
windows: 'ctrl+k',
{this.props.user.name}
;
+ }
+}
+
+export default UserInfo;
+```
+
+### 在组件中 dispatch 事件
+
+connect 方法同时也会添加 `dispatch` 到 `this.props` 上，你可以在用户触发某个事件的时候调用它来触发 model 中的 effects 或者 reducer 来修改 model 中的数据。如下所示：
+
+```javascript
+import React, { Component } from 'react';
+import { connect } from 'umi';
+
+@connect(({ user }) => ({
+ user,
+}))
+class UserInfo extends Component {
+ constructor(props) {
+ super(props);
+ }
+ render() {
+ return (
+ {
+ this.props.dispatch({
+ type: 'user/test',
+ });
+ }}
+ >
+ {this.props.user.name}
+
+ );
+ }
+}
+
+export default UserInfo;
+```
+
+### 修改数据
+
+dispatch 一个 action 之后会按照 action 中的 type 找到定义在 model 中的一个 effect 或者 reducer。
+
+如果是 effect，那么可以去请求后端数据，然后再触发一个 reducer 来修改数据。通过 reducer 修改数据之后组件便会按照最新的数据更新，至此，一次数据的流动就结束了。
+
+## 文档
+
+### model 定义
+
+一个 model 中可以定义如下几个部分：
+
+- namespace # model 的命名空间，唯一标识一个 model，如果与文件名相同可以省略不写
+- state # model 中的数据
+- effects # 异步 action，用来发送异步请求
+- reducers # 同步 action，用来修改 state
+
+### connect
+
+`connect` 的是用来将 model 和组件关联在一起的，它会将相关数据和 `dispatch` 添加到组件的 `props` 中。如下所示：
+
+```jsx
+import React, { Component } from 'react';
+import { connect } from 'umi';
+
+const mapModelToProps = allModels => {
+ return {
+ test: 'hello world',
+ // props you want connect to Component
+ };
+};
+
+@connect(mapModelToProps)
+class UserInfo extends Component {
+ render() {
+ return {this.props.test}
;
+ }
+}
+
+export default UserInfo;
+```
+
+推荐通过注解的方式调用 connect，它等同于 `export default connect(mapModelToProps)(UserInfo);`。connect 接收一个参数，是一个方法，在该方法中你接收到所有的 model 信息，需要返回要添加到 props 上的对象。在上面的例子中你就可以通过 `this.props.test` 得到 `hello world` 的字符串了。
+
+### dispatch
+
+在使用 `connect` 将组件和 model 关联在一起的同时框架也会添加一个 `this.props.dispatch` 的方法，通过该方法你可以触发一个 action 到 model 中。如下所示：
+
+```jsx
+render() {
+ return {
+ this.props.dispatch({
+ type: 'modelnamespace/actionname',
+ sometestdata: 'xxx',
+ othertestdata: {},
+ }).then(() => {
+ // it will return a promise
+ // action success
+ });
+ }}>test
+}
+```
+
+通过 `this.props.dispatch` 触发的 action 分为 effect 和 reducer 两类，下面是对他们的更多细节说明。
+
+### Reducer
+
+reducer 是一个函数，用来处理修改数据的逻辑（同步，不能请求后端）。接受 state 和 action，返回老的或新的 state 。即：`(state, action) => state`。
+
+#### 增删改
+
+以 todos 为例。
+
+```javascript
+exports default {
+ namespace: 'todos',
+ state: [],
+ reducers: {
+ add(state, { payload: todo }) {
+ return state.concat(todo);
+ },
+ remove(state, { payload: id }) {
+ return state.filter(todo => todo.id !== id);
+ },
+ update(state, { payload: updatedTodo }) {
+ return state.map(todo => {
+ if (todo.id === updatedTodo.id) {
+ return { ...todo, ...updatedTodo };
+ } else {
+ return todo;
+ }
+ });
+ },
+ },
+};
+```
+
+#### 嵌套数据的增删改
+
+建议最多一层嵌套，以保持 state 的扁平化，深层嵌套会让 reducer 很难写和难以维护。
+
+```javascript
+app.model({
+ namespace: 'app',
+ state: {
+ todos: [],
+ loading: false,
+ },
+ reducers: {
+ add(state, { payload: todo }) {
+ const todos = state.todos.concat(todo);
+ return { ...state, todos };
+ },
+ },
+});
+```
+
+下面是深层嵌套的例子，应尽量避免。
+
+```javascript
+app.model({
+ namespace: 'app',
+ state: {
+ a: {
+ b: {
+ todos: [],
+ loading: false,
+ },
+ },
+ },
+ reducers: {
+ add(state, { payload: todo }) {
+ const todos = state.a.b.todos.concat(todo);
+ const b = { ...state.a.b, todos };
+ const a = { ...state.a, b };
+ return { ...state, a };
+ },
+ },
+});
+```
+
+### Effect
+
+effects 是定义在 model 中的。它也是一种类型的 action，主要用于和后端的异步通讯。通过 effects 请求后端发送和接收必要的数据之后可以通过 put 方法再次发送一个 reducer 来修改数据。
+
+effect 通过 ES6 中 [Generator 函数](http://es6.ruanyifeng.com/#docs/generator) 来支持通过顺序的代码实现异步的请求，示例如下：
+
+```javascript
+export default {
+ namespace: 'todos',
+ effects: {
+ *addRemote({ payload: todo }, { put, call }) {
+ yield call(addTodo, todo);
+ yield put({ type: 'add', payload: todo });
+ },
+ },
+};
+```
+
+effects 中定义的 action 都必须是通过 `*` 定义的 Generator 函数，然后在函数中通过关键字 `yield` 来触发异步逻辑。
+
+#### Effects
+
+##### put
+
+用于触发 action 。
+
+```javascript
+yield put({ type: 'todos/add', payload: 'Learn Dva' });
+```
+
+##### call
+
+用于调用异步逻辑，支持 promise 。
+
+```javascript
+const result = yield call(fetch, '/todos');
+```
+
+##### select
+
+用于从 state 里获取数据。
+
+```javascript
+const todos = yield select(state => state.todos);
+```
+
+### loading
+
+框架会默认添加一个命名空间为 loading 的 model，该 model 包含 effects 异步加载 loading 的相关信息，它的 state 格式如下：
+
+```js
+{
+ global: Boolean, // 是否真正有异步请求发送中
+ models: {
+ [modelnamespace]: Boolean, // 具体每个 model 的加载情况
+ },
+ effects: {
+ [modelnamespace/effectname]: Boolean, // 具体每个 effect 的加载情况
+ },
+}
+```
+
+你可以使用该 model 实现在组件中添加 loading 动画。
+
+## 调试
+
+### redux
+
+dva 的底层是基于 redux，所以你可以安装 redux 的[开发者工具](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=zh-CN)用来查看 model 中的数据和变化的记录。
+
+
+
+## 参考文章
+
+- [dva 官网](https://dvajs.com/)
diff --git a/docs/docs/max/i18n.md b/docs/docs/max/i18n.md
index dc8c2271758e..d8d232a04110 100644
--- a/docs/docs/max/i18n.md
+++ b/docs/docs/max/i18n.md
@@ -1,16 +1,16 @@
import { Message } from 'umi';
-# 国际化
+# Internationalization
-`@umi/max` 内置了[国际化插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/locale.ts)，它可以轻松地将国际化功能集成到你的 Umi 应用程序之中。
+`@umi/max` comes with a built-in [Internationalization (i18n) plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/locale.ts) that makes it easy to integrate internationalization features into your Umi application.
-## 开始使用
+## Getting Started
-国际化插件采用约定式目录结构，我们约定在 `src/locales` 目录下引入多语言文件。
+The internationalization plugin uses a conventional directory structure. We agree to import language files under the `src/locales` directory.
-多语言文件的命名需遵循此规范：`Welcome to Umi's world!
```
-## 在组件的参数中使用
+## Using in Component Parameters
-在某些情况下，您需要将多语言内容作为参数传递给某个组件。可以通过 `intl` 对象来实现：
+In some cases, you might need to pass localized content as parameters to a component. You can achieve this using the `intl` object:
```tsx
import { Alert } from 'antd';
@@ -106,13 +106,13 @@ export default function Page() {
};
```
-在底层，国际化插件基于 [`react-intl`](https://github.com/formatjs/formatjs/tree/main/packages/react-intl) 封装，并支持它的所有接口，详情可见[此文档](https://github.com/formatjs/formatjs/blob/main/website/docs/react-intl/api.md)。
+At its core, the internationalization plugin is based on [`react-intl`](https://github.com/formatjs/formatjs/tree/main/packages/react-intl) and supports all its interfaces. For more details, see the [documentation](https://github.com/formatjs/formatjs/blob/main/website/docs/react-intl/api.md).
-在上面的代码中，我们就运用到了 `react-intl` 提供的 `useIntl()` 接口来初始化 `intl` 对象，并调用此对象的 [`formatMessage()`](https://github.com/formatjs/formatjs/blob/main/website/docs/react-intl/api.md#formatmessage) 方法来格式化字符串。
+In the above code, we used the `useIntl()` interface provided by `react-intl` to initialize the `intl` object and called its [`formatMessage()`](https://github.com/formatjs/formatjs/blob/main/website/docs/react-intl/api.md#formatmessage) method to format the string.
-## 格式化字符串
+## Formatting Strings
-您可能想要在多语言翻译中动态插值，那么可以像这样编写多语言内容：
+You might want to dynamically interpolate values in your localized translations. You can achieve this by writing your language content like this:
```ts
// src/locales/zh-CN.ts
@@ -132,7 +132,7 @@ export default {
};
```
-在上面，我们编写了特殊的语法 `{name}`，这允许我们在运行时动态赋值：
+In the examples above, we used the special syntax `{name}` which allows us to dynamically assign values at runtime:
```tsx
import { FormattedMessage } from 'umi';
@@ -146,7 +146,7 @@ export default function Page() {
};
```
-如果您希望通过 `intl` 对象来实现，那么可以这样对它赋值：
+If you prefer to use the `intl` object, you can assign it like this:
```tsx
import { useIntl } from 'umi';
@@ -166,9 +166,9 @@ export default function Page() {
};
```
-注意，用于赋值的键值对对象应当作为 `formatMessage()` 方法的第二个参数传递。
+Note that the key-value object used for assignment should be passed as the second argument to the `formatMessage()` method.
-渲染的结果如下：
+The rendered result will be:
```html
@@ -178,9 +178,9 @@ export default function Page() {
张三, what a nice day!
``` -## 切换语言 +## Switching Languages -通过预设的 `
+
+ );
+};
+```
+
+渲染的结果如下：
+
+```html
+
+欢迎光临 Umi 的世界！
+
+
+Welcome to Umi's world!
+```
+
+## 在组件的参数中使用
+
+在某些情况下，您需要将多语言内容作为参数传递给某个组件。可以通过 `intl` 对象来实现：
+
+```tsx
+import { Alert } from 'antd';
+import { useIntl } from 'umi';
+
+export default function Page() {
+ const intl = useIntl();
+ const msg = intl.formatMessage({
+ id: 'welcome',
+ });
+
+ return
+
{msg}
; +}; +``` + +注意，用于赋值的键值对对象应当作为 `formatMessage()` 方法的第二个参数传递。 + +渲染的结果如下： + +```html + +张三，今天也是美好的一天！
+ + +张三, what a nice day!
+``` + +## 切换语言 + +通过预设的 `
+
+ );
+};
+```
+
+[示例代码](https://github.com/umijs/umi/blob/master/examples/mf-host/src/pages/safe-remote-component.tsx)
+
+### rawMfImport
+
+加载远端模块，接口如下。
+
+```ts
+rawMfImport(opts: {
+ entry: string;
+ remoteName: string;
+ moduleName: string;
+}): Promise
@@ -474,15 +474,15 @@ export const qiankun = {
```
-### 子应用加载动画
+### Child App Loading Animation
-启用此能力后，当子应用正在加载时，会自动显示加载动画。当子应用挂载完成变成 `MOUNTED` 状态时，加载状态结束，显示子应用内容。
+When this feature is enabled, an automatic loading animation will be displayed while the child app is loading. When the child app finishes mounting and transitions to the `MOUNTED` state, the loading state ends and the child app content is displayed.
-#### 基于 antd 的加载动画
+#### Ant Design-Based Loading Animation
-当您使用 antd 作为项目组件库时，可以向子应用传入 `autoSetLoading` 属性以开启子应用加载动画，插件将会自动调用 antd 的 [`{JSON.stringify(masterProps)}
;
+};
+```
+
+或者可以通过高阶方法 `connectMaster()` 来获取并消费父应用透传的数据，如下所示：
+
+```tsx
+import { connectMaster } from 'umi';
+
+function MyPage(props) {
+ return {JSON.stringify(props)}
;
+}
+
+export default connectMaster(MyPage);
+```
+
+子应用也可以在生命周期钩子中能够获取并消费得到的 `props` 属性，根据需求[实现对应的生命周期钩子](#子应用配置生命周期钩子)即可。
+
+特别的，当父应用使用 `
+
+```
+
+### 子应用加载动画
+
+启用此能力后，当子应用正在加载时，会自动显示加载动画。当子应用挂载完成变成 `MOUNTED` 状态时，加载状态结束，显示子应用内容。
+
+#### 基于 antd 的加载动画
+
+当您使用 antd 作为项目组件库时，可以向子应用传入 `autoSetLoading` 属性以开启子应用加载动画，插件将会自动调用 antd 的 [`{data.name}
;
};
```
-上面代码中 data 并不是你后端返回的数据，而是其内部的 data，（因为构建时配置默认是 'data')
-需要注意的是，ahooks 已经更新到3.0，而我们为了让 `umi@3` 的项目升级起来不那么困难，继续沿用了 ahooks2.0
+In the above code, `data` is not the data returned by your backend, but the internal `data` of the hook (due to the default `dataField` set in build-time configuration).
+Please note that ahooks has been updated to version 3.0. However, we've continued using ahooks 2.0 to make upgrading `umi@3` projects to `umi@4` easier.
### request
-通过 `import { request } from '@@/plugin-request'` 你可以使用内置的请求方法。
+You can use the built-in request method by importing `request` from `'@@/plugin-request'`.
+
+`request` accepts `options` in addition to passing through all axios config. We've also added several additional properties: `skipErrorHandler`, `getResponse`, `requestInterceptors`, and `responseInterceptors`.
-`request` 接收的 `options`除了透传 [axios](https://axios-http.com/docs/req_config) 的所有 config 之外，我们还额外添加了几个属性 `skipErrorHandler`，`getResponse`，`requestInterceptors` 和 `responseInterceptors` 。
+Here's an example:
-示例如下：
```typescript
request('/api/user', {
- params: { name : 1 },
+ params: { name: 1 },
timeout: 2000,
// other axios options
skipErrorHandler: true,
getResponse: false,
requestInterceptors: [],
responseInterceptors: [],
-}
+});
```
-当你的某个请求想要跳过错误处理时，可以通过将`skipErrorHandler`设为 `true` 来实现
+You can set `skipErrorHandler` to `true` if you want to skip error handling for a specific request.
+
+By default, `request` returns the data from your backend. If you want to get
-request 默认返回的是你后端的数据，如果你想要拿到 axios 完整的 response 结构，可以通过传入 `{ getResponse: true }` 来实现。
+ the complete axios response structure, you can pass `{ getResponse: true }`.
-`requestInterceptors` 和 `responseInterceptors` 的写法同运行时配置中的拦截器写法相同，它们为 request 注册拦截器。区别在于这里注册的拦截器是 "一次性" 的。另外，这里写的拦截器会在运行时配置中的拦截器之后被注册。
+The syntax for `requestInterceptors` and `responseInterceptors` is the same as the interceptors in runtime configuration. These interceptors are registered for a single request only. Also, interceptors registered here will be executed after the interceptors from the runtime configuration.
-**注意： 当你使用了 errorHandler 时，在这里注册的 response 拦截器会失效，因为在 errorHandler 就会 throw error**
+**Note: When you use an `errorHandler`, response interceptors registered here will be ineffective because the errorHandler will throw an error.**
### RequestConfig
-这是一个接口的定义，可以帮助你更好地配置运行时配置。
+This is the interface definition that helps you properly configure the runtime configuration.
+
```typescript
import type { RequestConfig } from 'umi';
-export const request:RequestConfig = {};
+export const request: RequestConfig = {};
```
-注意，在导入时要加 type
-## umi@3 到 umi@4
-在 `umi@3` 到 `umi@4` 的升级中，我们弃用了 umi-request ，选用了 axios 作为默认的请求方案。在这个更换中，我们的功能也发生了一些变化。
+Note that you need to use `type` when importing it.
+
+## Transition from umi@3 to umi@4
+During the transition from `umi@3` to `umi@4`, we've deprecated umi-request and adopted axios as the default request solution. This change has resulted in some differences in functionality.
+
+### Changes to Runtime Configuration
+Compared to `umi@3`, the runtime configuration in `umi@4` has undergone significant changes:
-### 运行时配置的变动
-相比于 `umi@3`， `umi@4` 的运行时配置发生了较大的变化。
```diff
- export const request: RequestConfig = {
- errorConfig: {
-++ errorHandler: () => {},
-++ errorThrower: () => {}
--- errorPage: '',
--- adaptor: ()=>{},
- };
--- middlewares: [],
-++ requestInterceptors: [],
-++ responseInterceptors: [],
- ... // umi-request 和 axios 的区别。
- };
+export const request: RequestConfig = {
+ errorConfig: {
+++ errorHandler: () => {},
+++ errorThrower: () => {}
+-- errorPage: '',
+-- adaptor: () => {},
+ };
+--middlewares: [],
+++requestInterceptors: [],
+++responseInterceptors: [],
+ ... // Differences between umi-request and axios.
+};
```
-- umi-request 的配置项变成了 axios 的配置项
-- 去除了 middlewares 中间件。你可以使用 axios 的 [拦截器](https://axios-http.com/docs/interceptors) 来实现相同的功能。
-- errorConfig 删除了原来的所有配置，新增了 errorHandler 和 errorThrower 来进行统一错误处理的设定。
+- umi-request configurations have become axios configurations.
+- The `middlewares` middleware has been removed. You can use axios [interceptors](https://axios-http.com/docs/interceptors) to achieve the same functionality.
+- The `errorConfig` has removed previous configurations and added `errorHandler` and `errorThrower` for unified error handling settings.
-中间件的替换方式。对于一个 `umi@3` 的中间件，`next()` 方法之前的需要放在 `requestInterceptors` 中，`next()` 方法之后的内容则需要放在 `responseInterceptors` 中。
+To replace middleware, for a middleware used in `umi@3`, content before the `next()` function should be placed in `requestInterceptors`, and content after `next()` should be placed in `responseInterceptors`.
```ts
-
-// 中间件
+// Middleware
async function middleware(ctx, next) {
const { url, options } = req;
if (url.indexOf('/api') !== 0) {
@@ -232,9 +239,9 @@ async function middleware(ctx, next) {
}
}
-// 拦截器
+// Interceptors
{
- requestInterceptors:[
+ requestInterceptors: [
(config) => {
if (config.url.indexOf('/api') !== 0) {
config.url = `/api/v1/${url}`;
@@ -243,21 +250,24 @@ async function middleware(ctx, next) {
}
],
responseInterceptors: [
- (response) => {
- if(!response.data.success){
- // do something
+ (response) => {
+ if (!response.data.success) {
+ // do something
+ }
}
- }
]
}
```
-### request 方法的参数变动
-[umi-request](https://github.com/umijs/umi-request#request-options) 和 [axios](https://axios-http.com/docs/req_config) 的配置项有着一定的区别。具体可以查看其各自的文档进行比较。
+### Changes to the `request` Method Parameters
+The configuration options for [umi-request](https://github.com/umijs/umi-request#request-options) and [axios](https://axios-http.com/docs/req_config) are slightly different. You can compare their respective documentation for details.
-### GET 请求参数序列化
+Sure, here's the translation of the additional content you provided:
-[Umi@3](https://github.com/umijs/umi-request/blob/master/src/middleware/simpleGet.js) 默认会用相同的 Key 来序列化数组。Umi@4 请求基于 axios，默认是带括号 `[]` 的形式序列化。
+```markdown
+### Serialization of GET Request Parameters
+
+[Umi@3](https://github.com/umijs/umi-request/blob/master/src/middleware/simpleGet.js) serializes arrays with the same key. In Umi@4, requests are based on axios and use parentheses `[]` to serialize arrays by default.
```tsx
// Umi@3
@@ -269,7 +279,7 @@ import { useRequest } from '@umijs/max';
// a: [1,2,3] => a[]=1&a[]=2&a[]=3
```
-如果希望保持 Umi@3 这种形式，可以这样做：
+If you want to maintain the Umi@3 serialization format, you can do it like this:
```ts
// src/app.[ts|tsx]
@@ -285,13 +295,13 @@ export const request: RequestConfig = {
}
```
-## 运行时配置示例
-这里给出一个完整的运行时配置示例，以帮助你能够更好的去为自己的项目设定个性化的请求方案。
+## Example of Runtime Configuration
+Here's a complete example of runtime configuration to help you better customize the request settings for your project.
```ts
import { RequestConfig } from './request';
-// 错误处理方案： 错误类型
+// Error handling solution: error types
enum ErrorShowType {
SILENT = 0,
WARN_MESSAGE = 1,
@@ -299,7 +309,7 @@ enum ErrorShowType {
NOTIFICATION = 3,
REDIRECT = 9,
}
-// 与后端约定的响应数据格式
+// Response data format agreed upon with the backend
interface ResponseStructure {
success: boolean;
data: any;
@@ -308,28 +318,28 @@ interface ResponseStructure {
showType?: ErrorShowType;
}
-// 运行时配置
+// Runtime configuration
export const request: RequestConfig = {
- // 统一的请求设定
+ // Uniform request settings
timeout: 1000,
headers: {'X-Requested-With': 'XMLHttpRequest'},
- // 错误处理： umi@3 的错误处理方案。
+ // Error handling: Umi@3 error handling solution.
errorConfig: {
- // 错误抛出
+ // Error thrower
errorThrower: (res: ResponseStructure) => {
const { success, data, errorCode, errorMessage, showType } = res;
if (!success) {
const error: any = new Error(errorMessage);
error.name = 'BizError';
error.info = { errorCode, errorMessage, showType, data };
- throw error; // 抛出自制的错误
+ throw error; // Throw a custom error
}
},
- // 错误接收及处理
+ // Error receiver and handler
errorHandler: (error: any, opts: any) => {
if (opts?.skipErrorHandler) throw error;
- // 我们的 errorThrower 抛出的错误。
+ // Our errorThrower-generated error.
if (error.name === 'BizError') {
const errorInfo: ResponseStructure | undefined = error.info;
if (errorInfo) {
@@ -358,38 +368,37 @@ export const request: RequestConfig = {
}
}
} else if (error.response) {
- // Axios 的错误
- // 请求成功发出且服务器也响应了状态码，但状态代码超出了 2xx 的范围
+ // Axios error
+ // The request was successfully sent and the server responded with a status code, but the status code is outside the 2xx range
message.error(`Response status:${error.response.status}`);
} else if (error.request) {
- // 请求已经成功发起，但没有收到响应
- // \`error.request\` 在浏览器中是 XMLHttpRequest 的实例，
- // 而在node.js中是 http.ClientRequest 的实例
+ // The request was successfully sent, but no response was received
+ // \`error.request\` is an instance of XMLHttpRequest in the browser and an instance of http.ClientRequest in Node.js
message.error('None response! Please retry.');
} else {
- // 发送请求时出了点问题
+ // Something went wrong while sending the request
message.error('Request error, please retry.');
}
},
},
- // 请求拦截器
+ // Request interceptors
requestInterceptors: [
(config) => {
- // 拦截请求配置，进行个性化处理。
+ // Intercept request configuration for individualized processing.
const url = config.url.concat('?token = 123');
return { ...config, url};
}
],
- // 响应拦截器
+ // Response interceptors
responseInterceptors: [
(response) => {
- // 拦截响应数据，进行个性化处理
+ // Intercept response data for individualized processing
const { data } = response;
if(!data.success){
- message.error('请求失败！');
+ message.error('Request failed!');
}
return response;
}
@@ -397,6 +406,7 @@ export const request: RequestConfig = {
};
```
-上面的例子中的错误处理方案来自于 `umi@3` 的内置错误处理。在这个版本中，我们把它删除了，以方便用户更加自由地定制错误处理方案。如果你仍然想要使用它，可以将这段运行时配置粘贴到你的项目中。
+The error handling solution in the example above comes from `umi@3`'s built-in error handling. In this version, we removed it to allow users more freedom in customizing error handling solutions. If you still want to use it, you can paste this runtime configuration into your project.
-你也可以通过写响应拦截器的方式来进行自己的错误处理，**不一定局限于 errorConfig**。
+You can also implement your own error handling by writing response interceptors, **not limited to errorConfig**.
+```
diff --git a/docs/docs/max/request.zh-CN.md b/docs/docs/max/request.zh-CN.md
new file mode 100644
index 000000000000..e3143b5653da
--- /dev/null
+++ b/docs/docs/max/request.zh-CN.md
@@ -0,0 +1,402 @@
+import { Message } from 'umi';
+
+# 请求
+
+`@umijs/max` 内置了插件方案。它基于 [axios](https://axios-http.com/) 和 [ahooks](https://ahooks-v2.surge.sh) 的 `useRequest` 提供了一套统一的网络请求和错误处理方案。
+
+```js
+import { request, useRequest } from 'umi';
+
+request;
+useRequest;
+```
+
+## 配置
+### 构建时配置
+```js
+export default {
+ request: {
+ dataField: 'data'
+ },
+};
+```
+
+构建时配置可以为 useRequest 配置 `dataField` ，该配置的默认值是 `data`。该配置的主要目的是方便 useRequest 直接消费数据。如果你想要在消费数据时拿到后端的原始数据，需要在这里配置 `dataField` 为 `''` 。
+
+比如你的后端返回的数据格式如下。
+
+```js
+{
+ success: true,
+ data: 123,
+ code: 1,
+}
+```
+
+那么 useRequest 就可以直接消费 `data`。其值为 123，而不是 `{ success, data, code }` 。
+
+### 运行时配置
+
+在 `src/app.ts` 中你可以通过配置 request 项，来为你的项目进行统一的个性化的请求设定。
+
+```ts
+import type { RequestConfig } from 'umi';
+
+export const request: RequestConfig = {
+ timeout: 1000,
+ // other axios options you want
+ errorConfig: {
+ errorHandler(){
+ },
+ errorThrower(){
+ }
+ },
+ requestInterceptors: [],
+ responseInterceptors: []
+};
+```
+
+除了 `errorConfig`, `requestInterceptors`, `responseInterceptors` 以外其它配置都直接透传 [axios](https://axios-http.com/docs/req_config) 的 request 配置。**在这里配置的规则将应用于所有的** `request` 和 `useRequest` **方法**。
+
+下面分别介绍 `plugin-request` 的运行时配置项。本节的末尾，我们会给出一个完整的运行时配置示例，并且对它的功能进行一个详细的描述。
+
+#### errorConfig
+如果你想要为自己的请求设定统一的错误处理方案，可以在这里进行配置。
+
+其中 `errorThrower` 接收你后端返回的数据并且需要抛出一个你自己设定的 error， 你可以在这里根据后端的数据进行一定的处理。
+
+我们的 `request` 会 catch `errorThrower` 抛出的错误，并且执行你的 `errorHandler` 方法，该方法接收两个参数，第一个参数是 catch 到的 error，第二个参数则是 request 的 opts。
+
+这里面的 `errorHandler` 和 `errorThrower` 需要配套使用。文档的末尾有一个完整的例子。
+
+如果你觉得这种方式进行错误处理过于繁琐，可以直接在拦截器中实现自己的错误处理。
+
+loading...
;
+ }
+ if (error) {
+ return {error.message}
;
+ }
+ return {data.name}
;
+};
+```
+上面代码中 data 并不是你后端返回的数据，而是其内部的 data，（因为构建时配置默认是 'data')
+
+需要注意的是，ahooks 已经更新到3.0，而我们为了让 `umi@3` 的项目升级起来不那么困难，继续沿用了 ahooks2.0
+
+
+### request
+通过 `import { request } from '@@/plugin-request'` 你可以使用内置的请求方法。
+
+`request` 接收的 `options`除了透传 [axios](https://axios-http.com/docs/req_config) 的所有 config 之外，我们还额外添加了几个属性 `skipErrorHandler`，`getResponse`，`requestInterceptors` 和 `responseInterceptors` 。
+
+示例如下：
+```typescript
+request('/api/user', {
+ params: { name : 1 },
+ timeout: 2000,
+ // other axios options
+ skipErrorHandler: true,
+ getResponse: false,
+ requestInterceptors: [],
+ responseInterceptors: [],
+}
+```
+
+当你的某个请求想要跳过错误处理时，可以通过将`skipErrorHandler`设为 `true` 来实现
+
+request 默认返回的是你后端的数据，如果你想要拿到 axios 完整的 response 结构，可以通过传入 `{ getResponse: true }` 来实现。
+
+`requestInterceptors` 和 `responseInterceptors` 的写法同运行时配置中的拦截器写法相同，它们为 request 注册拦截器。区别在于这里注册的拦截器是 "一次性" 的。另外，这里写的拦截器会在运行时配置中的拦截器之后被注册。
+
+**注意： 当你使用了 errorHandler 时，在这里注册的 response 拦截器会失效，因为在 errorHandler 就会 throw error**
+
+### RequestConfig
+这是一个接口的定义，可以帮助你更好地配置运行时配置。
+```typescript
+import type { RequestConfig } from 'umi';
+
+export const request:RequestConfig = {};
+```
+注意，在导入时要加 type
+
+## umi@3 到 umi@4
+在 `umi@3` 到 `umi@4` 的升级中，我们弃用了 umi-request ，选用了 axios 作为默认的请求方案。在这个更换中，我们的功能也发生了一些变化。
+
+### 运行时配置的变动
+相比于 `umi@3`， `umi@4` 的运行时配置发生了较大的变化。
+```diff
+ export const request: RequestConfig = {
+ errorConfig: {
+++ errorHandler: () => {},
+++ errorThrower: () => {}
+-- errorPage: '',
+-- adaptor: ()=>{},
+ };
+-- middlewares: [],
+++ requestInterceptors: [],
+++ responseInterceptors: [],
+ ... // umi-request 和 axios 的区别。
+ };
+```
+
+- umi-request 的配置项变成了 axios 的配置项
+- 去除了 middlewares 中间件。你可以使用 axios 的 [拦截器](https://axios-http.com/docs/interceptors) 来实现相同的功能。
+- errorConfig 删除了原来的所有配置，新增了 errorHandler 和 errorThrower 来进行统一错误处理的设定。
+
+中间件的替换方式。对于一个 `umi@3` 的中间件，`next()` 方法之前的需要放在 `requestInterceptors` 中，`next()` 方法之后的内容则需要放在 `responseInterceptors` 中。
+
+```ts
+
+// 中间件
+async function middleware(ctx, next) {
+ const { url, options } = req;
+ if (url.indexOf('/api') !== 0) {
+ ctx.req.url = `/api/v1/${url}`;
+ }
+ await next();
+ if (!ctx.res.success) {
+ // do something
+ }
+}
+
+// 拦截器
+{
+ requestInterceptors:[
+ (config) => {
+ if (config.url.indexOf('/api') !== 0) {
+ config.url = `/api/v1/${url}`;
+ }
+ return config;
+ }
+ ],
+ responseInterceptors: [
+ (response) => {
+ if(!response.data.success){
+ // do something
+ }
+ }
+ ]
+}
+```
+
+### request 方法的参数变动
+[umi-request](https://github.com/umijs/umi-request#request-options) 和 [axios](https://axios-http.com/docs/req_config) 的配置项有着一定的区别。具体可以查看其各自的文档进行比较。
+
+### GET 请求参数序列化
+
+[Umi@3](https://github.com/umijs/umi-request/blob/master/src/middleware/simpleGet.js) 默认会用相同的 Key 来序列化数组。Umi@4 请求基于 axios，默认是带括号 `[]` 的形式序列化。
+
+```tsx
+// Umi@3
+import { useRequest } from 'umi';
+// a: [1,2,3] => a=1&a=2&a=3
+
+// Umi@4
+import { useRequest } from '@umijs/max';
+// a: [1,2,3] => a[]=1&a[]=2&a[]=3
+```
+
+如果希望保持 Umi@3 这种形式，可以这样做：
+
+```ts
+// src/app.[ts|tsx]
+
+/** @doc https://github.com/sindresorhus/query-string#arrayformat-1 */
++ import queryString from 'query-string';
+
+export const request: RequestConfig = {
++ paramsSerializer(params) {
++ return queryString.stringify(params);
++ },
+ ...
+}
+```
+
+## 运行时配置示例
+这里给出一个完整的运行时配置示例，以帮助你能够更好的去为自己的项目设定个性化的请求方案。
+
+```ts
+import { RequestConfig } from './request';
+
+// 错误处理方案： 错误类型
+enum ErrorShowType {
+ SILENT = 0,
+ WARN_MESSAGE = 1,
+ ERROR_MESSAGE = 2,
+ NOTIFICATION = 3,
+ REDIRECT = 9,
+}
+// 与后端约定的响应数据格式
+interface ResponseStructure {
+ success: boolean;
+ data: any;
+ errorCode?: number;
+ errorMessage?: string;
+ showType?: ErrorShowType;
+}
+
+// 运行时配置
+export const request: RequestConfig = {
+ // 统一的请求设定
+ timeout: 1000,
+ headers: {'X-Requested-With': 'XMLHttpRequest'},
+
+ // 错误处理： umi@3 的错误处理方案。
+ errorConfig: {
+ // 错误抛出
+ errorThrower: (res: ResponseStructure) => {
+ const { success, data, errorCode, errorMessage, showType } = res;
+ if (!success) {
+ const error: any = new Error(errorMessage);
+ error.name = 'BizError';
+ error.info = { errorCode, errorMessage, showType, data };
+ throw error; // 抛出自制的错误
+ }
+ },
+ // 错误接收及处理
+ errorHandler: (error: any, opts: any) => {
+ if (opts?.skipErrorHandler) throw error;
+ // 我们的 errorThrower 抛出的错误。
+ if (error.name === 'BizError') {
+ const errorInfo: ResponseStructure | undefined = error.info;
+ if (errorInfo) {
+ const { errorMessage, errorCode } = errorInfo;
+ switch (errorInfo.showType) {
+ case ErrorShowType.SILENT:
+ // do nothing
+ break;
+ case ErrorShowType.WARN_MESSAGE:
+ message.warn(errorMessage);
+ break;
+ case ErrorShowType.ERROR_MESSAGE:
+ message.error(errorMessage);
+ break;
+ case ErrorShowType.NOTIFICATION:
+ notification.open({
+ description: errorMessage,
+ message: errorCode,
+ });
+ break;
+ case ErrorShowType.REDIRECT:
+ // TODO: redirect
+ break;
+ default:
+ message.error(errorMessage);
+ }
+ }
+ } else if (error.response) {
+ // Axios 的错误
+ // 请求成功发出且服务器也响应了状态码，但状态代码超出了 2xx 的范围
+ message.error(`Response status:${error.response.status}`);
+ } else if (error.request) {
+ // 请求已经成功发起，但没有收到响应
+ // \`error.request\` 在浏览器中是 XMLHttpRequest 的实例，
+ // 而在node.js中是 http.ClientRequest 的实例
+ message.error('None response! Please retry.');
+ } else {
+ // 发送请求时出了点问题
+ message.error('Request error, please retry.');
+ }
+ },
+
+ },
+
+ // 请求拦截器
+ requestInterceptors: [
+ (config) => {
+ // 拦截请求配置，进行个性化处理。
+ const url = config.url.concat('?token = 123');
+ return { ...config, url};
+ }
+ ],
+
+ // 响应拦截器
+ responseInterceptors: [
+ (response) => {
+ // 拦截响应数据，进行个性化处理
+ const { data } = response;
+ if(!data.success){
+ message.error('请求失败！');
+ }
+ return response;
+ }
+ ]
+};
+```
+
+上面的例子中的错误处理方案来自于 `umi@3` 的内置错误处理。在这个版本中，我们把它删除了，以方便用户更加自由地定制错误处理方案。如果你仍然想要使用它，可以将这段运行时配置粘贴到你的项目中。
+
+你也可以通过写响应拦截器的方式来进行自己的错误处理，**不一定局限于 errorConfig**。
diff --git a/docs/docs/max/styled-components.md b/docs/docs/max/styled-components.md
index c7c8eff1148d..9eebef2ddec7 100644
--- a/docs/docs/max/styled-components.md
+++ b/docs/docs/max/styled-components.md
@@ -1,10 +1,10 @@
# styled-components
-@umijs/max 内置了 [styled-components](https://styled-components.com/) 样式方案。
+`@umijs/max` comes with built-in support for the [styled-components](https://styled-components.com/) styling solution.
-## 启用方式
+## Activation
-如果是 @umijs/max，配置开启。
+If you're using `@umijs/max`, enable it by configuring the following:
```ts {2}
export default {
@@ -12,7 +12,7 @@ export default {
}
```
-如果是 umi，先安装 `@umijs/plugins` 依赖，再通过配置开启。
+If you're using Umi, first install the `@umijs/plugins` dependency, then activate it through configuration.
```bash
$ pnpm i @umijs/plugins -D
@@ -25,23 +25,23 @@ export default {
}
```
-## 特性
+## Features
-插件帮你做了几件事，
+The plugin handles a few tasks for you:
-1、大部分 styled-components 的导出可以从 `umi` 或 `@umijs/max` 里 import 使用。
+1. Most styled-components exports can be imported from either `umi` or `@umijs/max`.
-2、支持通过配置的方式开启 styled-components 的 babel 插件，仅 dev 模式有效。
+2. It supports enabling the styled-components Babel plugin through configuration, applicable only in the development mode.
-3、支持通过运行时配置的方式声明全局样式。
+3. It supports declaring global styles through runtime configuration.
-## 配置项
+## Configuration Options
-可以在 `styledComponents` 中做以下配置。
+You can use the following configurations under `styledComponents`:
-- `babelPlugin`: Object，开启 styled-components 的 babel 插件，仅 dev 模式有效
+- `babelPlugin`: Object, enable the styled-components Babel plugin, only effective in development mode.
-比如：
+For example:
```ts
export default {
@@ -51,16 +51,16 @@ export default {
}
```
-## 运行时配置项
+## Runtime Configuration Options
-包含以下配置。
+This includes the following configuration:
-- `GlobalStyle`：ReactComponent
+- `GlobalStyle`: ReactComponent
-比如：
+For example:
```ts
-import {createGlobalStyle} from "umi";
+import { createGlobalStyle } from "umi";
export const styledComponents = {
GlobalStyle: createGlobalStyle`
diff --git a/docs/docs/max/styled-components.zh-CN.md b/docs/docs/max/styled-components.zh-CN.md
new file mode 100644
index 000000000000..c7c8eff1148d
--- /dev/null
+++ b/docs/docs/max/styled-components.zh-CN.md
@@ -0,0 +1,73 @@
+# styled-components
+
+@umijs/max 内置了 [styled-components](https://styled-components.com/) 样式方案。
+
+## 启用方式
+
+如果是 @umijs/max，配置开启。
+
+```ts {2}
+export default {
+ styledComponents: {},
+}
+```
+
+如果是 umi，先安装 `@umijs/plugins` 依赖，再通过配置开启。
+
+```bash
+$ pnpm i @umijs/plugins -D
+```
+
+```ts
+export default {
+ plugins: ['@umijs/plugins/dist/styled-components'],
+ styledComponents: {},
+}
+```
+
+## 特性
+
+插件帮你做了几件事，
+
+1、大部分 styled-components 的导出可以从 `umi` 或 `@umijs/max` 里 import 使用。
+
+2、支持通过配置的方式开启 styled-components 的 babel 插件，仅 dev 模式有效。
+
+3、支持通过运行时配置的方式声明全局样式。
+
+## 配置项
+
+可以在 `styledComponents` 中做以下配置。
+
+- `babelPlugin`: Object，开启 styled-components 的 babel 插件，仅 dev 模式有效
+
+比如：
+
+```ts
+export default {
+ styledComponents: {
+ babelPlugin: {},
+ },
+}
+```
+
+## 运行时配置项
+
+包含以下配置。
+
+- `GlobalStyle`：ReactComponent
+
+比如：
+
+```ts
+import {createGlobalStyle} from "umi";
+
+export const styledComponents = {
+ GlobalStyle: createGlobalStyle`
+ h1 {
+ background: #ccc;
+ }
+ `
+}
+```
+
diff --git a/docs/docs/max/tailwindcss.zh-CN.md b/docs/docs/max/tailwindcss.zh-CN.md
new file mode 100644
index 000000000000..ffc3fdee05db
--- /dev/null
+++ b/docs/docs/max/tailwindcss.zh-CN.md
@@ -0,0 +1,37 @@
+import { Tabbed, Message } from 'umi';
+
+# Tailwind CSS 插件
+
+在 Max 项目使用 Tailwind CSS 功能。
+
+## 配置
+
+使用微生成器一键开启 Tailwind CSS 插件
+
+