@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.11 → 3.2.0-ultramodern.111

package/docs/zh/apis/app/commands.mdx

@@ -4,16 +4,16 @@ sidebar_position: 1
 
 # 命令
 
-Modern.js 内置了一些命令，可以帮助你快速启动开发服务器、构建生产环境代码等。
+UltraModern.js 内置了一些命令，可以帮助你快速启动开发服务器、构建生产环境代码等。
 
-通过本章节，你可以了解到 Modern.js 内置的命令有哪些，以及如何使用这些命令。
+通过本章节，你可以了解到 UltraModern.js 内置的命令有哪些，以及如何使用这些命令。
 
-## modern dev
+## ultramodern dev
 
-`modern dev` 命令用于启动一个本地开发服务器，对源代码进行开发环境编译。
+`ultramodern dev` 命令用于启动一个本地开发服务器，对源代码进行开发环境编译。
 
 ```bash
-Usage: modern dev [options]
+Usage: ultramodern dev [options]
 
 Options:
   -e --entry <entry>    指定入口，只编译特定的页面
@@ -23,10 +23,10 @@ Options:
   --api-only            仅启动 API 接口服务
 ```
 
-运行 `modern dev` 后，Modern.js 会监听源文件变化并进行模块热更新。
+运行 `ultramodern dev` 后，UltraModern.js 会监听源文件变化并进行模块热更新。
 
 ```bash
-$ modern dev
+$ ultramodern dev
 
 info    Starting dev server...
 
@@ -38,10 +38,10 @@ info    Starting dev server...
 
 在多页面（MPA）项目中，可以添加 `--entry` 参数来指定编译其中的一个或多个页面。这样可以只编译项目中的部分代码，从而提升 dev 启动速度。
 
-比如执行 `modern dev --entry`，在命令行界面中会展示入口选择框：
+比如执行 `ultramodern dev --entry`，在命令行界面中会展示入口选择框：
 
 ```bash
-$ modern dev --entry
+$ ultramodern dev --entry
 
 ? 请选择需要构建的入口
 ❯ ◯ foo
@@ -57,22 +57,22 @@ $ modern dev --entry
 
 ```bash
 # 编译 foo 页面
-modern dev --entry foo
+ultramodern dev --entry foo
 
 # 编译 foo 和 bar 页面
-modern dev --entry foo,bar
+ultramodern dev --entry foo,bar
 ```
 
-## modern start
+## ultramodern start
 
-`modern start` 是 `modern dev` 命令的别名，两者的功能和用法完全一致。
+`ultramodern start` 是 `ultramodern dev` 命令的别名，两者的功能和用法完全一致。
 
-## modern build
+## ultramodern build
 
-`modern build` 命令默认会在 `dist/` 目录下构建出可用于生产环境的产物。你可以通过修改配置 [`output.distPath`](/configure/app/output/dist-path) 指定产物的输出目录。
+`ultramodern build` 命令默认会在 `dist/` 目录下构建出可用于生产环境的产物。你可以通过修改配置 [`output.distPath`](/configure/app/output/dist-path) 指定产物的输出目录。
 
 ```bash
-Usage: modern build [options]
+Usage: ultramodern build [options]
 
 Options:
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
@@ -80,14 +80,14 @@ Options:
   -w --watch  开启 watch 模式, 监听文件变更并重新构建
 ```
 
-## modern new
+## ultramodern new
 
-`modern new` 命令用于在已有项目中添加项目元素。
+`ultramodern new` 命令用于在已有项目中添加项目元素。
 
 比如添加应用入口、启用一些可选功能如 BFF、微前端开发模式等。
 
 ```bash
-Usage: modern new [options]
+Usage: ultramodern new [options]
 
 Options:
   --config-file <configFile>  指定配置文件路径，可以为相对路径或绝对路径
@@ -104,7 +104,7 @@ Options:
 在 Modern.js 工程中，执行 `new` 命令添加入口的步骤如下：
 
 ```bash
