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

package/docs/en/guides/advanced-features/international/routing.mdx

@@ -0,0 +1,212 @@
+---
+title: Routing Integration
+---
+
+# Routing Integration
+
+The plugin is deeply integrated with Modern.js routing system, supporting language path prefixes and automatic path redirection.
+
+## Enable Path Redirection
+
+When `localePathRedirect` is set to `true`, the plugin will automatically add language prefixes to URLs and handle path redirection when switching languages.
+
+**Configuration**:
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
+    // Optional: ignore automatic redirection for certain routes
+    ignoreRedirectRoutes: ['/api', '/admin'],
+  },
+});
+```
+
+### Ignore Redirection Routes
+
+Some routes (such as API routes, static resources, etc.) don't need language prefixes. You can use the `ignoreRedirectRoutes` configuration to ignore automatic redirection for these routes:
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
+    // String array: supports exact match and prefix match
+    ignoreRedirectRoutes: ['/api', '/admin', '/static'],
+    // Or use function for more flexible judgment
+    ignoreRedirectRoutes: pathname => {
+      return pathname.startsWith('/api') || pathname.startsWith('/admin');
+    },
+  },
+});
+```
+
+For more details, please refer to the `ignoreRedirectRoutes` configuration in the [Locale Detection documentation](./locale-detection#ignoreredirectroutes).
+
+## Route Configuration
+
+After enabling path redirection, you need to add `:lang` dynamic parameter to the route configuration.
+
+### Convention-based Routing
+
+When using convention-based routing, you need to create a `[lang]` directory under the `routes/` directory to represent the language parameter:
+
+```bash
+routes/
+├── [lang]/
+│   ├── layout.tsx    # Layout component
+│   ├── page.tsx      # Home page
+│   ├── about/
+│   │   └── page.tsx  # About page
+│   └── contact/
+│       └── page.tsx  # Contact page
+```
+
+**routes/[lang]/layout.tsx**:
+
+```tsx
+import { Outlet } from '@modern-js/runtime/router';
+
+export default function Layout() {
+  return <Outlet />;
+}
+```
+
+**routes/[lang]/page.tsx**:
+
+```tsx
+export default function Home() {
+  return <div>Home</div>;
+}
+```
+
+**routes/[lang]/about/page.tsx**:
+
+```tsx
+export default function About() {
+  return <div>About</div>;
+}
+```
+
+**routes/[lang]/contact/page.tsx**:
+
+```tsx
+export default function Contact() {
+  return <div>Contact</div>;
+}
+```
+
+**Generated Route Structure**:
+
+```
+/:lang          → Home page
+/:lang/about    → About page
+/:lang/contact  → Contact page
+```
+
+When accessing `/` or `/about`, it will automatically redirect to `/en` or `/en/about` (using the default language).
+
+### Custom Routing
+
+If using custom routing (`modern.routes.ts`), you need to add `:lang` dynamic parameter in the route configuration:
+
+```tsx
+import {
+  BrowserRouter,
+  Route,
+  Routes,
+  Outlet,
+} from '@modern-js/runtime/router';
+
+function App() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        {/* Add :lang parameter */}
+        <Route path=":lang" element={<Outlet />}>
+          <Route index element={<Home />} />
+          <Route path="about" element={<About />} />
+          <Route path="contact" element={<Contact />} />
+        </Route>
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+
+:::info
+Convention-based routing will automatically generate corresponding routes based on the file structure. It's recommended to use convention-based routing. Only use custom routing when special route control is needed.
+
+:::
+
+## I18nLink Component
+
+The `I18nLink` component is provided by `@modern-js/plugin-i18n` and automatically adds the current language prefix to paths.
+
+### Basic Usage
+
+```tsx
+import { I18nLink } from '@modern-js/plugin-i18n/runtime';
+
+function Navigation() {
+  return (
+    <nav>
+      <I18nLink to="/">Home</I18nLink>
+      <I18nLink to="/about">About</I18nLink>
+      <I18nLink to="/contact">Contact</I18nLink>
+    </nav>
+  );
+}
+```
+
+**When current language is `en`**:
+
+- `<I18nLink to="/">` → Actual link: `/en`
+- `<I18nLink to="/about">` → Actual link: `/en/about`
+
+**When current language is `zh`**:
+
+- `<I18nLink to="/">` → Actual link: `/zh`
+- `<I18nLink to="/about">` → Actual link: `/zh/about`
+
+### Automatic Language Prefix
+
+`I18nLink` automatically handles language prefixes, no need to add them manually:
+
+```tsx
+// ✅ Correct: No need to manually add language prefix
+<I18nLink to="/about">About</I18nLink>
+
+// ❌ Wrong: Don't manually add language prefix
+<I18nLink to="/en/about">About</I18nLink>
+```
+
+### Props
+
+`I18nLink` accepts all `Link` component props and additionally supports:
+
+```tsx
+interface I18nLinkProps {
+  /** Target path (no need to include language prefix) */
+  to: string;
+  /** Child elements */
+  children: React.ReactNode;
+  /** Other Link component props */
+  [key: string]: any;
+}
+```
+
+**Example**:
+
+```tsx
+<I18nLink to="/about" replace>
+  About
+</I18nLink>
+
+<I18nLink to="/contact" state={{ from: 'home' }}>
+  Contact
+</I18nLink>
+```

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

@@ -0,0 +1,37 @@
+---
+title: Internationalization
+---
+
+# Internationalization
+
+import I18nPluginIntroduce from '@site-docs/components/international/introduce';
+
+<I18nPluginIntroduce />
+
+## Core Features
+
+- 🌍 **Multi-language Support**: Easily manage translation resources for multiple languages
+- 🔍 **Smart Language Detection**: Supports automatic language detection from URL paths, cookies, request headers, and more
+- 📦 **Flexible Resource Loading**: Supports three resource loading methods: HTTP, file system, and custom SDK
+- 🛣️ **Route Integration**: Deeply integrated with Modern.js routing system, supports language path prefixes
+- ⚡ **SSR Support**: Full support for server-side rendering (SSR) scenarios
+- 🎯 **TypeScript Support**: Complete TypeScript type definitions
+
+## Use Cases
+
+- Web applications that need to support multiple languages
+- Multi-language routing that is SEO-friendly
+- Multi-language applications that require server-side rendering
+- Applications that need to dynamically load translation resources from external services
+
+## Documentation Navigation
+
+- [Basic Concepts](./international/basic) - Core concepts and terminology
+- [Quick Start](./international/quick-start) - Detailed installation and configuration guide
+- [Configuration](./international/configuration) - CLI and runtime configuration details
+- [Locale Detection](./international/locale-detection) - Multiple language detection methods and priorities
+- [Resource Loading](./international/resource-loading) - HTTP, FS, and SDK backend usage
+- [Routing Integration](./international/routing) - Path redirection and I18nLink component
+- [API Reference](./international/api) - Complete API documentation and type definitions
+- [Advanced Usage](./international/advanced) - SSR, multi-entry, custom instances, and more
+- [Best Practices](./international/best-practices) - Resource organization, error handling, type safety

package/docs/en/guides/advanced-features/low-level.mdx

@@ -6,16 +6,18 @@ sidebar_position: 10
 
 ## Usage
 
-Modern.js internally integrates tools such as [Babel](https://babeljs.io/), [TypeScript](https://www.typescriptlang.org/), [Webpack](https://webpack.js.org/), [PostCSS](https://postcss.org/), [Tailwind CSS](https://tailwindcss.com/) by default.
+Modern.js internally integrates tools such as [TypeScript](https://www.typescriptlang.org/), [Rspack](https://rspack.rs/), [PostCSS](https://postcss.org/), [SWC](https://swc.rs/) by default.
 
 Usually, the default configuration can meet most development needs. When there are special needs, it can be achieved through the underlying configuration.
 
-Take configuring Webpack as an example, just add [tools.webpack](/configure/app/tools/webpack) to the modern.config.ts:
+Take configuring Rspack as an example, just add [tools.rspack](/configure/app/tools/rspack) to the modern.config.ts:
 
 ```ts title="modern.config.ts"
 export default defineConfig({
   tools: {
-    webpack: config => {},
+    rspack: config => {
+      // Modify Rspack configuration
+    },
   },
 });
 ```
@@ -30,16 +32,19 @@ When the value is `Function`, the first parameter is the default configuration v
 
 Currently provided is as follows:
 
-| Tools             | Config                                                                |
-| ----------------- | --------------------------------------------------------------------- |
-| DevServer         | [tools.devServer](/configure/app/tools/dev-server)               |
-| Babel             | [tools.babel](/configure/app/tools/babel)                        |
-| styled-components | [tools.styledComponents](/configure/app/tools/styled-components) |
-| PostCSS           | [tools.postcss](/configure/app/tools/postcss)                    |
-| Less              | [tools.less](/configure/app/tools/less)                          |
-| Sass              | [tools.sass](/configure/app/tools/sass)                          |
-| webpack           | [tools.webpack](/configure/app/tools/webpack)                    |
-| Minify CSS        | [tools.minifyCss](/configure/app/tools/minify-css)               |
-| terser            | [tools.terser](/configure/app/tools/terser)                      |
-| Tailwind CSS      | [tools.tailwind](/configure/app/tools/tailwindcss)               |
-| Autoprefixer      | [tools.autoprefixer](/configure/app/tools/autoprefixer)          |
+| Tools              | Config                                                               |
+| ------------------ | -------------------------------------------------------------------- |
+| Rspack             | [tools.rspack](/configure/app/tools/rspack)                          |
+| Bundler Chain      | [tools.bundlerChain](/configure/app/tools/bundler-chain)             |
+| SWC                | [tools.swc](/configure/app/tools/swc)                                |
+| TypeScript Checker | [tools.tsChecker](/configure/app/tools/ts-checker)                   |
+| PostCSS            | [tools.postcss](/configure/app/tools/postcss)                        |
+| Less               | [tools.less](/configure/app/tools/less)                              |
+| Sass               | [tools.sass](/configure/app/tools/sass)                              |
+| CSS Extract        | [tools.cssExtract](/configure/app/tools/css-extract)                 |
+| CSS Loader         | [tools.cssLoader](/configure/app/tools/css-loader)                   |
+| Style Loader       | [tools.styleLoader](/configure/app/tools/style-loader)               |
+| Lightning CSS      | [tools.lightningcssLoader](/configure/app/tools/lightningcss-loader) |
+| Minify CSS         | [tools.minifyCss](/configure/app/tools/minify-css)                   |
+| Autoprefixer       | [tools.autoprefixer](/configure/app/tools/autoprefixer)              |
+| HTML Plugin        | [tools.htmlPlugin](/configure/app/tools/html-plugin)                 |

package/docs/en/guides/advanced-features/page-performance/code-split.mdx

@@ -7,7 +7,7 @@ sidebar_position: 3
 Code splitting is a common way to optimize frontend resource loading. This article will introduce the three types of code splitting supported by Modern.js:
 
 :::info
-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.
+When using Modern.js [Conventional routing](/guides/basic-features/routes/routes#conventional-routing). By default, code splitting is done according to the routing component, so you don't need to do it yourself.
 :::
 
 - dynamic `import`
@@ -16,7 +16,7 @@ When using Modern.js [Conventional routing](/guides/basic-features/routes#conven
 
 ## Dynamic import
 
-use dynamic `import()`, the JS modules pass to this API will be bundled as a separate JS file, for example:
+When using dynamic `import()`, the JS modules passed to this API will be bundled as a separate JS file. For example:
 
 ```ts
 import('./math').then(math => {
@@ -26,10 +26,10 @@ import('./math').then(math => {
 
 ## React.lazy
 
-The officially way provides by React to split component code.
+The official way provided by React to split component code.
 
 :::caution
-`React.lazy` is typically used in together with `<Suspense>`, hence it is only available in CSR or React 18 Streaming SSR.
+`React.lazy` is typically used 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.
 :::

package/docs/en/guides/advanced-features/page-performance/inline-assets.mdx

@@ -102,12 +102,12 @@ Excluding assets from inlining will increase the number of assets that the Web A
 
 In addition to inlining static assets into JS files, Modern.js also supports inlining JS files into HTML files.
 
-Just enable the [output.enableInlineScripts](/configure/app/output/enable-inline-scripts) config, and the generated JS files will not be written into the output directory, but will be directly inlined to the corresponding in the HTML file.
+Just enable the [output.inlineScripts](/configure/app/output/inline-scripts) config, and the generated JS files will not be written into the output directory, but will be directly inlined to the corresponding in the HTML file.
 
 ```ts
 export default {
   output: {
-    enableInlineScripts: true,
+    inlineScripts: true,
   },
 };
 ```
@@ -120,12 +120,12 @@ Inline JS files may cause the single HTML file to be too large, and it will brea
 
 You can also inline CSS files into HTML files.
 
-Just enable the [output.enableInlineStyles](/configure/app/output/enable-inline-styles) config, the generated CSS file will not be written into the output directory, but will be directly inlined to the corresponding in the HTML file.
+Just enable the [output.inlineStyles](/configure/app/output/inline-styles) config, the generated CSS file will not be written into the output directory, but will be directly inlined to the corresponding in the HTML file.
 
 ```ts
 export default {
   output: {
-    enableInlineStyles: true,
+    inlineStyles: true,
   },
 };
 ```

package/docs/en/guides/advanced-features/page-performance/optimize-bundle.mdx

@@ -40,26 +40,26 @@ If you want to find out the large libraries in the project, you can add the `BUN
 BUNDLE_ANALYZE=true pnpm build
 ```
 
-See the [performance.bundleAnalyze](/configure/app/performance/bundle-analyze.html) configuration for details.
+This will generate a bundle analysis report to help you identify large dependencies.
 
 ## Adjust Browserslist
 
 Modern.js will compile the code according to the project's Browserslist config, and inject some Polyfills. If the project does not need to be compatible with legacy browsers, you can adjust the Browserslist and drop some legacy browsers, thereby reducing the compilation overhead on syntax and polyfill.
 
-Modern.js's default Browserslist config is:
+Modern.js's default [`output.overrideBrowserslist`](/configure/app/output/override-browserslist.html) config is:
 
 ```js
-['> 0.01%', 'not dead', 'not op_mini all'];
+['chrome >= 87', 'edge >= 88', 'firefox >= 78', 'safari >= 14'];
 ```
 
-For example, if you only need to be compatible with browsers above Chrome 61, you can change it to:
+For example, if you only need to be compatible with browsers above Chrome 100, you can change it to:
 
 ```js
-['Chrome >= 61'];
+['Chrome >= 100'];
 ```
 
 :::tip
-Please read the [Browserslist](https://rsbuild.rs/guide/advanced/browserslist) chapter to know more about the usage of Browserslist.
+Please read the [Browserslist configuration](/guides/advanced-features/compatibility.html) chapter to know more about the usage of Browserslist.
 :::
 
 ## Usage polyfill
@@ -96,23 +96,9 @@ See details in [plugin-image-compress](https://github.com/rspack-contrib/rsbuild
 
 ## Split Chunk
 
-A great code splitting strategy is very important to improve the loading performance of the application. It can make full use of the browser's caching mechanism to reduce the number of requests and improve the loading speed of the application.
+A great chunk splitting strategy is very important to improve the loading performance of the application. It can make full use of the browser's caching mechanism to reduce the number of requests and improve the loading speed of the application.
 
-Modern.js provides the same [Code Splitting](https://rsbuild.rs/zh/guide/optimization/code-splitting) as Rsbuild. But there are some differences in the default strategy `split-by-experience`.
-
-When the project installs `antd`, `@arco-design/web-react`, or `@douyinfe/semi-ui` packages, it will automatically add the corresponding group. The implementation reference is as follows:
-
-```ts
-if (isPackageInstalled('antd', rootPath)) {
-  groups.antd = ['antd'];
-}
-if (isPackageInstalled('@arco-design/web-react', rootPath)) {
-  groups.arco = [/@?arco-design/];
-}
-if (isPackageInstalled('@douyinfe/semi-ui', rootPath)) {
-  groups.semi = [/@(ies|douyinfe)[\\/]semi-.*/];
-}
-```
+A variety of [chunk splitting strategies](https://rsbuild.rs/guide/optimization/split-chunk) are built into Modern.js, which can meet the needs of most applications. You can also customize the chunk splitting config according to your own business scenarios.
 
 For example, split the `axios` library under node_modules into `axios.js`:
 

package/docs/en/guides/advanced-features/page-performance/react-compiler.mdx

@@ -6,11 +6,25 @@ Before starting to use the React Compiler, it is recommended to read the [React
 
 ## How to Use
 
-The steps to use the React Compiler in Modern.js are as follows:
+### React 19
 
-1. Modern.js does not officially support React 19 yet, but you can install `react-compiler-runtime@rc` in React 17 or 18 projects to allow the compiled code to run on versions before 19.
+If you are using React 19, Modern.js has built-in support for React Compiler, and no additional configuration is required.
 
-2. Currently, the React Compiler only provides a Babel plugin, so you need to install `babel-plugin-react-compiler`.
+### React 17 or 18
+
+If you are using React 17 or 18, you need to configure it as follows:
+
+1. Install `react-compiler-runtime` to allow the compiled code to run on versions before 19:
+
+```bash
+npm install react-compiler-runtime
+```
+
+2. Install `babel-plugin-react-compiler`:
+
+```bash
+npm install babel-plugin-react-compiler
+```
 
 3. Register the Babel plugin in your Modern.js configuration file:
 
@@ -18,26 +32,19 @@ The steps to use the React Compiler in Modern.js are as follows:
 import { appTools, defineConfig } from '@modern-js/app-tools';
 
 export default defineConfig({
-  runtime: {
-    router: true,
-  },
   tools: {
     babel(_, { addPlugins }) {
       addPlugins([
         [
           'babel-plugin-react-compiler',
           {
-            target: '18',
+            target: '18', // or '17', depending on your React version
           },
         ],
       ]);
     },
   },
-  plugins: [
-    appTools({
-      bundler: 'rspack',
-    }),
-  ],
+  plugins: [appTools()],
 });
 ```
 

package/docs/en/guides/advanced-features/rspack-start.mdx

@@ -22,33 +22,13 @@ import InitRspackApp from '@site-docs-en/components/init-rspack-app';
 
 After the project is created, you can experience the project by running `pnpm run dev`. For more project information, please refer to [Quick Start](/guides/get-started/quick-start.html).
 
-## Enable Rspack build
-
-Since Modern.js MAJOR_VERSION.59.0, you can enable Rspack build by add the following configuration in `modern.config.ts`:
-
-```diff title=modern.config.ts
-import { appTools, defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  plugins: [
-    appTools({
-+     bundler: 'rspack',
-    }),
-  ],
-});
-```
-
-:::tip
-If your current version is lower than MAJOR_VERSION.59.0, you can upgrade by executing `npx modern upgrade`.
-:::
-
 import RspackPrecautions from '@site-docs-en/components/rspackPrecautions.mdx';
 
 <RspackPrecautions />
 
 ## Migrating configuration
 
-In Modern.js, the [tools.webpack](/configure/app/tools/webpack) and [tools.webpackChain](/configure/app/tools/webpack-chain) configurations only take effect in webpack mode, after turning on the Rspack build, you can modify it to [tools.rspack](/configure/app/tools/rspack) and [tools.bundlerChain](/configure/app/tools/bundler-chain).
+In Modern.js, the [tools.rspack](/configure/app/tools/rspack) and [tools.bundlerChain](/configure/app/tools/bundler-chain) configurations take effect in Rspack mode. If you were previously using webpack mode, after turning on the Rspack build, you can modify it to [tools.rspack](/configure/app/tools/rspack) and [tools.bundlerChain](/configure/app/tools/bundler-chain).
 
 ```diff
 export default {
@@ -81,7 +61,7 @@ If you have custom configuration requirements for `builtin:swc-loader`, you can
 ```ts
 import { defineConfig } from '@modern-js/app-tools';
 
-export default defineConfig<'rspack'>({
+export default defineConfig({
   tools: {
     swc: {
       jsc: {
@@ -93,7 +73,7 @@ export default defineConfig<'rspack'>({
 ```
 
 :::tip
-When Rspack build is enabled, `babel-loader` is not enabled by default. If you need to add some babel plugins, you can configure it through [tools.babel](/configure/app/tools/babel). This will generate additional compilation overhead and slow down the Rspack build speed to a certain extent.
+When Rspack build is enabled, `babel-loader` is not enabled by default. If you need to add some babel plugins, you can configure it through [babel plugin](https://rsbuild.rs/plugins/list/plugin-babel#babel-plugin). This will generate additional compilation overhead and slow down the Rspack build speed to a certain extent.
 :::
 
 ## The relationship between Rspack and Modern.js versions

package/docs/en/guides/advanced-features/server-monitor/logger.mdx

@@ -17,11 +17,7 @@ Modern.js also retains SSR logs from legacy versions using `useLoader`:
 | Stage         | Message                         | Level |
 | ------------- | ------------------------------- | ----- |
 | PRERENDER     | App Prerender                   | error |
-| USE_LOADER    | App run useLoader               | error |
 
-:::tip
-The `useLoader` API is now deprecated. We recommend migrating to convention-based routing and using Data Loaders for data fetching. Applications already using Data Loaders can enable [`ssr.disablePrerender`](/configure/app/server/ssr.html#object-type) to disable prerendering and improve SSR performance.
-:::
 
 ## Built-in Monitor