@modern-js/main-doc 2.69.5 → 3.0.0-alpha.0

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

@@ -0,0 +1,437 @@
+---
+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.
+
+:::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.
+:::
+
+## CLI Configuration (modern.config.ts)
+
+Configure plugin options in `modern.config.ts`:
+
+```ts
+import { i18nPlugin } from '@modern-js/plugin-i18n';
+
+export default defineConfig({
+  plugins: [
+    i18nPlugin({
+      localeDetection: {
+        // Language detection configuration
+      },
+      backend: {
+        // Backend resource loading configuration
+      },
+    }),
+  ],
+});
+```
+
+### localeDetection Configuration
+
+`localeDetection` is used to configure language detection related options:
+
+:::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**:
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    i18nextDetector: true,
+    languages: ['zh', 'en', 'ja'],
+    fallbackLanguage: 'en',
+    detection: {
+      order: ['path', 'cookie', 'header'],
+      lookupCookie: 'i18next',
+      caches: ['cookie'],
+    },
+  },
+});
+```
+
+### 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.
+:::
+
+```ts
+interface BaseBackendOptions {
+  /** Whether to enable backend resource loading */
+  enabled?: boolean;
+
+  /** Resource file loading path (HTTP backend) */
+  loadPath?: string;
+
+  /** Missing translation save path (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';
+
+  /** 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;
+}
+
+interface BackendOptions extends BaseBackendOptions {
+  /** Configure backend by entry (multi-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**:
+
+If you need to disable HTTP/FS backend and use only SDK backend, you can explicitly set `loadPath: ''`:
+
+```ts
+i18nPlugin({
+  backend: {
+    enabled: true,
+    loadPath: '', // Explicitly disable HTTP/FS backend
+    sdk: true, // Use SDK backend only
+  },
+});
+```
+
+:::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.
+:::
+
+### Multi-Entry Configuration
+
+If the project has multiple entries, you can configure each entry separately:
+
+```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',
+      },
+    },
+  },
+});
+```
+
+## Runtime Configuration (modern.runtime.ts)
+
+You can configure runtime options in `src/modern.runtime.ts`:
+
+```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
+    initOptions: {
+      fallbackLng: 'en',
+      supportedLngs: ['zh', 'en'],
+      // Other i18next configuration options
+    },
+  },
+});
+```
+
+### i18nInstance Configuration
+
+If you need to use a custom i18next instance, you can provide it in runtime configuration:
+
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import i18next from 'i18next';
+
+// Create custom instance
+const customI18n = i18next.createInstance({
+  // Custom configuration
+});
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance: customI18n,
+  },
+});
+```
+
+### initOptions Configuration
+
+`initOptions` will be passed to i18next's `init` method and supports all i18next configuration options:
+
+:::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.
+:::
+
+```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,
+      },
+
+      // Other i18next options
+      interpolation: {
+        escapeValue: false,
+      },
+    },
+  },
+});
+```
+
+### 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`.
+:::
+
+**Enable SDK mode in `modern.config.ts`**:
+
+```ts
+i18nPlugin({
+  backend: {
+    enabled: true,
+    sdk: true, // Enable SDK mode
+  },
+});
+```
+
+**Provide SDK function in `modern.runtime.ts`**:
+
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import type { I18nSdkLoader } from '@modern-js/plugin-i18n/runtime';
+
+const mySdkLoader: I18nSdkLoader = async options => {
+  if (options.all) {
+    // Load all resources
+    return await fetchAllResources();
+  }
+
+  if (options.lng && options.ns) {
+    // Load single resource
+    const response = await fetch(`/api/i18n/${options.lng}/${options.ns}`);
+    return response.json();
+  }
+
+  // Handle other cases
+  return {};
+};
+
+export default defineRuntimeConfig({
+  i18n: {
+    initOptions: {
+      backend: {
+        sdk: mySdkLoader,
+      },
+    },
+  },
+});
+```

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

@@ -0,0 +1,276 @@
+---
+title: Locale Detection
+---
+
+# Locale Detection
+
+The plugin supports multiple language detection methods, which can be combined to meet different business requirements.
+
+## Detection Methods
+
+### 1. URL Path Detection (localePathRedirect)
+
+When `localePathRedirect` is set to `true`, the plugin will detect the language from the URL path.
+
+**Examples**:
+
+- `/zh/about` → Detected language: `zh`
+- `/en/about` → Detected language: `en`
+- `/about` → If there's no language prefix, will redirect to the default language path
+
+**Configuration**:
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
+  },
+});
+```
+
+**Route Configuration** (Convention-based Routing):
+
+When using convention-based routing, you need to create a `[lang]` directory under the `routes/` directory to represent the language parameter:
+
+```bash
+routes/
+├── [lang]/
+│   ├── layout.tsx    # Layout component
+│   ├── page.tsx      # Home page
+│   └── about/
+│       └── page.tsx  # About page
+```
+
+**routes/[lang]/layout.tsx**:
+
+```tsx
+import { Outlet } from '@modern-js/runtime/router';
+
+export default function Layout() {
+  return <Outlet />;
+}
+```
+
+**routes/[lang]/page.tsx**:
+
+```tsx
+export default function Home() {
+  return <div>Home</div>;
+}
+```
+
+**routes/[lang]/about/page.tsx**:
+
+```tsx
+export default function About() {
+  return <div>About</div>;
+}
+```
+
+:::info
+If using custom routing (`modern.routes.ts`), you need to add `:lang` dynamic parameter in the route configuration. Convention-based routing will automatically generate corresponding routes based on the file structure.
+:::
+
+### 2. i18next Language Detector
+
+When `i18nextDetector` is set to `true`, the i18next language detector will be enabled, supporting language detection from the following locations:
+
+- **Cookie**: Read language settings from cookies
+- **LocalStorage**: Read from browser LocalStorage
+- **Query Parameters**: Read from URL query parameters (e.g., `?lng=en`)
+- **Request Headers**: Read from HTTP request headers (e.g., `Accept-Language`)
+- **HTML Tag**: Read from the `lang` attribute of HTML tags
+- **Subdomain**: Read from subdomain (e.g., `en.example.com`)
+
+**Configuration**:
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    i18nextDetector: true,
+    detection: {
+      order: ['cookie', 'querystring', 'header'],
+      lookupCookie: 'i18next',
+      lookupQuerystring: 'lng',
+      lookupHeader: 'accept-language',
+      caches: ['cookie'],
+    },
+  },
+});
+```
+
+### 3. Custom Detection Configuration
+
+You can customize detection behavior through the `detection` option:
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    i18nextDetector: true,
+    detection: {
+      // Detection order
+      order: ['path', 'cookie', 'querystring', 'header'],
+
+      // Cookie related
+      lookupCookie: 'i18next',
+      cookieExpirationDate: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000), // Expires in 1 year
+      cookieDomain: '.example.com',
+
+      // Query parameter related
+      lookupQuerystring: 'lng',
+
+      // Request header related
+      lookupHeader: 'accept-language',
+
+      // Cache configuration
+      caches: ['cookie', 'localStorage'],
+    },
+  },
+});
+```
+
+## Detection Priority
+
+The plugin's language detection follows the following priority order (from highest to lowest):
+
+1. **SSR Data** (highest priority): Read language from `window._SSR_DATA` set during server-side rendering, applicable to both SSR and CSR projects
+2. **Path Detection**: If `localePathRedirect` is `true`, detect language prefix from URL path
+3. **i18next Detector**: Execute detection according to the order configured in `detection.order` (Cookie, LocalStorage, query parameters, request headers, etc.)
+4. **User Configured Language**: Use the language configured in `initOptions.lng`
+5. **Fallback Language**: Use `fallbackLanguage` as the final fallback
+
+:::info
+SSR data detection has the highest priority to ensure the client uses the language detected during server-side rendering, avoiding language flickering issues caused by client-side re-detection.
+:::
+
+**Example**:
+
+```ts
+// Configured detection order (only affects priority within i18next detector)
+detection: {
+  order: ['path', 'cookie', 'querystring', 'header'],
+}
+
+// Actual detection flow:
+// 1. First check SSR data (window._SSR_DATA)
+// 2. Then check URL path (if localePathRedirect is enabled)
+// 3. Then check i18next detector according to order:
+//    - Cookie
+//    - Query parameters
+//    - Request headers
+// 4. Then use initOptions.lng (if configured)
+// 5. Finally use fallbackLanguage
+```
+
+## Detection Options
+
+### order (Detection Order)
+
+Specifies the order of language detection, optional values:
+
+- `path`: Detect from URL path
+- `querystring`: Detect from query parameters
+- `cookie`: Detect from cookies
+- `localStorage`: Detect from LocalStorage
+- `sessionStorage`: Detect from SessionStorage
+- `navigator`: Detect from browser language settings
+- `htmlTag`: Detect from HTML tags
+- `header`: Detect from HTTP request headers
+- `subdomain`: Detect from subdomain
+
+:::warning
+`path` detection requires `localePathRedirect` to be `true`. `localStorage`, `sessionStorage`, `navigator`, and `htmlTag` are only available in browser environments.
+:::
+
+### caches (Cache Method)
+
+Specifies where the detected language should be cached, optional values:
+
+- `false`: No caching
+- `['cookie']`: Cache to Cookie
+- `['localStorage']`: Cache to LocalStorage (browser only)
+- `['cookie', 'localStorage']`: Cache to both Cookie and LocalStorage
+
+### lookupQuerystring, lookupCookie, lookupLocalStorage, lookupSession, lookupHeader
+
+Specifies the key name used when reading language from query parameters, cookies, LocalStorage, SessionStorage, or request headers:
+
+- `lookupQuerystring`: Default `'lng'`, e.g., `?lng=en`
+- `lookupCookie`: Default `'i18next'`
+- `lookupLocalStorage`: Default `'i18nextLng'` (browser only)
+- `lookupSession`: SessionStorage key name (browser only)
+- `lookupHeader`: Default `'accept-language'`
+
+### lookupFromPathIndex
+
+Specifies which position in the URL path to start detecting language (when `'path'` is included in `order`):
+
+- `lookupFromPathIndex`: Path segment index, defaults to `0` (first path segment)
+
+**Example**:
+
+```ts
+// URL: /api/v1/en/users
+// If lookupFromPathIndex = 2, detection starts from the third path segment ('en')
+detection: {
+  order: ['path'],
+  lookupFromPathIndex: 2,
+}
+```
+
+### cookieMinutes, cookieExpirationDate
+
+Controls Cookie expiration time:
+
+- `cookieMinutes`: Cookie expiration time (minutes), default `525600` (1 year)
+- `cookieExpirationDate`: Cookie expiration date (Date object), takes precedence over `cookieMinutes`
+
+**Example**:
+
+```ts
+detection: {
+  cookieMinutes: 60 * 24 * 7, // Expires in 7 days
+  // or
+  cookieExpirationDate: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // Expires in 7 days
+}
+```
+
+### ignoreRedirectRoutes
+
+Specifies which routes should ignore automatic language redirection. This is very useful for API routes, static resources, and other paths that don't need language prefixes.
+
+**Configuration**:
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
+    // String array: supports exact match and prefix match
+    ignoreRedirectRoutes: ['/api', '/admin', '/static'],
+    // Or use function for more flexible judgment
+    ignoreRedirectRoutes: pathname => {
+      return pathname.startsWith('/api') || pathname.startsWith('/admin');
+    },
+  },
+});
+```
+
+**Matching Rules**:
+
+- String array: Supports exact match (`'/api'`) and prefix match (`'/api'` will match `/api` and `/api/users`)
+- Function: Receives pathname (with language prefix removed), returns `true` to indicate ignoring redirection
+
+**Example**:
+
+```ts
+// Ignore all API routes and static resources
+ignoreRedirectRoutes: ['/api', '/static', '/assets'];
+
+// Use function to ignore all paths starting with /api
+ignoreRedirectRoutes: pathname => pathname.startsWith('/api');
+```
+