-$ npx modern new
+$ npx ultramodern new
 ? 请选择你想要的操作 创建工程元素
 ? 请选择创建元素类型 新建「应用入口」
 ? 请填写入口名称 entry
@@ -115,7 +115,7 @@ $ npx modern new
 在 Modern.js 工程中，执行 `new` 命令启用可选能力的步骤如下：
 
 ```bash
-$ npx modern new
+$ npx ultramodern new
 ? 请选择你想要的操作 启用可选功能
 ? 请选择功能名称 (Use arrow keys)
 ❯ 启用「BFF」功能
@@ -133,12 +133,12 @@ import ServeCommand from '@site-docs/components/serve-command';
 
 <ServeCommand />
 
-## modern upgrade
+## ultramodern upgrade
 
-在项目根目录下执行命令 `npx modern upgrade`，会默认将当前执行命令项目的 `package.json` 中的 Modern.js 相关依赖更新至最新版本。
+在项目根目录下执行命令 `npx ultramodern upgrade`，会默认将当前执行命令项目的 `package.json` 中的 UltraModern.js 相关依赖更新至最新版本。
 
 ```bash
-Usage: modern upgrade [options]
+Usage: ultramodern upgrade [options]
 
 Options:
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
@@ -148,12 +148,12 @@ Options:
   -h, --help             display help for command
 ```
 
-## modern inspect
+## ultramodern inspect
 
-`modern inspect` 命令用于查看项目的 Modern.js 配置、[Rsbuild 配置](https://v2.rsbuild.rs/zh/config/index) 以及 Rspack 配置。
+`ultramodern inspect` 命令用于查看项目的 UltraModern.js 配置、[Rsbuild 配置](https://v2.rsbuild.rs/zh/config/index) 以及 Rspack 配置。
 
 ```bash
-Usage: modern inspect [options]
+Usage: ultramodern inspect [options]
 
 Options:
   --env <env>           查看指定环境下的配置 (default: "development")
@@ -163,14 +163,14 @@ Options:
   -h, --help            显示命令帮助
 ```
 
-在项目根目录下执行命令 `npx modern inspect` 后，会在项目的 `dist` 目录生成以下文件：
+在项目根目录下执行命令 `npx ultramodern inspect` 后，会在项目的 `dist` 目录生成以下文件：
 
 - `modern.js.config.mjs`: 表示当前使用的 Modern.js 配置。
 - `rsbuild.config.mjs`: 表示在构建时使用的 Rsbuild 配置。
 - `rspack.config.web.mjs`: 表示在构建时使用的 Rspack 配置。
 
 ```bash
-➜ npx modern inspect
+➜ npx ultramodern inspect
 
 Inspect config succeed, open following files to view the content:
 
@@ -184,7 +184,7 @@ Inspect config succeed, open following files to view the content:
 默认情况下，inspect 命令会输出开发环境的配置，你可以添加 `--env production` 选项来输出生产环境的配置：
 
 ```bash
-modern inspect --env production
+ultramodern inspect --env production
 ```
 
 ### 完整内容
@@ -192,7 +192,7 @@ modern inspect --env production
 默认情况下，inspect 命令会省略配置对象中的函数内容，你可以添加 `--verbose` 选项来输出函数的完整内容：
 
 ```bash
-modern inspect --verbose
+ultramodern inspect --verbose
 ```
 
 ### SSR 构建配置
