})
```
-支持别名，比如通过 `@` 指向 src 目录：
+Aliases are also supported, such as using `@` to point to the `src` directory:
```js
export default () => })
```
-## JS 里使用svg
+## Using SVGs in JavaScript
-**组件式引入**
+**Component-Based Import**
```js
import { ReactComponent as Logo } from './logo.svg'
@@ -33,7 +26,7 @@ function Analysis() {
}
```
-**url式引入**
+**URL-Based Import**
```js
import logoSrc from './logo.svg'
@@ -43,12 +36,9 @@ function Analysis() {
}
```
+## Using Images in CSS
-## CSS 里使用图片
-
-通过相对路径引用。
-
-比如，
+You can reference images with relative paths in CSS. For example:
```css
.logo {
@@ -56,7 +46,7 @@ function Analysis() {
}
```
-CSS 里也支持别名，但需要在前面加 `~` 前缀，
+Aliases are also supported in CSS, but you need to prefix them with `~`. For example:
```css
.logo {
@@ -64,26 +54,26 @@ CSS 里也支持别名，但需要在前面加 `~` 前缀，
}
```
-注意：
+Please note:
-1. 这是 webpack 的规则，如果切到其他打包工具，可能会有变化
-2. less 中同样适用
+1. These rules are specific to Webpack. If you switch to another bundling tool, there may be differences.
+2. The same rules apply to Less as well.
-## 图片路径问题
+## Image Path Considerations
-项目中使用图片有两种方式，
+There are two ways to use images in your project:
-1. 先把图片传到 cdn，然后在 JS 和 CSS 中使用图片的绝对路径
-2. 把图片放在项目里，然后在 JS 和 CSS 中通过相对路径的方式使用
+1. Upload the images to a CDN and then use absolute paths to reference them in your JS and CSS.
+2. Place the images in your project and use relative paths in your JS and CSS.
-前者不会有任何问题；后者，如果在 JS 中引用相对路径的图片时，在发布时会根据 publicPath 绝对引入路径，所以就算没有开启 dynamicImport 时，也需要注意 publicPath 的正确性。
+The first approach should work without any issues. For the second approach, when referencing images with relative paths in JavaScript, they will be included with absolute paths in the build based on the `publicPath`. So, even if you haven't enabled `dynamicImport`, ensure that the `publicPath` is configured correctly.
-## Base64 编译
+## Base64 Encoding
-通过相对路径引入图片的时候，如果图片小于 10K，会被编译为 Base64，否则会被构建为独立的图片文件。
+When importing images with relative paths, images smaller than 10KB will be encoded as Base64. Otherwise, they will be built as separate image files.
-10K 这个阈值可以通过 [inlineLimit 配置](../config#inlinelimit)修改。
+You can modify the 10KB threshold using the [inlineLimit configuration](../config#inlinelimit).
-## 使用 CDN
+## Using CDN
TODO
diff --git a/docs/docs/cli.md b/docs/docs/cli.md
index 6bd3e164ec48..84b50c79b5cf 100644
--- a/docs/docs/cli.md
+++ b/docs/docs/cli.md
@@ -1,13 +1,8 @@
----
-translateHelp: true
----
-
-# Cli Commands
-
+# CLI Commands
## umi build
-编译构建 web 产物。通常需要针对部署环境，做特定的配置和环境变量修改。相关详情，请查阅[部署](./deployment)。
+Compiles and builds web assets. Typically, you need to make specific configurations and environment variable modifications for the deployment environment. For more details, please refer to the [deployment](./deployment) documentation.
```bash
$ umi build
@@ -21,32 +16,32 @@ Build success.
✨ Done in 9.77s.
```
-默认产物输出到项目的 `dist` 文件夹，你可以通过修改配置 `outputPath` 指定产物输出目录。
-默认编译时会将 `public` 文件夹内的所有文件，原样拷贝到 `dist` 目录，如果你不需要这个特性，可以通过配置 `chainWebpack` 来删除它。
+By default, the build output goes to the `dist` folder in your project. You can specify the output directory by modifying the `outputPath` configuration.
+
+During compilation, all files within the `public` folder are copied as-is to the `dist` directory. If you don't need this feature, you can remove it by configuring `chainWebpack`:
```js
export default {
chainWebpack(memo, { env, webpack }) {
- // 删除 umi 内置插件
+ // Remove the built-in copy plugin
memo.plugins.delete('copy');
}
}
```
-> 注意：如果 `public` 里面存在产物同名文件，如 `index.html`，将会导致产物文件被覆盖。
+> Note: If there are files with the same name in the `public` folder, like `index.html`, they will overwrite the output files.
## umi dev
-启动本地开发服务器进行项目的开发调试
+Starts a local development server for debugging and developing your project.
```bash
$ umi dev
```
-启动在浏览器中运行的开发服务器，并监视源文件变化，自动热加载。
+It launches a development server in your browser, watches for source file changes, and provides hot reloading.
-默认使用 `8000` 端口，如果 `8000` 端口被占用，将会使用 `8001` 端口，以此类推。
-你可以通过设置环境变量 `PORT` 来指定开发端口号。更多环境变量配置，请查阅[环境变量](/docs/env-variables)。
+By default, it uses port `8000`, and if port `8000` is occupied, it will use `8001`, and so on. You can specify the development port by setting the `PORT` environment variable. For more environment variable configurations, please refer to the [environment variables](/docs/env-variables) documentation.
```bash
umi dev
@@ -62,19 +57,19 @@ Starting the development server...
- Network: http://192.168.50.236:8000
```
-开启开发服务还会同时提供一个 Network 的链接，你可以在能访问到你当前运行设备的其他设备中预览页面。
+Starting the development server also provides a Network link that allows you to preview the page on other devices that can access the current running device.
-> 注意：如果是在开启了VPN，或者虚拟机等复杂的网络环境中，这个地址很可能会错误。你可以通过访问你真实可用 `ip` 的对应端口号来访问开发页面。
+> Note: If you are in a complex network environment with VPN or virtual machines, this address may be incorrect. You can access the development page by using the corresponding port number of your real and available IP.
## umi generate
-内置的生成器功能，内置的类型有 `page` ，用于生成最简页面。支持别名调用 `umi g`。
+This command is an embedded generator with the built-in type `page` for generating simple pages. You can also use the alias `umi g`.
```bash
$ umi generate 
+
-需配置 NODE_PATH 环境变量，如使用 yarn，可通过执行 `yarn global bin` 拿到 bin 路径。
+You need to configure the `NODE_PATH` environment variable. If you are using Yarn, you can obtain the bin path by running `yarn global bin`.
-### 配了 `dynamicImport.loading` 后外层报错不生效怎么办？
+### 'dynamicImport.loading' is configured, but outer errors are not working. What should I do?
-组件报错有两种形式：
+There are two types of errors in components:
-1)
+1)
```js
-a(); // 出错
+a(); // Throws an error
export default () => <>..;
```
@@ -127,24 +123,24 @@ export default () => <>..;
```js
export default () => {
- a(); // 出错
+ a(); // Throws an error
return <>..;
}
```
-第二种不管怎么样都能正常抛错，第一种在开启 dynamicImport 并配置了 loading 时可能会不生效。
+The second type of error will always work, regardless of whether dynamicImport is enabled and configured with a loading component. However, in the first type, when dynamicImport is enabled and a loading component is configured, the error might not be displayed.
-比如 loading 指向的文件内容为：
+For example, if the loading component points to a file with the following content:
```js
export default () => <>loading...
```
-那么出错时也会只显示 loading... 。
+In this case, when an error occurs, it will only display "loading..."
-#### 解决
+#### Solution
-loading 处理出错场景，比如：
+Handle error scenarios in the loading component. For example:
```js
export default class extends React.PureComponent {
@@ -158,26 +154,26 @@ export default class extends React.PureComponent {
};
```
-### ie报错和压缩问题解决思路
+### Internet Explorer (IE) Errors and Compression Issues Resolution Approach
-感觉现在ie下的错误，都是因为这个问题引起的。
+Most errors encountered in IE are typically caused by this issue.
-#### 典型错误
+#### Typical Errors
-
+
-#### 解决思路
+#### Resolution Approach
-##### 第一步、确认你的需求
+##### Step 1: Determine Your Requirements
-主要是**是否需要兼容旧版本不支持 es6 的浏览器**，
+The primary consideration is whether you need to support older browsers that do not support ES6:
-* 如果需要兼容，跳到第二步
-* 如果不需要兼容，配置 `minimizer` 为 `terserjs`
+* If you need to support older browsers, proceed to step 2.
+* If you do not need to support older browsers, configure `minimizer` to use `terserjs`.
-##### 第二步
+##### Step 2
-检查 `targets` 配置，确认是否有包含旧版本浏览器比如，
+Check the `targets` configuration to determine if it includes older browser versions. For example:
```js
{
@@ -185,78 +181,86 @@ export default class extends React.PureComponent {
}
```
-尝试构建，如果没有问题，则不用再执行下一步。
+Try building the project. If it succeeds, there's no need to proceed to the next step.
-##### 第三步、记录错误文件和行号
+##### Step 3: Record the Error Details
-比如前面的，
+For example, record the following error details:
-* 文件：vendors.async.js
-* 行号：193
-* 出错 token：`>`
+* File: `vendors.async.js`
+* Line Number: `193`
+* Error Token: `>`
-##### 第四步、不压缩构建，查找出错源
+##### Step 4: Build Without Compression and Identify the Error Source
```bash
-# 如果你用 umi
+# If you're using Umi
$ COMPRESS=none umi build
-# 如果你用 bigfish
+# If you're using Bigfish
$ COMPRESS=none bigfish build
```
-找 `vendors.async.js` 的 193 行，看下是哪个包出错的，记录包名和版本号。
+Locate the error in `vendors.async.js` at line 193 and determine which package is causing the error. Note the package name and version.
-##### 第五步、修改本地`node_modules/es5-imcompatible-versions/package.json` 文件，写入刚刚出错的包名和版本号。
+##### Step 5: Modify the `node_modules/es5-incompatible-versions/package.json` File
-```js
+Edit the `node_modules/es5-incompatible-versions/package.json` file and add the package name and version that caused the error. For example:
+
+```json
"antd-table-infinity": {
"^1.1.2": {
"version": "^1.1.2",
- "reason": "https://github.com/Leonard-Li777/antd-table-infinity/blob/master/src/components/Table/InfinityTable/index.jsx#L7"
+ "reason": "https://github.com/Leonard-Li777/antd-table-infinity/blob/master/src/components/Table/InfinityTable/index.jsx
+
+#L7"
}
}
```
-##### 第六步、保存文件，重新build，确认错误已修复
+##### Step 6: Save the File and Rebuild to Confirm the Error Is Fixed
+
+##### Step 7: Submit a Pull Request (PR) to [es5-imcompatible-versions](https://github.com/umijs/es5-imcompatible-versions)
-##### 第七步、给 [es5-imcompatible-versions](https://github.com/umijs/es5-imcompatible-versions) 提 PR
+If you are unable to submit a PR, you can follow these steps instead:
-###### 不会提交PR的同学，请按下面步骤操作
-1、在[编辑](https://github.com/umijs/es5-imcompatible-versions/edit/master/package.json)里面，把你刚才的修改，在这里也修改一下。
-2、修改完，页面拉到最下方。创建一个分支（可能会是自动创建分支的情况，如果没得选择，这里不理会就好）点击绿色按钮 `Propose file change`
-
-3、在跳转后的页面，点击绿色按钮 `Create pull request`
-
+1. Go to the [edit](https://github.com/umijs/es5-imcompatible-versions/edit/master/package.json) page.
+2. Make the same modification you made locally to the file here.
+3. Once you've made the changes, scroll to the bottom of the page and create a new branch (you may be prompted to do this automatically).
+4. Click the green button "Propose file change."
+5. On the next page, click the green button "Create pull request."
-##### 第八步、将跳转后的链接，发到群里面。等待合并
+##### Step 8: Share the Link to the PR and Wait for It to Be Merged
-如：` https://github.com/umijs/es5-imcompatible-versions/pull/36`
+For example: `https://github.com/umijs/es5-imcompatible-versions/pull/36`
-#### 参考
+#### References
* [https://github.com/sorrycc/blog/issues/68](https://github.com/sorrycc/blog/issues/68)
* [https://github.com/umijs/es5-imcompatible-versions](https://github.com/umijs/es5-imcompatible-versions)
-### The dependency was not found
+### The Dependency Was Not Found
-
+
-一般是网络不好装包错误导致的，可以删除 `*.lock` 和 `node_modules` 重新执行 `yarn`，如果多次尝试都无法解决。可以在项目目录下执行 `git clean -dfx`，再重装，一般可以解决。
+This error typically occurs due to package installation issues caused by poor network connectivity. You can try the following steps to resolve it:
-如果同一个项目你同事可以运行，你运行出错。一般都是缓存或者安装包过程出错问题。可以尝试删除几个缓存目录，比如删除 `src/.umi/cache` 后重试。
+1. Delete the `*.lock` files and the `node_modules` directory in your project.
+2. Run `yarn` to reinstall dependencies.
+3. If the issue persists, you can execute `git clean -dfx` in your project directory to remove any untracked files and directories. Then, run `yarn` again to reinstall dependencies.
+4. If you're still encountering issues, consider deleting specific cache directories, such as `src/.umi/cache`, and then retry the installation.
-## webpack
+## Webpack
-### 如何配置额外的 loader ?
+### How can I configure additional loaders?
-比如 svg 我希望不走 base64，而是全部产生 svg 文件，可以这样配：
+For example, if you want to handle SVG files differently and not include them as base64-encoded data, you can configure it like this:
```js
export default {
- // 添加 url-loader 的 exclude
+ // Add url-loader excludes
urlLoaderExcludes: [/.svg$/],
- // 添加 loader
+ // Add loader
chainWebpack(config) {
config.module.rule('svg-with-file')
.test(/.svg$/)
@@ -268,18 +272,18 @@ export default {
## CSS
-### 为啥我 import 的 css 文件不生效？
+### Why isn't my imported CSS file working?
-umi 默认是开启 css modules 的，请按照 css modules 的方式进行书写。
+Umi enables CSS modules by default, so you should write your styles using CSS modules conventions. Make sure you are following the CSS modules approach for your styles.
-参考：
+References:
* [css-modules/css-modules](https://github.com/css-modules/css-modules)
-* [CSS Modules 用法教程](http://www.ruanyifeng.com/blog/2016/06/css_modules.html)
+* [A Guide to CSS Modules](http://www.ruanyifeng.com/blog/2016/06/css_modules.html)
-### 如何禁用 css modules ？
+### How can I disable CSS modules?
-修改 `.umirc.js`:
+To disable CSS modules, modify your `.umirc.js` file:
```json
{
@@ -287,17 +291,17 @@ umi 默认是开启 css modules 的，请按照 css modules 的方式进行书
}
```
-但没有特殊的理由时，不建议关闭 css modules。
+However, it's not recommended to disable CSS modules unless you have a specific reason to do so.
-### 如何使用 sass ？
+### How can I use Sass?
-先安装额外的依赖，
+First, install the necessary dependencies:
```bash
$ npm i node-sass sass-loader --save
```
-然后修改 `.umirc.js`:
+Then, modify your `.umirc.js`:
```json
{
@@ -305,9 +309,9 @@ $ npm i node-sass sass-loader --save
}
```
-#### 开启按需加载后如何把 css 打包成一个文件？
+#### How can I bundle CSS into a single file when using dynamic imports?
-配置 splitChunks，比如：
+Configure the `splitChunks` optimization in your `.umirc.js` to bundle CSS into a single file. For example:
```js
export default {
@@ -329,30 +333,17 @@ export default {
}
```
-打包后会输出：
+After building, you'll see a single CSS file, such as `styles.chunk.css`, containing all your CSS styles.
-```
-File sizes after gzip:
-
- 126.85 KB dist/umi.js
- 535 B dist/p__users.async.js
- 533 B dist/p__index.async.js
- 337 B dist/styles.async.js
- 96 B dist/styles.chunk.css
-```
+References:
-示例：
+* [Mini CSS Extract Plugin - Extracting All CSS in a Single File](https://github.com/webpack-contrib/mini-css-extract-plugin#extracting-all-css-in-a-single-file)
+* [Example: `.umirc.js` Configuration](https://github.com/umijs/umi/blob/master/packages/umi-plugin-react/test/chunks/.umirc.js#L1)
-* [sorrycc-123.zip](https://github.com/umijs/umi/files/2556654/sorrycc-123.zip)
+### How can I prevent the "loading..." state from displaying when refreshing a route?
-参考：
+To prevent the "loading..." state from displaying when refreshing a route, import an empty component, such as `Loading.tsx`, and use it as the loading component. Here's an example:
-* https://github.com/webpack-contrib/mini-css-extract-plugin#extracting-all-css-in-a-single-file
-* https://github.com/umijs/umi/blob/master/packages/umi-plugin-react/test/chunks/.umirc.js#L1
-
-### 如何禁用掉每次刷新路由时出现的 loading... 状态？
-
-给 dynamicImport 引入一个空组件比如 `Loading.tsx` ，内容如下：
```typescript
// components/Loading.tsx
@@ -360,7 +351,10 @@ import React from 'react';
export default () => <>;
```
-```typescript
+
+Then, in your `.umirc.js` configuration, specify the loading component:
+
+```json
export default {
dynamicImport: {
loading: '@/components/Loading',
@@ -368,75 +362,61 @@ export default {
};
```
-## Test
+## Testing
-### 如何断点调试
+### How can I debug with breakpoints?
-确保 node 在 8.10 以上，然后执行：
+Ensure that you have Node.js version 8.10 or higher installed. Then, execute the following command:
```bash
$ node --inspect-brk ./node_modules/.bin/umi test
```
-然后在浏览器里打开 chrome://inspect/#devices 进行 inspect 和断点。
-
-## 请求
-
-### proxy代理不成功,没有代理到实际地址
-
-
+After that, open `chrome://inspect/#devices` in your browser to inspect and set breakpoints.
-代理只是服务请求代理，这个地址是不会变的。
-原理可以简单的理解为，在本地启了一个服务，你先请求了本地的服务，本地的服务转发了你的请求到实际服务器。所以你在浏览器上看到的请求地址还是http://localhost:8000/xxx 。以服务端是否收到请求为准
+## Requests
-https://github.com/ant-design/ant-design-pro/issues/2779
+### Why is my proxy not working, and it's not proxying to the actual address?
-## 部署
+The proxy serves as a request proxy and doesn't change the request address. So, even if you see the request address as `http://localhost:8000/xxx` in your browser, it means the request is first sent to your local server, and then your local server forwards the request to the actual server. Therefore, it's essential to check if the server received the request successfully.
-### build 后访问路由刷新后 404？
+### Why do images go missing after building?
-几个方案供选择：
-
-* 改用 hashHistory，在 `.umirc.js` 里配 `history: 'hash'`
-* 静态化，在 `.umirc.js` 里配 `exportStatic: true`
-* 服务端配置路由 fallback 到 index.html
-
-### build之后图片丢失？
-
-可能是图片没有正确引用，可以参考一下代码，正确引入图片。
+If images are missing after building, it could be due to incorrect image references. Ensure that you are correctly importing and using images in your code. For example:
```js
import React from 'react';
-import logo from './logo.png'; // 告诉WebPACK这个JS文件使用这个图像
+import logo from './logo.png'; // Inform Webpack that this JS file uses this image
console.log(logo); // logo.84287d09.png
function Header() {
- // 导入图片
+ // Import the image
return 
+
+Based on these two images, SSR is commonly used in the following two scenarios:
-第二张，**白屏时间**上 SSR 较少，因为当 HTML 文档返回时，已经有对应的内容。（见 Network）
+1. **SEO Requirements**: It's used for search engine indexing and social sharing, typically in frontend applications.
+2. **Fast Initial Rendering**: It's used when there are requirements for fast initial rendering, often in mobile applications or under poor network conditions.
-
+> In other words, if you're building an admin or backend application (such as antd pro or a management dashboard), think carefully about whether to use SSR.
-综上两图可知，SSR 常用于以下两个场景：
+## What is Pre-rendering?
-1. 有 **SEO 诉求**，用在搜索引擎检索以及社交分享，用在前台类应用。
-1. **首屏渲染**时长有要求，常用在移动端、弱网情况下。
+Server-Side Rendering requires a backend server (usually Node.js) to work. If you don't have a backend server but still want to achieve the goals mentioned above, you can use **pre-rendering**.
-> 也就是说，如果你是中后台应用（如 antd pro、管理后台等），请谨慎考虑是否使用 SSR。
+The key difference between pre-rendering and server-side rendering is the **timing of rendering**. Server-side rendering happens when a user accesses the page (i.e., **server-side rendering**), and the data is generally the most up-to-date. Pre-rendering, on the other hand, occurs during project build time, and when a user accesses the page, the data might not be the most up-to-date (pre-rendering is suitable when data doesn't need to be real-time).
-## 什么是预渲染？
+Pre-rendering (Pre Render) involves rendering during the build process to generate static HTML fragments. It doesn't require real-time dynamic HTML compilation by a web server and is suitable for **static site generation**.
-服务端渲染，首先得有后端服务器（一般是 Node.js）才可以使用，如果我没有后端服务器，也想用在上面提到的两个场景，那么推荐使用**预渲染**。
+## Umi Server-Side Rendering Features
-预渲染与服务端渲染唯一的不同点在于**渲染时机**，服务端渲染的时机是在用户访问时执行渲染（即**实时渲染**，数据一般是最新的），预渲染的时机是在项目构建时，当用户访问时，数据不一定是最新的（如果数据没有实时性，则可以直接考虑预渲染）。
+> As early as Umi 2.8+, Umi already had SSR capabilities, but it had a higher learning curve for newcomers.
-预渲染（Pre Render）在构建时执行渲染，将渲染后的 HTML 片段生成静态 HTML 文件。无需使用 web 服务器实时动态编译 HTML，适用于**静态站点生成**。
+With Umi 3, significant optimizations and improvements have been made to SSR based on its specific business scenarios, offering the following features:
-## Umi 服务端渲染特性
+- **Out of the Box**: SSR is built-in and can be easily enabled with a single command, `umi dev`, making development and debugging convenient.
+- **Server Framework Agnostic**: Umi doesn't couple with server frameworks like [Egg.js](https://eggjs.org/), [Express](https://expressjs.com/), or [Koa](https://koajs.com/). It can be integrated seamlessly with any framework or Serverless mode.
+- **Support for Data Pre-fetching at the Application and Page Level**: Umi 3 continues the page data pre-fetching (getInitialProps) feature from Umi 2 to solve the problem of fetching global data in the previous version.
+- **Support for Lazy Loading**: With `dynamicImport` enabled, Umi 3 will load corresponding resource files (CSS/JS) based on different routes.
+- **Built-in Pre-rendering**: Umi 3 includes pre-rendering functionality out of the box. You no longer need to install additional plugins. Simply enable `ssr` and `exportStatic`, and Umi will compile the rendered HTML during `umi build`.
+- **Support for Rendering Degradation**: Umi 3 prioritizes SSR. If server-side rendering fails, it automatically falls back to client-side rendering (CSR) without disrupting normal business processes.
+- **Support for Streaming Rendering**: Enabling `ssr: { mode: 'stream' }` allows streaming rendering, which results in shorter [TTFB](https://baike.baidu.com/item/TTFB) (Time To First Byte) times compared to normal SSR.
+- **Compatible with Client-Side Dynamic Loading**: In Umi 2, using both SSR and dynamicImport (dynamic loading) had some issues. In Umi 3, you can use them simultaneously.
+- **Modular SSR Features**: While Umi 3's built-in SSR features are quite comprehensive, if your requirements are not met or you want to customize the rendering method, you can do so using the provided APIs.
-> 早在 Umi 2.8+ 版本时，Umi 已具备 SSR 能力，只是使用上对新手而言，门槛较高。
+## Enabling Server-Side Rendering
-Umi 3 结合自身业务场景，在 SSR 上做了大量优化及开发体验的提升，具有以下特性：
+By default, server-side rendering is disabled. You need to enable it through configuration:
-- **开箱即用**：内置 SSR，一键开启，`umi dev` 即 SSR 预览，开发调试方便。
-- **服务端框架无关**：Umi 不耦合服务端框架（例如 [Egg.js](https://eggjs.org/)、[Express](https://expressjs.com/)、[Koa](https://koajs.com/)），无论是哪种框架或者 Serverless 模式，都可以非常简单进行集成。
-- **支持应用和页面级数据预获取**：Umi 3 中延续了 Umi 2 中的页面数据预获取（getInitialProps），来解决之前全局数据的获取问题。
-- **支持按需加载**：按需加载 `dynamicImport` 开启后，Umi 3 中会根据不同路由加载对应的资源文件（css/js）。
-- **内置预渲染功能**：Umi 3 中内置了预渲染功能，不再通过安装额外插件使用，同时开启 `ssr` 和 `exportStatic`，在 `umi build` 构建时会编译出渲染后的 HTML。
-- **支持渲染降级**：优先使用 SSR，如果服务端渲染失败，自动降级为客户端渲染（CSR），不影响正常业务流程。
-- **支持流式渲染**：`ssr: { mode: 'stream' }` 即可开启流式渲染，流式 SSR 较正常 SSR 有更少的 [TTFB](https://baike.baidu.com/item/TTFB)（发出页面请求到接收到应答数据第一个字节所花费的毫秒数） 时间。
-- **兼容客户端动态加载**：在 Umi 2 中同时使用 SSR 和 dynamicImport（动态加载）会有一些问题，在 Umi 3 中可同时开启使用。
-- **SSR 功能插件化**：Umi 3 内置的 SSR 功能基本够用，若不满足需求或者想自定义渲染方法，可通过提供的 API 来自定义。
-
-## 启用服务端渲染
-
-默认情况下，服务端渲染功能是关闭的，你需要在使用之前通过配置开启：
-
-```js
+```javascript
export default {
ssr: {},
}
```
-## 开发
+## Development
-执行 `umi dev`，访问页面，即是服务端渲染后的。
+Execute `umi dev` to access the page, and it will be server-side rendered.
-
+
-> [如何判断当前页面是 SSR 还是 CSR？](#如何判断当前页面是-ssr-还是-csr？)
+> [How to Determine Whether the Current Page Is SSR or CSR?](#how-to-determine-whether-the-current-page-is-ssr-or-csr)
-如果与后端框架在开发模式下一起使用时，可通过配置来关闭 `umi dev` 下的服务端渲染行为：
-
-```js
+If you're using it together with a backend framework in development mode, you can disable server-side rendering behavior under `umi dev` with the following configuration:
+```javascript
export default {
ssr: {
- // 默认为 true
+ // Defaults to true
devServerRender: false,
},
}
```
-## 数据预获取
+## Data Pre-fetching
-服务端渲染的数据获取方式与 SPA（单页应用）有所不同，为了让客户端和服务端都能获取到同一份数据，我们提供了 页面级数据 预获取。
+Data retrieval in server-side rendering differs from Single Page Applications (SPAs). To ensure that both the client and server have access to the same data, Umi 3 provides **page-level data pre-fetching**.
-
-
-### 页面级数据获取
-
-### 使用
-
-每个页面可能有单独的数据预获取逻辑，这里我们会获取页面组件上的 `getInitialProps` 静态方法，执行后将结果注入到该页面组件的 `props` 中，例如：
-
-```tsx
-// pages/index.tsx
import { IGetInitialProps } from 'umi';
import React from 'react';
@@ -146,7 +105,7 @@ Home.getInitialProps = (async (ctx) => {
})
}) as IGetInitialProps;
-/** 同时也可以使用 class 组件
+/** You can also use a class component:
class Home extends React.Component {
static getInitialProps = (async (ctx) => {
return Promise.resolve({
@@ -154,518 +113,159 @@ class Home extends React.Component {
title: 'Hello World',
}
})
- }) as IGetInitialProps
+ }) as IGetInitialProps;
+
render() {
const { data } = props;
return (
- {data.title}
+ {data.title}
)
}
}
*/
-
export default Home;
```
-`getInitialProps` 中有几个固定参数：
+> `getInitialProps` should be an `async` function. After switching to Umi 3, existing `getInitialProps` will work without any changes.
-- `match`： 与客户端页面 props 中的 `match` 保持一致，有当前路由的相关数据。
-- `isServer`：是否为服务端在执行该方法。
-- `route`：当前路由对象
-- `history`：history 对象
+#### Data Pre-fetching Execution Timing
-### 扩展 ctx 参数
+- **Server Side**: In server-side rendering, `getInitialProps` is executed on the server side, and the result is sent to the client as part of the initial HTML.
-为了结合数据流框架，我们提供了 `modifyGetInitialPropsCtx` 方法，由插件或应用来扩展 `ctx` 参数，以 `dva` 为例：
+- **Client Side**: On the client side, `getInitialProps` is executed as a normal React lifecycle method (componentDidMount). It won't be executed during server-side rendering if `shouldPrefetch` is set to `false`. The data is passed to the component as `props`.
-```ts
-// plugin-dva/runtime.ts
-export const ssr = {
- modifyGetInitialPropsCtx: async (ctx) => {
- ctx.store = getApp()._store;
- },
-}
-```
+#### Data Pre-fetching in Detail
-然后在页面中，可以通过获取到 `store`：
+Let's break down how data pre-fetching works in Umi 3:
-```tsx
-// pages/index.tsx
-const Home = () => ;
+1. On the server side, when a user accesses a page, Umi 3 first routes the request to the appropriate page component.
-Home.getInitialProps = async (ctx) => {
- const state = ctx.store.getState();
- return state;
-}
+2. If the page component has a `getInitialProps` method defined (it's optional), Umi 3 executes it and awaits the result.
-export default Home;
-```
+3. Once the `getInitialProps` method completes (whether by resolving or rejecting the returned Promise), Umi 3 injects the result into the component's `props`.
-同时也可以在自身应用中进行扩展：
+4. The page component is then rendered with the pre-fetched data on the server side. The HTML is sent to the browser.
-```js
-// app.(ts|js)
-export const ssr = {
- modifyGetInitialPropsCtx: async (ctx) => {
- ctx.title = 'params';
- return ctx;
- }
-}
-```
-
-同时可以使用 `getInitialPropsCtx` 将服务端参数扩展到 `ctx` 中，例如：
-
-```js
-app.use(async (req, res) => {
- // 或者从 CDN 上下载到 server 端
- // const serverPath = await downloadServerBundle('http://cdn.com/bar/umi.server.js');
- const render = require('./dist/umi.server');
- res.setHeader('Content-Type', 'text/html');
-
- const context = {};
- const { html, error, rootContainer } = await render({
- // 有需要可带上 query
- path: req.url,
- context,
- getInitialPropsCtx: {
- req,
- },
- });
-})
-```
+5. On the client side, when the browser receives the HTML, it also receives the pre-fetched data. The page component on the client side is rehydrated (React's term for initializing the component with existing data), and the data is used for rendering.
-在使用的时候，就有 `req` 对象，不过需要注意的是，只在服务端执行时才有此参数：
-
-```js
-Page.getInitialProps = async (ctx) => {
- if (ctx.isServer) {
- // console.log(ctx.req);
- }
- return {};
-}
-```
+6. On subsequent client-side navigations within the app, `getInitialProps` will be executed on the client side, not on the server side, unless `shouldPrefetch` is set to `false`.
-则在执行 `getInitialProps` 方法时，除了以上两个固定参数外，还会获取到 `title` 和 `store` 参数。
+### API-Level Data Pre-fetching
-关于 `getInitialProps` 执行逻辑和时机，这里需要注意：
+In addition to page-level data pre-fetching with `getInitialProps`, Umi 3 also supports **API-level data pre-fetching**. This allows you to fetch data in the layout component (or any component) that wraps your pages and share that data with multiple pages.
-- 开启 ssr，且执行成功
- - 未开启 `forceInitial`，首屏不触发 `getInitialProps`，切换页面时会执行请求，和客户端渲染逻辑保持一致。
- - 开启 `forceInitial`，无论是首屏还是页面切换，都会触发 `getInitialProps`，目的是始终以客户端请求的数据为准。（有用在静态页面站点的实时数据请求上）
-- 未开启 ssr 时，只要页面组件中有 `getInitialProps` 静态方法，则会执行该方法。
+API-level data pre-fetching can be achieved using the `getInitialProps` method in your layout component:
-## 部署
+```javascript
+// layouts/index.tsx
+import { IGetInitialProps } from 'umi';
-执行 `umi build` ，除了正常的 `umi.js` 外，会多一个服务端文件： `umi.server.js` （相当于服务端入口文件，类比浏览器加载 umi.js 客户端渲染）
+const Layout: React.FC = ({ children }) => {
+ return (
+ 
-
-### 预渲染动态路由
-预渲染默认情况下不会渲染动态路由里的所有页面，如果需要渲染动态路由中的页面，通过配置 `extraRoutePaths`，例如：
-
-```diff
-export default {
- ssr: {},
- exportStatic: {
-+ extraRoutePaths: async () => {
-+ // const result = await request('https://your-api/news/list');
-+ return Promise.resolve(['/news/1', 'news/2']);
-+ }
- },
- routes: [
- {
- path: '/',
- component: '@/layout',
- routes: [
- { path: '/', component: '@/pages/index' },
- { path: '/news', component: '@/pages/news' },
- { path: '/news/:id', component: '@/pages/news/detail' }
- ]
- }
- ]
-}
-```
-
-则会生成以下产物：
-
-```diff
- - dist
- - umi.js
- - umi.css
- - index.html
- - news
- - :id
- - index.html
-+ - 1
-+ - index.html
-+ - 2
-+ - index.html
- - index.html
-```
-
-> 默认情况下，预渲染后会删除 `umi.server.js` 服务端入口文件，如果需要保留，可使用变量 `RM_SERVER_FILE=none` 来保留 `umi.server.js`。
-
-## 页面标题渲染
-
-[@umijs/preset-react](/zh-CN/plugins/preset-react#umijspreset-react) 插件集中已内置对标题的渲染，通过以下步骤使用：
-
-安装：
-
-```bash
-$ yarn add @umijs/preset-react
-```
+ // Fetch the data if it's not in the cache
+ const response = await fetch('https://api.example.com/data');
+ const data = await response.json();
-在页面中，即直接可以渲染标题：
+ // Store the data in the cache
+ cache.set('data', data);
-```tsx
-// pages/bar.tsx
-import React from 'react';
-import { Helmet } from 'umi';
+ return data;
+};
-export default props => {
+const Home = (props) => {
+ const { data } = props;
return (
- <>
- {/* 可自定义需不需要编码 */}
-
-
- Hello Umi Bar Title
-
-
+ 
-
-## 数据流结合
-
-### 与 dva 结合使用
-
-[@umijs/preset-react](/zh-CN/plugins/preset-react#umijspreset-react) 插件集中已内置 dva，通过以下步骤使用：
-
-```bash
-$ yarn add @umijs/preset-react
-```
-开启 dva，并在 `models` 目录下创建 dva model：
+Home.getInitialProps = async (ctx) => {
+ return {
+ data: await fetchData(),
+ };
+};
-```js
-export default {
- ssr: {},
- dva: {}
-}
+export default Home;
```
-这时候 `getInitialProps(ctx)` 中的 `ctx` 就会有 `store` 属性，可执行 `dispatch`，并返回初始化数据。
+In this example, we create a cache using `lru-cache` and use it to store fetched data. Before making a network request, we check if the data is already in the cache. If it is, we return the cached data; otherwise, we fetch it, store it in the cache, and return it.
-```js
-Page.getInitialProps = async (ctx) => {
- const { store } = ctx;
- store.dispatch({
- type: 'bar/getData',
- });
- return store.getState();
-}
-```
+This caching mechanism helps reduce the load on your server and improves the response time for subsequent requests for the same data.
-## 包大小分析
+Keep in mind that caching strategies may vary based on your specific requirements and the nature of your data. You can customize the caching logic to suit your needs.
-Umi 同时支持对服务端和客户端包大小的分析
+### Data Pre-fetching Pitfalls
-```bash
-# 服务端包大小分析
-$ ANALYZE_SSR=1 umi build
-# 客户端包大小分析
-$ ANALYZE=1 umi build
-```
+While data pre-fetching in server-side rendering is a powerful feature, it comes with some potential pitfalls and considerations:
-
+1. **Error Handling**: Ensure that you handle errors properly when fetching data in `getInitialProps`. If a data fetch fails on the server side, it can result in a failed SSR response. You should handle errors gracefully and possibly return default data or an error message to avoid breaking the entire page.
-## 谁在使用？
+2. **Data Hydration**: When pre-fetched data is passed to the client, make sure your client-side code can properly hydrate (initialize) components with this data. Mismatched data structures or unexpected null values can lead to client-side errors.
-
+ {/* Your layout content */}
+ {children}
+
+ );
+};
-```diff
-- dist
- - umi.js
- - umi.css
- - index.html
-+ - umi.server.js
-```
+Layout.getInitialProps = async (ctx) => {
+ // Fetch data and return it as an object
+ const data = await fetchData();
-然后在后端框架中，引用该文件：
-
-```js
-// Express
-app.use(async (req, res) => {
- // 或者从 CDN 上下载到 server 端
- // const serverPath = await downloadServerBundle('http://cdn.com/bar/umi.server.js');
- const render = require('./dist/umi.server');
- res.setHeader('Content-Type', 'text/html');
-
- const context = {};
- const { html, error, rootContainer } = await render({
- // 有需要可带上 query
- path: req.url,
- context,
-
- // 可自定义 html 模板
- // htmlTemplate: defaultHtml,
-
- // 启用流式渲染
- // mode: 'stream',
-
- // html 片段静态标记（适用于静态站点生成）
- // staticMarkup: false,
-
- // 扩展 getInitialProps 在服务端渲染中的参数
- // getInitialPropsCtx: {},
-
- // manifest，正常情况下不需要
- });
-
- // support stream content
- if (content instanceof Stream) {
- html.pipe(res);
- html.on('end', function() {
- res.end();
- });
- } else {
- res.send(res);
- }
-})
-```
+ return { data };
+};
-`render` 方法参数和返回值如下：
-
-参数：
-
-```ts
-{
- // 渲染页面路由，支持 `base` 和带 query 的路由，通过 umi 配置
- path: string;
- // 可选，初始化数据，传透传到 getInitialProps 方法的参数中
- initialData?: object;
- // 可选，html 模板，这里可自定义模板，默认是用 umi 内置的 html
- htmlTemplate?: string;
- // 可选，页面内容挂载节点，与 htmlTemplate 配合使用，默认为 root
- mountElementId?: string;
- // 上下文数据，可用来标记服务端渲染页面时的状态
- context?: object
- // ${protocol}://${host} 扩展 location 对象
- origin?: string;
-}
+export default Layout;
```
-返回值：
+In this example, the `Layout` component fetches data using `getInitialProps` and makes it available to all child pages wrapped by this layout. Child pages can access this data through their own `getInitialProps` or by simply accessing it from `props`.
-```ts
-{
- // html 内容，服务端渲染错误后，会返回原始 html
- html?: string | Stream;
- // 挂载节点中的渲染内容（ssr 渲染实际上只是渲染挂载节点中的内容），同时你也可以用该值来拼接自定义模板
- rootContainer: string | Stream;
- // 错误对象，服务端渲染错误后，值不为 null
- error?: Error;
-}
-```
+### Caching Data Pre-fetched on the Server
-## 示例
+To prevent redundant data fetching, you can use caching mechanisms when pre-fetching data on the server side. Caching helps improve the performance and efficiency of your SSR application.
-目前做了两个示例分别是基于[koa](https://github.com/umijs/umi/tree/master/examples/ssr-koa)和[egg](https://github.com/umijs/umi/tree/master/examples/ssr-with-eggjs)的，示例内置dva数据流和国际化解决方案，代码部分有注释，可参照进行个性化的修改。
+Here's a basic example of caching pre-fetched data using the popular `lru-cache` library:
-## polyfill
+```javascript
+// pages/index.tsx
+import { IGetInitialProps } from 'umi';
+import React from 'react';
+import LRU from 'lru-cache';
-Umi 3 默认移除了 DOM/BOM 浏览器 API 在 Node.js 的 polyfill，如果应用确实需要 polyfill 一些浏览器对象，可以使用 `beforeRenderServer` 运行时事件 API 进行扩展
+const cache = new LRU({
+ max: 500, // Maximum cache size
+ maxAge: 1000 * 60 * 60, // Cache data for 1 hour
+});
-```js
-// app.ts
-export const ssr = {
- beforeRenderServer: async ({
- env,
- location,
- history,
- mode,
- context,
- }) => {
- // global 为 Node.js 下的全局变量
- // 避免直接 mock location，这样会造成一些环境判断失效
- global.mockLocation = location;
+const fetchData = async () => {
+ // Check if the data is in the cache
+ const cachedData = cache.get('data');
- // 国际化
- if (location.pathname.indexOf('zh-CN') > -1) {
- global.locale = 'zh-CN'
- }
+ if (cachedData) {
+ return cachedData;
}
-}
-```
-
-## 动态加载（dynamicImport）
-
-完美兼容客户端动态加载，配置如下：
-
-```ts
-// .umirc.ts
-export default {
- ssr: {},
- dynamicImport: {},
-}
-```
-
-使用动态加载后，启动和构建会自动开启 [manifest](/zh-CN/config#manifest) 配置，并在产物目录中生成 `asset-manifest.json` 做资源映射，并自动将页面对应的资源注入到 HTML 中，避免开启动态加载后，**页面首屏闪烁**的问题。
-
-```bash
-- dist
- - umi.server.js
- - asset-manifest.json
-```
-
-则页面返回的 HTML 将增加对应 chunk（资源）：
-
-```diff
-
-
-
-
-+
-
-
-```
-
-## 使用流式渲染（Streaming）
-
-提供开箱即用的流式渲染功能，开启方式：
-
-```js
-export default {
- ssr: {
- mode: 'stream',
- },
-}
-```
-
-## 使用预渲染
-
-### 开启预渲染
-
-通过 `exportStatic` 结合 `ssr` 开启预渲染
-
-```js
-export default {
- ssr: {},
- exportStatic: {},
-}
-```
-
-执行 `umi build`，会将输出渲染后的 HTML
-
-
-
-### 预渲染动态路由
-预渲染默认情况下不会渲染动态路由里的所有页面，如果需要渲染动态路由中的页面，通过配置 `extraRoutePaths`，例如：
-
-```diff
-export default {
- ssr: {},
- exportStatic: {
-+ extraRoutePaths: async () => {
-+ // const result = await request('https://your-api/news/list');
-+ return Promise.resolve(['/news/1', 'news/2']);
-+ }
- },
- routes: [
- {
- path: '/',
- component: '@/layout',
- routes: [
- { path: '/', component: '@/pages/index' },
- { path: '/news', component: '@/pages/news' },
- { path: '/news/:id', component: '@/pages/news/detail' }
- ]
- }
- ]
-}
-```
-
-则会生成以下产物：
-
-```diff
- - dist
- - umi.js
- - umi.css
- - index.html
- - news
- - :id
- - index.html
-+ - 1
-+ - index.html
-+ - 2
-+ - index.html
- - index.html
-```
-
-> 默认情况下，预渲染后会删除 `umi.server.js` 服务端入口文件，如果需要保留，可使用变量 `RM_SERVER_FILE=none` 来保留 `umi.server.js`。
-
-## 页面标题渲染
-
-[@umijs/preset-react](/zh-CN/plugins/preset-react#umijspreset-react) 插件集中已内置对标题的渲染，通过以下步骤使用：
-
-安装：
-
-```bash
-$ yarn add @umijs/preset-react
-```
+ // Fetch the data if it's not in the cache
+ const response = await fetch('https://api.example.com/data');
+ const data = await response.json();
-在页面中，即直接可以渲染标题：
+ // Store the data in the cache
+ cache.set('data', data);
-```tsx
-// pages/bar.tsx
-import React from 'react';
-import { Helmet } from 'umi';
+ return data;
+};
-export default props => {
+const Home = (props) => {
+ const { data } = props;
return (
- <>
- {/* 可自定义需不需要编码 */}
- {data.title}
);
};
-```
-
-
-
-## 在 dumi 中使用
-
-[dumi](https://d.umijs.org/)：基于 Umi、为组件开发场景而生的文档工具，Umi 官网文档即使用 dumi 编写并结合预渲染，让文档内容具备 SEO，可使用源代码查看，开启方法：
-
-```jsx
-export default {
- ssr: {},
- exportStatic: {},
-}
-```
-
-
-
-## 数据流结合
-
-### 与 dva 结合使用
-
-[@umijs/preset-react](/zh-CN/plugins/preset-react#umijspreset-react) 插件集中已内置 dva，通过以下步骤使用：
-
-```bash
-$ yarn add @umijs/preset-react
-```
-开启 dva，并在 `models` 目录下创建 dva model：
+Home.getInitialProps = async (ctx) => {
+ return {
+ data: await fetchData(),
+ };
+};
-```js
-export default {
- ssr: {},
- dva: {}
-}
+export default Home;
```
-这时候 `getInitialProps(ctx)` 中的 `ctx` 就会有 `store` 属性，可执行 `dispatch`，并返回初始化数据。
+In this example, we create a cache using `lru-cache` and use it to store fetched data. Before making a network request, we check if the data is already in the cache. If it is, we return the cached data; otherwise, we fetch it, store it in the cache, and return it.
-```js
-Page.getInitialProps = async (ctx) => {
- const { store } = ctx;
- store.dispatch({
- type: 'bar/getData',
- });
- return store.getState();
-}
-```
+This caching mechanism helps reduce the load on your server and improves the response time for subsequent requests for the same data.
-## 包大小分析
+Keep in mind that caching strategies may vary based on your specific requirements and the nature of your data. You can customize the caching logic to suit your needs.
-Umi 同时支持对服务端和客户端包大小的分析
+### Data Pre-fetching Pitfalls
-```bash
-# 服务端包大小分析
-$ ANALYZE_SSR=1 umi build
-# 客户端包大小分析
-$ ANALYZE=1 umi build
-```
+While data pre-fetching in server-side rendering is a powerful feature, it comes with some potential pitfalls and considerations:
-
+1. **Error Handling**: Ensure that you handle errors properly when fetching data in `getInitialProps`. If a data fetch fails on the server side, it can result in a failed SSR response. You should handle errors gracefully and possibly return default data or an error message to avoid breaking the entire page.
-## 谁在使用？
+2. **Data Hydration**: When pre-fetched data is passed to the client, make sure your client-side code can properly hydrate (initialize) components with this data. Mismatched data structures or unexpected null values can lead to client-side errors.
-Hello
- )
-}
-```
-
-2. 通过 umi 提供的 `isBrowser` 方法做环境判断，例如：
-
-```diff
-import React from 'react';
-+ import { isBrowser } from 'umi';
-
-export default () => {
-- window.alert(1);
-+ if (!isBrowser()) {
- window.alert(1);
-+ }
+10. **Monitoring and Logging**: Implement monitoring and logging for data pre-fetching to track performance, detect errors, and troubleshoot issues in production.
- return (
- Hello
- )
-}
-```
-3.如果是第三方库可以通过 umi 提供的 `dynamic` 动态加载组件
-```
-import React from 'react';
-import { dynamic } from 'umi';
-const renderLoading = () => 组件动态加载中...
-export default dynamic({ - loader: async () => { - // 动态加载第三方组件 - const { default: DynamicComponent } = await import( - /* webpackChunkName: "dynamic-component" */ 'dynamic-component' - ); - return DynamicComponent; - }, - loading: () => renderLoading(), -}); -``` -避免ssr渲染时报 ` did not match.`警告，使用时候ssr应当渲染相同`loading`组件 -``` -import React from 'react'; -import { isBrowser } from 'umi'; -import DynamicComponent from 'DynamicComponent'; -export default () => { - if(isBrowser()) returnHello
' }} /> -+Hello' }} />
-```
+### Conclusion
-### 如何判断当前页面是 SSR 还是 CSR？
+Data pre-fetching is a crucial aspect of server-side rendering in Umi 3. It enables you to fetch data on the server and include it in the initial HTML response, improving performance and SEO. By understanding the concepts and best
-查看网页源代码，如果 `
` DOM 里的元素不为空，则是 SSR，否则为 CSR。
+ practices of data pre-fetching, you can build efficient and fast-rendering React applications with Umi 3.
diff --git a/docs/docs/upgrade-to-umi-3.md b/docs/docs/upgrade-to-umi-3.md
index 50bd98080c8e..ced86171a345 100644
--- a/docs/docs/upgrade-to-umi-3.md
+++ b/docs/docs/upgrade-to-umi-3.md
@@ -1,14 +1,10 @@
----
-translateHelp: true
----
-
# Upgrade to Umi 3
-本文档将帮助你从 Umi 2.x 版本升级到 Umi 3.x 版本。
+This document will guide you through the process of upgrading from Umi 2.x to Umi 3.x.
## package.json
-修改 `umi` 的版本为 `^3.0.0` 或以上，
+Update the version of `umi` to `^3.0.0` or higher in your `package.json`:
```diff
{
@@ -19,21 +15,21 @@ translateHelp: true
}
```
-由于 Umi 3 需要 Node 10.13 或以上，如果之前有配 engines，需确认下版本号。
+Since Umi 3 requires Node 10.13 or higher, make sure to check your `engines` configuration if you had it defined previously.
## tsconfig.json
-为了有更好的 ts 提示，需配置 `@@` 为 `["src/.umi/*"]`。
+For better TypeScript type checking, configure `@@` to `["src/.umi/*"]` in your `tsconfig.json`:
```diff
+ "@@/*": ["src/.umi/*"]
```
-## 升级 umi-plugin-react 为 @umijs/preset-react
+## Upgrade `umi-plugin-react` to `@umijs/preset-react`
-如果之前有使用 `umi-plugin-react`，以下是修改的步骤。
+If you were previously using `umi-plugin-react`, follow these steps to upgrade:
-先在 package.json 中修改依赖，
+First, update the dependency in your `package.json`:
```diff
{
@@ -44,7 +40,7 @@ translateHelp: true
}
```
-然后由于 Umi 3 的配置方式是拍平的方式，还需要修改配置，
+Then, because Umi 3 uses a flattened configuration format, you need to modify your configuration. Instead of using plugins, you'll directly configure your plugins and options:
```diff
export default {
@@ -61,59 +57,59 @@ export default {
}
```
-注意：
+Notes:
-1. 无需重复注册插件，Umi 3 会自动注册依赖中的 Umi 插件
-2. 配置提取到外面
+1. There's no need to redundantly register plugins in Umi 3; Umi 3 will automatically register dependencies from your `package.json`.
+2. Configuration has been extracted to the top level.
-功能变化，
+Changes in functionality:
-- 删除了 routes、library、dll、hardSource、pwa、hd、fastClick、chunks，不可继续使用
-- 内置 dynamicImport、title、scripts、headScripts、metas 和 links 到 Umi 中，可继续使用
-- 其他功能不变
+- Removed `routes`, `library`, `dll`, `hardSource`, `pwa`, `hd`, `fastClick`, and `chunks`. These are no longer available.
+- Built-in `dynamicImport`, `title`, `scripts`, `headScripts`, `metas`, and `links` into Umi, and they can still be used.
+- Other functionalities remain unchanged.
-## 配置层
+## Configuration Layer
-Umi 3 在配置层做了大量精简，以下修改以字母排序，便于查找。
+Umi 3 has significantly streamlined the configuration layer. Below are modifications sorted alphabetically for easier reference:
-- 删除 browserslist，和 targets 重复了
-- 删除 babel，基本用不上
-- 修改 cssLoaderOptions 命名为 cssLoader
-- 删除 cssLoaderVersion，只保留 css-loader@2 的版本
-- 删除 cssPublicPath，css 引用的资源文件用相对路径 `./` 可满足所有场景，没有必要再配
-- 删除 disableGlobalVariables，始终无全局变量，无需配置
-- 删除 disableRedirectHoist，始终不再做 redirect hoist
-- 删除 disableCSSModules 和 cssModulesWithAffix，Umi 3 自动识别 css modules 的使用，无需配置
-- 删除 extraBabelIncludes 和 es5ImcompatibleVersions，node_modules 也走 babel 编译后就没有意义了，无需配置
-- 修改 history 格式为 `{ type, options }` ，不再支持 string 格式
-- 修改 lessLoaderOptions 命名为 lessLoader
-- 删除 minimizer，只保留 terserjs
-- 修改 plugins 的格式为字符串，需要先确保依赖的插件是否升级到 Umi 3，然后修改方式参考前面 umi-plugin-react 的修改方式
-- 删除 sass，不再支持，后续会以插件的方式提供
-- 删除 treeShaking，已内置，无需配置
-- 删除 tsConfigFile，没有必要
-- 删除 typescript，TypeScript 编译交给 babel 处理后，之前 ts-loader 的配置就没有意义了
-- 删除 uglifyJSOptions，没有必要
-- 删除 urlLoaderExcludes，没有必要
+- Removed `browserslist`, as it was redundant with `targets`.
+- Removed `babel`, which is rarely needed.
+- Renamed `cssLoaderOptions` to `cssLoader`.
+- Removed `cssLoaderVersion`, keeping only version 2 of `css-loader`.
+- Removed `cssPublicPath`. Using a relative path `./` for CSS resource files covers all scenarios and eliminates the need for this configuration.
+- Removed `disableGlobalVariables`, as there are no global variables by default, so no need for configuration.
+- Removed `disableRedirectHoist`, as redirect hoisting is no longer performed.
+- Removed `disableCSSModules` and `cssModulesWithAffix`. Umi 3 automatically detects the use of CSS modules, so no need for configuration.
+- Removed `extraBabelIncludes` and `es5ImcompatibleVersions`. Compiling `node_modules` with Babel is no longer meaningful in Umi 3, so no need for configuration.
+- Changed the format of `history` to `{ type, options }`, and string format is no longer supported.
+- Renamed `lessLoaderOptions` to `lessLoader`.
+- Removed `minimizer`, keeping only `terserjs`.
+- Changed the format of `plugins` to strings. Ensure that the plugins you depend on have been updated to Umi 3, and then modify them as shown in the previous `umi-plugin-react` upgrade steps.
+- Removed `sass`, which is no longer supported and will be provided as a plugin in the future.
+- Removed `treeShaking`, as it's already built-in and doesn't require configuration.
+- Removed `tsConfigFile`, as it's unnecessary.
+- Removed `typescript`. After TypeScript compilation is handled by Babel, the previous `ts-loader` configuration is no longer needed.
+- Removed `uglifyJSOptions`, as it's unnecessary.
+- Removed `urlLoaderExcludes`, as it's unnecessary.
-## 环境变量层
+## Environment Variable Layer
-## 代码层
+## Code Layer
-### import all from umi
+### Import All from Umi
-不再保留 `umi/xxx` 的接口，全部从 umi 中 import。
+All `umi/xxx` interfaces have been removed. Instead, import everything from `umi`.
-比如：
+For example:
```diff
- import Link from 'umi/link';
+ import { Link } from 'umi';
```
-### umi/router
+### `umi/router`
-改用 `history` 代替。
+Replace `umi/router` with `history`.
```diff
- import router from 'umi/router';
@@ -123,28 +119,28 @@ Umi 3 在配置层做了大量精简，以下修改以字母排序，便于查
+ history.push('/foo');
```
-### CSS 里引用别名或三方库
+### Referencing Aliases or Third-Party Libraries in CSS
-需要加 `~` 前缀。
+You need to prefix with `~` when referencing aliases or third-party libraries in CSS.
-比如：
+For example:
```diff
-# 别名
+# Aliases
- background: url(@/assets/logo.png);
+ background: url(~@/assets/logo.png);
-# 三方库
+# Third-party libraries
- @import url(foo/bar.css);
+ @import url(~foo/bar.css);
```
-## 遇到问题
+## Troubleshooting
-Umi v3 做了非常多的细节改进和重构，我们尽可能收集了已知的所有不兼容变化和相关影响，但是有可能还是有一些场景我们没有考虑到。如果你在升级过程中遇到了问题，请到 [Github issues](https://github.com/umijs/umi/issues) 进行反馈。我们会尽快响应和相应改进这篇文档。
+Umi 3 introduces numerous refinements and refactorings, and we've made every effort to collect all known breaking changes and related impacts. However, there might still be scenarios we haven't considered. If you encounter any issues during the upgrade process, please provide feedback on the [Github issues](https://github.com/umijs/umi/issues) page. We will respond promptly and make corresponding improvements to this document.
-也可以加 "Umi 3 升级问题互帮互助" 群，
+You can also join the "Umi 3 Upgrade Support" group by scanning the QR code below:
-
+
-扫上方二维码，并回复 **umi 3**。
+Scan the QR code and reply with **umi 3** to join the group for assistance.
diff --git a/docs/docs/use-umi-ui.md b/docs/docs/use-umi-ui.md
index 8202e62b67a2..50cb9c8973d3 100644
--- a/docs/docs/use-umi-ui.md
+++ b/docs/docs/use-umi-ui.md
@@ -1,37 +1,31 @@
----
-translateHelp: true
----
-
# Using Umi UI
+> Due to Umi 3's microkernel architecture, the previous Umi UI has been split into a [separate repository](https://github.com/umijs/umi-ui). You can use Umi UI by loading [@umijs/preset-ui](https://github.com/umijs/umi-ui#-%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B).
-> 由于 Umi 3 使用微内核架构，将之前 Umi UI 拆分到[独立的仓库](https://github.com/umijs/umi-ui)，通过加载 [@umijs/preset-ui](https://github.com/umijs/umi-ui#-%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B) 使用 Umi UI。
-
-Umi 项目的本地研发工作台
+Local development workspace for Umi projects
-# ✨ 特性
+# ✨ Features
-- 项目管理。集中式管理本地项目。
-- 配置管理。umi / bigfish 常用项目配置。
-- 任务管理。集成启动、构建、测试、代码规范检查、重新安装依赖等常用操作。
-- 资产、区块管理
+- Project management: Centralized management of local projects.
+- Configuration management: Common project configurations for umi/bigfish.
+- Task management: Integration of common operations such as starting, building, testing, code quality checking, and reinstallation of dependencies.
+- Asset and block management
-# 🔨 使用
+# 🔨 Usage
-在项目中执行
+Execute the following commands in your project:
```bash
$ yarn add @umijs/preset-ui -D
$ UMI_UI=1 umi dev
```
-详见：[Umi UI 视频介绍](https://www.bilibili.com/video/av66178967)。
-
+See: [Introduction to Umi UI (Video)](https://www.bilibili.com/video/av66178967).
-# 🤔 未来
+# 🤔 Future
-更强大的本地研发工作台。
+A more powerful local development workspace.
+
-扫上方二维码，并回复 **umi 3**。
+Scan the QR code and reply with **umi 3** to join the group for assistance.
diff --git a/docs/docs/use-umi-ui.md b/docs/docs/use-umi-ui.md
index 8202e62b67a2..50cb9c8973d3 100644
--- a/docs/docs/use-umi-ui.md
+++ b/docs/docs/use-umi-ui.md
@@ -1,37 +1,31 @@
----
-translateHelp: true
----
-
# Using Umi UI
+> Due to Umi 3's microkernel architecture, the previous Umi UI has been split into a [separate repository](https://github.com/umijs/umi-ui). You can use Umi UI by loading [@umijs/preset-ui](https://github.com/umijs/umi-ui#-%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B).
-> 由于 Umi 3 使用微内核架构，将之前 Umi UI 拆分到[独立的仓库](https://github.com/umijs/umi-ui)，通过加载 [@umijs/preset-ui](https://github.com/umijs/umi-ui#-%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B) 使用 Umi UI。
-
-Umi 项目的本地研发工作台
+Local development workspace for Umi projects
-# ✨ 特性
+# ✨ Features
-- 项目管理。集中式管理本地项目。
-- 配置管理。umi / bigfish 常用项目配置。
-- 任务管理。集成启动、构建、测试、代码规范检查、重新安装依赖等常用操作。
-- 资产、区块管理
+- Project management: Centralized management of local projects.
+- Configuration management: Common project configurations for umi/bigfish.
+- Task management: Integration of common operations such as starting, building, testing, code quality checking, and reinstallation of dependencies.
+- Asset and block management
-# 🔨 使用
+# 🔨 Usage
-在项目中执行
+Execute the following commands in your project:
```bash
$ yarn add @umijs/preset-ui -D
$ UMI_UI=1 umi dev
```
-详见：[Umi UI 视频介绍](https://www.bilibili.com/video/av66178967)。
-
+See: [Introduction to Umi UI (Video)](https://www.bilibili.com/video/av66178967).
-# 🤔 未来
+# 🤔 Future
-更强大的本地研发工作台。
+A more powerful local development workspace.
