@modern-js/main-doc 3.1.5 → 3.2.1

package/docs/en/community/contributing-guide.mdx

@@ -125,7 +125,7 @@ pnpm run reset
 
 If you've fixed a bug or added code that should be tested, then add some tests.
 
-You can add unit test cases in the `<PACKAGE_DIR>/tests` folder. The test syntax is based on [Rstest](https://rstest.rs/).
+Modern.js uses [Rstest](https://rstest.rs/) for unit tests across the repository. You can add test cases in the `<PACKAGE_DIR>/tests` folder, using Rstest syntax.
 
 ### Run Unit Tests
 

package/docs/en/components/international/init-options-desc.mdx

@@ -1 +1 @@
-`initOptions` will be passed to i18next's `init` method and supports all i18next configuration options:
+All [i18next initialization options](https://www.i18next.com/overview/configuration-options) are supported. Common options are described below:

package/docs/en/components/international/install-command.mdx

@@ -1,23 +1,10 @@
-```bash
-pnpm add @modern-js/plugin-i18n i18next react-i18next
-```
-
-:::tip Version Consistency
-Make sure the version of `@modern-js/plugin-i18n` matches the version of `@modern-js/app-tools` in your project. All Modern.js official packages are released with a uniform version number, and version mismatches may cause compatibility issues.
+`i18next` and `react-i18next` are **Peer Dependencies** and must be installed manually.
 
-Check the version of `@modern-js/app-tools` first, then install the same version of `@modern-js/plugin-i18n`:
+:::note Version consistency
+`@modern-js/plugin-i18n` should use the same version as `@modern-js/app-tools` in your project.
+:::
 
 ```bash
-# Check the current version of @modern-js/app-tools
 pnpm list @modern-js/app-tools
-
-# Install the same version of @modern-js/plugin-i18n
 pnpm add @modern-js/plugin-i18n@<version> i18next react-i18next
 ```
-
-:::
-
-:::info
-`i18next` and `react-i18next` are peer dependencies and need to be installed manually.
-
-:::

package/docs/en/components/international/instance-code.mdx

@@ -1,26 +1,16 @@
-Create the `src/modern.runtime.ts` file and configure i18n runtime options:
+Create `src/modern.runtime.ts`:
 
 ```ts
 import { defineRuntimeConfig } from '@modern-js/runtime';
 import i18next from 'i18next';
 
-// It's recommended to create a new i18next instance to avoid using the global default instance
+// i18next exports a global singleton by default, which can cause multiple apps to affect each other.
+// createInstance() creates an isolated instance so each app has independent language state.
 const i18nInstance = i18next.createInstance();
 
 export default defineRuntimeConfig({
   i18n: {
-    i18nInstance: i18nInstance,
-    initOptions: {
-      fallbackLng: 'en',
-      supportedLngs: ['zh', 'en'],
-    },
+    i18nInstance,
   },
 });
 ```
-
-:::info
-`modern.runtime.ts` is a runtime configuration file used to configure i18next initialization options. Even for the most basic configuration, it's recommended to create this file to ensure the plugin works correctly.
-
-It's recommended to use `i18next.createInstance()` to create a new instance instead of directly using the default exported `i18next`. This avoids global state pollution and ensures each application has an independent i18n instance.
-
-:::

package/docs/en/components/international/introduce.mdx

@@ -1,2 +1,5 @@
-`@modern-js/plugin-i18n` is Modern.js's internationalization plugin, built on top of [i18next](https://www.i18next.com/) and [react-i18next](https://react.i18next.com/), providing a complete internationalization solution for Modern.js applications.
+`@modern-js/plugin-i18n` is the internationalization plugin for Modern.js, built on [i18next](https://www.i18next.com/) and [react-i18next](https://react.i18next.com/).
 
+- **The plugin itself**: Integrates with the Modern.js framework, including SSR language passing, route prefix handling, and more.
+- **i18next**: Provides core translation capabilities, such as the `t()` function, interpolation, plurals, and namespaces.
+- **react-i18next**: Provides React components and Hooks, such as `useTranslation`, to integrate translations with the React lifecycle.

package/docs/en/configure/app/server/tsconfig-path.mdx

@@ -0,0 +1,63 @@
+---
+title: tsconfigPath
+---
+
+# server.tsconfigPath
+
+- **Type:** `string`
+- **Default:** `<appDirectory>/tsconfig.json`
+
+Specifies the tsconfig file used by server-side TypeScript processes.
+
+This option affects:
+
+- BFF / API compilation (`@modern-js/plugin-bff`)
+- Custom server compilation (`*.ts` files under `server/`)
+- Runtime ts-node registration, such as SSR, `modern.config.ts`, and `.ts` files under `config/`
+
+When this option is not set, `<appDirectory>/tsconfig.json` is used by default.
+
+## When to use
+
+Use this option when frontend and server-side code need different TypeScript configurations.
+
+For example, the frontend can use `moduleResolution: "Bundler"`, while the server side uses `moduleResolution: "NodeNext"` for type resolution of conditional exports or subpath exports.
+
+## Example
+
+The example below uses `tsconfig.server.json` as the file name. You can use another name in your project.
+
+Add `<appDirectory>/tsconfig.server.json`:
+
+```jsonc title="tsconfig.server.json"
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ES2022",
+    "lib": ["ESNext"],
+    "types": ["node"],
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": ["api", "shared", "server", "config", "modern.config.ts"]
+}
+```
+
+Specify this file in `modern.config.ts`:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    tsconfigPath: './tsconfig.server.json',
+  },
+});
+```
+
+## Notes
+
+- `tsconfigPath` is resolved relative to `appDirectory`. Absolute paths are also supported.
+- It is recommended to inherit shared options such as `paths` from the root tsconfig through `extends`, instead of maintaining them in multiple files.
+- If the configured file does not exist, TypeScript / ts-node will throw an error at startup.

package/docs/en/configure/app/source/enable-async-pre-entry.mdx

@@ -0,0 +1,30 @@
+---
+title: enableAsyncPreEntry
+---
+
+# source.enableAsyncPreEntry
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+When enabled, Modern.js will inject the modules configured in `source.preEntry` to the top of the auto-generated entry file (`index.jsx`) in order.
+
+This option only takes effect when `source.enableAsyncEntry` is enabled. If async entry is not enabled, this behavior will be skipped and the original builder-side `source.preEntry` injection remains unchanged.
+
+This option is mainly designed to work with `source.enableAsyncEntry`: when async entry is enabled, the final build entry becomes `bootstrap.jsx`, and the builder-side `source.preEntry` may not be injected into the real entry code. With `source.enableAsyncPreEntry` enabled, `preEntry` will be injected into `index.jsx` (the real entry code), so it also works in async entry scenarios.
+
+Meanwhile, when both `source.enableAsyncEntry` and `source.enableAsyncPreEntry` are enabled, Modern.js will not pass `source.preEntry` into builder config to avoid duplicate injection or injection into an unexpected entry.
+
+## Example
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    enableAsyncEntry: true,
+    enableAsyncPreEntry: true,
+    preEntry: ['./src/pre-a.ts', './src/pre-b.ts'],
+  },
+});
+```

package/docs/en/configure/app/tools/dev-server.mdx

@@ -9,10 +9,6 @@ title: devServer
 
 The config of DevServer can be modified through `tools.devServer`.
 
-:::tip
-Modern.js does not directly use [webpack-dev-server](https://webpack.js.org/api/webpack-dev-server/) or [@rspack/dev-server](https://rspack.rs/guide/dev-server.html), but implement DevServer based on [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware).
-:::
-
 ### Options
 
 #### compress

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

@@ -1,5 +1,4 @@
 [
-  "basic",
   "quick-start",
   "configuration",
   "locale-detection",

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

@@ -4,103 +4,81 @@ title: Advanced Usage
 
 # Advanced Usage
 
-## SSR Configuration
+## SSR Scenarios
 
-The plugin fully supports server-side rendering (SSR) scenarios.
+In SSR scenarios, the plugin detects the language on the server, loads translation resources, and injects the result into the page. The client reuses it directly to avoid language flicker.
 
-### 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:
+**Complete configuration:**
 
 ```ts
+// modern.config.ts
 export default defineConfig({
   server: {
     ssr: true,
-    publicDir: './locales', // Resource file directory
   },
   plugins: [
+    appTools(),
     i18nPlugin({
+      localeDetection: {
+        localePathRedirect: true,
+        i18nextDetector: true,
+        languages: ['zh', 'en'],
+        fallbackLanguage: 'en',
+        detection: {
+          order: ['path', 'cookie', 'header'],
+          lookupHeader: 'accept-language',
+          caches: ['cookie'],
+        },
+      },
       backend: {
-        enabled: true,
+        loadPath: '/locales/{{lng}}/{{ns}}.json',
       },
     }),
   ],
 });
 ```
 
-Resource file structure:
+Server-side language detection priority: URL path -> Cookie -> `Accept-Language` request header -> `fallbackLanguage`.
+
+**Route configuration (file-system routes):**
 
 ```
-Project Root/
-└── locales/
-    ├── en/
-    │   └── translation.json
-    └── zh/
-        └── translation.json
+routes/
+└── [lang]/
+    ├── layout.tsx
+    └── page.tsx
 ```
 
-## Multi-Entry Configuration
+In SSR scenarios, the language detected on the server is written to `window._SSR_DATA`. The client reads it directly and does not detect again, ensuring both sides use the same language.
 
-If the project has multiple entries, you can configure language detection and backend options separately for each entry.
+## Multiple Entries
 
-### Configure Language Detection by Entry
+Different entries can use different language lists, detection methods, and resource paths:
 
 ```ts
+// modern.config.ts
 i18nPlugin({
   localeDetection: {
-    // Global configuration
+    // Global defaults
     localePathRedirect: true,
     languages: ['zh', 'en'],
     fallbackLanguage: 'en',
 
-    // Override configuration by entry
+    // Per-entry overrides
     localeDetectionByEntry: {
       admin: {
-        localePathRedirect: false, // admin entry does not use path redirection
-        languages: ['en'], // admin entry only supports English
+        localePathRedirect: false, // admin does not use path prefixes
+        languages: ['en'],         // admin only supports English
       },
       mobile: {
-        languages: ['zh', 'en', 'ja'], // mobile entry supports more languages
+        languages: ['zh', 'en', 'ja'], // mobile supports more languages
       },
     },
   },
-})
-```
-
-### Configure Backend by Entry
-
-```ts
-i18nPlugin({
   backend: {
-    enabled: true,
-    loadPath: '/locales/{{lng}}/{{ns}}.json', // Default path
+    loadPath: '/locales/{{lng}}/{{ns}}.json', // Global default path
 
-    // Override configuration by entry
+    // Per-entry overrides
     backendOptionsByEntry: {
       admin: {
         loadPath: '/admin/locales/{{lng}}/{{ns}}.json',
@@ -110,33 +88,24 @@ i18nPlugin({
       },
     },
   },
-})
+});
 ```
 
 ## Custom i18next Instance
 
-If you need to use a custom i18next instance, you can provide it in runtime configuration.
-
-### Create Custom Instance
+By default, the plugin uses an internally created i18next instance. If you need deeper customization, such as custom plugins or preconfigured options, pass a custom instance through runtime configuration:
 
 ```ts
 // src/i18n.ts
 import i18next from 'i18next';
 
-const customI18n = i18next.createInstance({
-  // Custom configuration
-  fallbackLng: 'en',
-  supportedLngs: ['zh', 'en'],
-  interpolation: {
-    escapeValue: false,
-  },
-});
+const customI18n = i18next.createInstance();
+// You can use custom plugins here.
+// customI18n.use(MyPlugin);
 
 export default customI18n;
 ```
 
-### Pass Custom Instance
-
 ```ts
 // src/modern.runtime.ts
 import { defineRuntimeConfig } from '@modern-js/runtime';
@@ -146,48 +115,18 @@ export default defineRuntimeConfig({
   i18n: {
     i18nInstance: customI18n,
     initOptions: {
-      // Other configuration options
+      fallbackLng: 'en',
+      supportedLngs: ['zh', 'en'],
     },
   },
 });
 ```
 
-## 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
-```
+## Language Switching Behavior
 
-If `localePathRedirect` is not enabled, language switching will only update the i18next instance and cache, without changing the URL.
+When `changeLanguage` is called to switch language:
 
+- **Translation update**: All components that use `t()` re-render automatically. No manual refresh is needed.
+- **URL update** (when `localePathRedirect` is enabled): Updates the URL with `history.pushState`, without triggering a page refresh and without affecting browser back/forward history.
+- **Cache update**: Writes to Cookie or LocalStorage based on the `caches` configuration, so the language choice is restored on the next visit.
+- **When path prefixes are not enabled**: Only the i18next instance and cache are updated. The URL stays unchanged.