@@ -200,7 +200,7 @@ modern inspect --verbose
 如果项目开启了 SSR 能力，则在 `dist` 目录会另外生成一份 `rspack.config.node.mjs` 文件，对应 SSR 构建时的 Rspack 配置。
 
 ```bash
-➜ npx modern inspect
+➜ npx ultramodern inspect
 
 Inspect config succeed, open following files to view the content:
 

package/docs/zh/community/blog/2022-0708-updates.md

@@ -17,7 +17,7 @@ Modern.js 7 ~ 8 月的最新版本为 v1.17.0，本双月的主要更新有：
 
 Modern.js 框架和相关插件完成对 React 18 的适配。现在，只需要将项目中的 `react`、`react-dom` 两个包的版本，升级到最新的 React 18 大版本，就可以使用 React 18 的新功能。
 
-注意，使用 `@modern-js/create` 命令默认创建的项目，安装的依赖 `react`、`react-dom` 的版本仍然为 17，如果希望使用 React 18，请手动升级这两个包的版本。
+注意，使用 `@bleedingdev/modern-js-create` 命令默认创建的项目，安装的依赖 `react`、`react-dom` 的版本仍然为 17，如果希望使用 React 18，请手动升级这两个包的版本。
 
 另外，SSR 流式渲染功能，目前尚在开发中，暂不支持。
 

package/docs/zh/community/blog/2022-0910-updates.md

@@ -15,7 +15,7 @@ Modern.js 9 ~ 10 月的最新版本为 v1.21.0，本双月的主要更新有：
 
 Modern.js 框架完成了对 pnpm v7 的变更适配。
 
-使用 `npx @modern-js/create@modern-1` 创建项目时会根据用户当前环境的 pnpm 版本进行安装依赖操作，并且在初始化项目中会在 `.npmrc` 中添加
+使用 `pnpm dlx @bleedingdev/modern-js-create` 创建项目时会根据用户当前环境的 pnpm 版本进行安装依赖操作，并且在初始化项目中会在 `.npmrc` 中添加
 `strict-peer-dependencies=false` 配置，避免安装时由于 `peerDependencies` 缺失导致安装依赖失败问题。
 同时适配 `release`、`deploy` 命令对 pnpm v7 的支持。
 
@@ -67,7 +67,7 @@ pnpm run command --options
 
 - husky 升级至 v8
 
-使用 `npx @modern-js/create@modern-1` 创建项目时，husky 会默认安装 v8 版本，并移除 `package.json` 中 husky 的配置，使用 `.husky` 文件夹的形式管理 husky 配置。
+使用 `pnpm dlx @bleedingdev/modern-js-create` 创建项目时，husky 会默认安装 v8 版本，并移除 `package.json` 中 husky 的配置，使用 `.husky` 文件夹的形式管理 husky 配置。
 
 在初次安装依赖时需要执行 `npx husky install` 进行 husky 初始化，默认项目会在 prepare 命令中完成，如果 husky 配置未生效，可通过手动执行完成 husky 配置。
 

package/docs/zh/community/blog/v2-release-note.mdx

@@ -86,20 +86,20 @@ title: Modern.js v2 发布
 
 大家对 Modern.js 框架的第一印象可能是「一个大而全的框架」，但事实上，为了避免变得臃肿，**Modern.js 采取了渐进式设计**，将所有功能建立在灵活的插件系统之上，因此具备按需启用和可插拔的能力。
 
-Modern.js 期望能支持不同规模的项目研发，考虑到中大型项目和小型项目对功能的诉求存在差异，**Modern.js 的大多数功能都是按需启用的**。在创建项目时，Modern.js 默认只安装核心模块，使 npm 依赖保持轻量；当需要用到额外功能时，你可以通过 modern new 命令一键开启，并自动安装相关依赖。
+Modern.js 期望能支持不同规模的项目研发，考虑到中大型项目和小型项目对功能的诉求存在差异，**Modern.js 的大多数功能都是按需启用的**。在创建项目时，Modern.js 默认只安装核心模块，使 npm 依赖保持轻量；当需要用到额外功能时，你可以通过 ultramodern new 命令一键开启，并自动安装相关依赖。
 
-![modern new 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/modern-new-code.png)
+![ultramodern new 命令](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/modern-new-code.png)
 
-<div style={{ textAlign: 'center', fontStyle: 'italic' }}>modern new 命令</div>
+<div style={{ textAlign: 'center', fontStyle: 'italic' }}>ultramodern new 命令</div>
 
 比如：
 
 - 对于基础的开发场景，项目中只需安装 Modern.js 的 CLI 工具 `@modern-js/app-tools`，即具备了开发调试、生产构建的能力。
-- 当你需要在应用中增加一些 BFF 接口时，可以执行 modern new 命令来启用 BFF 功能。启用后，Modern.js 会自动安装所需的 BFF 插件，以及某个 Node.js 框架对应的插件（如 Koa / Express）：
+- 当你需要在应用中增加一些 BFF 接口时，可以执行 ultramodern new 命令来启用 BFF 功能。启用后，Modern.js 会自动安装所需的 BFF 插件，以及某个 Node.js 框架对应的插件（如 Koa / Express）：
 
 ![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/bff-plugins.png)
 
-目前，你可以通过 `modern new` 命令来按需开启以下功能，未来我们也会将更多功能加入到 `new` 命令中，使其能够被便捷地集成。
+目前，你可以通过 `ultramodern new` 命令来按需开启以下功能，未来我们也会将更多功能加入到 `new` 命令中，使其能够被便捷地集成。
 
 ![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/v2-release/modern-new.png)
 

package/docs/zh/community/blog/v3-release-note.mdx

@@ -338,7 +338,7 @@ export default defineRoutes(({ route, layout, page }) => {
 
 #### 路由调试
 
-运行 `npx modern routes` 命令即可在 `dist/routes-inspect.json` 文件中生成完整的路由结构分析报告。
+运行 `npx ultramodern routes` 命令即可在 `dist/routes-inspect.json` 文件中生成完整的路由结构分析报告。
 
 报告中会显示每个路由的路径、组件文件、数据加载器、错误边界、Loading 组件等完整信息，帮助开发者快速了解项目的路由配置，快速定位和排查路由相关问题。结构化的 JSON 格式也便于 AI agent 理解和分析路由结构，提升 AI 辅助开发的效率。
 

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

@@ -38,8 +38,7 @@ nvm use 22
 ### 安装 pnpm
 
 ```bash
