@modern-js/main-doc 3.1.4 → 3.2.0

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

@@ -4,21 +4,29 @@ title: Locale Detection
 
 # Locale Detection
 
-The plugin supports multiple language detection methods, which can be combined to meet different business requirements.
+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 Methods
+## Detection Priority
 
-### 1. URL Path Detection (localePathRedirect)
+No matter which detection methods are enabled, the priority is fixed as follows, from high to low:
 
-When `localePathRedirect` is set to `true`, the plugin will detect the language from the URL path.
+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.
 
-**Examples**:
+## Detection Methods
 
-- `/zh/about` → Detected language: `zh`
-- `/en/about` → Detected language: `en`
-- `/about` → If there's no language prefix, will redirect to the default language path
+### URL Path Detection
 
-**Configuration**:
+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({
@@ -30,61 +38,11 @@ i18nPlugin({
 });
 ```
 
-**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
+After enabling path detection, you also need to configure a `[lang]` dynamic parameter in your routes. See [Routing Integration](./routing.md).
 
-When `i18nextDetector` is set to `true`, the i18next language detector will be enabled, supporting language detection from the following locations:
+### i18next Detector
 
-- **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**:
+Set `i18nextDetector: true` to enable language detection from Cookie, LocalStorage, query parameters, request headers, and other sources:
 
 ```ts
 i18nPlugin({
@@ -101,176 +59,72 @@ i18nPlugin({
 });
 ```
 
-### 3. Custom Detection Configuration
-
-You can customize detection behavior through the `detection` option:
+Both methods can be enabled at the same time:
 
 ```ts
 i18nPlugin({
   localeDetection: {
-    i18nextDetector: true,
+    localePathRedirect: true,   // Path prefix
+    i18nextDetector: true,      // Cookie / Header, etc.
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
     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'],
+      order: ['cookie', 'header'],
     },
   },
 });
 ```
 
-## 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
+## Detection Options (`detection`)
 
-Specifies which position in the URL path to start detecting language (when `'path'` is included in `order`):
+| 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 |
 
-- `lookupFromPathIndex`: Path segment index, defaults to `0` (first path segment)
-
-**Example**:
+**Default detection order when `order` is not configured:**
 
 ```ts
-// URL: /api/v1/en/users
-// If lookupFromPathIndex = 2, detection starts from the third path segment ('en')
-detection: {
-  order: ['path'],
-  lookupFromPathIndex: 2,
-}
+['querystring', 'cookie', 'localStorage', 'header', 'navigator', 'htmlTag', 'path', 'subdomain']
 ```
 
-### 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`
+**Available `order` values:**
 
-**Example**:
+| 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`) | - |
 
-```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
 
-### 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.
 
-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**:
+**Syntax 1: string array** (supports exact match and prefix match)
 
 ```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');
-    },
-  },
-});
+ignoreRedirectRoutes: ['/api', '/admin', '/static']
+// '/api' matches both /api and /api/users.
 ```
 
-**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**:
+**Syntax 2: function** (more flexible custom logic)
 
 ```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');
+ignoreRedirectRoutes: pathname =>
+  pathname.startsWith('/api') || pathname.startsWith('/admin'),
 ```
-

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

@@ -4,11 +4,9 @@ title: Quick Start
 
 # Quick Start
 
-This guide will help you quickly integrate internationalization functionality into your Modern.js project.
+This guide helps you quickly integrate internationalization into a Modern.js project.
 
-## Install Plugin
-
-First, install the necessary dependencies:
+## Install the Plugin
 
 import InstallCommand from '@site-docs/components/international/install-command';
 
@@ -16,111 +14,99 @@ import InstallCommand from '@site-docs/components/international/install-command'
 
 ## Basic Configuration
 
-### Configure Plugin in `modern.config.ts`
+### 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({
-  server: {
-    publicDir: './locales', // Required: specify the resource file directory
-  },
   plugins: [
     appTools(),
     i18nPlugin({
       localeDetection: {
-        languages: ['zh', 'en'], // Supported language list
-        fallbackLanguage: 'en', // Default language
-      },
-      backend: {
-        enabled: true, // Enable backend resource loading
-        // loadPath defaults to '/locales/{{lng}}/{{ns}}.json', usually no need to modify
-        // Note: You can also omit 'enabled' and just configure 'loadPath' or 'addPath',
-        // or omit backend config entirely to let the plugin auto-detect locales directory
+        languages: ['zh', 'en'],
+        fallbackLanguage: 'en',
       },
     }),
   ],
 });
 ```
 
-:::info
-`server.publicDir` is a required configuration used to specify the actual location of resource files. Even when using the default `loadPath`, this configuration is still required.
+### 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.
 :::
 
-### Configure Runtime Options in `src/modern.runtime.ts`
-
-import InstanceCode from '@site-docs/components/international/instance-code';
-
-<InstanceCode />
-
-### Create Language Resource Files
-
-Create a `locales` folder in the project root and organize resource files by language:
+Create the `config/public/locales` directory:
 
 ```
-locales/
+config/public/locales/
 ├── en/
 │   └── translation.json
 └── zh/
     └── translation.json
 ```
 
-**locales/en/translation.json**:
-
 ```json
+// locales/en/translation.json
 {
-  "hello": "Hello",
-  "world": "World",
   "welcome": "Welcome to Modern.js"
 }
 ```
 
-**locales/zh/translation.json**:
-
 ```json
+// locales/zh/translation.json
 {
-  "hello": "你好",
-  "world": "世界",
   "welcome": "欢迎使用 Modern.js"
 }
 ```
 
-### Use in Components
+### 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 { useModernI18n } from '@modern-js/plugin-i18n/runtime';
 import { useTranslation } from 'react-i18next';
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
 
 function App() {
-  const { language, changeLanguage, supportedLanguages } = useModernI18n();
   const { t } = useTranslation();
+  const { language, changeLanguage, supportedLanguages } = useModernI18n();
 
   return (
     <div>
       <h1>{t('welcome')}</h1>
       <p>Current language: {language}</p>
-      <div>
-        {supportedLanguages.map(lang => (
-          <button
-            key={lang}
-            onClick={() => changeLanguage(lang)}
-            disabled={lang === language}
-          >
-            {lang}
-          </button>
-        ))}
-      </div>
+      {supportedLanguages.map(lang => (
+        <button
+          key={lang}
+          onClick={() => changeLanguage(lang)}
+          disabled={lang === language}
+        >
+          {lang}
+        </button>
+      ))}
     </div>
   );
 }
-
-export default App;
 ```
 
 ## Next Steps
 
-- Learn detailed [Configuration](./configuration) instructions
-- Learn about multiple [Locale Detection](./locale-detection) methods
-- Check [Resource Loading](./resource-loading) configuration options
+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)