@modern-js/main-doc 3.1.5 → 3.2.0

package/docs/zh/guides/advanced-features/international/advanced.mdx

@@ -4,103 +4,81 @@ title: 高级用法
 
 # 高级用法
 
-## SSR 配置
+## SSR 场景
 
-插件完全支持服务端渲染（SSR）场景。
+SSR 场景下，插件在服务端检测语言、加载翻译资源，并将结果注入页面，客户端直接复用，避免语言闪烁。
 
-### 服务端语言检测
-
-在 SSR 场景下，插件会从 HTTP 请求中检测语言：
-
-1. **URL 路径**：从路径中提取语言前缀
-2. **Cookie**：从 Cookie 中读取语言设置
-3. **请求头**：从 `Accept-Language` 请求头读取
-
-**配置示例**：
-
-```ts
-i18nPlugin({
-  localeDetection: {
-    localePathRedirect: true,
-    i18nextDetector: true,
-    languages: ['zh', 'en'],
-    fallbackLanguage: 'en',
-    detection: {
-      order: ['path', 'cookie', 'header'],
-      lookupHeader: 'accept-language',
-    },
-  },
-})
-```
-
-### SSR 资源加载
-
-在 SSR 场景下，插件会自动使用文件系统后端加载资源：
+**完整配置：**
 
 ```ts
+// modern.config.ts
 export default defineConfig({
   server: {
     ssr: true,
-    publicDir: './locales', // 资源文件目录
   },
   plugins: [
+    appTools(),
     i18nPlugin({
+      localeDetection: {
+        localePathRedirect: true,
+        i18nextDetector: true,
+        languages: ['zh', 'en'],
+        fallbackLanguage: 'en',
+        detection: {
+          order: ['path', 'cookie', 'header'],
+          lookupHeader: 'accept-language',
+          caches: ['cookie'],
+        },
+      },
       backend: {
-        enabled: true,
+        loadPath: '/locales/{{lng}}/{{ns}}.json',
       },
     }),
   ],
 });
 ```
 
-资源文件结构：
+服务端检测语言的优先级：URL 路径 → Cookie → `Accept-Language` 请求头 → `fallbackLanguage`。
+
+**路由配置（约定式路由）：**
 
 ```
-项目根目录/
-└── locales/
-    ├── en/
-    │   └── translation.json
-    └── zh/
-        └── translation.json
+routes/
+└── [lang]/
+    ├── layout.tsx
+    └── page.tsx
 ```
 
-## 多入口配置
+SSR 场景下，服务端检测到的语言会写入 `window._SSR_DATA`，客户端直接读取，不会再重新检测，确保两端语言一致。
 
-如果项目有多个入口，可以为每个入口单独配置语言检测和后端选项。
+## 多入口配置
 
-### 按入口配置语言检测
+不同入口可以使用不同的语言列表、检测方式和资源路径：
 
 ```ts
+// modern.config.ts
 i18nPlugin({
   localeDetection: {
-    // 全局配置
+    // 全局默认配置
     localePathRedirect: true,
     languages: ['zh', 'en'],
     fallbackLanguage: 'en',
 
-    // 按入口覆盖配置
+    // 按入口覆盖
     localeDetectionByEntry: {
       admin: {
-        localePathRedirect: false, // admin 入口不使用路径重定向
-        languages: ['en'], // admin 入口只支持英文
+        localePathRedirect: false, // admin 入口不使用路径前缀
+        languages: ['en'],         // admin 只支持英文
       },
       mobile: {
-        languages: ['zh', 'en', 'ja'], // mobile 入口支持更多语言
+        languages: ['zh', 'en', 'ja'], // mobile 支持更多语言
       },
     },
   },
-})
-```
-
-### 按入口配置后端
-
-```ts
-i18nPlugin({
   backend: {
-    enabled: true,
-    loadPath: '/locales/{{lng}}/{{ns}}.json', // 默认路径
+    loadPath: '/locales/{{lng}}/{{ns}}.json', // 全局默认路径
 
-    // 按入口覆盖配置
+    // 按入口覆盖
     backendOptionsByEntry: {
       admin: {
         loadPath: '/admin/locales/{{lng}}/{{ns}}.json',
@@ -110,33 +88,24 @@ i18nPlugin({
       },
     },
   },
-})
+});
 ```
 
 ## 自定义 i18next 实例
 
-如果需要使用自定义的 i18next 实例，可以在运行时配置中提供。
-
-### 创建自定义实例
+默认情况下，插件会使用内部创建的 i18next 实例。如果需要对实例进行深度定制（如使用自定义插件、预配置选项），可以在运行时配置中传入自定义实例：
 
 ```ts
 // src/i18n.ts
 import i18next from 'i18next';
 
-const customI18n = i18next.createInstance({
-  // 自定义配置
-  fallbackLng: 'en',
-  supportedLngs: ['zh', 'en'],
-  interpolation: {
-    escapeValue: false,
-  },
-});
+const customI18n = i18next.createInstance();
+// 可以在此 use() 自定义插件
+// customI18n.use(MyPlugin);
 
 export default customI18n;
 ```
 
-### 传递自定义实例
-
 ```ts
 // src/modern.runtime.ts
 import { defineRuntimeConfig } from '@modern-js/runtime';
@@ -146,48 +115,18 @@ export default defineRuntimeConfig({
   i18n: {
     i18nInstance: customI18n,
     initOptions: {
-      // 其他配置选项
+      fallbackLng: 'en',
+      supportedLngs: ['zh', 'en'],
     },
   },
 });
 ```
 
-## 语言切换
-
-### 编程式切换
-
-使用 `useModernI18n` Hook 的 `changeLanguage` 方法：
-
-```tsx
-import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
-
-function LanguageSwitcher() {
-  const { language, changeLanguage, supportedLanguages } = useModernI18n();
-
-  return (
-    <select
-      value={language}
-      onChange={e => changeLanguage(e.target.value)}
-    >
-      {supportedLanguages.map(lang => (
-        <option key={lang} value={lang}>
-          {lang}
-        </option>
-      ))}
-    </select>
-  );
-}
-```
-
-### URL 同步
-
-当启用 `localePathRedirect` 时，切换语言会自动更新 URL：
-
-```tsx
-// 当前 URL: /en/about
-// 调用 changeLanguage('zh')
-// URL 自动更新为: /zh/about
-```
+## 语言切换行为说明
 
-如果未启用 `localePathRedirect`，语言切换只会更新 i18next 实例和缓存，不会改变 URL。
+调用 `changeLanguage` 切换语言时：
 
+- **翻译更新**：所有使用 `t()` 的组件自动重新渲染，无需手动刷新
+- **URL 更新**（启用 `localePathRedirect` 时）：使用 `history.pushState` 更新 URL，不触发页面刷新，不影响浏览器前进/后退历史
+- **缓存更新**：根据 `caches` 配置写入 Cookie 或 LocalStorage，下次访问自动还原语言选择
+- **未启用路径前缀时**：只更新 i18next 实例和缓存，URL 不变