-# 使用 corepack 启用 pnpm，仅在 Node.js >= `v14.19.0` 上可用
-corepack enable
+mise install
 ```
 
 ### 安装依赖
@@ -124,7 +123,7 @@ pnpm run reset
 
 如果你进行了 bugfix，或者添加了需要测试的代码，请添加一些测试代码。
 
-你可以在 `<PACKAGE_DIR>/tests` 文件夹中添加单元测试用例。测试语法基于 [Rstest](https://rstest.rs/)。
+Modern.js 仓库的单元测试统一使用 [Rstest](https://rstest.rs/)。你可以在 `<PACKAGE_DIR>/tests` 文件夹中添加测试用例，测试语法基于 Rstest。
 
 ### 运行单元测试
 

package/docs/zh/community/releases.mdx

@@ -24,8 +24,8 @@ Modern.js 遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/) 语义化
 
 ## 版本升级
 
-当你需要升级项目中的 Modern.js 版本时，可以使用 `modern upgrade` 命令，参考 [版本升级](/guides/get-started/upgrade)。
+当你需要升级项目中的 Modern.js 版本时，可以使用 `ultramodern upgrade` 命令，参考 [版本升级](/guides/get-started/upgrade)。
 
 ```bash
-npx modern upgrade
+npx ultramodern upgrade
 ```

package/docs/zh/components/build-output.mdx

@@ -3,7 +3,7 @@
 ```bash
 $ pnpm run build
 
-> modern build
+> ultramodern build
 
   Modern.js Framework
 

package/docs/zh/components/debug-app.mdx

@@ -3,7 +3,7 @@
 ```bash
 $ pnpm run dev
 
-> modern dev
+> ultramodern dev
 
   Modern.js Framework
 

package/docs/zh/components/deploy-command.mdx

@@ -1,9 +1,9 @@
-## modern deploy
+## ultramodern deploy
 
-`modern deploy` 命令，用于生成部署平台需要的产物。
+`ultramodern deploy` 命令，用于生成部署平台需要的产物。
 
 ```bash
-Usage: modern deploy [options]
+Usage: ultramodern deploy [options]
 
 Options:
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径

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

