generator-mico-cli 0.2.13 → 0.2.14

package/generators/micro-react/templates/packages/common-intl/README.md

@@ -0,0 +1,428 @@
+# @portal-web/common-intl
+
+通用国际化（i18n）库，用于 Portal 多应用间的多语言文案管理。
+
+## 功能特性
+
+- **跨端兼容**：不内置 UI 提示能力，通过外部注入 `messageInstance` 实现跨平台兼容
+- **缓存机制**：支持 IndexedDB 持久化存储 + 内存缓存双重保障
+- **插值替换**：支持 `%AA%`、`%BB%` 等占位符的动态替换
+- **降级处理**：当翻译 key 不存在时，自动返回兜底文案
+- **环境感知**：自动根据 `NODE_ENV` 切换开发/生产 API 地址
+- **微前端共享**：主应用获取的文案数据自动共享给所有子应用
+
+## 安装
+
+在 monorepo 项目中，通过 workspace 引用：
+
+```json
+{
+  "dependencies": {
+    "@portal-web/common-intl": "workspace:*"
+  }
+}
+```
+
+## 两种使用模式
+
+根据应用架构的不同，`@portal-web/common-intl` 支持两种使用模式：
+
+| 模式         | 适用场景                                         | 示例应用                                                     |
+| ------------ | ------------------------------------------------ | ------------------------------------------------------------ |
+| 微前端模式   | qiankun 主子应用架构，主应用获取文案后子应用共享 | layout、conversation-v2、session、workorder、faq、permission |
+| 独立应用模式 | 独立运行的应用，自己获取和管理文案               | mico-cs-mobile                                               |
+
+### 微前端模式
+
+在 qiankun 微前端架构中，**主应用负责获取文案**，子应用直接使用共享的文案对象，无需重复初始化。
+
+**工作原理**：
+
+- 主应用调用 `initIntl()` 获取远程文案
+- 文案数据存储到 `window.__MICO_COMMON_INTL_TRANSLATIONS__`
+- 子应用直接使用 `intl` 对象，自动从 window 读取共享数据
+
+**主应用配置**（参考 `apps/layout/src/app.tsx`）：
+
+```typescript
+import {
+  getCurrentLocale,
+  initIntl,
+  type ILang,
+} from "@portal-web/common-intl";
+import { Message } from "@arco-design/web-react";
+import { request } from "@umijs/max";
+
+// 初始化国际化模块
+const fetchMultilingualData = initIntl({
+  requestInstance: request,
+  messageInstance: {
+    error: (msg: string) => Message.error(msg),
+    warning: (msg: string) => Message.warning(msg),
+  },
+  fetchMultilingualDataParams: {
+    tag: "cs_fe_pc",
+    lang: getCurrentLocale() as ILang,
+    app_name: "middle",
+  },
+  indexedDBParams: {
+    dbName: "mico_cs_web_i18n_db",
+  },
+});
+
+// 在应用渲染前加载多语言数据
+export function render(oldRender: () => void): void {
+  fetchMultilingualData()
+    .then(oldRender)
+    .catch((error: Error) => {
+      console.error("获取多语言文案失败", error);
+      oldRender(); // 失败时继续渲染，使用兜底文案
+    });
+}
+```
+
+**子应用使用**（无需初始化）：
+
+```typescript
+// apps/conversation-v2、apps/session、apps/workorder 等子应用
+import { intl } from "@portal-web/common-intl";
+
+// 直接使用，文案来自主应用
+<h1>{intl.cs_web_workbench_conversation_record()}</h1>;
+```
+
+### 独立应用模式
+
+对于非 qiankun 架构的独立应用（如 H5 应用），需要自己调用 `initIntl()` 获取文案，并维护独立的文案文件。
+
+**独立应用配置**（参考 `apps/mico-cs-mobile/src/app.ts`）：
+
+```typescript
+import { initIntl } from "@portal-web/common-intl";
+import { Toast } from "@arco-design/mobile-react";
+import { request } from "@umijs/max";
+import { convertLocaleToLangParam } from "./locales/utils";
+import { getSearchParams } from "@/common/jsbridge/jsbridge";
+
+// 初始化国际化模块
+const fetchMultilingualData = initIntl({
+  // 请求实例（必填）
+  requestInstance: request,
+  // 消息提示实例（必填）
+  messageInstance: {
+    error: (msg: string) => Toast.error(msg),
+    warning: (msg: string) => Toast.warn(msg),
+  },
+  // 多语言中台接口参数（必填）
+  fetchMultilingualDataParams: {
+    tag: 'cs_fe_mobile',           // 多语言标签，参考翻译中台-文案管理列表页-Tags 表格列 https://lang-test.micoplatform.com/lang/#/langs
+    lang: convertLocaleToLangParam(getSearchParams().language as string),
+    app_name: 'middle',            // 应用名称，参考翻译中台左上角 https://lang-test.micoplatform.com/lang/#/langs
+  },
+  // IndexedDB 参数（可选）
+  indexedDBParams: {
+    dbName: 'mico_cs_mobile_i18n_db',
+  },
+});
+
+// 在应用渲染前加载多语言数据
+// 如果是基于 umi 的项目，可以在 app.tsx 的 render 函数中调用加载函数 https://umijs.org/docs/api/runtime-config#render
+export function render(oldRender: () => void): void {
+  fetchMultilingualData()
+    .then(oldRender)
+    .catch((error: Error) => {
+      console.error('获取多语言文案失败', error);
+      // 即使失败也继续渲染，使用兜底文案
+      oldRender();
+    });
+}
+```
+
+**独立应用的文案文件**（`apps/mico-cs-mobile/src/locales/index.ts`）：集中管理所有国际化文案
+
+```typescript
+import { i18n } from "@portal-web/common-intl";
+
+const intl = {
+  // 无插值示例
+  sdk_h5_ticket_record: () =>
+    i18n({
+      key: 'sdk_h5_ticket_record',
+      defaultMessage: '工单记录',
+    }),
+
+  // 单个插值示例
+  sdk_h5_common_request_failed_aa: (code: string | number) =>
+    i18n({
+      key: 'sdk_h5_common_request_failed_aa',
+      interpolations: [code],
+      defaultMessage: `请求失败 (${code})`,
+    }),
+
+  // 多个插值示例
+  sdk_h5_common_upload_failed_status_aa_bb: (
+    statusCode: string | number,
+    responseText: string,
+  ) =>
+    i18n({
+      key: 'sdk_h5_common_upload_failed_status_aa_bb',
+      interpolations: [statusCode, responseText],
+      defaultMessage: `上传失败，状态码 ${statusCode}${responseText}`,
+    }),
+};
+
+export default intl;
+```
+
+**在组件中使用**：
+
+```tsx
+import intl from '@/locales';
+
+function MyComponent() {
+  return (
+    <div>
+      <h1>{intl.sdk_h5_ticket_record()}</h1>
+      <p>{intl.sdk_h5_common_request_failed_aa(404)}</p>
+    </div>
+  );
+}
+```
+
+## API 参考
+
+### `initIntl(params: IInitIntlParams)`
+
+初始化国际化模块，返回 `fetchMultilingualData` 函数。
+
+#### 参数
+
+| 参数                                   | 类型               | 必填 | 说明                                         |
+| -------------------------------------- | ------------------ | ---- | -------------------------------------------- |
+| `requestInstance`                      | `Function`         | ✅   | HTTP 请求函数，用于请求多语言中台接口        |
+| `messageInstance`                      | `IMessageInstance` | ✅   | 消息提示实例，包含 `error` 和 `warning` 方法 |
+| `fetchMultilingualDataParams`          | `Object`           | ✅   | 多语言接口参数                               |
+| `fetchMultilingualDataParams.tag`      | `string`           | ✅   | 多语言标签                                   |
+| `fetchMultilingualDataParams.lang`     | `ILang`            | ✅   | 语言类型                                     |
+| `fetchMultilingualDataParams.app_name` | `string`           | ✅   | 应用名称                                     |
+| `indexedDBParams`                      | `Object`           | ❌   | IndexedDB 配置参数                           |
+
+#### 返回值
+
+返回 `fetchMultilingualData(): Promise<Record<string, string>>` 函数，调用后会：
+
+1. 从多语言中台拉取翻译数据
+2. 将数据存储到 IndexedDB 和全局变量缓存（`window.__MICO_COMMON_INTL_TRANSLATIONS__`）
+3. 返回翻译数据对象
+
+### `i18n(params: II18nParams)`
+
+国际化翻译函数，同步返回翻译后的文案。
+
+#### 参数
+
+| 参数             | 类型                      | 必填 | 说明                                         |
+| ---------------- | ------------------------- | ---- | -------------------------------------------- |
+| `key`            | `string`                  | ✅   | 翻译文案的 key                               |
+| `interpolations` | `Array<string \| number>` | ❌   | 插值数组，按顺序替换 `%AA%`、`%BB%` 等占位符 |
+| `defaultMessage` | `string`                  | ✅   | 兜底文案，当找不到翻译时返回                 |
+
+#### 返回值
+
+返回翻译后的字符串。
+
+### `getCurrentLocale()`
+
+获取当前语言环境，按优先级从高到低：
+
+1. URL 参数 `lang`
+2. localStorage 中的 `umi_locale`
+3. 浏览器默认语言
+
+#### 返回值
+
+返回当前语言类型 `ILang`。
+
+### `setLocaleToStorage(locale: ILang)`
+
+将语言设置保存到 localStorage。
+
+### `LANG`
+
+支持的语言常量对象：
+
+```typescript
+const LANG = {
+  ZH_CN: "zh_CN", // 简体中文
+  EN: "en", // 英语
+  AR: "ar", // 阿拉伯语
+  TR: "tr", // 土耳其语
+} as const;
+```
+
+### `LOCALE`
+
+`LANG` 的别名，用于兼容现有代码。
+
+### `SUPPORTED_LOCALES`
+
+支持的语言列表数组：`['zh_CN', 'en', 'ar', 'tr']`
+
+### 类型定义
+
+```typescript
+// 语言类型
+type ILang = "zh_CN" | "en" | "ar" | "tr";
+
+// TLocale 是 ILang 的别名，用于兼容
+type TLocale = ILang;
+
+// 消息提示实例接口
+interface IMessageInstance {
+  error: (message: string) => unknown;
+  warning: (message: string) => unknown;
+}
+
+// 初始化参数接口
+interface IInitIntlParams {
+  requestInstance: (
+    url: string,
+    options: { method: string; params: Record<string, string> }
+  ) => Promise<{
+    code: number;
+    data?: Record<string, string>;
+    errorMessage?: string;
+  }>;
+  messageInstance: IMessageInstance;
+  fetchMultilingualDataParams: {
+    tag: string;
+    lang: ILang;
+    app_name: string;
+  };
+  indexedDBParams?: {
+    dbName?: string;
+    dbVersion?: number;
+    storeName?: string;
+    keyPathKey?: string;
+  };
+}
+
+// i18n 函数参数接口
+interface II18nParams {
+  key: string;
+  interpolations?: Array<string | number | undefined>;
+  defaultMessage: string;
+}
+```
+
+## 导出清单
+
+| 导出                 | 类型 | 说明                                                      |
+| -------------------- | ---- | --------------------------------------------------------- |
+| `initIntl`           | 函数 | 初始化国际化模块，返回 `fetchMultilingualData` 函数       |
+| `i18n`               | 函数 | 翻译函数，用于获取单条翻译文案                            |
+| `intl`               | 对象 | PC 端主子应用共享的文案对象（仅供 layout 及其子应用使用） |
+| `LANG`               | 常量 | 支持的语言常量：`ZH_CN`、`EN`、`AR`、`TR`                 |
+| `LOCALE`             | 常量 | `LANG` 的别名，用于兼容                                   |
+| `SUPPORTED_LOCALES`  | 常量 | 支持的语言列表数组                                        |
+| `getCurrentLocale`   | 函数 | 获取当前语言环境（按优先级：URL > localStorage > 浏览器） |
+| `setLocaleToStorage` | 函数 | 设置语言到 localStorage                                   |
+| `ILang`              | 类型 | 语言类型定义                                              |
+| `TLocale`            | 类型 | `ILang` 的别名，用于兼容                                  |
+
+## 占位符规则
+
+翻译文案中的占位符使用大写字母对表示：
+
+| 占位符 | 对应 interpolations 索引 |
+| ------ | ------------------------ |
+| `%AA%` | `interpolations[0]`      |
+| `%BB%` | `interpolations[1]`      |
+| `%CC%` | `interpolations[2]`      |
+| ...    | ...                      |
+| `%ZZ%` | `interpolations[25]`     |
+
+### 示例
+
+```typescript
+// 翻译文案: "共 %AA% 条记录，第 %BB% 页"
+i18n({
+  key: "pagination_info",
+  interpolations: [100, 1],
+  defaultMessage: `共 100 条记录，第 1 页`,
+});
+// 输出: "共 100 条记录，第 1 页"
+```
+
+## 缓存策略
+
+1. **内存缓存**：翻译数据首先存储在 `window.__MICO_COMMON_INTL_TRANSLATIONS__` 全局变量中，保证 `i18n()` 函数的同步调用，同时支持微前端主子应用间的数据共享
+2. **IndexedDB 缓存**：同时持久化到 IndexedDB，支持离线访问和页面刷新后的快速加载
+3. **降级处理**：当 IndexedDB 不可用时（如某些 WebView 环境），仅使用内存缓存
+
+## 添加新翻译
+
+1. 在 `src/intl.ts` 中添加新的 key：
+
+```typescript
+const intl = {
+  // ... 其他 keys ...
+
+  // 新增的 key（无参数）
+  cs_web_your_new_key: () =>
+    i18n({
+      key: "cs_web_your_new_key",
+      defaultMessage: "你的新文案",
+    }),
+
+  // 带参数的 key（单个参数）
+  cs_web_your_new_key_aa: (param: string | number) =>
+    i18n({
+      key: "cs_web_your_new_key_aa",
+      interpolations: [param],
+      defaultMessage: `你的新文案 ${param}`,
+    }),
+
+  // 带参数的 key（多个参数）
+  cs_web_your_new_key_multi: (a: string | number, b: string | number) =>
+    i18n({
+      key: "cs_web_your_new_key_multi",
+      interpolations: [a, b],
+      defaultMessage: `参数A: ${a}，参数B: ${b}`,
+    }),
+};
+```
+
+2. 在业务代码中使用：
+
+```typescript
+import { intl } from "@portal-web/common-intl";
+
+// 使用新 key
+intl.cs_web_your_new_key();
+intl.cs_web_your_new_key_aa("参数值");
+intl.cs_web_your_new_key_multi("值A", "值B");
+```
+
+3. 把 key 和兜底文案 defaultMessage 添加到 https://micoworld.feishu.cn/wiki/Ak4pwBl86ixhXyk39bKcgQbknTf?sheet=MzAybi ，并上传到翻译中台
+
+## 开发命令
+
+```bash
+# 开发模式（监听文件变化）
+pnpm dev
+
+# 构建
+pnpm build
+```
+
+## 注意事项
+
+本项目暂时没有独立发包。各个业务应用 （/apps/\*） 通过 pnpm workspace 引入本项目，可参考 [/apps/mico-cs-mobile](../../apps/mico-cs-mobile/package.json)。原因：本项目代码量较少，暂时由各个业务应用各自把本项目打包到产物中，后续有必要时再优化。
+
+1. **不要直接调用 `i18n` 函数**：应通过 `intl.xxx()` 方式调用
+2. **参数类型**：插值参数支持 `string | number | undefined`。无插值时，`interpolations` 参数可以不传
+3. **默认文案**：每个 key 都需要提供 `defaultMessage` 作为后备
+4. **TypeScript 支持**：`intl` 对象有完整的类型提示
+5. **同步调用**：`i18n` 函数是同步的，从全局变量缓存读取数据，因此必须确保在 `fetchMultilingualData()` 完成后才能使用
+6. **离线支持**：即使网络请求失败，也会尝试从 IndexedDB 读取历史缓存，保证基本可用性

package/generators/micro-react/templates/packages/common-intl/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './utils';
+export { LANG as LOCALE, type ILang as TLocale } from './utils';
+export { default as intl } from './intl';