chore: review code split docs (#3921)

* chore: review code split docs * docs: change changeset * chore: code review
web-infra-dev · Jun 12, 2023 · 8bb0e14 · 8bb0e14
1 parent 65721f2
commit 8bb0e14
Show file tree

Hide file tree

Showing 3 changed files with 34 additions and 26 deletions.
diff --git a/.changeset/weak-parents-poke.md b/.changeset/weak-parents-poke.md
@@ -0,0 +1,6 @@
+---
+'@modern-js/main-doc': patch
+---
+
+chore: review code split docs
+chore: 审查代码分割文档
diff --git a/packages/document/main-doc/docs/en/guides/advanced-features/code-split.mdx b/packages/document/main-doc/docs/en/guides/advanced-features/code-split.mdx
@@ -2,13 +2,12 @@
 title: Code Split
 sidebar_position: 6
 ---
-# Code Split
+# Code Splitting
 
-Code Split is a common way to optimizing front-end resource loading. This doc will introduce three methods supported by Modern.js:
+Code splitting is a common method to optimize frontend resource loading. This article will introduce the three types of code splitting supported by Modern.js:
 
 :::info
-When you use Modern.js [Conventional routing](/guides/basic-features/routes#conventional-routing), by default it will do code splitting based on routing components, wrapping `Suspense` components, no need to do code splitting by yourself.
-
+When using Modern.js [Conventional routing](/guides/basic-features/routes#conventional-routing). By default, code splitting is done according to the routing component, so you don't need to do it yourself.
 :::
 
 - `import`
@@ -17,23 +16,22 @@ When you use Modern.js [Conventional routing](/guides/basic-features/routes#conv
 
 ## import
 
-use dynamic `import()`, `import` The JS modules pass to this API will be packaged into a separate JS file as a new packaging entry, for example:
+use dynamic `import()`, the JS modules pass to this API will be packaged as a separate JS file, for example:
 
 ```ts
 import('./math').then(math => {
   console.log(math.add(16, 26));
 });
 ```
 
-The JS modules corresponding to the './math' path will be packaged in a separate JS file.
-
 ## React.lazy
 
 The officially way provides by React to split component code.
 
 :::caution
-SSR is not supported in React 17 and below, and it is recommended that SSR applications for React 17 use loadable.
+`React.lazy` is typically used in together with `<Suspense>`, hence it is only available in CSR or React 18 Streaming SSR.
 
+For projects that use Traditional SSR（renderToString）, `React.lazy` is not supported. Please use the Loadable API instead.
 :::
 
 ```ts
@@ -56,11 +54,11 @@ function MyComponent() {
 }
 ```
 
-For detail, see [React lazy](https://reactjs.org/docs/code-splitting.html#reactlazy).
+For details, see [React lazy](https://reactjs.org/docs/code-splitting.html#reactlazy).
 
-## loadable
+## Loadable
 
-use `loadable` API, for example:
+In Modern.js, you can use the Loadable API, which is exported from `@modern-js/runtime/loadable`. Here's an example:
 
 ```ts
 import loadable from '@modern-js/runtime/loadable';
@@ -72,9 +70,12 @@ function MyComponent() {
 }
 ```
 
-For detail, see [loadable API](/apis/app/runtime/utility/loadable).
+With the out-of-the-box support of `loadable` in SSR by Modern.js, you no longer need to add Babel plugins or inject scripts into HTML during SSR.
 
-:::info
-SSR is supported out of the box by `loadable`.
+However, it's important to note that any Loadable API in SSR does not support the use of `<Suspense>`.
 
+:::info
+If you want to use `<Suspense>` in CSR projects with React 17 and below, you can substitute `React.lazy` with `loadable.lazy`.
 :::
+
+For details, see [Loadable API](/apis/app/runtime/utility/loadable).
diff --git a/packages/document/main-doc/docs/zh/guides/advanced-features/code-split.mdx b/packages/document/main-doc/docs/zh/guides/advanced-features/code-split.mdx
@@ -7,8 +7,7 @@ sidebar_position: 6
 代码分割是优化前端资源加载的一种常用手段，本文将介绍 Modern.js 支持的三种代码分割方式：
 
 :::info
-使用 Modern.js [约定式路由](/guides/basic-features/routes#约定式路由)时，默认会根据路由组件做代码分割，包裹 `Suspense` 组件，无需自行进行代码分割。
-
+使用 Modern.js [约定式路由](/guides/basic-features/routes#约定式路由)时，默认会根据路由组件做代码分割，无需自行进行代码分割。
 :::
 
 - `import`
@@ -17,23 +16,22 @@ sidebar_position: 6
 
 ## import
 
-使用动态 `import()` 语法，`import` 接收的 JS 模块将作为一个新的打包入口被打包到单独的 JS 文件中。例如：
+使用动态 `import()` 语法，传入的 JS 模块将会被被打包到单独的 JS 文件中。例如：
 
 ```ts
 import('./math').then(math => {
   console.log(math.add(16, 26));
 });
 ```
 
-`./math` 路径对应的 JS 模块会被打包到单独的 JS 文件中。
-
 ## React.lazy
 
 React 官方提供的组件代码分割的方式。
 
 :::caution
-React 17 及以下版本不支持 SSR，建议 React17 的 SSR 应用使用 loadable。
+`React.lazy` 通常配合 `<Suspense>` 使用，因此仅在 CSR 或 React 18 Streaming SSR 中可用。
 
+对于使用传统 SSR（字符串渲染）的项目，不支持 `React.lazy`，请使用 Loadable API。
 :::
 
 ```ts
@@ -56,11 +54,11 @@ function MyComponent() {
 }
 ```
 
-`React.lazy` 更多用法请见 [React lazy](https://zh-hans.reactjs.org/docs/code-splitting.html#reactlazy)。
+`React.lazy` 更多用法请见 [React 官网文档](https://zh-hans.reactjs.org/docs/code-splitting.html#reactlazy)。
 
-## loadable
+## Loadable
 
-使用 `loadable` API，示例如下：
+在 Modern.js 中，可以从 `@modern-js/runtime/loadable` 中导出使用 Loadable API，示例如下：
 
 ```ts
 import loadable from '@modern-js/runtime/loadable';
@@ -72,9 +70,12 @@ function MyComponent() {
 }
 ```
 
-`loadable` 更多用法请见 [loadable API](/apis/app/runtime/utility/loadable)。
+Modern.js 开箱即用的支持在 SSR 中使用 `loadable`，无需再添加 Babel 插件，或是在 SSR 时向 HTML 中注入脚本。
 
-:::info
-`loadable` 开箱即用的支持 SSR，但不支持和 Suspense 一起使用，如果是 CSR 项目可以使用 [loadable.lazy](https://loadable-components.com/docs/suspense/)
+但需要注意的是，任何 Loadable API 在 SSR 中都不支持配合 `<Suspense>` 使用。
 
+:::info
+如果希望在 React 17 及以下的 CSR 项目中使用 `<Suspense>`，可以用 [loadable.lazy](https://loadable-components.com/docs/suspense/) 代替 `React.lazy`。
 :::
+
+更多用法请见 [Loadable API](/apis/app/runtime/utility/loadable)。