@@ -1,64 +1,48 @@
-Modern.js 提供了 `@modern-js/create` 工具来创建项目，不需要全局安装，直接使用 `npx` 按需运行即可。
+UltraModern.js 提供 BleedingDev create 包来创建项目，不需要全局安装，直接使用 `pnpm dlx` 按需运行即可。
 
-你可以在已有的空目录来创建项目：
+你可以在当前已有的空目录中初始化项目：
 
 ```bash
 mkdir myapp && cd myapp
-npx @modern-js/create@latest
+pnpm dlx @bleedingdev/modern-js-create .
 ```
 
 也可以直接用新目录创建项目：
 
 ```bash
-npx @modern-js/create@latest myapp
-```
-
-初始化 TanStack Router 模板：
-
-```bash
-npx @modern-js/create@latest myapp --router tanstack
-```
-
-初始化 Tailwind CSS v4 模板：
-
-```bash
-npx @modern-js/create@latest myapp --tailwind
+pnpm dlx @bleedingdev/modern-js-create myapp
 ```
 
-同时初始化 TanStack Router + Tailwind CSS v4：
+默认会初始化 TanStack Router。如需强制使用 React Router 兼容路径：
 
 ```bash
-npx @modern-js/create@latest myapp --router tanstack --tailwind
+pnpm dlx @bleedingdev/modern-js-create myapp --router react-router
 ```
 
-初始化当前默认运行时的 BFF 模板：
+默认会初始化 Tailwind CSS v4 模板。如需关闭：
 
 ```bash
-npx @modern-js/create@latest myapp --bff
+pnpm dlx @bleedingdev/modern-js-create myapp --no-tailwind
 ```
 
-初始化带 Effect HttpApi 运行时的 BFF 模板：
-
-```bash
-npx @modern-js/create@latest myapp --bff-runtime effect
-```
+默认会初始化 Effect HttpApi BFF 模板。
 
 初始化带 Hono 运行时的 BFF 模板：
 
 ```bash
-npx @modern-js/create@latest myapp --bff-runtime hono
+pnpm dlx @bleedingdev/modern-js-create myapp --bff-runtime hono
 ```
 
 使用 workspace 协议依赖初始化（用于在本地 monorepo 中联调未发布的 Modern.js 包）：
 
 ```bash
-npx @modern-js/create@latest myapp --router tanstack --bff-runtime effect --workspace
+pnpm dlx @bleedingdev/modern-js-create myapp --workspace
 ```
 
-`@modern-js/create` 会直接创建应用，不再提供问答界面：
+BleedingDev create 包会直接创建应用，不再提供问答界面：
 
 ```bash
-🚀 欢迎使用 Modern.js
+🚀 欢迎使用 UltraModern.js
 
 📦 正在创建项目 "myapp"...
 
@@ -101,17 +85,35 @@ npx @modern-js/create@latest myapp --router tanstack --bff-runtime effect --work
 └── tsconfig.json
 ```
 
-当启用 `--tailwind` 时，项目根目录会额外生成 `postcss.config.mjs` 和 `tailwind.config.ts`。
+默认会生成 Tailwind CSS v4；传入 `--no-tailwind` 时会省略 `postcss.config.mjs`、`tailwind.config.ts` 和 Tailwind 导入。
 
-当启用 `--bff` 或 `--bff-runtime effect` 时，会在 `modern.config.ts` 中启用 `@modern-js/plugin-bff`，生成 `api/effect/index.ts` 与 `shared/effect/api.ts`，并将 `bff.runtimeFramework` 设置为 `effect`。
+默认会在 `modern.config.ts` 中启用 `@modern-js/plugin-bff`，生成 `api/effect/index.ts` 与 `shared/effect/api.ts`，并将 `bff.runtimeFramework` 设置为 `effect`。
 当启用 `--bff-runtime hono` 时，会在 `modern.config.ts` 中启用 `@modern-js/plugin-bff`，生成 `api/lambda/hello.ts`，并将 `bff.runtimeFramework` 设置为 `hono`。
 当启用 `--workspace` 时，`@modern-js/*` 依赖会使用 `workspace:*` 版本，便于本地 monorepo 联调。
 
