@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.100 → 3.5.0-ultramodern.102

package/docs/guides/advanced-features/{compatibility.mdx → compatibility.md}

@@ -1,7 +1,3 @@
----
-sidebar_position: 6
----
-
 # Browser Compatibility
 
 ## Browserslist Configuration
@@ -14,10 +10,12 @@ Modern.js supports setting the range of browsers that a web application needs to
 
 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.
 
-import DefaultBrowserslist from '@site-docs/components/default-browserslist';
-
-<DefaultBrowserslist />
-
+```yaml title=".browserslistrc"
+chrome >= 87
+edge >= 88
+firefox >= 78
+safari >= 14
+```
 
 When the `overrideBrowserslist` configuration is not specified in the project, this `.browserslistrc` file will take effect.
 
@@ -36,7 +34,7 @@ You can also configure browserslist by setting the `browserslist` field in the `
 
 ### 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:
+You can also configure browserslist by setting the [`output.overrideBrowserslist`](/configure/app/output/override-browserslist.md) field in the `modern.config.js` file:
 
 ```js title="modern.config.js"
 export default {
@@ -59,9 +57,6 @@ In most scenarios, it is recommended to prioritize using the `.browserslistrc` f
 Please refer to [Rsbuild - Setting Browser Range](https://v2.rsbuild.rs/zh/guide/advanced/browserslist) for more information.
 :::
 
-import UpgradeBrowserslist from '@site-docs-en/components/upgrade-browserslist';
-
-<UpgradeBrowserslist />
 
 ## Polyfill
 
@@ -72,10 +67,54 @@ Modern.js by default injects corresponding polyfill code at compile time through
 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 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.
+For scenarios where certain third-party dependencies clearly do not require polyfills, you can set [`output.polyfill`](/configure/app/output/polyfill.md) 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/components/ua-polyfill';
+### 运行时按需 Polyfill
+
+Modern.js 中还提供了基于浏览器 [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) 信息的运行时按需 Polyfill 方案，相比于 Babel 优势如下：
+
+- 不会插入到代码中，只根据访问页面的设备，按需下发 Polyfill 代码 ，减少整体代码体积。
+- 相同浏览器会公用一份 Polyfill 代码。因此，随着项目越来越多，基于 UA 的 Polyfill 代码下发速度会越来越快，综合速度超过常规方案。
+
+Modern.js 提供了 `@modern-js/plugin-polyfill` 插件来实现该功能，可以通过安装该插件来开启该功能：
+
+
+```sh [npm]
+npm install @modern-js/plugin-polyfill
+```
+
+```sh [yarn]
+yarn add @modern-js/plugin-polyfill
+```
+
+```sh [pnpm]
+pnpm add @modern-js/plugin-polyfill
+```
+
+然后在 `modern.config.ts` 中注册 Polyfill 插件:
+
+```ts title="modern.config.ts"
+import { polyfillPlugin } from '@modern-js/plugin-polyfill';
+
+export default defineConfig({
+  plugins: [..., polyfillPlugin()],
+});
+```
+
+配置 `output.polyfill` 为 `ua` 并且执行 `pnpm run build && pnpm run serve` 启动服务器后，访问页面可以看到 HTML 产物中包含如下脚本:
 
-<UAPolyfill />
+```js
+<script src="/__polyfill__" crossorigin></script>
+```
+
+在 Chrome 51 下访问页面可以看到 `http://localhost:8080/__polyfill__` 返回内容如下:
+
+![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)
+
+:::caution 注意
+该功能只有在使用 Modern.js 内置的 Web Server 时才会生效。
+
+如果有自定义模版的需求，请参考 [HTML 模板](/zh/guides/basic-features/html.md)。通过 `html.template` 或 `tools.html` 手动修改模版时，可能会导致该功能无法正确生效。
+:::

package/docs/guides/advanced-features/international/{advanced.mdx → advanced.md}

@@ -1,7 +1,3 @@
----
-title: Advanced Usage
----
-
 # Advanced Usage
 
 ## SSR Scenarios

package/docs/guides/advanced-features/international/{api.mdx → api.md}

@@ -1,7 +1,3 @@
----
-title: API Reference
----
-
 # API Reference
 
 ## useModernI18n
@@ -10,15 +6,15 @@ title: API Reference
 
 ### Return Value
 
-| Field | Type | Description |
-| --- | --- | --- |
-| `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 |
+| Field                 | Type                                                | Description                                                                  |
+| --------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `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.
 
@@ -88,13 +84,13 @@ A route link component with a locale prefix.
 
 ### Props
 
-| Prop | Type | Required | Description |
-| --- | --- | --- | --- |
-| `to` | `string` | Yes | Target path. Do not include the 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 | Passed to the active router link when a router is available |
+| Prop             | Type              | Required | Description                                                 |
+| ---------------- | ----------------- | -------- | ----------------------------------------------------------- |
+| `to`             | `string`          | Yes      | Target path. Do not include the 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       | Passed to the active router link when a router is available |
 
 ### Usage
 

package/docs/guides/advanced-features/international/{best-practices.mdx → best-practices.md}

@@ -1,7 +1,3 @@
----
-title: Best Practices
----
-
 # Best Practices
 
 ## Resource File Organization

package/docs/guides/advanced-features/international/configuration.md

@@ -0,0 +1,228 @@
+# Configuration
+
+Plugin configuration is split between two files, each with a different responsibility:
+
+| File                    | Purpose                                          |
+| ----------------------- | ------------------------------------------------ |
+| `modern.config.ts`      | Basic plugin settings, read during build/startup |
+| `src/modern.runtime.ts` | i18next initialization options, read at runtime  |
+
+:::warning Function values can only be configured at runtime
+`modern.config.ts` runs at build time and cannot serialize functions. SDK loaders, custom detection functions, and similar function values must be placed in `modern.runtime.ts`.
+:::
+
+## Configuration Ownership
+
+| Configuration                                                  | Where to configure  |
+| -------------------------------------------------------------- | ------------------- |
+| `localeDetection` (language detection, path redirects, etc.)   | `modern.config.ts`  |
+| `backend` (resource paths, SDK declaration, etc.)              | `modern.config.ts`  |
+| `i18nInstance`                                                 | `modern.runtime.ts` |
+| `initOptions` (`fallbackLng`, `ns`, and other i18next options) | `modern.runtime.ts` |
+| The actual `backend.sdk` loader function                       | `modern.runtime.ts` |
+
+## CLI Configuration
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { i18nPlugin } from '@modern-js/plugin-i18n';
+
+export default defineConfig({
+  plugins: [
+    appTools(),
+    i18nPlugin({
+      localeDetection: { ... },
+      backend: { ... },
+    }),
+  ],
+});
+```
+
+### localeDetection Options
+
+| Field                    | Type                                                | Default              | Description                                                                                                                                                                 |
+| ------------------------ | --------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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](/guides/advanced-features/international/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](/guides/advanced-features/international/locale-detection.md)                                                |
+| `ignoreRedirectRoutes`   | `string[] \| Function`                              | -                    | Routes that skip redirects. See [Locale Detection](/guides/advanced-features/international/locale-detection.md#ignoreredirectroutes)                                        |
+| `localeDetectionByEntry` | `Record<string, ...>`                               | -                    | Per-entry overrides for multiple entries                                                                                                                                    |
+
+**Example:**
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    i18nextDetector: true,
+    languages: ['zh', 'en', 'ja'],
+    fallbackLanguage: 'en',
+    detection: {
+      order: ['path', 'cookie', 'header'],
+      lookupCookie: 'i18next',
+      caches: ['cookie'],
+    },
+  },
+});
+```
+
+### backend Options
+
+```ts
+interface BackendOptions {
+  // Whether to enable backend resource loading.
+  // Automatically enabled when loadPath/addPath is configured, or when a locales directory exists.
+  enabled?: boolean;
+
+  // Decides which URL or local file to request for translations. Supports {{lng}} and {{ns}}.
+  // Default: '/locales/{{lng}}/{{ns}}.json'
+  loadPath?: string;
+
+  // Path for reporting missing translations (optional).
+  addPath?: string;
+
+  // Enables the custom backend SDK. The actual loader is provided in runtime config.
+  sdk?: boolean | string;
+
+  // Cache strategy for chained backend mode, effective when both loadPath and sdk are configured.
+  // 'none'                  - use local files and do not request the custom backend after a hit
+  // 'refresh'               - continue requesting the custom backend and update cache, but not the page
+  // 'refreshAndUpdateStore' - continue requesting and update page text as well (default)
+  cacheHitMode?: 'none' | 'refresh' | 'refreshAndUpdateStore';
+
+  // Per-entry overrides for multiple-entry scenarios.
+  backendOptionsByEntry?: Record<string, BaseBackendOptions>;
+}
+```
+
+**About the `sdk` field:** In `modern.config.ts`, set it to `true` to declare that the SDK backend is enabled. Provide the actual loader in `initOptions.backend.sdk` in `modern.runtime.ts`. See [Resource Loading -> Custom Backend](/guides/advanced-features/international/resource-loading.md#custom-backend).
+
+**backend auto-enable rules:**
+
+| Situation                                                                          | Result                                                  |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `loadPath` or `addPath` is configured                                              | Automatically enabled. No need to write `enabled: true` |
+| No backend is configured, but a `locales` directory exists and contains JSON files | Automatically enabled with the default `loadPath`       |
+| `enabled: false` is set explicitly                                                 | Disabled, and auto-detection is skipped                 |
+
+Auto-detected directory locations, in priority order:
+
+1. `{project root}/config/public/locales`
+2. The `locales` subdirectory under the directory configured by `server.publicDir`
+
+**Which backend should you choose?**
+
+| Scenario                                                    | Recommended approach                                                     |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Translation files are local to the project                  | Static file backend (configure `loadPath`; CSR/SSR switch automatically) |
+| Translations come from a remote API or translation platform | Custom backend (configure `sdk: true`)                                   |
+| Local fallback + remote real-time updates                   | Chained backend (configure both `loadPath` and `sdk`)                    |
+
+See [Resource Loading](/guides/advanced-features/international/resource-loading.md) for detailed usage.
+
+## Runtime Configuration
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import i18next from 'i18next';
+
+const i18nInstance = i18next.createInstance();
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance,   // Optional. An isolated instance is recommended.
+    initOptions: {
+      fallbackLng: 'en',
+      supportedLngs: ['zh', 'en'],
+      ns: ['translation'],
+      defaultNS: 'translation',
+      interpolation: {
+        escapeValue: false, // React already escapes text; disable this to avoid double escaping.
+      },
+    },
+  },
+});
+```
+
+### i18nInstance Configuration
+
+If you need to use a custom i18n instance, provide it in the runtime configuration:
+
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import i18next from 'i18next';
+
+// 创建自定义实例
+const customI18n = i18next.createInstance({
+  // 自定义配置
+});
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance: customI18n,
+  },
+});
+```
+
+### initOptions
+
+支持所有 [i18next 初始化选项](https://www.i18next.com/overview/configuration-options)，常用选项说明如下：
+
+| Field           | Description                                                                                                                            |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `fallbackLng`   | Which language resources i18next falls back to when a translation key is missing. Supports strings, arrays, and maps (fallback chains) |
+| `supportedLngs` | Language list supported by i18next                                                                                                     |
+| `ns`            | Namespace list. Default is `['translation']`                                                                                           |
+| `defaultNS`     | Default namespace. Default is `'translation'`                                                                                          |
+| `lng`           | Forces the initial language. Usually not needed because the detector decides it                                                        |
+
+`fallbackLng` supports fallback chains, which are useful for regional language degradation:
+
+```ts
+initOptions: {
+  lng: 'zh-CN',
+  fallbackLng: {
+    'zh-CN': ['zh', 'en'], // If zh-CN is missing, try zh first, then en.
+    default: ['en'],
+  },
+},
+```
+
+### Custom Backend Function Configuration
+
+The actual loader function for a custom backend must be provided in runtime configuration:
+
+```ts
+// modern.config.ts: only declare that it is enabled.
+i18nPlugin({
+  backend: { sdk: true },
+});
+
+// modern.runtime.ts: provide the actual function.
+import type { I18nSdkLoader } from '@modern-js/plugin-i18n/runtime';
+
+const myLoader: I18nSdkLoader = async options => {
+  if (options.lng && options.ns) {
+    const res = await fetch(`/api/i18n/${options.lng}/${options.ns}`);
+    return res.json();
+  }
+  return {};
+};
+
+export default defineRuntimeConfig({
+  i18n: {
+    initOptions: {
+      backend: { sdk: myLoader },
+    },
+  },
+});
+```
+
+For complete usage, see [Resource Loading -> Custom Backend](/guides/advanced-features/international/resource-loading.md#custom-backend).
+
+## Multiple Entries
+
+Multiple-entry projects can override configuration per entry. See [Advanced Usage -> Multiple Entries](/guides/advanced-features/international/advanced.md#multiple-entries).

package/docs/guides/advanced-features/international/{locale-detection.mdx → locale-detection.md}

@@ -1,7 +1,3 @@
----
-title: Locale Detection
----
-
 # Locale Detection
 
 Locale detection means automatically inferring which language to use when the user has not manually selected one. The plugin can detect language from URL path, Cookie, request headers, browser settings, and other sources, and these methods can be combined.
@@ -38,7 +34,7 @@ i18nPlugin({
 });
 ```
 
-After enabling path detection, you also need to configure a `[lang]` dynamic parameter in your routes. See [Routing Integration](./routing.md).
+After enabling path detection, you also need to configure a `[lang]` dynamic parameter in your routes. See [Routing Integration](/guides/advanced-features/international/routing.md).
 
 ### i18next Detector
 
@@ -77,19 +73,19 @@ i18nPlugin({
 
 ## Detection Options (`detection`)
 
-| Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `order` | `string[]` | See below | Detection order inside the i18next detector |
-| `lookupQuerystring` | `string` | `'lng'` | Query parameter key, such as `?lng=en` |
-| `lookupCookie` | `string` | `'i18next'` | Cookie key |
-| `lookupLocalStorage` | `string` | `'i18nextLng'` | LocalStorage key (browser only) |
-| `lookupSession` | `string` | - | SessionStorage key (browser only) |
-| `lookupHeader` | `string` | `'accept-language'` | HTTP request header key |
-| `lookupFromPathIndex` | `number` | `0` | Which URL path segment to start recognizing language from |
-| `caches` | `false \| string[]` | - | Where to cache the detected language, such as `['cookie']` |
-| `cookieMinutes` | `number` | `525600` (1 year) | Cookie expiration time in minutes |
-| `cookieExpirationDate` | `Date` | - | Cookie expiration date. Takes precedence over `cookieMinutes` |
-| `cookieDomain` | `string` | - | Cookie domain |
+| Option                 | Type                | Default             | Description                                                   |
+| ---------------------- | ------------------- | ------------------- | ------------------------------------------------------------- |
+| `order`                | `string[]`          | See below           | Detection order inside the i18next detector                   |
+| `lookupQuerystring`    | `string`            | `'lng'`             | Query parameter key, such as `?lng=en`                        |
+| `lookupCookie`         | `string`            | `'i18next'`         | Cookie key                                                    |
+| `lookupLocalStorage`   | `string`            | `'i18nextLng'`      | LocalStorage key (browser only)                               |
+| `lookupSession`        | `string`            | -                   | SessionStorage key (browser only)                             |
+| `lookupHeader`         | `string`            | `'accept-language'` | HTTP request header key                                       |
+| `lookupFromPathIndex`  | `number`            | `0`                 | Which URL path segment to start recognizing language from     |
+| `caches`               | `false \| string[]` | -                   | Where to cache the detected language, such as `['cookie']`    |
+| `cookieMinutes`        | `number`            | `525600` (1 year)   | Cookie expiration time in minutes                             |
+| `cookieExpirationDate` | `Date`              | -                   | Cookie expiration date. Takes precedence over `cookieMinutes` |
+| `cookieDomain`         | `string`            | -                   | Cookie domain                                                 |
 
 **Default detection order when `order` is not configured:**
 
@@ -99,17 +95,17 @@ i18nPlugin({
 
 **Available `order` values:**
 
-| Value | Source | Limitation |
-| --- | --- | --- |
-| `querystring` | URL query parameter (`?lng=en`) | - |
-| `cookie` | Cookie | - |
-| `localStorage` | LocalStorage | Browser only |
-| `sessionStorage` | SessionStorage | Browser only |
-| `navigator` | Browser language settings | Browser only |
-| `htmlTag` | `<html lang="...">` | Browser only |
-| `header` | `Accept-Language` request header | - |
-| `path` | URL path (requires `localePathRedirect`) | - |
-| `subdomain` | Subdomain (`en.example.com`) | - |
+| Value            | Source                                   | Limitation   |
+| ---------------- | ---------------------------------------- | ------------ |
+| `querystring`    | URL query parameter (`?lng=en`)          | -            |
+| `cookie`         | Cookie                                   | -            |
+| `localStorage`   | LocalStorage                             | Browser only |
+| `sessionStorage` | SessionStorage                           | Browser only |
+| `navigator`      | Browser language settings                | Browser only |
+| `htmlTag`        | `<html lang="...">`                      | Browser only |
+| `header`         | `Accept-Language` request header         | -            |
+| `path`           | URL path (requires `localePathRedirect`) | -            |
+| `subdomain`      | Subdomain (`en.example.com`)             | -            |
 
 ## ignoreRedirectRoutes
 

package/docs/guides/advanced-features/international/{quick-start.mdx → quick-start.md}

@@ -1,16 +1,19 @@
----
-title: Quick Start
----
-
 # Quick Start
 
 This guide helps you quickly integrate internationalization into a Modern.js project.
 
 ## Install the Plugin
 
-import InstallCommand from '@site-docs/components/international/install-command';
+`i18next` 和 `react-i18next` 是 **Peer Dependency**，需要手动安装。
 
-<InstallCommand />
+:::note 版本一致性
+`@modern-js/plugin-i18n` 需要与项目中 `@modern-js/app-tools` 版本保持一致。
+:::
+
+```bash
+pnpm list @modern-js/app-tools
+pnpm add @modern-js/plugin-i18n@<version> i18next react-i18next
+```
 
 ## Basic Configuration
 
@@ -67,9 +70,22 @@ config/public/locales/
 
 ### Step 3: Configure Runtime Options
 
-import InstanceCode from '@site-docs/components/international/instance-code';
+创建 `src/modern.runtime.ts`：
 
-<InstanceCode />
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import i18next from 'i18next';
+
+// i18next 默认导出一个全局单例，多个应用共用会互相影响。
+// createInstance() 创建独立实例，确保每个应用有独立的语言状态。
+const i18nInstance = i18next.createInstance();
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance,
+  },
+});
+```
 
 ### Step 4: Use It in Components
 
@@ -105,8 +121,8 @@ function App() {
 
 Choose what to read next based on your needs:
 
-- **Want a URL structure like `/en/about`** -> [Routing Integration](./routing.md)
-- **Need automatic language switching based on Cookie / Header** -> [Locale Detection](./locale-detection.md)
-- **Translation resources come from a remote service** -> [Resource Loading -> Custom Backend](./resource-loading.md#custom-backend)
-- **SSR scenarios** -> [Advanced Usage](./advanced.md)
-- **View all configuration options** -> [Configuration](./configuration.md)
+- **Want a URL structure like `/en/about`** -> [Routing Integration](/guides/advanced-features/international/routing.md)
+- **Need automatic language switching based on Cookie / Header** -> [Locale Detection](/guides/advanced-features/international/locale-detection.md)
+- **Translation resources come from a remote service** -> [Resource Loading -> Custom Backend](/guides/advanced-features/international/resource-loading.md#custom-backend)
+- **SSR scenarios** -> [Advanced Usage](/guides/advanced-features/international/advanced.md)
+- **View all configuration options** -> [Configuration](/guides/advanced-features/international/configuration.md)

package/docs/guides/advanced-features/international/{resource-loading.mdx → resource-loading.md}

@@ -1,16 +1,12 @@
----
-title: Resource Loading
----
-
 # Resource Loading
 
 How translation files are loaded depends on where your translation resources are stored:
 
-| Scenario | Loading method |
-| --- | --- |
-| Translation files are local to the project | Static file backend (the default method in this guide) |
-| Translations come from a remote API or translation platform | Custom backend |
-| Both: local fallback + remote real-time updates | Chained backend |
+| Scenario                                                    | Loading method                                         |
+| ----------------------------------------------------------- | ------------------------------------------------------ |
+| Translation files are local to the project                  | Static file backend (the default method in this guide) |
+| Translations come from a remote API or translation platform | Custom backend                                         |
+| Both: local fallback + remote real-time updates             | Chained backend                                        |
 
 ## Static File Backend
 
@@ -111,7 +107,7 @@ interface I18nSdkLoadOptions {
 }
 ```
 
-When using a custom backend, translation resources are loaded asynchronously. You can use `isResourcesReady` to show a loading state before loading is complete. See [Best Practices -> Loading State Handling](./best-practices.md#loading-state-handling).
+When using a custom backend, translation resources are loaded asynchronously. You can use `isResourcesReady` to show a loading state before loading is complete. See [Best Practices -> Loading State Handling](/guides/advanced-features/international/best-practices.md#loading-state-handling).
 
 ## Chained Backend
 
@@ -151,8 +147,8 @@ export default defineRuntimeConfig({
 
 **`cacheHitMode` option** (controls how the two backends cooperate):
 
-| Value | Behavior |
-| --- | --- |
-| `'none'` | Use local files after a successful local hit and do not request the custom backend |
-| `'refresh'` | Continue requesting the custom backend and update cache, but do not update the current page |
-| `'refreshAndUpdateStore'` | Continue requesting the custom backend, update cache, and refresh page text (default) |
+| Value                     | Behavior                                                                                    |
+| ------------------------- | ------------------------------------------------------------------------------------------- |
+| `'none'`                  | Use local files after a successful local hit and do not request the custom backend          |
+| `'refresh'`               | Continue requesting the custom backend and update cache, but do not update the current page |
+| `'refreshAndUpdateStore'` | Continue requesting the custom backend, update cache, and refresh page text (default)       |

package/docs/guides/advanced-features/international/{routing.mdx → routing.md}

@@ -1,7 +1,3 @@
----
-title: Routing Integration
----
-
 # Routing Integration
 
 ## Enable Locale Path Prefixes
@@ -26,13 +22,13 @@ i18nPlugin({
 
 **Result:**
 
-| Visited path | Result |
-| --- | --- |
-| `/about` | Redirects to `/en/about` |
-| `/en/about` | Visits normally, language is `en` |
-| `/zh/about` | Visits normally, language is `zh` |
+| Visited path | Result                            |
+| ------------ | --------------------------------- |
+| `/about`     | Redirects to `/en/about`          |
+| `/en/about`  | Visits normally, language is `en` |
+| `/zh/about`  | Visits normally, language is `zh` |
 
-API and BFF prefixes are skipped automatically, including server API routes, the default `/api` BFF prefix when BFF is configured, and custom `bff.prefix` values. Those routes do not need locale prefixes or `localisedUrls` entries. For additional application paths that should not redirect, use `ignoreRedirectRoutes`. See [Locale Detection -> ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes).
+API and BFF prefixes are skipped automatically, including server API routes, the default `/api` BFF prefix when BFF is configured, and custom `bff.prefix` values. Those routes do not need locale prefixes or `localisedUrls` entries. For additional application paths that should not redirect, use `ignoreRedirectRoutes`. See [Locale Detection -> ignoreRedirectRoutes](/guides/advanced-features/international/locale-detection.md#ignoreredirectroutes).
 
 ## Localised URL Paths
 
@@ -69,11 +65,11 @@ i18nPlugin({
 
 **Result:**
 
-| Visited path | Result |
-| --- | --- |
-| `/terms-of-service` | Redirects to `/en/terms-of-service` |
-| `/cs/terms-of-service` | Redirects to `/cs/podminky-pouzivani` |
-| `/cs/podminky-pouzivani` | Visits normally, language is `cs` |
+| Visited path             | Result                                |
+| ------------------------ | ------------------------------------- |
+| `/terms-of-service`      | Redirects to `/en/terms-of-service`   |
+| `/cs/terms-of-service`   | Redirects to `/cs/podminky-pouzivani` |
+| `/cs/podminky-pouzivani` | Visits normally, language is `cs`     |
 
 Set `localisedUrls: false` as the escape hatch when a preset, shared config, or generated metadata would otherwise provide a map but this entry should keep locale prefixes without translated path segments.
 
@@ -174,4 +170,4 @@ function Navigation() {
 <I18nLink to="/en/about">About</I18nLink>
 ```
 
-`I18nLink` uses the active Modern.js router. In React Router projects it renders the React Router `Link`; in TanStack Router projects it navigates through TanStack Router. For the full Props type, see [API Reference](./api.md#i18nlink-component).
+`I18nLink` uses the active Modern.js router. In React Router projects it renders the React Router `Link`; in TanStack Router projects it navigates through TanStack Router. For the full Props type, see [API Reference](/guides/advanced-features/international/api.md#i18nlink-component).