@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.12 → 3.2.0-ultramodern.121

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

@@ -4,9 +4,9 @@ sidebar_position: 1
 
 # Commands
 
-Modern.js has some built-in commands that can help you quickly start a development server, build production environment code, and more.
+UltraModern.js has some built-in commands that can help you quickly start a development server, build production environment code, and more.
 
-Through this chapter, you can learn about the built-in commands of Modern.js and how to use them.
+Through this chapter, you can learn about the built-in commands of UltraModern.js and how to use them.
 
 ## modern dev
 
@@ -23,7 +23,7 @@ Options:
   --api-only            only start API service
 ```
 
-After running `modern dev`, Modern.js will watch source file changes and apply hot module replacement.
+After running `modern dev`, UltraModern.js will watch source file changes and apply hot module replacement.
 
 ```bash
 $ modern dev
@@ -80,77 +80,67 @@ Options:
   -w --watch            turn on watch mode, watch for changes and rebuild
 ```
 
-## modern new
+## modern runtime status
 
-The `modern new` command is used to enable features in an existing project.
-
-For example, add application entry, enable some optional features such as BFF, micro frontend, etc.
+The `modern runtime status` command reads the runtime status endpoint and prints the response. It targets `http://127.0.0.1:8080/_modern/runtime/status` by default.
 
 ```bash
-Usage: modern new [options]
+Usage: modern runtime status [options]
 
 Options:
-  --config-file <configFile>  specify the configuration file, which can be a relative or absolute path
-  --lang <lang>          set the language (zh or en) for the new command.
-  -d, --debug            using debug mode to log something (default: false)
-  -c, --config <config>  set default generator config(json string)
-  --dist-tag <tag>       use specified tag version for its generator
-  --registry             set npm registry url to run npm command
-  -h, --help             show command help
+  --endpoint <endpoint>  runtime status endpoint URL or path
+  --token <token>        runtime status auth token
+  --token-env <name>     environment variable name that stores runtime status auth token (default: "MODERN_RUNTIME_SIGNAL_TOKEN")
+  --header-name <name>   auth header name (default: "x-modernjs-runtime-signal-token")
+  --timeout <ms>         request timeout in milliseconds (default: "5000")
+  --json                 output as JSON format for machine reading
+  -h, --help             display help for command
 ```
 
-### Add Entry
+If `--endpoint` is a path, it is resolved against `http://127.0.0.1:8080`. If `--token` is omitted, the command reads the token from the environment variable named by `--token-env`.
 
-In the project, execute the `new` command to add entries as follows:
+By default, the command formats the response as readable key/value lines. Add `--json` to print the raw JSON payload.
 
-```text
-$ npx modern new
-? Please select the operation you want: Create Element
-? Please select the type of element to create: New "entry"
-? Please fill in the entry name: entry
+```bash
+modern runtime status --json
 ```
 
-### Enable Features
+## modern runtime fallback-signal
 
-In the project, execute the `new` command to enable features as follows:
+The `modern runtime fallback-signal` command posts a runtime fallback signal to the canary contract-gate endpoint. It targets `http://127.0.0.1:8080/_modern/contract-gates/runtime-fallback` by default.
 
