@modern-js/main-doc 2.69.4 → 3.0.0-alpha.0

package/docs/en/guides/advanced-features/build-performance.mdx

@@ -24,42 +24,39 @@ If you are not using Rspack yet, you can switch to Rspack build mode to improve
 
 In general, updating Node.js to the latest [LTS release](https://github.com/nodejs/release#release-schedule) will help improve build performance.
 
-Especially for devices with Apple M1/M2 chips, it is recommended to use at least Node 18.
+Modern.js requires Node.js version >= 20.19.5. We strongly recommend using the latest LTS version (such as Node.js 22 LTS) for the best build performance.
 
-Node >= 16 provides Apple Silicon binaries by default, so the performance on M1/M2 models will be greatly improved than Node 14. According to our tests, **After switching from Node 14 to Node >= 16, the compilation speed can be improved by more than 100%**.
-
-You can switch to Node 18 by following steps:
+You can switch to the latest LTS version by following these steps:
 
 ```bash
-# Install Node v18
-nvm install 18
+# Install the latest LTS version (e.g., Node.js 22)
+nvm install --lts
 
-# switch to Node 18
-nvm use 18
+# Switch to the latest LTS version
+nvm use --lts
 
-# Set Node 18 as the default version
-nvm default 18
+# Set the latest LTS version as the default
+nvm alias default lts/*
 
 # View Node version
 node -v
 ```
 
-### Avoid using ts-loader
+Or install Node.js 22 LTS specifically:
 
-By default, Modern.js uses Babel to compile TS files. After enabling the [tools.tsLoader](/en/configure/app/tools/ts-loader.html) option, `ts-loader` will be used to compile TS files.
+```bash
+# Install Node.js 22 LTS
+nvm install 22 --lts
 
-Please avoid using `ts-loader` because it requires additional parsing and type checking, which will slow down the build.
+# Switch to Node.js 22
+nvm use 22
 
-```js
-export default {
-  tools: {
-    // remove this config
-    tsLoader: {},
-  },
-};
-```
+# Set Node.js 22 as the default version
+nvm alias default 22
 
-See the [tools.tsLoader documentation](/en/configure/app/tools/ts-loader.html) for details.
+# View Node version
+node -v
+```
 
 ## Development optimization strategies
 
@@ -99,7 +96,7 @@ export default {
 };
 ```
 
-> For detailed differences between different Source Map formats, see [webpack - devtool](https://webpack.js.org/configuration/devtool/).
+> For detailed differences between different Source Map formats, see [rspack - devtool](https://rspack.rs/config/devtool).
 
 ### Adjust Browserslist for development
 
@@ -128,14 +125,14 @@ The following are strategies for improve build performance in production environ
 
 ### Disable Source Map
 
-If your project does not need Source Map in the production, you can turn it off through the `disableSourceMap` config to improve the build speed.
+If your project does not need Source Map in the production, you can turn it off through the `sourcemap` config to improve the build speed.
 
 ```js
 export default {
   output: {
-    disableSourceMap: true,
+    sourceMap: false,
   },
 };
 ```
 
-See [output.disableSourceMap](/en/configure/app/output/disable-source-map.html) for details.
+See [output.sourceMap](/en/configure/app/output/source-map.html) for details.

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

@@ -1,14 +1,18 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # Browser Compatibility
 
 ## Browserslist Configuration
 
-Modern.js supports setting the browserslist for your web applications. You can set the value of [Browserslist](https://browsersl.ist/) in the `.browserslistrc` file.
+Modern.js supports three ways to set the range of browsers that a web application needs to support.
 
-When you create a new Modern.js project, it will includes a `.browserslistrc` configuration by default, which means that the JavaScript code will be compiled to ES6.
+### Method 1: Configure via `.browserslistrc` File
+
+Modern.js supports setting the range of browsers that a web application needs to support. You can set the [Browserslist](https://browsersl.ist/) values in the `.browserslistrc` file.
+
+When you create a new Modern.js project, a default `.browserslistrc` configuration is included, which indicates that JavaScript code will be compiled to ES6 format.
 
 ```yaml title=".browserslistrc"
 chrome >= 51
@@ -18,23 +22,63 @@ safari >= 10
 ios_saf >= 10
 ```
 
+When the `overrideBrowserslist` configuration is not specified in the project, this `.browserslistrc` file will take effect.
+
+### Method 2: Configure via package.json
+
+You can also configure browserslist by setting the `browserslist` field in the `package.json` file:
+
+```json title="package.json"
+{
+  "browserslist": [
+    "chrome >= 51"
+    // Other browser configurations...
+  ]
+}
+```
+
+### Method 3: Configure via `output.overrideBrowserslist`
+
+You can also configure browserslist by setting the [`output.overrideBrowserslist`](/configure/app/output/override-browserslist) field in the `modern.config.js` file:
+
+```js title="modern.config.js"
+export default {
+  output: {
+    overrideBrowserslist: [
+      'chrome >= 51',
+      // Other browser configurations...
+    ],
+  },
+};
+```
+
+### Configuration Priority
+
+The `overrideBrowserslist` configuration has a higher priority than the `.browserslistrc` file and the `browserslist` field in package.json.
+
+In most scenarios, it is recommended to prioritize using the `.browserslistrc` file rather than the `overrideBrowserslist` configuration because the `.browserslistrc` file is the officially defined configuration file, has better general applicability, and can be recognized by other libraries in the community.
+
 :::tip
-Please refer to [Rsbuild - Browserslist](https://rsbuild.rs/guide/advanced/browserslist) for more information.
+Please refer to [Rsbuild - Setting Browser Range](https://rsbuild.rs/zh/guide/advanced/browserslist) for more information.
 :::
 
+import UpgradeBrowserslist from '@site-docs-en/components/upgrade-browserslist';
+
+<UpgradeBrowserslist />
+
 ## Polyfill
 
-### Polyfill At Compile
+### Compile-time Polyfill
 
-Modern.js defaults to importing corresponding polyfill code from [core-js](https://github.com/zloirock/core-js) during compilation.
+Modern.js by default injects corresponding polyfill code at compile time through [core-js](https://github.com/zloirock/core-js).
 
-By default, the required Polyfill code will be introduced according to the settings of the Browserslist, so there is no need to worry about the Polyfill problem of the project source code and third-party dependencies, but because it contains some Polyfill code that is not used, the final bundle size may be increased.
+By default, it will include the necessary polyfill code based on the project's Browserslist settings, so you generally do not need to worry about polyfill issues for your project source code and third-party dependencies. However, since some unused polyfill code is included, the final bundle size may increase.
 
 :::info
-For case where Polyfill is not required for third-party dependencies, you can set ['output.polyfill'](/configure/app/output/polyfill) to `usage`, so that Babel compiles only Polyfill code based on the syntax used in the code.
+For scenarios where certain third-party dependencies clearly do not require polyfills, you can set [`output.polyfill`](/configure/app/output/polyfill) to `usage`. This way, Babel will only inject polyfill code based on the syntax used in the code during compilation.
 
 :::
 
-import UAPolyfill from '@site-docs-en/components/ua-polyfill';
+import UAPolyfill from '@site-docs/components/ua-polyfill';
 
 <UAPolyfill />

package/docs/en/guides/advanced-features/international/_meta.json

@@ -0,0 +1,11 @@
+[
+  "basic",
+  "quick-start",
+  "configuration",
+  "locale-detection",
+  "resource-loading",
+  "routing",
+  "api",
+  "advanced",
+  "best-practices"
+]

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

@@ -0,0 +1,193 @@
+---
+title: Advanced Usage
+---
+
+# Advanced Usage
+
+## SSR Configuration
+
+The plugin fully supports server-side rendering (SSR) scenarios.
+
+### Server-side Language Detection
+
+In SSR scenarios, the plugin will detect language from HTTP requests:
+
+1. **URL Path**: Extract language prefix from path
+2. **Cookie**: Read language settings from cookies
+3. **Request Headers**: Read from `Accept-Language` request header
+
+**Configuration Example**:
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    i18nextDetector: true,
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
+    detection: {
+      order: ['path', 'cookie', 'header'],
+      lookupHeader: 'accept-language',
+    },
+  },
+})
+```
+
+### SSR Resource Loading
+
+In SSR scenarios, the plugin will automatically use the file system backend to load resources:
+
+```ts
+export default defineConfig({
+  server: {
+    ssr: true,
+    publicDir: './locales', // Resource file directory
+  },
+  plugins: [
+    i18nPlugin({
+      backend: {
+        enabled: true,
+      },
+    }),
+  ],
+});
+```
+
+Resource file structure:
+
+```
+Project Root/
+└── locales/
+    ├── en/
+    │   └── translation.json
+    └── zh/
+        └── translation.json
+```
+
+## Multi-Entry Configuration
+
+If the project has multiple entries, you can configure language detection and backend options separately for each entry.
+
+### Configure Language Detection by Entry
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    // Global configuration
+    localePathRedirect: true,
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
+
+    // Override configuration by entry
+    localeDetectionByEntry: {
+      admin: {
+        localePathRedirect: false, // admin entry does not use path redirection
+        languages: ['en'], // admin entry only supports English
+      },
+      mobile: {
+        languages: ['zh', 'en', 'ja'], // mobile entry supports more languages
+      },
+    },
+  },
+})
+```
+
+### Configure Backend by Entry
+
+```ts
+i18nPlugin({
+  backend: {
+    enabled: true,
+    loadPath: '/locales/{{lng}}/{{ns}}.json', // Default path
+
+    // Override configuration by entry
+    backendOptionsByEntry: {
+      admin: {
+        loadPath: '/admin/locales/{{lng}}/{{ns}}.json',
+      },
+      mobile: {
+        loadPath: '/mobile/locales/{{lng}}/{{ns}}.json',
+      },
+    },
+  },
+})
+```
+
+## Custom i18next Instance
+
+If you need to use a custom i18next instance, you can provide it in runtime configuration.
+
+### Create Custom Instance
+
+```ts
+// src/i18n.ts
+import i18next from 'i18next';
+
+const customI18n = i18next.createInstance({
+  // Custom configuration
+  fallbackLng: 'en',
+  supportedLngs: ['zh', 'en'],
+  interpolation: {
+    escapeValue: false,
+  },
+});
+
+export default customI18n;
+```
+
+### Pass Custom Instance
+
+```ts
+// src/modern.runtime.ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import customI18n from './i18n';
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance: customI18n,
+    initOptions: {
+      // Other configuration options
+    },
+  },
+});
+```
+
+## Language Switching
+
+### Programmatic Switching
+
+Use the `changeLanguage` method of the `useModernI18n` Hook:
+
+```tsx
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+
+function LanguageSwitcher() {
+  const { language, changeLanguage, supportedLanguages } = useModernI18n();
+
+  return (
+    <select
+      value={language}
+      onChange={e => changeLanguage(e.target.value)}
+    >
+      {supportedLanguages.map(lang => (
+        <option key={lang} value={lang}>
+          {lang}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+### URL Synchronization
+
+When `localePathRedirect` is enabled, switching languages will automatically update the URL:
+
+```tsx
+// Current URL: /en/about
+// Call changeLanguage('zh')
+// URL automatically updates to: /zh/about
+```
+
+If `localePathRedirect` is not enabled, language switching will only update the i18next instance and cache, without changing the URL.
+