@modern-js/main-doc 3.1.5 → 3.2.0

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

@@ -4,80 +4,57 @@ title: Configuration
 
 # Configuration
 
-Plugin configuration is divided into two parts: CLI configuration (`modern.config.ts`) and runtime configuration (`modern.runtime.ts`). Both need to be used together - CLI configuration is for basic plugin settings, while runtime configuration is for i18next initialization options.
+Plugin configuration is split between two files, each with a different responsibility:
 
-:::warning
-Function-type configurations (such as SDK loader functions) can only be set in runtime configuration (`modern.runtime.ts`), not in CLI configuration. This is because CLI configuration is executed at build time and cannot serialize functions.
+| 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`.
 :::
 
-## CLI Configuration (modern.config.ts)
+## Configuration Ownership
 
-Configure plugin options in `modern.config.ts`:
+| 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` |
 
-```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: {
-        // Language detection configuration
-      },
-      backend: {
-        // Backend resource loading configuration
-      },
+      localeDetection: { ... },
+      backend: { ... },
     }),
   ],
 });
 ```
 
-### localeDetection Configuration
+### localeDetection Options
 
-`localeDetection` is used to configure language detection related 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 |
 
-:::warning
-If `localePathRedirect` is enabled, the `detection` configuration must be placed in CLI configuration (`modern.config.ts`), because the server-side plugin needs to read this configuration to get language information and perform path redirection.
-:::
-
-```ts
-interface BaseLocaleDetectionOptions {
-  /** Whether to enable path redirection, adds language prefix to URL when enabled */
-  localePathRedirect?: boolean;
-
-  /** Whether to enable i18next language detector */
-  i18nextDetector?: boolean;
-
-  /** Supported language list */
-  languages?: string[];
-
-  /** Default fallback language */
-  fallbackLanguage?: string;
-
-  /** Custom detection configuration */
-  detection?: LanguageDetectorOptions;
-
-  /** Routes to ignore automatic redirection (array of path patterns or function)
-   *
-   * Can be a string array (path patterns) or a function to determine if redirection should be ignored.
-   * Supports exact match and prefix match (e.g., '/api' will match '/api' and '/api/users').
-   *
-   * @example
-   * // String array
-   * ignoreRedirectRoutes: ['/api', '/admin']
-   *
-   * // Function
-   * ignoreRedirectRoutes: (pathname) => pathname.startsWith('/api')
-   */
-  ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean);
-}
-
-interface LocaleDetectionOptions extends BaseLocaleDetectionOptions {
-  /** Configure language detection by entry (multi-entry scenarios) */
-  localeDetectionByEntry?: Record<string, BaseLocaleDetectionOptions>;
-}
-```
-
-**Example**:
+**Example:**
 
 ```ts
 i18nPlugin({
@@ -95,236 +72,79 @@ i18nPlugin({
 });
 ```
 
-### backend Configuration
-
-`backend` is used to configure resource loading methods:
-
-:::info
-**Auto-detection**: The plugin automatically detects and enables backend in the following scenarios:
-
-1. **If you configure `loadPath` or `addPath`**: The backend will be automatically enabled (`enabled: true`) without checking for locales directory, since you've already specified the resource path.
-
-2. **If you don't configure backend**: The plugin will automatically detect if a `locales` directory exists in:
-
-   - Project root: `{projectRoot}/locales`
-   - Config public directory: `{projectRoot}/config/public/locales`
-   - Public directory configured via `server.publicDir`: `{projectRoot}/{publicDir}/locales`
-
-   If the directory exists and contains JSON files, the backend will be automatically enabled.
-
-3. **If you explicitly set `enabled: false`**: No auto-detection will be performed, and the backend will remain disabled.
-
-This automatic detection helps reduce unnecessary backend registration when locales directory doesn't exist, improving performance.
-:::
+### backend Options
 
 ```ts
-interface BaseBackendOptions {
-  /** Whether to enable backend resource loading */
+interface BackendOptions {
+  // Whether to enable backend resource loading.
+  // Automatically enabled when loadPath/addPath is configured, or when a locales directory exists.
   enabled?: boolean;
 
-  /** Resource file loading path (HTTP backend) */
+  // Decides which URL or local file to request for translations. Supports {{lng}} and {{ns}}.
+  // Default: '/locales/{{lng}}/{{ns}}.json'
   loadPath?: string;
 
-  /** Missing translation save path (optional) */
+  // Path for reporting missing translations (optional).
   addPath?: string;
 
-  /** Cache hit mode for chained backend (only effective when both `loadPath` and `sdk` are provided)
-   *
-   * - `'none'` (default, only when chained backend is not configured): If the first backend returns resources, stop and don't try the next backend
-   * - `'refresh'`: Try to refresh the cache by loading from the next backend and update the cache
-   * - `'refreshAndUpdateStore'` (default for chained backend): Try to refresh the cache by loading from the next backend,
-   *   update the cache and also update the i18next resource store. This allows FS/HTTP resources to be displayed first,
-   *   then SDK resources will update them asynchronously.
-   *
-   * @default 'refreshAndUpdateStore' when both loadPath and sdk are provided
-   */
-  cacheHitMode?: 'none' | 'refresh' | 'refreshAndUpdateStore';
+  // Enables the custom backend SDK. The actual loader is provided in runtime config.
+  sdk?: boolean | string;
 
-  /** SDK loader function (custom backend)
-   *
-   * Note: In CLI configuration, can only be set to `true` or a string identifier to enable SDK mode.
-   * The actual SDK function must be provided through `initOptions.backend.sdk` in runtime configuration (`modern.runtime.ts`).
-   *
-   * When both `loadPath` (or FS backend) and `sdk` are provided, the plugin will automatically use `i18next-chained-backend`
-   * to chain multiple backends. The loading order will be:
-   * 1. HTTP/FS backend (primary) - loads from `loadPath` or file system first for quick initial display
-   * 2. SDK backend (update) - loads from the SDK function to update/refresh translations
-   *
-   * With `cacheHitMode: 'refreshAndUpdateStore'` (default), FS/HTTP resources will be displayed immediately,
-   * then SDK resources will be loaded asynchronously to update the translations.
-   */
-  sdk?: I18nSdkLoader | 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';
 
-interface BackendOptions extends BaseBackendOptions {
-  /** Configure backend by entry (multi-entry scenarios) */
+  // Per-entry overrides for multiple-entry scenarios.
   backendOptionsByEntry?: Record<string, BaseBackendOptions>;
 }
 ```
 