-```text
-$ npx modern new
-? Please select the operation you want: Enable Features
-? Please select the feature name: (Use arrow keys)
-❯ Enable BFF
-  Enable SSG
-  Enable Micro Frontend
+```bash
+Usage: modern runtime fallback-signal [options]
+
+Options:
+  --app <appName>          remote app name
+  --endpoint <endpoint>    runtime fallback signal endpoint URL or path
+  --reason <reason>        fallback reason (default: "runtime_fallback")
+  --phase <phase>          fallback phase (default: "load")
+  --entry <entry>          remote entry URL
+  --runtime-digest <digest>  runtime digest value
+  --metadata <json>        metadata JSON object string
+  --token <token>          runtime signal auth token
+  --token-env <name>       environment variable name that stores runtime signal auth token (default: "MODERN_RUNTIME_SIGNAL_TOKEN")
+  --header-name <name>     auth header name (default: "x-modernjs-runtime-signal-token")
+  --timeout <ms>           request timeout in milliseconds (default: "5000")
+  --json                   output as JSON format for machine reading
+  -h, --help               display help for command
 ```
 
-:::tip
-The `--config` parameter needs to use a JSON string.
+The request body always includes `appName`, `reason`, and `phase`. It includes `entry`, `runtimeDigest`, and `metadata` only when those options are provided. `--metadata` must be a JSON object string.
 
-pnpm does not support the use of JSON strings as parameter values currently. Use `npm new` to turn on.【[Relate Issue](https://github.com/pnpm/pnpm/issues/3876)】
-:::
+```bash
+modern runtime fallback-signal --app crm-shell --reason remote_load_failed --phase load --json
+```
 
 import ServeCommand from '@site-docs-en/components/serve-command';
 
 <ServeCommand />
 
-## modern upgrade
-
-Execute the command `npx modern upgrade` in the project, by default, dependencies in the `package.json` are updated to the latest version.
-
-```bash
-Usage: modern upgrade [options]
-
-Options:
-  --config <config> specify the configuration file, which can be a relative or absolute path
-  --registry <registry>  specify npm registry (default: "")
-  -d,--debug             using debug mode to log something (default: false)
-  --cwd <cwd>            app directory (default: "")
-  -h, --help             show command help
-```
-
 ## modern inspect
 
-The `modern inspect` command is used to view the Modern.js config, [Rsbuild config](https://v2.rsbuild.rs/config/index) and Rspack config of the project.
+The `modern inspect` command is used to view the UltraModern.js config, [Rsbuild config](https://v2.rsbuild.rs/config/index) and Rspack config of the project.
 
 ```bash
 Usage: modern inspect [options]

package/docs/en/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/en/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/en/community/contributing-guide.mdx

@@ -39,8 +39,7 @@ nvm use 22
 ### Install pnpm
 
 ```sh
-# Enable pnpm with corepack, only available on Node.js >= `v14.19.0`
-corepack enable
+mise install
 ```
 
 ### Install Dependencies
@@ -125,7 +124,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/community/releases.mdx