-如果你需要公开的 UltraModern.js SuperApp 路径，请使用 BleedingDev create 包。
-它默认生成规范的 Effect + TanStack + SSR + Micro Verticals workspace，并使用已发布的 BleedingDev 包别名：
+它默认创建一个简单、可上线的 UltraModern 应用，并安装已发布的
+BleedingDev 包别名：
 
 ```bash
 pnpm dlx @bleedingdev/modern-js-create myapp
 ```
 
-底层 `--ultramodern-*` 参数只保留给发布工程和本地包源测试使用。
+只有在需要多个独立归属的 vertical 时，才显式创建 SuperApp workspace：
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace
+```
+
+在已生成的 SuperApp workspace 根目录中，可以就地添加业务
+MicroVertical：
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create transportation --vertical
+```
+
+`--vertical` 会修改当前 workspace：新增 vertical 包，并写入 topology、
+ownership 元数据、shell Module Federation、开发 overlays、包依赖、生成契约、
+路由归属 i18n、CSS 隔离，以及 Effect BFF/client surface。
+
+底层 `--ultramodern-package-*` 参数只保留给发布工程和本地包源测试使用。
+BleedingDev 包通过 GitHub Actions trusted publishing 发布；不要从开发机器手动发布。

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

@@ -1,5 +1,5 @@
 ```bash
-$ npx @modern-js/create@latest myapp
+$ pnpm dlx @bleedingdev/modern-js-create myapp
 ? 请选择开发语言：TS
 ? 请选择包管理工具：pnpm
 ```

package/docs/zh/components/prerequisites.mdx