-**Examples**:
-
-**1. HTTP/FS backend only**:
-
-You can explicitly enable backend:
-
-```ts
-i18nPlugin({
-  backend: {
-    enabled: true,
-    loadPath: '/locales/{{lng}}/{{ns}}.json',
-  },
-});
-```
-
-Or simply configure `loadPath` or `addPath`, and backend will be automatically enabled:
-
-```ts
-i18nPlugin({
-  backend: {
-    // enabled will be automatically set to true
-    loadPath: '/locales/{{lng}}/{{ns}}.json',
-  },
-});
-```
-
-**Auto-detection without configuration**:
-
-If you don't configure backend at all, the plugin will automatically detect locales directory:
-
-```ts
-i18nPlugin({
-  // No backend config - plugin will auto-detect locales directory
-  localeDetection: {
-    languages: ['zh', 'en'],
-    fallbackLanguage: 'en',
-  },
-});
-```
-
-If `locales` directory exists with JSON files, backend will be automatically enabled with default `loadPath: '/locales/{{lng}}/{{ns}}.json'`.
-
-**2. Chained backend (recommended)**: Use both HTTP/FS backend and SDK backend
-
-When `backend.enabled = true` and `sdk` is configured, if `loadPath` is not explicitly configured, the default `loadPath` will be used automatically and chained backend will be enabled:
-
-```ts
-i18nPlugin({
-  backend: {
-    enabled: true,
-    // When loadPath is not configured, default '/locales/{{lng}}/{{ns}}.json' will be used
-    sdk: true, // SDK backend
-    // cacheHitMode: 'refreshAndUpdateStore', // Default value, can be omitted
-  },
-});
-```
-
-You can also explicitly configure `loadPath`:
-
-```ts
-i18nPlugin({
-  backend: {
-    enabled: true,
-    loadPath: '/locales/{{lng}}/{{ns}}.json', // HTTP/FS backend
-    sdk: true, // SDK backend
-  },
-});
-```
-
-Provide the SDK function in `modern.runtime.ts`:
-
-```ts
-export default defineRuntimeConfig({
-  i18n: {
-    initOptions: {
-      backend: {
-        sdk: async options => {
-          // SDK implementation
-          if (options.lng && options.ns) {
-            return await mySdk.getResource(options.lng, options.ns);
-          }
-        },
-      },
-    },
-  },
-});
-```
-
-When using chained backend, the system will:
-
-1. First load resources from `/locales/{{lng}}/{{ns}}.json` and display immediately (quick initial display of basic translations)
-2. Then asynchronously load resources from SDK and update the i18next store (update/supplement translations)
-
-This ensures users see page content quickly while the latest translation resources are loaded in the background.
-
-**3. SDK backend only**:
+**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).
 
-If you need to disable HTTP/FS backend and use only SDK backend, you can explicitly set `loadPath: ''`:
+**backend auto-enable rules:**
 
-```ts
-i18nPlugin({
-  backend: {
-    enabled: true,
-    loadPath: '', // Explicitly disable HTTP/FS backend
-    sdk: true, // Use SDK backend only
-  },
-});
-```
+| 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 |
 
-:::warning
-When using SDK backend only, you must provide the actual SDK function in `modern.runtime.ts`, otherwise it will fallback to HTTP/FS backend.
-:::
+Auto-detected directory locations, in priority order:
 
-### Multi-Entry Configuration
+1. `{project root}/config/public/locales`
+2. The `locales` subdirectory under the directory configured by `server.publicDir`
 
