@modern-js/main-doc 2.21.0 → 2.22.0

package/docs/en/apis/app/hooks/src/pages.mdx

@@ -4,11 +4,15 @@ sidebar_position: 3
 ---
 # pages/
 
-Entry identifier if the application want uses file system-based routing.
+The identifier for the entry point when the application uses the [`Pages` entry](https://modernjs.dev/v1/docs/guides/usages/entries#pages-%E5%85%A5%E5%8F%A3) type.
 
-When the entry is the **Pages entry** type, the files in the `pages/` directory will be analyzed to client side routing.
+:::info
+Compatible with Modern.js 1.0 `Pages` entry. It is recommended to use [conventional routing](guides/basic-features/routes.html#conventional-routing).
+:::
+
+When the project structure is of the `Pages entry` type, the client-side routing configuration will be obtained by analyzing the files in the `src/pages` directory.
 
-For example, the following directory:
+For example, the following directory structure:
 
 ```bash
 .
@@ -20,7 +24,7 @@ For example, the following directory:
         └── info.jsx
 ```
 
-The generated route is configured as:
+The corresponding generated routing configuration is:
 
 ```bash
 [
@@ -30,22 +34,22 @@ The generated route is configured as:
 ]
 ```
 
-Files match the following conditions will not be treated as routing files:
+Files under the pages directory that meet the following conditions will not be treated as routing files:
 
-- suffix is not `.(j|t)sx?`.
-- `.d.ts` type definition file.
-- test file suffix like `.(test|spec|e2e).(j|t)sx?`.
+- Files whose suffix is not `.(j|t)sx?`.
+- `.d.ts` type definition files.
+- Test files ending in `.test.(j|t)sx?` or `.spec.(j|t)sx?` or `.e2e.(j|t)sx?`.
 
 :::tip
-it is recommended to write only the routing files in the `pages/`, and write the business logic to the independent features directory outside the `pages/`. In this way, most of the files in the pages directory will be routing files, and there is no need for additional filtering rules.
+It is recommended to only write entry code in the pages directory and write business logic in the independent features directory outside the pages directory. In this way, most of the files under the pages directory will be routing files, and there is no need for additional filtering rules.
 
 :::
 
 ### Dynamic Routing
 
-Directories or files wrapped with `[]` are considered dynamic routing.
+If the directory name of the route file is named with [], the generated route will be used as a dynamic route.
 
-For example the following directory structure:
+For example, the following directory structure:
 
 ```bash
 .
@@ -60,7 +64,7 @@ For example the following directory structure:
         └── info.jsx
 ```
 
-The generated route is configured as:
+The corresponding generated routing configuration is:
 
 ```js
 [
@@ -72,13 +76,13 @@ The generated route is configured as:
 ]
 ```
 
-Basis dynamic routing, it supports adding special routing suffixes `(*、?、+)`.
+On the basis of dynamic routing, special routing suffixes `(*, ?, +)` can be added.
 
-For example: `src/pages/users/[id]*.tsx` generate route `/users/:id*`
+For example: `src/pages/users/[id]*.tsx` will result in the route `/users/:id*`.
 
 ### Global Layout
 
-When the entire App needs a global `layout`, it can be achieved through `pages/_app.tsx`, which as follows:
+When the entire application needs a global `layout`, it can be achieved through `pages/_app.tsx`. The specific writing method is as follows:
 
 ```js
 import React from 'react';
@@ -93,9 +97,9 @@ export const App = ({Component, ...pageProps}:{ Component: React.ComponentType})
 }
 ```
 
-The above `Component` is the component to which the route is accessed.
+The above `Component` is the component matched when accessing a specific route.
 
-For example the following directory structure:
+For example, the following directory structure:
 
 ```bash
 .
@@ -107,26 +111,26 @@ For example the following directory structure:
     └── index.js
 ```
 
-- access `/`, the `Component` is `pages/index.js`.
-- access `/a`, the `Component` is `pages/a/index.js`.
-- access `/a/b`, the `Component` is `pages/a/b/index.js`.
+- Accessing `/` corresponds to the `Component` component in `pages/index.js`.
+- Accessing `/a` corresponds to the `Component` component in `pages/a/index.js`.
+- Accessing `/a/b` corresponds to the `Component` component in `pages/a/b/index.js`.
 
-:::tip Advantages
+:::tip Advantages of global layout
 
-- preserve the state of the global layout when the page changes.
-- add global css.
-- handle ComponentDidCatch error
-- use [defineConfig](/apis/app/runtime/app/define-config) dynamic configuration runtime.
+- Preserve the state of the global layout when the page changes.
+- Add global styles.
+- ComponentDidCatch error handling.
+- Use [defineConfig](/apis/app/runtime/app/define-config) to dynamically configure the runtime configuration.
 
 :::
 
 ### Partial Layout
 
-When developing an App, where sub routes under the same route may share the layout.
+When developing an application, there are scenarios where sub-routes under the same route share a layout.
 
-For this scene, Modern.js convention, when there is a `_layout.js` in the directory, the routes can shared this layout.
+For this scenario, Modern.js conventionally has a similar effect to global layout when there is `_layout.js` under the directory.
 
-For example the following directory structure:
+For example, the following directory structure:
 
 ```bash
 └── pages
@@ -147,18 +151,18 @@ const ALayout = ({ Component, ...pageProps }) => {
 export default ALayout;
 ```
 
-The Component props is the specific route, for example
+The `Component` parameter is the component corresponding to a specific accessed route, for example:
 
-- access `/a`, the `Component` is `pages/a/index.js`.
-- 访问 `/a/b`, the `Component` is `pages/a/b/index.js`.
+- Accessing `/a` corresponds to the `Component` component in `pages/a/index.js`.
+- Accessing `/a/b` corresponds to the `Component` component in `pages/a/b/index.js`.
 
-In this way, you can use `pages/a/_layout.js` to display the routing common layout in the `a` directory.
+In this way, `pages/a/_layout.js` can be used to meet the layout needs of shared routes under the `a` directory.
 
-### 404 路由
+### 404 Route
 
-The convention `pages/404.[tj]sx` is the default 404 route.
+`pages/404.[tj]sx` is conventionally the default 404 route.
 
-For example the following directory structure:
+For example, the following directory structure:
 
 ```bash
 .
@@ -169,7 +173,7 @@ For example the following directory structure:
         ├── 404.js
 ```
 
-the generated route is configured is as:
+The generated routing configuration is as follows:
 
 ```bash
 [
@@ -179,4 +183,4 @@ the generated route is configured is as:
 ]
 ```
 
-All unmatched routes will match to `pages/404.[tj]s`.
+All unmatched routes will be matched to `pages/404.[tj]s`.

package/docs/en/apis/app/hooks/src/routes.mdx

@@ -4,13 +4,13 @@ sidebar_position: 2
 ---
 # routes/
 
-The entry identifier when the application uses file system-based routing.
+The identifier for the entry point when the application uses [Conventional Routing](guides/basic-features/routes.html#conventional-routing).
 
-When the project structure is of type `Routes directory entry`, the files in the `src/routes` directory are parsed to get the client-side routing configuration. See [Routing by convention](/guides/basic-features/routes) for more details on usage.
+Conventional routing uses `routes/` as the convention for the entry point and analyzes the files in the `src/routes` directory to obtain the client-side routing configuration.
 
-Any `layout.[tj]sx` and `page.[tj]sx` under `src/routes` will be used as a route to the application:
+Any `layout.[tj]sx` and `page.[tj]sx` under `src/routes` will be used as the application's routes:
 
-```bash {3}
+```bash {3,4}
 .
 └── routes
     ├── layout.tsx
@@ -20,9 +20,9 @@ Any `layout.[tj]sx` and `page.[tj]sx` under `src/routes` will be used as a route
         └── page.tsx
 ```
 
-## basic example
+## Basic Example
 
-The directory names in the `routes` directory will be used as a mapping of the route url, where `layout.tsx` is used as the layout component and `page.tsx` as the content component, which is a leaf node of the whole route, for example the following directory structure:
+The directory name under `routes` will be used as the mapping of the route URL. `layout.tsx` is used as the layout component and `page.tsx` is used as the content component in the routing. They are the leaf nodes of the entire route. For example, the following directory structure:
 
 ```bash
 .
@@ -32,14 +32,14 @@ The directory names in the `routes` directory will be used as a mapping of the r
         └── page.tsx
 ```
 
-The following two routes are produced:
+will generate two routes:
 
 - `/`
 - `/user`
 
-## Dynamic Route
+## Dynamic Routing
 
-If the directory name of the route file is named with `[]`, the generated route will be used as a dynamic route. For example, the following file directories:
+If the directory name of the route file is named with `[]`, the generated route will be used as a dynamic route. For example, the following file directory:
 
 ```
 └── routes
@@ -50,35 +50,15 @@ If the directory name of the route file is named with `[]`, the generated route
     └── page.tsx
 ```
 
-The `routes/[id]/page.tsx` file will be converted to a `/:id` route. All `/xxx` will match that route, except for the `/blog` route, which can be matched exactly.
+The `routes/[id]/page.tsx` file will be converted to the `/:id` route. Except for the `/blog` route that can be matched exactly, all other `/xxx` routes will be matched to this route.
 
-In the component, you can get the corresponding parameters by [useParams](/apis/app/runtime/router/router#useparams).
+In the component, you can use [useParams](/apis/app/runtime/router/router#useparams) to obtain the corresponding named parameter.
 
-In the loader, params will be used as input to [loader](/guides/basic-features/data-fetch#loader-function), and the corresponding parameters can be retrieved through the property `params`.
+When using the [loader](/guides/basic-features/data-fetch#the-loader-function) function to obtain data, `params` will be passed as an input parameter to the `loader` function, and the corresponding parameter can be obtained through the attribute of `params`.
 
-## Dynamic Optional Routes
+## Layout Component
 
-By using file directories named with `[$]`, the generated routes will be treated as dynamic routes. For example, the following file directory:
-
-```
-└── routes
-    ├── user
-    │   └── [id$]
-    │       └── page.tsx
-    ├── blog
-    │   └── page.tsx
-    └── page.tsx
-```
-
-The `routes/user/[id$]/page.tsx` file will be converted to the `/user/:id?` route. All routes under `/user` will match this route, and the `id` parameter is optional. This route is commonly used to differentiate between **creating** and **editing**.
-
-In the component, you can get the corresponding named parameters using [useParams](/apis/app/runtime/router/router#useparams).
-
-In the loader, params will be passed as an argument to the [loader](/guides/basic-features/data-fetch#loader-函数), and you can get them through `params.xxx`.
-
-## Layout component
-
-As in the example below, you can add a common layout component for all routing components by adding `layout.tsx`
+In the following example, a common layout component can be added to all route components by adding `layout.tsx`:
 
 ```bash
 .
@@ -90,7 +70,7 @@ As in the example below, you can add a common layout component for all routing c
         └── page.tsx
 ```
 
-You can represent child components in layout components by using `<Outlet>`:
+In the layout component, you can use `<Outlet>` to represent the child components:
 
 ```tsx title=routes/layout.tsx
 import { Link, Outlet, useLoaderData } from '@modern-js/runtime/router';
@@ -105,6 +85,6 @@ export default () => {
 ```
 
 :::note
-`<Outlet>` is a new API in React Router 6, see [Outlet] for details(https://reactrouter.com/en/main/components/outlet#outlet).
+`<Outlet>` is a new API in React Router 6. For details, see [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
 
 :::

package/docs/en/apis/app/hooks/src/server.mdx

@@ -4,4 +4,4 @@ sidebar_position: 8
 ---
 # *.[server|node].[tj]sx
 
-Used in application projects to place server side code, When `*.tsx` and `*. [server|node].tsx` coexist, rendering on the server side will give preference to the `*. [server|node].tsx` file instead of the `*.tsx` file.
+Used in the application project to place server-side code. When `*.tsx` and `*.[server|node].tsx` coexist, SSR will prefer to use the `*.[server|node].tsx` file instead of the `*.tsx` file when rendering on the server.

package/docs/en/apis/app/hooks/src/stories.mdx

@@ -4,11 +4,14 @@ sidebar_position: 7
 ---
 # **/*.stories.[tj]sx
 
-App Storybook debug file. files in `src/` which suffix `*.stories.[tj]sx` are as debug files for Storybook.
+Application project Storybook files.
 
-Execute the `dev story` command to debugging these files in the Storybook.
+You can create files in the `*.stories.[tj]sx` format in the project source code directory `src/` as Storybook files.
+
+Run the `npm run dev story` command in the project to use these files to debug relevant content in Storybook.
 
 :::info
-Using a Storybook requires executing `new` command to enable the 「Visual Testing (Storybook)」 mode.
+To use Storybook, you need to enable the "Visual Testing (Storybook)" mode by running the `new` command in the project first.
 
 :::
+

package/docs/en/apis/app/hooks/src/test.mdx

@@ -2,13 +2,14 @@
 title: '**/*.test.[tj]sx?'
 sidebar_position: 6
 ---
+
 # **/*.test.[tj]sx?
 
-App test file.
+Application project test files.
 
-The App supports the file suffixed with `.test.[tj]sx` under the `src/` to write test cases.
+The application project supports creating files with the suffix `.test.[tj]sx?` in the project source code directory (`src`) to write test cases.
 
 :::info
-To use unit test and integration test, you need to execute the `new` command in advance to enable the `unit test/integration test`.
+To use unit testing and integration testing, you need to enable the "Unit Testing / Integration Testing" feature by running the `new` command in the project first.
 
 :::

package/docs/en/apis/app/runtime/core/use-runtime-context.mdx

@@ -28,6 +28,7 @@ type RuntimeContext = {
     cookie: string;
   };
   store: ReduckStore;
+  router: RemixRouter;
 };
 
 function useRuntimeContext(): RuntimeContext;
@@ -41,7 +42,10 @@ function useRuntimeContext(): RuntimeContext;
   - `query`: the query of the request.
   - `headers`: the header info of the request.
   - `cookie`: the cookie of the request.
-- `store`: when the runtime.state is enabled, this value is the reduck global `store`.
+- `store`: when the `runtime.state` is enabled, this value is the Reduck global `store`.
+- `router`: When the `runtime.router` is enabled, this value exists.
+  - `location`: The current location reflected by the router. The same as [`useLocation`] the return value of (/apis/app/runtime/router/router.html#uselocation).
+  - `navigate`: Navigate to the given path. The same as the return value of [`useNavigate`](/apis/app/runtime/router/router.html#usenavigate).
 
 ## Example
 

package/docs/en/apis/app/runtime/web-server/hook.mdx

@@ -24,8 +24,8 @@ Before using this API, please execute `pnpm run new` to create a new "Custom Web
 
 ```bash
 pnpm run new
-? Action Create project element
-? New "Custom Web Server" source code directory
+? Please select the operation you want: Create Elements
+? Please select the type of element to create: New "Custom Web Server" source code directory
 ```
 
 :::

package/docs/en/apis/app/runtime/web-server/middleware.mdx

@@ -27,8 +27,8 @@ Before using this API, please execute `pnpm run new` to create a new "Custom Web
 
 ```bash
 pnpm run new
-? Action Create project element
-? New "Custom Web Server" source code directory
+? Please select the operation you want: Create Element
+? Please select the type of element to create: New "Custom Web Server" source code directory
 ```
 
 :::

package/docs/en/components/global-proxy.mdx

@@ -1,14 +1,14 @@
-Modern.js provides out-of-the-box global proxy plugin `@modern-js/plugin-proxy`, which is based on [whistle](https://github.com/avwo/whistle) and can be used to view and modify HTTP/HTTPS requests and responses, and can also be used as an HTTP proxy server.
+Modern.js provides an out-of-the-box global proxy plugin `@modern-js/plugin-proxy`, which is based on [whistle](https://github.com/avwo/whistle) and can be used to view and modify the requests and responses of HTTP/HTTPS, as well as be used as an HTTP proxy server.
 
-### Set Proxy Rules
+### Setting Proxy Rules
 
-After install the proxy plugin and filling in the rules, execute `pnpm run dev`, Modern.js will automatically enable the proxy server after the development server starts.
+After installing the proxy plugin and configuring the rules, run `pnpm run dev`. Modern.js will automatically enable the proxy server when the development server is started.
 
 Specific proxy rules can be set via the [`dev.proxy`](/configure/app/dev/proxy) or the `config/proxy.js` file.
 
-### Use Proxy Dashboard
+### Proxy Dashboard
 
-After exec `pnpm run dev` command:
+After installing the proxy plugin and configuring the proxy rules, run the `pnpm run dev` command:
 
 ```bash
   App running at:
@@ -20,8 +20,8 @@ After exec `pnpm run dev` command:
 ✔  success   Proxy Server start on localhost:8899
 ```
 
-In the console you can see that the proxy server started successfully.
+You can see that the proxy server has started successfully in the console.
 
-Accessing the `http://localhost:8899` and, you can set the rules through the dashboard.
+Access `http://localhost:8899`, and you can set the rules through the dashboard.
 
 ![debug-proxy-ui](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/debug/debug-proxy-ui.png)

package/docs/en/components/init-app.mdx

@@ -1,9 +1,9 @@
 Modern.js generator will provide an interactive Q & A interface, initialization items according to the result, according to the default selection:
 
 ```bash
-? Please select the solution you want to create: Web App
-? Development Language: TS
-? Package Manager: pnpm
+? Please select the type of project you want to create: Web App
+? Please select the programming language: TS
+? Please select the package manager: pnpm
 ```
 
 After create the project, Modern.js automatically installs dependency and creates a git repository.

package/docs/en/components/init-rspack-app.mdx

@@ -1,7 +1,7 @@
 ```bash
 $ npx @modern-js/create@latest myapp
-? Please select the solution you want to create: Web App
-? Development Language: TS
-? Package Manager: pnpm
-? Bundler: Rspack
+? Please select the type of project you want to create: Web App
+? Please select the programming language: TS
+? Please select the package manager: pnpm
+? Please select the bundler: Rspack
 ```

package/docs/en/components/language-config.mdx

@@ -0,0 +1,9 @@
+### language
+
+Question: Please select the programming language.
+
+Options:
+
+- TS -- ts
+
+- ES6+ -- js

package/docs/en/components/package-manager.mdx

@@ -0,0 +1,11 @@
+### packageManager
+
+Question: Please select the package manager.
+
+Options:
+
+- pnpm -- pnpm
+
+- Yarn -- yarn
+
+- npm -- npm

package/docs/en/components/ua-polyfill.mdx

@@ -9,8 +9,8 @@ Modern.js also provides a runtime Polyfill solution based on browser [UA](https:
 exec `pnpm run new` to enable this features:
 
 ```bash
-? Action Enable features
-? Enable features Enable UA-based Polyfill Feature
+? Please select the operation you want: Enable features
+? Please select the feature name: Enable UA-based Polyfill Feature
 ```
 
 After executing the command, register the Polyfill plugin in `modern.config.ts`:

package/docs/en/configure/app/source/config-dir.mdx

@@ -9,7 +9,7 @@ sidebar_label: configDir
 
 Modern.js supports placing some files in the `./config` folder to customize HTML templates, icons, static resources, etc. For details, please refer to [File Convention](/apis/app/hooks/config/html).
 
-This option allows you to customize the directory of configuration files.
+This option allows you to customize the directory of the configuration files.
 
 For example, adjust the resource file directory to the `resources` directory: