@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

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

@@ -0,0 +1,221 @@
+---
+title: Configuration
+---
+
+# 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](./routing.md#enable-locale-path-prefixes) |
+| `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) |
+| `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](./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](./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:
+
+import CustomInstanceCode from '@site-docs/components/international/custom-instance-code';
+
+<CustomInstanceCode />
+
+### initOptions
+
+import Desc from '@site-docs/components/international/init-options-desc';
+
+<Desc />
+
+| 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](./resource-loading.md#custom-backend).
+
+## Multiple Entries
+
+Multiple-entry projects can override configuration per entry. See [Advanced Usage -> Multiple Entries](./advanced.md#multiple-entries).

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

@@ -0,0 +1,130 @@
+---
+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.
+
+## Detection Priority
+
+No matter which detection methods are enabled, the priority is fixed as follows, from high to low:
+
+1. **SSR data**: Reads the language detected during server-side rendering from `window._SSR_DATA`, ensuring client and server consistency and avoiding language flicker.
+2. **Path detection**: Reads the locale prefix from the URL path. Requires `localePathRedirect`.
+3. **i18next detector**: Detects in the order configured by `detection.order` (Cookie, LocalStorage, query parameters, etc.).
+4. **initOptions.lng**: A language forced by runtime configuration.
+5. **fallbackLanguage**: The fallback language used when all detection methods fail.
+
+## Detection Methods
+
+### URL Path Detection
+
+After setting `localePathRedirect: true`, the plugin recognizes the language from the URL path prefix and automatically redirects paths without a prefix to the default language:
+
+```
+/about        -> redirects to /en/about (when fallbackLanguage is en)
+/zh/about     -> recognizes zh, no redirect
+/en/about     -> recognizes en, no redirect
+```
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
+  },
+});
+```
+
+After enabling path detection, you also need to configure a `[lang]` dynamic parameter in your routes. See [Routing Integration](./routing.md).
+
+### i18next Detector
+
+Set `i18nextDetector: true` to enable language detection from Cookie, LocalStorage, query parameters, request headers, and other sources:
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    i18nextDetector: true,
+    detection: {
+      order: ['cookie', 'querystring', 'header'],
+      lookupCookie: 'i18next',
+      lookupQuerystring: 'lng',
+      lookupHeader: 'accept-language',
+      caches: ['cookie'],
+    },
+  },
+});
+```
+
+Both methods can be enabled at the same time:
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,   // Path prefix
+    i18nextDetector: true,      // Cookie / Header, etc.
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
+    detection: {
+      order: ['cookie', 'header'],
+    },
+  },
+});
+```
+
+## 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 |
+
+**Default detection order when `order` is not configured:**
+
+```ts
+['querystring', 'cookie', 'localStorage', 'header', 'navigator', 'htmlTag', 'path', 'subdomain']
+```
+
+**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`) | - |
+
+## 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.
+
+**Syntax 1: string array** (supports exact match and prefix match)
+
+```ts
+ignoreRedirectRoutes: ['/api', '/admin', '/static']
+// '/api' matches both /api and /api/users.
+```
+
+**Syntax 2: function** (more flexible custom logic)
+
+```ts
+ignoreRedirectRoutes: pathname =>
+  pathname.startsWith('/api') || pathname.startsWith('/admin'),
+```

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

