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

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

@@ -0,0 +1,234 @@
+---
+title: API 参考
+---
+
+# API 参考
+
+## useModernI18n
+
+`useModernI18n` 是插件提供的 React Hook，用于在组件中访问国际化状态和操作。
+
+### 返回值
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `language` | `string` | 当前语言代码 |
+| `changeLanguage` | `(lang: string) => Promise<void>` | 切换语言 |
+| `supportedLanguages` | `string[]` | 支持的语言列表（来自 `localeDetection.languages`） |
+| `isLanguageSupported` | `(lang: string) => boolean` | 检查语言是否在支持列表中 |
+| `isResourcesReady` | `boolean` | 当前语言的翻译资源是否已加载完成 |
+| `i18nInstance` | `I18nInstance` | i18next 实例（用于高级场景） |
+
+### 基本用法
+
+```tsx
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+import { useTranslation } from 'react-i18next';
+
+function LanguageSwitcher() {
+  const { language, changeLanguage, supportedLanguages } = useModernI18n();
+  const { t } = useTranslation();
+
+  return (
+    <div>
+      <p>{t('welcome')}</p>
+      {supportedLanguages.map(lang => (
+        <button
+          key={lang}
+          onClick={() => changeLanguage(lang)}
+          disabled={lang === language}
+        >
+          {lang}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+### changeLanguage
+
+切换语言时会依次执行：
+
+1. 更新 i18next 实例的语言
+2. 更新浏览器缓存（Cookie / LocalStorage，取决于 `caches` 配置）
+3. 更新 URL 路径前缀（如果启用了 `localePathRedirect`）
+
+`changeLanguage` 是异步函数，使用时需要 `await`：
+
+```ts
+await changeLanguage('zh');
+```
+
+### isResourcesReady
+
+在自定义后端场景中，翻译资源需要异步加载，可以用 `isResourcesReady` 防止在资源未就绪时渲染：
+
+```tsx
+function MyComponent() {
+  const { isResourcesReady } = useModernI18n();
+  const { t } = useTranslation();
+
+  if (!isResourcesReady) {
+    return <div>加载翻译中...</div>;
+  }
+
+  return <div>{t('content')}</div>;
+}
+```
+
+`isResourcesReady` 会检查：i18n 实例是否已初始化、当前语言是否有资源正在加载、所有必需命名空间是否已加载完成。
+
+## I18nLink 组件
+
+带语言前缀的路由链接组件。
+
+### Props
+
+| Prop | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `to` | `string` | 是 | 目标路径，不需要包含语言前缀 |
+| `children` | `React.ReactNode` | 是 | 链接内容 |
+| `replace` | `boolean` | 否 | 使用 `history.replace` 而非 `push` |
+| `state` | `any` | 否 | 传递给目标路由的状态 |
+| 其他 Link props | — | 否 | 继承自 `@modern-js/runtime/router` 的 `Link` 组件 |
+
+### 用法
+
+```tsx
+import { I18nLink } from '@modern-js/plugin-i18n/runtime';
+
+<I18nLink to="/about">关于</I18nLink>
+<I18nLink to="/contact" replace>联系</I18nLink>
+<I18nLink to="/profile" state={{ from: 'home' }}>个人中心</I18nLink>
+```
+
+## Runtime 插件 API
+
+i18n 插件会在 `onBeforeRender` 钩子的 context 上挂载 `changeLanguage` 和 `i18nInstance`，供其他 Runtime 插件使用：
+
+```ts
+import type { RuntimePlugin } from '@modern-js/runtime';
+
+const myPlugin = (): RuntimePlugin => ({
+  name: 'my-plugin',
+  setup: api => {
+    api.onBeforeRender(async context => {
+      if (!context.changeLanguage) return; // 确保 i18n 插件已加载
+
+      const lang = detectLangFromRequest(context);
+      const supported = context.i18nInstance?.options?.supportedLngs ?? [];
+
+      if (supported.includes(lang)) {
+        try {
+          await context.changeLanguage(lang);
+        } catch (e) {
+          console.error('Language change failed:', e);
+        }
+      }
+    });
+  },
+});
+```
+
+**注意事项：**
+- 确保 i18n 插件在使用 `context.changeLanguage` 的插件之前注册
+- `changeLanguage` 在服务端不会更新 URL 路径，需要配合路由插件或手动处理
+
+## 类型定义
+
+### I18nInstance
+
+插件使用的 i18next 实例类型（i18next `i18n` 类型的子集，仅列出插件实际使用的字段）：
+
+```ts
+interface I18nInstance {
+  language: string;
+  isInitialized: boolean;
+  init: (options?: I18nInitOptions) => void | Promise<void>;
+  changeLanguage: (lang: string) => void | Promise<void>;
+  use: (plugin: any) => void;
+  createInstance: (options?: I18nInitOptions) => I18nInstance;
+  options?: {
+    backend?: BackendOptions;
+    supportedLngs?: string[];
+    [key: string]: any;
+  };
+}
+```
+
+### I18nSdkLoader
+
+自定义后端加载函数的类型：
+
+```ts
+type I18nSdkLoader = (options: I18nSdkLoadOptions) => Promise<Resources>;
+
+interface I18nSdkLoadOptions {
+  lng?: string;      // 单个语言代码
+  ns?: string;       // 单个命名空间
+  lngs?: string[];   // 多个语言代码
+  nss?: string[];    // 多个命名空间
+  all?: boolean;     // 加载所有资源
+}
+
+type Resources = {
+  [lng: string]: {
+    [ns: string]: Record<string, any>;
+  };
+};
+```
+
+### LanguageDetectorOptions
+
+```ts
+interface LanguageDetectorOptions {
+  order?: string[];
+  lookupQuerystring?: string;   // 默认 'lng'
+  lookupCookie?: string;        // 默认 'i18next'
+  lookupLocalStorage?: string;  // 默认 'i18nextLng'
+  lookupSession?: string;
+  lookupHeader?: string;        // 默认 'accept-language'
+  lookupFromPathIndex?: number; // 默认 0
+  caches?: false | string[];
+  cookieMinutes?: number;       // 默认 525600（1年）
+  cookieExpirationDate?: Date;
+  cookieDomain?: string;
+}
+```
+
+## 与 react-i18next 集成
+
+插件完全兼容 react-i18next，两套 API 可以混用：
+
+- **`useTranslation`**（react-i18next）：获取 `t()` 函数做翻译，这是最常用的 Hook
+- **`useModernI18n`**（插件提供）：获取语言切换、支持列表、资源加载状态等插件层面的状态
+
+大多数组件只需要 `useTranslation`，只有涉及语言切换或需要检查加载状态时才需要 `useModernI18n`：
+
+```tsx
+import { useTranslation } from 'react-i18next';
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+
+function App() {
+  const { t } = useTranslation();                          // 翻译文本
+  const { language, changeLanguage } = useModernI18n();    // 语言切换
+
+  return (
+    <div>
+      <h1>{t('welcome')}</h1>
+      <button onClick={() => changeLanguage('zh')}>中文</button>
+      <button onClick={() => changeLanguage('en')}>English</button>
+    </div>
+  );
+}
+```
+
+也可以通过 `useModernI18n` 获取 i18next 实例后直接调用 react-i18next 之外的能力：
+
+```tsx
+const { i18nInstance } = useModernI18n();
+
+// 动态添加翻译资源
+i18nInstance.addResourceBundle('zh', 'translation', { key: '值' }, true, true);
+```

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

@@ -0,0 +1,290 @@
+---
+title: 最佳实践
+---
+
+# 最佳实践
+
+## 资源文件组织
+
+命名空间（Namespace）用于按业务模块拆分翻译文件，默认命名空间为 `translation`。按模块拆分可以减少初始加载体积，只在用到时按需加载对应命名空间。
+
+推荐目录结构：
+
+```
+locales/
+├── en/
+│   ├── translation.json  ← 默认命名空间，放通用文案
+│   ├── common.json       ← 按钮、标签等公共 UI 文案
+│   └── errors.json       ← 错误信息
+└── zh/
+    ├── translation.json
+    ├── common.json
+    └── errors.json
+```
+
+声明多个命名空间：
+
+```ts
+// src/modern.runtime.ts
+export default defineRuntimeConfig({
+  i18n: {
+    initOptions: {
+      ns: ['translation', 'common', 'errors'],
+      defaultNS: 'translation',
+    },
+  },
+});
+```
+
+在组件中使用指定命名空间：
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+// 指定单个命名空间
+function MyButton() {
+  const { t } = useTranslation('common');
+  return <button>{t('submit')}</button>;
+}
+
+// 同时使用多个命名空间，用 namespace:key 格式访问
+function Dashboard() {
+  const { t } = useTranslation(['dashboard', 'common']);
+  return (
+    <header>
+      <h1>{t('dashboard:title')}</h1>
+      <button>{t('common:button.refresh')}</button>
+    </header>
+  );
+}
+
+// keyPrefix 可以省略重复的前缀
+function ButtonGroup() {
+  const { t } = useTranslation('common', { keyPrefix: 'button' });
+  return (
+    <>
+      <button>{t('submit')}</button>   {/* → common:button.submit */}
+      <button>{t('cancel')}</button>   {/* → common:button.cancel */}
+    </>
+  );
+}
+```
+
+## 翻译键命名规范
+
+翻译键的命名质量直接影响后续维护成本，建议：
+
+- **用语义化词语**，避免缩写：`button.submit` 优于 `btn.sbm`
+- **按模块划分前缀**：`dashboard.table.header`、`auth.login.title`
+- **不要用完整中文文案当键名**：键名应是稳定的标识符，而不是翻译内容本身
+- **用点号表示层级**：与 JSON 嵌套结构一一对应
+
+```json
+// ✅ 推荐
+{
+  "page": {
+    "title": "用户设置",
+    "description": "管理你的账号信息"
+  },
+  "form": {
+    "username": { "label": "用户名", "placeholder": "请输入用户名" },
+    "submit": "保存更改"
+  }
+}
+```
+
+```tsx
+t('page.title')
+t('form.username.label')
+t('form.submit', { defaultValue: '保存' }) // defaultValue 防止键缺失时显示 key 字符串
+```
+
+## 复数
+
+i18next 根据 `count` 参数自动选择对应的复数形式。**注意：i18next v21 之后默认使用 JSON v4 格式**，复数后缀改为 CLDR 标准（`_zero`、`_one`、`_other` 等），旧的 `_plural` 写法已废弃。
+
+```json
+// locales/en/translation.json（JSON v4 格式）
+{
+  "item_zero": "No items",
+  "item_one": "{{count}} item",
+  "item_other": "{{count}} items"
+}
+```
+
+```json
+// locales/zh/translation.json
+{
+  "item_zero": "没有条目",
+  "item_other": "{{count}} 个条目"
+}
+```
+
+```tsx
+t('item', { count: 0 })  // → "没有条目" / "No items"
+t('item', { count: 1 })  // → "没有条目" / "1 item"（中文通常只有一种形式）
+t('item', { count: 5 })  // → "5 个条目" / "5 items"
+```
+
+不同语言的复数规则不同（英语有单复数，俄语有 one/few/many 等多种形式），i18next 会根据语言代码自动匹配 CLDR 规则。
+
+:::tip
+如果项目使用了旧版 i18next 或显式配置了 `compatibilityJSON: 'v3'`，才需要使用 `_plural` 写法。新项目统一使用 v4 格式。
+:::
+
+## 嵌套键
+
+嵌套结构可以直观反映 UI 层级，用点号访问：
+
+```json
+{
+  "modal": {
+    "confirm": {
+      "title": "确认删除",
+      "message": "此操作不可撤销，是否继续？",
+      "actions": {
+        "ok": "确认",
+        "cancel": "取消"
+      }
+    }
+  }
+}
+```
+
+```tsx
+t('modal.confirm.title')
+t('modal.confirm.actions.ok')
+```
+
+嵌套层级不建议超过 4 层，过深的结构会让键名变得冗长难维护。
+
+## 格式化插值
+
+通过 `interpolation.format` 函数统一处理数字、日期、货币等格式化，避免在每个组件里各自调用 `Intl` API：
+
+```ts
+// src/modern.runtime.ts
+export default defineRuntimeConfig({
+  i18n: {
+    initOptions: {
+      interpolation: {
+        escapeValue: false, // React 已默认转义文本，关闭避免重复转义
+        format(value, format, lng) {
+          if (format === 'currency') {
+            return new Intl.NumberFormat(lng, {
+              style: 'currency',
+              currency: lng === 'zh' ? 'CNY' : 'USD',
+            }).format(Number(value));
+          }
+          if (format === 'date') {
+            return new Intl.DateTimeFormat(lng, { dateStyle: 'medium' }).format(
+              value instanceof Date ? value : new Date(value),
+            );
+          }
+          return value;
+        },
+      },
+    },
+  },
+});
+```
+
+翻译文件中用 `, format` 指定格式化类型：
+
+```json
+{
+  "price": "当前价格：{{value, currency}}",
+  "expiry": "到期日：{{date, date}}"
+}
+```
+
+```tsx
+t('price', { value: 99.5 })       // → "当前价格：¥99.50"（zh）/ "$99.50"（en）
+t('expiry', { date: new Date() }) // → "到期日：2025年5月12日"（zh）
+```
+
+## 错误处理
+
+### 加载状态处理
+
+使用自定义后端时，翻译资源需要异步加载，推荐用 `isResourcesReady` 处理加载中状态：
+
+```tsx
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+import { useTranslation } from 'react-i18next';
+
+function MyComponent() {
+  const { isResourcesReady } = useModernI18n();
+  const { t } = useTranslation();
+
+  if (!isResourcesReady) {
+    return <div>加载翻译中...</div>;
+  }
+
+  return <div>{t('content', { defaultValue: '默认内容' })}</div>;
+}
+```
+
+静态资源（HTTP/FS 后端）加载较快，通常不需要处理加载状态；如需检查，可以用 `i18n.isInitialized`：
+
+```tsx
+const { t, i18n } = useTranslation();
+if (!i18n.isInitialized) return null;
+```
+
+### 翻译键缺失处理
+
+通过 `defaultValue` 提供兜底文案，防止界面显示 key 字符串：
+
+```tsx
+t('missing.key', { defaultValue: '默认文案' })
+```
+
+开发环境可以开启 `saveMissing`，将缺失的键输出到控制台方便排查：
+
+```ts
+initOptions: {
+  fallbackLng: 'en',
+  saveMissing: true, // 仅建议开发环境开启
+}
+```
+
+### 网络失败与资源 404
+
+翻译文件加载失败时，i18next 会回退到 `fallbackLng` 对应的资源；若仍失败，`t()` 直接返回 key 字符串。建议：
+
+- 生产环境确保 `fallbackLng`（通常是 `en`）对应的翻译文件完整且稳定
+- 使用链式后端时，本地文件作为兜底，减少对远程服务的依赖
+
+## 类型安全
+
+通过扩展 react-i18next 的类型定义，让 TypeScript 检查翻译键是否存在并提供自动补全：
+
+```ts
+// types/i18n.d.ts
+import 'react-i18next';
+import type translation from '../locales/en/translation.json';
+import type common from '../locales/en/common.json';
+
+declare module 'react-i18next' {
+  interface CustomTypeOptions {
+    defaultNS: 'translation';
+    resources: {
+      translation: typeof translation;
+      common: typeof common;
+    };
+  }
+}
+```
+
+直接引用 JSON 文件的类型，比手写 interface 更不容易与实际翻译文件漂移：
+
+```tsx
+const { t } = useTranslation();
+t('welcome');       // ✅ TypeScript 自动补全
+t('nonExistent');   // ❌ TypeScript 报错
+```
+
+:::tip 大型项目
+翻译文件较多时，手动维护类型文件成本较高。可以使用 [i18next-parser](https://github.com/i18next/i18next-parser) 或 [i18next-resources-for-ts](https://github.com/i18next/i18next-resources-for-ts) 从翻译文件自动生成 TypeScript 类型。
+:::