-If the project has multiple entries, you can configure each entry separately:
+**Which backend should you choose?**
 
-```ts
-i18nPlugin({
-  localeDetection: {
-    localePathRedirect: true,
-    languages: ['zh', 'en'],
-    fallbackLanguage: 'en',
-    // Override configuration for specific entry
-    localeDetectionByEntry: {
-      admin: {
-        localePathRedirect: false, // admin entry does not use path redirection
-      },
-    },
-  },
-  backend: {
-    enabled: true,
-    // Override configuration for specific entry
-    backendOptionsByEntry: {
-      admin: {
-        loadPath: '/admin/locales/{{lng}}/{{ns}}.json',
-      },
-    },
-  },
-});
-```
+| 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`) |
 
-## Runtime Configuration (modern.runtime.ts)
+See [Resource Loading](./resource-loading.md) for detailed usage.
 
-You can configure runtime options in `src/modern.runtime.ts`:
+## Runtime Configuration
 
-```ts
+```ts title="src/modern.runtime.ts"
 import { defineRuntimeConfig } from '@modern-js/runtime';
 import i18next from 'i18next';
 
-// It's recommended to create a new i18next instance to avoid using the global default instance
 const i18nInstance = i18next.createInstance();
 
 export default defineRuntimeConfig({
   i18n: {
-    // Use custom i18next instance (optional)
-    i18nInstance: i18nInstance,
-
-    // i18next initialization options
+    i18nInstance,   // Optional. An isolated instance is recommended.
     initOptions: {
       fallbackLng: 'en',
       supportedLngs: ['zh', 'en'],
-      // Other i18next configuration options
+      ns: ['translation'],
+      defaultNS: 'translation',
+      interpolation: {
+        escapeValue: false, // React already escapes text; disable this to avoid double escaping.
+      },
     },
   },
 });
@@ -332,97 +152,70 @@ export default defineRuntimeConfig({
 
 ### i18nInstance Configuration
 
-If you need to use a custom i18n instance, you can provide it in runtime 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 Configuration
+### initOptions
 
-import InitOptionsDesc from '@site-docs/components/international/init-options-desc';
+import Desc from '@site-docs/components/international/init-options-desc';
 
-<InitOptionsDesc />
+<Desc />
 
-:::info
-If `localePathRedirect` is enabled, the `detection` configuration should be set in CLI configuration, not in `initOptions`. This is because the server-side plugin needs to read the `detection` option from CLI configuration to perform language detection and path redirection.
-:::
+| 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 |
 
-```ts
-export default defineRuntimeConfig({
-  i18n: {
-    initOptions: {
-      // Language related
-      lng: 'en',
-      fallbackLng: 'en',
-      supportedLngs: ['zh', 'en'],
-
-      // Namespace related
-      ns: ['translation', 'common'],
-      defaultNS: 'translation',
-
-      // React related
-      react: {
-        useSuspense: false,
-      },
+`fallbackLng` supports fallback chains, which are useful for regional language degradation:
 
-      // Other i18next options
-      interpolation: {
-        escapeValue: false,
-      },
-    },
+```ts
+initOptions: {
+  lng: 'zh-CN',
+  fallbackLng: {
+    'zh-CN': ['zh', 'en'], // If zh-CN is missing, try zh first, then en.
+    default: ['en'],
   },
-});
+},
 ```
 
-### SDK Backend Configuration
-
-If using SDK backend, you need to provide the actual SDK function in runtime configuration:
-
-:::info
-Function-type configurations can only be set in runtime configuration. In CLI configuration, `sdk` can only be set to `true` or a string identifier to enable SDK mode. The actual function implementation must be provided in `modern.runtime.ts`.
-:::
+### Custom Backend Function Configuration
 
-**Enable SDK mode in `modern.config.ts`**:
+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: {
-    enabled: true,
-    sdk: true, // Enable SDK mode
-  },
+  backend: { sdk: true },
 });
-```
 
-**Provide SDK function in `modern.runtime.ts`**:
-
-```ts
-import { defineRuntimeConfig } from '@modern-js/runtime';
+// modern.runtime.ts: provide the actual function.
 import type { I18nSdkLoader } from '@modern-js/plugin-i18n/runtime';
 
-const mySdkLoader: I18nSdkLoader = async options => {
-  if (options.all) {
-    // Load all resources
-    return await fetchAllResources();
-  }
-
+const myLoader: I18nSdkLoader = async options => {
   if (options.lng && options.ns) {
-    // Load single resource
-    const response = await fetch(`/api/i18n/${options.lng}/${options.ns}`);
-    return response.json();
+    const res = await fetch(`/api/i18n/${options.lng}/${options.ns}`);
+    return res.json();
   }
-
-  // Handle other cases
   return {};
 };
 
 export default defineRuntimeConfig({
   i18n: {
     initOptions: {
-      backend: {
-        sdk: mySdkLoader,
-      },
+      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).