@@ -0,0 +1,112 @@
+---
+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';
+
+<InstallCommand />
+
+## Basic Configuration
+
+### Step 1: Register the Plugin
+
+Register the plugin in `modern.config.ts`:
+
+```ts
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { i18nPlugin } from '@modern-js/plugin-i18n';
+
+export default defineConfig({
+  plugins: [
+    appTools(),
+    i18nPlugin({
+      localeDetection: {
+        languages: ['zh', 'en'],
+        fallbackLanguage: 'en',
+      },
+    }),
+  ],
+});
+```
+
+### Step 2: Create Translation Files
+
+:::note Resource loading
+By default, the plugin looks for translation resources in the specified local directory. More resource loading methods are covered in later chapters.
+:::
+
+Create the `config/public/locales` directory:
+
+```
+config/public/locales/
+├── en/
+│   └── translation.json
+└── zh/
+    └── translation.json
+```
+
+```json
+// locales/en/translation.json
+{
+  "welcome": "Welcome to Modern.js"
+}
+```
+
+```json
+// locales/zh/translation.json
+{
+  "welcome": "欢迎使用 Modern.js"
+}
+```
+
+### Step 3: Configure Runtime Options
+
+import InstanceCode from '@site-docs/components/international/instance-code';
+
+<InstanceCode />
+
+### Step 4: Use It in Components
+
+Text returned by the `t()` function updates automatically after `changeLanguage` is called. No manual refresh is required.
+
+```tsx
+import { useTranslation } from 'react-i18next';
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+
+function App() {
+  const { t } = useTranslation();
+  const { language, changeLanguage, supportedLanguages } = useModernI18n();
+
+  return (
+    <div>
+      <h1>{t('welcome')}</h1>
+      <p>Current language: {language}</p>
+      {supportedLanguages.map(lang => (
+        <button
+          key={lang}
+          onClick={() => changeLanguage(lang)}
+          disabled={lang === language}
+        >
+          {lang}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+## Next Steps
+
+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)

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

@@ -0,0 +1,158 @@
+---
+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 |
+
+## Static File Backend
+
+Put translation files in your project and the plugin loads them directly. This is the most common approach.
+
+**CSR and SSR use different loading mechanisms, but the configuration is exactly the same:**
+
+- CSR: The browser fetches translation files through HTTP, such as `GET /locales/zh/translation.json`.
+- SSR: The server reads files directly from disk without making HTTP requests.
+
+The plugin automatically chooses the right mechanism based on the runtime environment. You only need to configure `loadPath` once.
+
+**Resource file location:**
+
+```
+config/public/locales/    <- Default location. No extra configuration required.
+├── en/translation.json
+└── zh/translation.json
+```
+
+```ts
+// modern.config.ts
+export default defineConfig({
+  plugins: [
+    appTools(),
+    i18nPlugin({
+      backend: {
+        // `{{lng}}` is the language code, and `{{ns}}` is the namespace name.
+        // During SSR, the plugin automatically converts the leading `/` prefix
+        // to a relative path before reading the file. No extra handling is needed.
+        loadPath: '/locales/{{lng}}/{{ns}}.json',
+      },
+    }),
+  ],
+});
+```
+
+To store files in another directory, configure `server.publicDir`. The relationship between **`server.publicDir` and `backend.loadPath`** is:
+
+- `server.publicDir`: Decides which local directory is exposed as static assets, that is, where files are placed.
+- `backend.loadPath`: Decides which URL i18next requests for translation files, or which path the server reads from.
+
+## Custom Backend
+
+When translation resources are not local files but come from a remote API, database, or translation platform, load them with an async function.
+
+**Step 1: declare it enabled in `modern.config.ts`**
+
+```ts
+i18nPlugin({
+  backend: {
+    sdk: true,
+  },
+});
+```
+
+**Step 2: implement the loader function in `modern.runtime.ts`**
+
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import type { I18nSdkLoader } from '@modern-js/plugin-i18n/runtime';
+
+const myLoader: I18nSdkLoader = async options => {
+  // Most common case: load a single resource by language + namespace.
+  if (options.lng && options.ns) {
+    const res = await fetch(`/api/i18n/${options.lng}/${options.ns}`);
+    const data = await res.json();
+    return { [options.lng]: { [options.ns]: data } };
+  }
+
+  // Load all resources at once.
+  if (options.all) {
+    const res = await fetch('/api/i18n/all');
+    return res.json(); // Format: { en: { translation: {...} }, zh: { translation: {...} } }
+  }
+
+  return {};
+};
+
+export default defineRuntimeConfig({
+  i18n: {
+    initOptions: {
+      backend: { sdk: myLoader },
+    },
+  },
+});
+```
+
+**Loader parameter type:**
+
+```ts
+interface I18nSdkLoadOptions {
+  lng?: string;      // Single language code
+  ns?: string;       // Single namespace
+  lngs?: string[];   // Multiple language codes
+  nss?: string[];    // Multiple namespaces
+  all?: boolean;     // Load all resources
+}
+```
+
+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).
+
+## Chained Backend
+
+Use local files and a custom backend together to implement "show local translations quickly first, then update asynchronously with the latest translations":
+
+1. When the page loads, translations are loaded from local files and displayed immediately.
+2. The custom backend loads the latest translations asynchronously in the background. After it completes, the page updates automatically.
+
+```ts
+// modern.config.ts
+i18nPlugin({
+  backend: {
+    loadPath: '/locales/{{lng}}/{{ns}}.json', // Local files, fast display
+    sdk: true,                                 // Remote loading, async update
+  },
+});
+```
+
+```ts
+// modern.runtime.ts
+export default defineRuntimeConfig({
+  i18n: {
+    initOptions: {
+      backend: {
+        sdk: async options => {
+          if (options.lng && options.ns) {
+            const res = await fetch(`https://api.example.com/i18n/${options.lng}/${options.ns}`);
+            return { [options.lng]: { [options.ns]: await res.json() } };
+          }
+          return {};
+        },
+      },
+    },
+  },
+});
+```
+
+**`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) |