@@ -9,8 +9,7 @@ import NodeVersion from '@site-docs/components/nodeVersion.mdx';
 推荐使用 [pnpm](https://pnpm.io/installation) 来管理依赖：
 
 ```bash
-corepack enable pnpm
-corepack prepare pnpm@11.1.2 --activate
+mise use pnpm@11.4.0
 ```
 
 :::note

package/docs/zh/components/serve-command.mdx

@@ -1,9 +1,9 @@
-## modern serve
+## ultramodern serve
 
-`modern serve` 命令用于在生产环境下启动 Modern.js 工程, 也可以用于在本地预览生产环境构建的产物。注意你需要提前执行 [`build`](/apis/app/commands#modern-build) 命令构建出对应产物。
+`ultramodern serve` 命令用于在生产环境下启动 UltraModern.js 工程, 也可以用于在本地预览生产环境构建的产物。注意你需要提前执行 [`build`](/apis/app/commands#ultramodern-build) 命令构建出对应产物。
 
 ```bash
-Usage: modern serve [options]
+Usage: ultramodern serve [options]
 
 Options:
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径

package/docs/zh/configure/app/bff/runtime-framework.mdx

@@ -25,4 +25,4 @@ export default defineConfig({
 - 设置为 `'hono'` 时，仅从 `api/lambda/**` 的文件约定处理函数运行 BFF。
 
 两种运行时之间没有隐式回退，应用需要显式选择其一。
-如果需要优先使用 Effect 分支的公开 UltraModern 预设，请在应用中显式设置，或使用 create 模板提供的 Effect 脚手架路径。
+生成的 UltraModern 应用默认使用 Effect 分支；仅在需要兼容运行时时设置 `runtimeFramework: 'hono'`。

package/docs/zh/configure/app/usage.mdx

@@ -86,8 +86,8 @@ export default defineConfig(({ env, command }) => ({
 该函数接受以下入参：
 
 - `env`：对应 `process.env.NODE_ENV` 的值。
-  - 当运行 `modern dev` 时，`env` 的值为 `development`。
-  - 当运行 `modern build` 或 `modern serve` 时，`env` 的值为 `production`。
+  - 当运行 `ultramodern dev` 时，`env` 的值为 `development`。
+  - 当运行 `ultramodern build` 或 `ultramodern serve` 时，`env` 的值为 `production`。
 - `command`：对应当前运行的命令，如 `dev`、`build`、`serve`。
 
 #### 导出异步函数
@@ -118,7 +118,7 @@ Modern.js 命令行支持通过 `--config` 选项来指定配置文件的名称
 {
   "scripts": {
     "dev": "modern modern",
-    "build": "modern build --config modern.prod.config.ts"
+    "build": "ultramodern build --config modern.prod.config.ts"
   }
 }
 ```
@@ -126,7 +126,7 @@ Modern.js 命令行支持通过 `--config` 选项来指定配置文件的名称
 你也可以将 `--config` 选项缩写为 `-c`：
 
 ```bash
-$ modern build -c modern.prod.config.js
+$ ultramodern build -c modern.prod.config.js
 ```
 
 ### 在 package.json 中配置（不推荐）
@@ -187,7 +187,7 @@ export default defineConfig({
 
 在使用 `modern.config.local.ts` 时，请注意以下事项：
 
-- `modern.config.local.ts` 文件仅会在执行 `modern dev` 命令时被加载，当执行 `modern build` 时不会被加载。
+- `modern.config.local.ts` 文件仅会在执行 `ultramodern dev` 命令时被加载，当执行 `ultramodern build` 时不会被加载。
 - `modern.config.local.ts` 文件的优先级不仅高于 `modern.config.ts`，也高于 `package.json` 中的 `modernConfig` 字段。
 - 由于 `modern.config.local.ts` 仅在本地调试时使用，因此不建议将其提交到代码仓库中，请确保项目的 `.gitignore` 文件中包含 `modern.config.local.ts` 等文件。
 

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

@@ -15,10 +15,13 @@ title: API 参考
 | `language` | `string` | 当前语言代码 |
 | `changeLanguage` | `(lang: string) => Promise<void>` | 切换语言 |
 | `supportedLanguages` | `string[]` | 支持的语言列表（来自 `localeDetection.languages`） |
+| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | 来自 `localeDetection.localisedUrls` 的本地化 URL 映射 |
 | `isLanguageSupported` | `(lang: string) => boolean` | 检查语言是否在支持列表中 |
 | `isResourcesReady` | `boolean` | 当前语言的翻译资源是否已加载完成 |
 | `i18nInstance` | `I18nInstance` | i18next 实例（用于高级场景） |
 
+启用 `localePathRedirect` 且省略 `localisedUrls` 时，Modern.js 会将本地化 URL 路径视为已启用。除非设置 `localisedUrls: false`，否则路由生成仍要求每个可本地化路径都为所有已配置语言提供路径。
+
 ### 基本用法
 
 ```tsx
@@ -91,7 +94,7 @@ function MyComponent() {
 | `children` | `React.ReactNode` | 是 | 链接内容 |
 | `replace` | `boolean` | 否 | 使用 `history.replace` 而非 `push` |
 | `state` | `any` | 否 | 传递给目标路由的状态 |
-| 其他 Link props | — | 否 | 继承自 `@modern-js/runtime/router` 的 `Link` 组件 |
+| 其他 Link props | — | 否 | 有可用路由时会传递给当前路由的 Link 组件 |
 
 ### 用法
 

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

@@ -48,6 +48,7 @@ export default defineConfig({
 | `languages` | `string[]` | `[]` | 支持的语言列表 |
 | `fallbackLanguage` | `string` | `''` | 语言检测失败时的兜底语言 |
 | `localePathRedirect` | `boolean` | `false` | 接管 URL 语言前缀的识别、重定向和切换，详见[路由集成](./routing.md#启用语言路径前缀) |
+| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | 启用 `localePathRedirect` 时为 `true` | 本地化路由路径映射。每个可本地化路由都必须为所有已配置语言提供路径。设置为 `false` 时只保留语言前缀，不翻译路径片段。 |
 | `i18nextDetector` | `boolean` | `false` | 启用 i18next 检测器（Cookie / Header 等） |
 | `detection` | `LanguageDetectorOptions` | — | i18next 检测器详细配置，见[语言检测](./locale-detection.md) |
 | `ignoreRedirectRoutes` | `string[] \| Function` | — | 跳过重定向的路由，见[语言检测](./locale-detection.md#ignoreredirectroutes) |

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

@@ -113,7 +113,7 @@ i18nPlugin({
 
 ## ignoreRedirectRoutes
 
-指定哪些路径跳过语言路径重定向，适用于 API 路由、静态资源等不需要语言前缀的路径。
+指定哪些额外路径跳过语言路径重定向。Modern.js 会自动跳过服务端 API 路由和 BFF 前缀，包括配置的 `bff.prefix`。`ignoreRedirectRoutes` 适用于其他不需要语言前缀的非 API 业务路径。
 
 **写法一：字符串数组**（支持精确匹配和前缀匹配）
 

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

@@ -32,7 +32,48 @@ i18nPlugin({
 | `/en/about` | 正常访问，语言为 `en` |
 | `/zh/about` | 正常访问，语言为 `zh` |
 
-某些路径（如 API 路由、静态资源）不需要语言前缀，可以通过 `ignoreRedirectRoutes` 跳过重定向，详见[语言检测 → ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes)。
+API 和 BFF 前缀会自动跳过，因此服务端 API 路由不需要语言前缀，也不需要配置 `localisedUrls`。如果还有其他业务路径不应该重定向，可以使用 `ignoreRedirectRoutes`，详见[语言检测 → ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes)。
+
+## 本地化 URL 路径
+
+启用 `localePathRedirect` 后，`localisedUrls` 默认启用。每个可本地化的路由路径都必须为所有已配置语言提供 URL。如果向 `languages` 中新增语言，Modern.js 会在路由生成阶段失败，直到每个 `localisedUrls` 条目都补齐该语言。
+
+`localisedUrls` 同时适用于 React Router 和 TanStack Router 项目的约定式路由。不要为 API 路由、BFF 前缀或配置的 `bff.prefix` 添加本地化 URL 条目；这些路径会自动排除在语言重定向之外。
+
+```ts
+// modern.config.ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    languages: ['en', 'cs'],
+    fallbackLanguage: 'en',
+    localisedUrls: {
+      '/terms-of-service': {
+        en: '/terms-of-service',
+        cs: '/podminky-pouzivani',
+      },
+      '/products': {
+        en: '/products',
+        cs: '/produkty',
+      },
+      '/products/:slug': {
+        en: '/products/:slug',
+        cs: '/produkty/:slug',
+      },
+    },
+  },
+});
+```
+
+**效果：**
+
+| 访问路径 | 结果 |
+| --- | --- |
+| `/terms-of-service` | 重定向到 `/en/terms-of-service` |
+| `/cs/terms-of-service` | 重定向到 `/cs/podminky-pouzivani` |
+| `/cs/podminky-pouzivani` | 正常访问，语言为 `cs` |
+
+只有在希望保留语言前缀、但不翻译路径片段时，才设置 `localisedUrls: false`。
 
 ## 路由配置
 
@@ -131,4 +172,4 @@ function Navigation() {
 <I18nLink to="/en/about">关于</I18nLink>
 ```
 
-`I18nLink` 继承自 `@modern-js/runtime/router` 的 `Link` 组件，支持 `replace`、`state`、`className` 等所有标准 Link props，完整 Props 类型见 [API 参考](./api.md#i18nlink-组件)。
+`I18nLink` 会使用当前启用的 Modern.js 路由。在 React Router 项目中渲染 React Router 的 `Link`；在 TanStack Router 项目中通过 TanStack Router 导航。完整 Props 类型见 [API 参考](./api.md#i18nlink-组件)。

package/docs/zh/guides/basic-features/debug/using-storybook.mdx

@@ -54,7 +54,7 @@ export default config
 ```json
 {
   "scripts": {
-    "dev:api": "modern dev --api-only",
+    "dev:api": "ultramodern dev --api-only",
     "storybook": "BFF_PROXY=1 storybook dev -p 6006 --no-open",
   }
 }