@@ -24,8 +24,4 @@ Modern.js follows the [Semantic Versioning](https://semver.org) specification.
 
 ## Version Upgrade
 
-When you need to upgrade the Modern.js version in your project, you can use the `modern upgrade` command, refer to [Upgrade](/guides/get-started/upgrade).
-
-```bash
-npx modern upgrade
-```
+Modern.js 3.0 no longer ships the `modern upgrade` command. When you need to upgrade a project, follow the manual migration steps in [Upgrade](/guides/get-started/upgrade).

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

@@ -1,66 +1,36 @@
-Modern.js provides the `@modern-js/create` tool to create projects. It does not require global installation and can be run on-demand using `npx`.
+UltraModern.js provides the BleedingDev create package to create SuperApp
+workspaces. It does not require global installation and can be run on-demand
+using `pnpm dlx`.
 
-You can create a project in an existing empty directory:
+The supported pnpm command is the scoped package specifier:
+`pnpm dlx @bleedingdev/modern-js-create <target>`. Do not shorten it to
+`pnpm dlx modern-js-create`; there is no unscoped package by that name.
+
+You can initialize the empty directory you are already in:
 
 ```bash
 mkdir myapp && cd myapp
-npx @modern-js/create@latest
+pnpm dlx @bleedingdev/modern-js-create .
 ```
 
 You can also create a project directly in a new directory:
 
 ```bash
-npx @modern-js/create@latest myapp
-```
-
-To initialize a TanStack Router template:
-
-```bash
-npx @modern-js/create@latest myapp --router tanstack
-```
-
-To initialize with Tailwind CSS v4 scaffold:
-
-```bash
-npx @modern-js/create@latest myapp --tailwind
-```
-
-To initialize TanStack Router with Tailwind CSS v4:
-
-```bash
-npx @modern-js/create@latest myapp --router tanstack --tailwind
-```
-
-To initialize BFF scaffold with the current default runtime:
-
-```bash
-npx @modern-js/create@latest myapp --bff
-```
-
-To initialize BFF scaffold with Effect HttpApi runtime:
-
-```bash
-npx @modern-js/create@latest myapp --bff-runtime effect
-```
-
-To initialize BFF scaffold with Hono runtime:
-
-```bash
-npx @modern-js/create@latest myapp --bff-runtime hono
+pnpm dlx @bleedingdev/modern-js-create my-super-app
 ```
 
 To initialize with workspace protocol dependencies (for local monorepo testing of unreleased Modern.js packages):
 
 ```bash
-npx @modern-js/create@latest myapp --router tanstack --bff-runtime effect --workspace
+pnpm dlx @bleedingdev/modern-js-create my-super-app --workspace
 ```
 
-`@modern-js/create` will directly create the application without providing an interactive Q & A interface:
+The BleedingDev create package will directly create the application without providing an interactive Q & A interface:
 
 ```bash
-🚀 Welcome to Modern.js
+🚀 Welcome to UltraModern.js
 
-📦 Creating project "myapp"...
+📦 Creating project "my-super-app"...
 
 ✨ Project created successfully! 🎉
 
@@ -68,7 +38,7 @@ npx @modern-js/create@latest myapp --router tanstack --bff-runtime effect --work
 
 📁 Enter the project directory:
 
-  cd myapp
+  cd my-super-app
 
 🔧 Initialize Git repository:
 
@@ -87,33 +57,37 @@ Now, the project structure is as follows:
 
 ```
 .
-├── biome.json
-├── modern.config.ts
+├── apps
+│   └── shell-super-app
 ├── package.json
-├── README.md
-├── src
-│   ├── modern-app-env.d.ts
-│   ├── modern.runtime.ts
-│   └── routes
-│       ├── index.css
-│       ├── layout.tsx
-│       └── page.tsx
-└── tsconfig.json
+├── packages
+│   ├── shared-contracts
+│   ├── shared-design-tokens
+│   └── shared-effect-client
+├── scripts
+├── topology
+└── verticals
 ```
 
-When `--tailwind` is enabled, `postcss.config.mjs` and `tailwind.config.ts` are generated in the project root.
+The default workspace starts shell-only and installs the published BleedingDev
+package aliases:
 
-When `--bff` or `--bff-runtime effect` is enabled, `modern.config.ts` enables `@modern-js/plugin-bff`, generates `api/effect/index.ts` + `shared/effect/api.ts`, and sets `bff.runtimeFramework` to `effect`.
-When `--bff-runtime hono` is enabled, `modern.config.ts` enables `@modern-js/plugin-bff`, generates `api/lambda/hello.ts`, and sets `bff.runtimeFramework` to `hono`.
-When `--workspace` is enabled, `@modern-js/*` dependencies use `workspace:*` versions for local monorepo linkage.
+```bash
+pnpm dlx @bleedingdev/modern-js-create my-super-app
+```
 
-If you want the public UltraModern.js SuperApp path, use the BleedingDev create
-package. It defaults to the canonical Effect + TanStack + SSR + Micro Verticals
-workspace and published BleedingDev package aliases:
+From a generated SuperApp workspace, add a business MicroVertical in place:
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-create myapp
+pnpm dlx @bleedingdev/modern-js-create transportation --vertical
 ```
 
-The lower-level `--ultramodern-*` flags are reserved for release engineering
-and local package-source testing.
+The `--vertical` command mutates the current workspace: it adds the vertical
+package and wires topology, ownership metadata, shell Module Federation,
+development overlays, package dependencies, generated contracts, route-owned
+i18n, CSS isolation, and the Effect BFF/client surface.
+
+The lower-level `--ultramodern-package-*` flags are reserved for release
+engineering and local package-source testing. BleedingDev packages are published
+through GitHub Actions trusted publishing; do not publish them manually from a
+developer machine.

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

@@ -1,5 +1,5 @@
 ```bash
-$ npx @modern-js/create@latest myapp
+$ pnpm dlx @bleedingdev/modern-js-create myapp
 ? Please select the programming language: TS
 ? Please select the package manager: pnpm
 ```

package/docs/en/components/prerequisites.mdx

@@ -9,8 +9,7 @@ import NodeVersion from '@site-docs-en/components/nodeVersion.mdx';
 It is recommended to use [pnpm](https://pnpm.io/installation) to manage dependencies:
 
 ```bash
-corepack enable pnpm
-corepack prepare pnpm@11.1.2 --activate
+mise use pnpm@11.4.0
 ```
 
 :::note

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

@@ -1,6 +1,6 @@
 ## modern serve
 
-The `modern serve` command is used to start a Modern.js project in the production environment. It can also be used to preview the artifacts built for the production environment locally. Please note that you need to execute the [`build`](/apis/app/commands#modern-build) command beforehand to generate the corresponding artifacts.
+The `modern serve` command is used to start an UltraModern.js project in the production environment. It can also be used to preview the artifacts built for the production environment locally. Please note that you need to execute the [`build`](/apis/app/commands#modern-build) command beforehand to generate the corresponding artifacts.
 
 ```bash
 Usage: modern serve [options]

package/docs/en/configure/app/bff/effect.mdx

@@ -123,13 +123,35 @@ export default defineConfig({
 }
 ```
 
-- **Default:** `{ enabled: true }`
+- **Default:**
+
+```ts
+{
+  enabled: true,
+  requireEnvelope: false,
+  envelopeHeader: 'x-modernjs-data-envelope',
+  validateOrigin: true,
+  requireTraceContext: false,
+  batch: {
+    enabled: true,
+    endpoint: '/_data/batch',
+    maxBatchSize: 16,
+    maxBatchBytes: 64 * 1024,
+    flushIntervalMs: 8,
+    maxConcurrency: 4,
+    requestTimeoutMs: 10000,
+    allowedMethods: ['GET'],
+  },
+}
+```
 
 Configure request-envelope validation for Effect runtime.
 
 Generated Effect client requests batching against `${bff.prefix}${batch.endpoint}` (for example, `/bff-api/_data/batch`).
 
-When `validateOrigin` is enabled, runtime compares envelope origin with request `Origin` header first, then falls back to request URL origin.
+Envelope validation is enabled by default but optional: requests without an envelope pass unless `requireEnvelope` is `true`. If an envelope is present, runtime validates it against the configured namespace, origin, trace, and selection policy. `expectedNamespace` is unset by default, and `selection` has no default limits unless configured.
+
+Origin validation is enabled by default. Runtime compares envelope origin with request `Origin` header first, then falls back to request URL origin; set `validateOrigin: false` to disable that comparison.
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -149,4 +171,6 @@ export default defineConfig({
 });
 ```
 
-`batch.flushIntervalMs` controls client-side micro-batch window in generated Effect client. `maxConcurrency` and `requestTimeoutMs` are applied by the server batch gateway when dispatching items.
+`batch.flushIntervalMs` controls the client-side micro-batch window in the generated Effect client. `maxConcurrency` and `requestTimeoutMs` are applied by the server batch gateway when dispatching items.
+
+The generated `effectBff.client.*` API only exists for loader-materialized `@api/effect/*` imports. Directly importing the server entry (`api/effect/index`) exposes the Effect BFF definition; its `client` property is a placeholder that fails on operation access.

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

@@ -25,4 +25,4 @@ export default defineConfig({
 - Set to `'hono'` to run BFF only from file-convention handlers under `api/lambda/**`.
 
 There is no implicit fallback between runtimes. Choose one runtime mode per app.
-If you want the public UltraModern preset that prefers the Effect lane, configure it explicitly in your app or scaffold with the create template's Effect path.
+Generated UltraModern apps use the Effect lane by default; set `runtimeFramework: 'hono'` only for the compatibility runtime.

package/docs/en/configure/app/performance/rsdoctor.mdx

@@ -11,22 +11,23 @@ type RsdoctorConfig =
   | boolean
   | {
       enabled?: boolean;
+      disableClientServer?: boolean;
     };
 ```
 
-- **Default:** `true` in production build, `false` in development mode.
+- **Default:** `undefined`, Rsdoctor is disabled unless this option is configured.
 
-Configure Rsdoctor diagnostics in Modern.js build.
+Configure Rsdoctor diagnostics in Modern.js build. Set this option to `true` to enable Rsdoctor:
 
 ```ts title="modern.config.ts"
 export default defineConfig({
   performance: {
-    rsdoctor: false,
+    rsdoctor: true,
   },
 });
 ```
 
-You can also use object form:
+You can also use object form. When an object is provided, Rsdoctor is enabled unless `enabled` is set to `false`:
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -37,3 +38,5 @@ export default defineConfig({
   },
 });
 ```
+
+To disable Rsdoctor after enabling it in shared config, set `rsdoctor` to `false` or set `enabled` to `false`.

package/docs/en/configure/app/tools/ts-checker.mdx

@@ -2,6 +2,8 @@
 title: tsChecker
 ---
 
+import { PackageManagerTabs } from '@theme';
+
 # tools.tsChecker
 
 - **Type:** `Object | Function`
@@ -14,6 +16,8 @@ const defaultOptions = {
     memoryLimit: 8192,
     // use tsconfig of user project
     configFile: tsconfigPath,
+    // use TypeScript Go checker by default
+    tsgo: true,
     // use TS-Go native preview of user project
     typescriptPath: require.resolve('@typescript/native-preview/package.json'),
   },
@@ -35,7 +39,7 @@ const defaultOptions = {
 },
 ```
 
-By default, Modern.js type checking is aligned with the TS-Go native preview used by this fork. You can use `output.disableTsChecker` config to disable build-time checking.
+By default, the [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check) is enabled for type checking. You can use `output.disableTsChecker` config to disable it.
 
 ## Example
 
@@ -53,4 +57,28 @@ export default {
 };
 ```
 
-> This fork keeps the TypeScript toolchain on `@typescript/native-preview` / `tsgo`; do not install the classic `typescript` compiler for application type checking.
+## TypeScript Go by Default
+
+Type checking runs on [TypeScript Go](https://github.com/microsoft/typescript-go) (`tsgo`) by default in this fork. The capability is provided by [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin), which is integrated by [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check), and reduces type-checking time by about 5-10x.
+
+`@typescript/native-preview` ships with the builder, so no extra install is needed. To pin your own version, install it in your project:
+
+<PackageManagerTabs command="install @typescript/native-preview -D" />
+
+When `tsgo` is enabled, the default `typescript.typescriptPath` resolves to `@typescript/native-preview/package.json`. If you manually set `typescript.typescriptPath`, it must be an absolute path to `@typescript/native-preview/package.json`.
+
+To fall back to the classic TypeScript checker, set `typescript.tsgo` to `false` and make sure `typescript` is installed in your project:
+
+```ts
+export default {
+  tools: {
+    tsChecker: {
+      typescript: {
+        tsgo: false,
+      },
+    },
+  },
+};
+```
+
+For supported options and limitations, please refer to [ts-checker-rspack-plugin - TypeScript Go support](https://github.com/rstackjs/ts-checker-rspack-plugin#typescript-go-support).

package/docs/en/guides/advanced-features/bff/data-platform.mdx

@@ -55,12 +55,14 @@ export default defineConfig({
 });
 ```
 
-When `validateOrigin` is enabled, Effect runtime validates envelope origin against the incoming `Origin` header (if present), otherwise falls back to request URL origin.
+Envelope validation is enabled by default but does not require an envelope unless `requireEnvelope` is set. Origin validation is enabled by default; set `validateOrigin: false` to skip comparing the envelope origin against the incoming `Origin` header, or the request URL origin when the header is absent.
 
 ## Generated Effect client behavior
 
 When using the generated Effect client (`@api/effect/index`), Modern.js automatically attaches a serialized data envelope header (`x-modernjs-data-envelope`) for same-origin requests.
 
+The generated client is loader-materialized. Import it from `@api/effect/*` in browser or client-bundled code; direct imports of the server entry (`api/effect/index`) expose the Effect BFF definition and only provide a placeholder `client`.
+
 The envelope includes:
 
 - operation metadata

package/docs/en/guides/advanced-features/bff/frameworks.mdx

@@ -105,7 +105,7 @@ const layer = HttpApiBuilder.layer(bffEffectApi).pipe(
 export default defineEffectBff({ api: bffEffectApi, layer });
 ```
 
-Call Effect endpoints from the browser via `@api/effect/index`:
+Call Effect endpoints from browser code via `@api/effect/index`:
 
 ```ts title="src/routes/page.tsx"
 import effectBff from '@api/effect/index';
@@ -113,6 +113,8 @@ import effectBff from '@api/effect/index';
 const response = await effectBff.client.hello.ping({});
 ```
 
+The `effectBff.client.*` surface is materialized by the BFF loader for `@api/effect/*` imports. Do not import `api/effect/index` directly and expect `client` to run in server code, scripts, or tests; direct entry imports expose the server runtime definition, and `client` is only a typed placeholder there.
+
 import Hono from '@site-docs-en/components/hono';
 
 <Hono />

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

@@ -15,10 +15,13 @@ title: API Reference
 | `language` | `string` | Current language code |
 | `changeLanguage` | `(lang: string) => Promise<void>` | Switches language |
 | `supportedLanguages` | `string[]` | Supported language list, from `localeDetection.languages` |
+| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | Localised URL mapping from `localeDetection.localisedUrls` |
 | `isLanguageSupported` | `(lang: string) => boolean` | Checks whether a language is in the supported list |
 | `isResourcesReady` | `boolean` | Whether translation resources for the current language have finished loading |
 | `i18nInstance` | `I18nInstance` | i18next instance for advanced scenarios |
 
+When `localePathRedirect` is enabled and `localisedUrls` is omitted, Modern.js keeps prefix-only paths such as `/en/about`. Translated path segments are enabled only by a non-empty `localisedUrls` map. Route generation validates every localisable path and every configured language only while that map is enabled.
+
 ### Basic Usage
 
 ```tsx
@@ -91,7 +94,7 @@ A route link component with a locale prefix.
 | `children` | `React.ReactNode` | Yes | Link content |
 | `replace` | `boolean` | No | Uses `history.replace` instead of `push` |
 | `state` | `any` | No | State passed to the target route |
-| Other Link props | - | No | Inherited from the `Link` component in `@modern-js/runtime/router` |
+| Other Link props | - | No | Passed to the active router link when a router is available |
 
 ### Usage
 

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

@@ -49,6 +49,7 @@ export default defineConfig({
 | `languages` | `string[]` | `[]` | Supported language list |
 | `fallbackLanguage` | `string` | `''` | Fallback language when detection fails |
 | `localePathRedirect` | `boolean` | `false` | Handles URL locale prefix recognition, redirects, and switching. See [Routing Integration](./routing.md#enable-locale-path-prefixes) |
+| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | Prefix-only behavior | Localised route path map. Only a non-empty map enables translated path segments; omitted, `true`, `false`, and `{}` keep locale prefixes without translating path segments. |
 | `i18nextDetector` | `boolean` | `false` | Enables the i18next detector (Cookie / Header, etc.) |
 | `detection` | `LanguageDetectorOptions` | - | Detailed i18next detector configuration. See [Locale Detection](./locale-detection.md) |
 | `ignoreRedirectRoutes` | `string[] \| Function` | - | Routes that skip redirects. See [Locale Detection](./locale-detection.md#ignoreredirectroutes) |

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

@@ -113,7 +113,7 @@ i18nPlugin({
 
 ## ignoreRedirectRoutes
 
-Specify which paths should skip locale path redirects. This is useful for API routes, static assets, and other paths that do not need a locale prefix.
+Specify which additional paths should skip locale path redirects. Modern.js automatically skips server API routes, the default `/api` BFF prefix when BFF is configured, and custom `bff.prefix` values. Use `ignoreRedirectRoutes` for non-API application paths that also do not need a locale prefix.
 
 **Syntax 1: string array** (supports exact match and prefix match)