@modern-js/main-doc 3.1.5 → 3.2.0

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

@@ -4,149 +4,101 @@ title: 路由集成
 
 # 路由集成
 
-插件与 Modern.js 路由系统深度集成，支持语言路径前缀和自动路径重定向。
+## 启用语言路径前缀
 
-## 启用路径重定向
+设置 `localePathRedirect: true` 后，插件会接管 URL 中的语言识别和跳转，具体做以下四件事：
 
-当 `localePathRedirect` 设置为 `true` 时，插件会自动在 URL 中添加语言前缀，并处理语言切换时的路径重定向。
-
-**配置**：
+1. **识别 URL 里的语言前缀**：访问 `/zh/detail` 时，插件从路径中提取 `zh` 作为当前语言
+2. **无前缀路径自动重定向**：访问 `/detail` 时，先通过 detector 检测语言，检测不到则用 `fallbackLanguage`，然后重定向到 `/en/detail` 或 `/zh/detail`
+3. **切换语言时同步更新 URL**：当前在 `/en/detail`，调用 `changeLanguage('zh')` 后 URL 自动变为 `/zh/detail`，而不只是改 i18next 内部的语言状态
+4. **避免路径被重复检测**：插件会自动从 i18next detector 的 `order` 中移除 `path`，因为路径语言识别已由插件自己处理，不需要 i18next 再检测一遍
 
 ```ts
+// modern.config.ts
 i18nPlugin({
   localeDetection: {
     localePathRedirect: true,
     languages: ['zh', 'en'],
     fallbackLanguage: 'en',
-    // 可选：忽略某些路由的自动重定向
-    ignoreRedirectRoutes: ['/api', '/admin'],
   },
 });
 ```
 
-### 忽略重定向的路由
-
-某些路由（如 API 路由、静态资源等）不需要语言前缀，可以使用 `ignoreRedirectRoutes` 配置来忽略这些路由的自动重定向：
+**效果：**
 
-```ts
-i18nPlugin({
-  localeDetection: {
-    localePathRedirect: true,
-    languages: ['zh', 'en'],
-    fallbackLanguage: 'en',
-    // 字符串数组：支持精确匹配和前缀匹配
-    ignoreRedirectRoutes: ['/api', '/admin', '/static'],
-    // 或使用函数进行更灵活的判断
-    ignoreRedirectRoutes: pathname => {
-      return pathname.startsWith('/api') || pathname.startsWith('/admin');
-    },
-  },
-});
-```
+| 访问路径 | 结果 |
+| --- | --- |
+| `/about` | 重定向到 `/en/about` |
+| `/en/about` | 正常访问，语言为 `en` |
+| `/zh/about` | 正常访问，语言为 `zh` |
 
-更多详情请参考[语言检测文档](./locale-detection#ignoreredirectroutes)中的 `ignoreRedirectRoutes` 配置说明。
+某些路径（如 API 路由、静态资源）不需要语言前缀，可以通过 `ignoreRedirectRoutes` 跳过重定向，详见[语言检测 → ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes)。
 
 ## 路由配置
 
-启用路径重定向后，需要在路由配置中添加 `:lang` 动态参数。
+启用 `localePathRedirect` 后，需要在路由中添加 `[lang]` 动态参数来接收语言前缀。
 
 ### 约定式路由
 
-使用约定式路由时，需要在 `routes/` 目录下创建 `[lang]` 目录来表示语言参数：
+在 `routes/` 目录下创建 `[lang]` 目录：
 
-```bash
+```
 routes/
-├── [lang]/
-│   ├── layout.tsx    # 布局组件
-│   ├── page.tsx      # 首页
-│   ├── about/
-│   │   └── page.tsx  # About 页面
-│   └── contact/
-│       └── page.tsx  # Contact 页面
+└── [lang]/
+    ├── layout.tsx    ← 可在此读取 params.lang
+    ├── page.tsx
+    └── about/
+        └── page.tsx
 ```
 
-**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>;
-}
+/:lang          → page.tsx
+/:lang/about    → about/page.tsx
 ```
 
-**routes/[lang]/about/page.tsx**:
+如果需要在布局或页面中读取当前语言参数：
 
 ```tsx
-export default function About() {
-  return <div>About</div>;
-}
-```
+// routes/[lang]/layout.tsx
+import { Outlet, useParams } from '@modern-js/runtime/router';
 
-**routes/[lang]/contact/page.tsx**:
-
-```tsx
-export default function Contact() {
-  return <div>Contact</div>;
+export default function Layout() {
+  const { lang } = useParams();
+  // lang 为当前 URL 中的语言代码，如 'en'、'zh'
+  // 通常不需要手动使用，useModernI18n() 会自动管理
+  return <Outlet />;
 }
 ```
 
-**生成的路由结构**：
-
-```
-/:lang          → Home 页面
-/:lang/about    → About 页面
-/:lang/contact  → Contact 页面
-```
-
-访问 `/` 或 `/about` 时，会自动重定向到 `/en` 或 `/en/about`（使用默认语言）。
-
 ### 自定义路由
 
-如果使用自定义路由（`modern.routes.ts`），需要在路由配置中添加 `:lang` 动态参数：
+:::info
+自定义路由仅在不使用 Modern.js 约定路由系统时才需要。大多数项目推荐使用约定式路由。
+:::
+
+如果使用自定义路由文件（`modern.routes.ts`），需要手动添加 `:lang` 参数：
 
 ```tsx
-import {
-  BrowserRouter,
-  Route,
-  Routes,
-  Outlet,
-} from '@modern-js/runtime/router';
-
-function App() {
+// modern.routes.ts
+import { Route, Routes, Outlet } from '@modern-js/runtime/router';
+
+export default function App() {
   return (
-    <BrowserRouter>
-      <Routes>
-        {/* 添加 :lang 参数 */}
-        <Route path=":lang" element={<Outlet />}>
-          <Route index element={<Home />} />
-          <Route path="about" element={<About />} />
-          <Route path="contact" element={<Contact />} />
-        </Route>
-      </Routes>
-    </BrowserRouter>
+    <Routes>
+      <Route path=":lang" element={<Outlet />}>
+        <Route index element={<Home />} />
+        <Route path="about" element={<About />} />
+      </Route>
+    </Routes>
   );
 }
 ```
 
-:::info
-约定式路由会自动根据文件结构生成对应的路由，推荐使用约定式路由。只有在需要特殊路由控制时才使用自定义路由。
-
-:::
-
 ## I18nLink 组件
 
-`I18nLink` 组件是 `@modern-js/plugin-i18n` 提供的链接组件，会自动在路径前添加当前语言前缀。
-
-### 基本用法
+`I18nLink` 是语言感知的链接组件，会自动在目标路径前添加当前语言前缀，无需手动拼接。
 
 ```tsx
 import { I18nLink } from '@modern-js/plugin-i18n/runtime';
@@ -156,57 +108,27 @@ function Navigation() {
     <nav>
       <I18nLink to="/">首页</I18nLink>
       <I18nLink to="/about">关于</I18nLink>
-      <I18nLink to="/contact">联系</I18nLink>
+      <I18nLink to="/contact" replace>联系</I18nLink>
     </nav>
   );
 }
 ```
 
-**当前语言为 `en` 时**：
-
-- `<I18nLink to="/">` → 实际链接：`/en`
-- `<I18nLink to="/about">` → 实际链接：`/en/about`
+**当前语言为 `en` 时：**
 
-**当前语言为 `zh` 时**：
-
-- `<I18nLink to="/">` → 实际链接：`/zh`
-- `<I18nLink to="/about">` → 实际链接：`/zh/about`
-
-### 自动添加语言前缀
+```
+<I18nLink to="/about">  →  实际链接：/en/about
+<I18nLink to="/">       →  实际链接：/en
+```
 
-`I18nLink` 会自动处理语言前缀，无需手动添加：
+**注意事项：**
 
 ```tsx
 // ✅ 正确：不需要手动添加语言前缀
 <I18nLink to="/about">关于</I18nLink>
 
-// ❌ 错误：不要手动添加语言前缀
+// ❌ 错误：不要手动添加语言前缀，会导致 /en/en/about
 <I18nLink to="/en/about">关于</I18nLink>
 ```
 
-### Props 说明
-
-`I18nLink` 接受所有 `Link` 组件的 props，并额外支持：
-
-```tsx
-interface I18nLinkProps {
-  /** 目标路径（不需要包含语言前缀） */
-  to: string;
-  /** 子元素 */
-  children: React.ReactNode;
-  /** 其他 Link 组件的 props */
-  [key: string]: any;
-}
-```
-
-**示例**：
-
-```tsx
-<I18nLink to="/about" replace>
-  关于
-</I18nLink>
-
-<I18nLink to="/contact" state={{ from: 'home' }}>
-  联系
-</I18nLink>
-```
+`I18nLink` 继承自 `@modern-js/runtime/router` 的 `Link` 组件，支持 `replace`、`state`、`className` 等所有标准 Link props，完整 Props 类型见 [API 参考](./api.md#i18nlink-组件)。

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

@@ -8,29 +8,22 @@ import I18nPluginIntroduce from '@site-docs/components/international/introduce';
 
 <I18nPluginIntroduce />
 
-## 核心功能特性
-
-- 🌍 **多语言支持**：轻松管理多种语言的翻译资源
-- 🔍 **智能语言检测**：支持从 URL 路径、Cookie、请求头等多种方式自动检测用户语言
-- 📦 **灵活的资源加载**：支持 HTTP、文件系统和自定义 SDK 三种资源加载方式
-- 🛣️ **路由集成**：与 Modern.js 路由系统深度集成，支持语言路径前缀
-- ⚡ **SSR 支持**：完整支持服务端渲染（SSR）场景
-- 🎯 **TypeScript 支持**：完整的 TypeScript 类型定义
-
-## 适用场景
-
-- 需要支持多语言的 Web 应用
-- 需要 SEO 友好的多语言路由
-- 需要服务端渲染的多语言应用
-- 需要从外部服务动态加载翻译资源
-
-## 文档导航
-
-- [快速开始](./international/quick-start) - 详细的安装和配置指南
-- [配置说明](./international/configuration) - CLI 和运行时配置详解
-- [语言检测](./international/locale-detection) - 多种语言检测方式和优先级
-- [资源加载](./international/resource-loading) - HTTP、FS、SDK 三种后端使用
-- [路由集成](./international/routing) - 路径重定向和 I18nLink 组件
-- [API 参考](./international/api) - 完整的 API 文档和类型定义
-- [高级用法](./international/advanced) - SSR、多入口、自定义实例等
-- [最佳实践](./international/best-practices) - 资源组织、错误处理、类型安全
+## 从哪里开始？
+
+| 想做的事 | 文档 |
+| --- | --- |
+| 首次接入，跑通示例 | [快速开始](./international/quick-start.md) |
+| 了解完整的配置选项 | [配置说明](./international/configuration.md) |
+| 根据 URL / Cookie / Header 自动判断语言 | [语言检测](./international/locale-detection.md) |
+| 实现 `/en/about` 这类带语言前缀的路径 | [路由集成](./international/routing.md) |
+| 从远程服务或平台加载翻译资源 | [资源加载 → 自定义后端](./international/resource-loading.md#sdk-后端) |
+| SSR 场景、多入口、自定义实例 | [高级用法](./international/advanced.md) |
+| 查询 Hook / 组件 / 类型定义 | [API 参考](./international/api.md) |
+
+## 核心能力
+
+- **语言检测**：支持 URL 路径、Cookie、LocalStorage、请求头、浏览器设置等多种检测方式，可自由组合优先级
+- **资源加载**：支持 HTTP 静态文件、文件系统（SSR）、SDK 自定义函数三种后端，以及链式后端渐进加载
+- **路由集成**：自动添加语言路径前缀（`/en/about`），提供 `I18nLink` 组件处理语言感知导航
+- **SSR 支持**：服务端检测语言并注入到页面，客户端直接使用，避免语言闪烁
+- **TypeScript 支持**：完整类型定义，支持翻译键类型安全检查

package/docs/zh/guides/basic-features/alias.mdx

@@ -35,7 +35,7 @@ sidebar_position: 4
 
 ## 通过 `source.alias` 配置
 
-Modern.js 提供了 [source.alias](/configure/app/source/alias) 配置项，对应 webpack / Rspack 原生的 [resolve.alias](https://webpack.js.org/configuration/resolve/#resolvealias) 配置，你可以通过对象或者函数的方式来配置这个选项。
+Modern.js 提供了 [source.alias](/configure/app/source/alias) 配置项，你可以通过对象或者函数的方式来配置这个选项。
 
 ### 使用场景
 

package/docs/zh/guides/basic-features/html.mdx

@@ -193,7 +193,7 @@ Modern.js 也支持通过 HTML(EJS) 语法来生成 HTML 文件。
   <head>
     <%= topTemplate %>
     <%= headTemplate %>
-    {/* webpack inject css  */}
+    {/* rspack inject css  */}
   </head>
   <body>
     <noscript>
@@ -202,7 +202,7 @@ Modern.js 也支持通过 HTML(EJS) 语法来生成 HTML 文件。
     </noscript>
     <div id="<%= mountId %>"></div>
     <%= bodyTemplate %>
-    {/* webpack inject js  */}
+    {/* rspack inject js  */}
     {/* <?- bottomTemplate ?> */}
   </body>
 </html>

package/docs/zh/guides/basic-features/static-assets.mdx

@@ -119,7 +119,7 @@ declare module '*.png' {
 
 ## 扩展静态资源类型
 
-如果 Modern.js 内置的静态资源类型不能满足你的需求，那么你可以通过 [tools.bundlerChain](/configure/app/tools/bundler-chain) 来修改内置的 webpack / Rspack 配置，并扩展你需要的静态资源类型。
+如果 Modern.js 内置的静态资源类型不能满足你的需求，那么你可以通过 [tools.bundlerChain](/configure/app/tools/bundler-chain) 来修改内置的 Rspack 配置，并扩展你需要的静态资源类型。
 
 比如，你需要把 `*.pdf` 文件当做静态资源直接输出到产物目录，可以添加以下配置：
 
@@ -147,7 +147,6 @@ console.log(myFile); // "/static/myFile.6c12aba3.pdf"
 关于以上配置的更多介绍，请参考：
 
 - [Rspack 文档 - Asset modules](https://rspack.rs/guide/asset-module.html#asset-modules)
-- [webpack 文档 - Asset modules](https://webpack.js.org/guides/asset-modules/)
 
 ## 图片格式
 

package/docs/zh/guides/concept/entries.mdx

@@ -273,13 +273,13 @@ export default defineConfig({
 
 ## 深入了解
 
-页面入口的概念衍生自 webpack 的入口（Entrypoint）概念，其主要用于配置 JavaScript 或其他模块在应用启动时加载和执行。webpack 对于网页应用的 [最佳实践](https://webpack.docschina.org/concepts/entry-points/#multi-page-application) 通常将入口与 HTML 产物对应，即每增加一个入口最终就会在产物中生成一份对应的 HTML 文件。入口引入的模块会在编译打包后生成多个 Chunk 产物，例如对于 JavaScript 模块最终可能会生成数个类似 `dist/static/js/index.ea39u8.js` 的文件产物。
+页面通常与 HTML 产物对应，即每增加一个入口最终就会在产物中生成一份对应的 HTML 文件。入口引入的模块会在编译打包后生成多个 Chunk 产物，例如对于 JavaScript 模块最终可能会生成数个类似 `dist/static/js/index.ea39u8.js` 的文件产物。
 
 需要注意区分入口、路由等概念之间的关系：
 
 - **入口**：包含多个用于启动时执行的模块。
 - **客户端路由**：在 Modern.js 中通常由 `react-router` 实现，通过 History API 判断浏览器当前 URL 决定加载和显示哪个 React 组件。
-- **服务端路由**：服务端可以模仿 [devServer 的行为](https://webpack.docschina.org/configuration/dev-server/#devserverhistoryapifallback)，将 index.html 页面代替所有 404 响应被返回以实现客户端路由，也可以自行实现任何路由逻辑。
+- **服务端路由**：由服务器根据请求 URL 决定返回什么内容。对于传统多页应用，不同 URL 通常会直接返回不同的 HTML 页面。对于使用客户端路由的单页应用，服务器一般会将非静态资源请求统一回退到入口 HTML，再由前端接管后续路由匹配与页面渲染
 
 它们的对应关系如下：
 

package/package.json

@@ -16,14 +16,14 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.1.5",
+  "version": "3.2.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.12.3",
-    "@modern-js/sandpack-react": "3.1.5"
+    "@modern-js/sandpack-react": "3.2.0"
   },
   "devDependencies": {
     "rsbuild-plugin-open-graph": "1.1.2",
@@ -37,8 +37,8 @@
     "classnames": "^2.5.1",
     "clsx": "^1.2.1",
     "fs-extra": "^10.1.0",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "ts-node": "^10.9.2",
     "typescript": "^5"
   },

package/docs/en/components/rspackPrecautions.mdx

@@ -1,6 +0,0 @@
-## Precautions
-
-Before using Rspack, you need to be aware of the following:
-
-- Rspack is compatible with most webpack plugins and almost all loaders, but there are still a few webpack plugins that cannot be used for now. For more details, see [Plugin Compatibility](https://rspack.rs/guide/compatibility/plugin).
-- Rspack uses [SWC](https://rspack.rs/guide/features/builtin-swc-loader) by default for code transformation and compression. In rare cases, you may encounter bugs in SWC in edge cases. You can provide feedback via [SWC issues](https://github.com/swc-project/swc/issues).