generator-mico-cli 0.2.28 → 0.2.30

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

@@ -1,427 +1,137 @@
 # <%= packageScope %>/common-intl
 
-通用国际化（i18n）库，用于 Portal 多应用间的多语言文案管理。
+本包是 [`@common-web/common-intl`](https://gitlab-vywrajy.micoworld.net/micocenter/mico-portal/portal-center/common-web/-/blob/release/0.0.9/packages/common-intl/README.md) 的项目级封装，提供预配置的 `tag` 绑定和业务文案集中管理。
 
-## 功能特性
+## 微前端模式
 
-- **跨端兼容**：不内置 UI 提示能力，通过外部注入 `messageInstance` 实现跨平台兼容
-- **缓存机制**：支持 IndexedDB 持久化存储 + 内存缓存双重保障
-- **插值替换**：支持 `%AA%`、`%BB%` 等占位符的动态替换
-- **降级处理**：当翻译 key 不存在时，自动返回兜底文案
-- **环境感知**：自动根据 `NODE_ENV` 切换开发/生产 API 地址
-- **微前端共享**：主应用获取的文案数据自动共享给所有子应用
-
-## 安装
-
-在 monorepo 项目中，通过 workspace 引用：
+在 qiankun 微前端架构中，**主应用负责获取文案**，子应用直接使用共享的文案对象，无需重复初始化。
 
-```json
-{
-  "dependencies": {
-    "<%= packageScope %>/common-intl": "workspace:*"
-  }
-}
+```
+┌─────────────────────────────────────────────────────────┐
+│                  apps/layout（主应用）                     │
+│  initIntl() 绑定 tag → render() 中 fetchMultilingualData │
+│  → 文案存储到 window.__MICO_COMMON_INTL_TRANSLATIONS__    │
+└─────────────────────────────────────────────────────────┘
+                            ↓
+      ┌─────────────────────┼─────────────────────┐
+      ↓                     ↓                     ↓
+┌───────────┐         ┌───────────┐         ┌───────────┐
+│  子应用 A  │         │  子应用 B  │         │  子应用 C  │
+│ import {  │         │ import {  │         │ import {  │
+│   intl    │         │   intl    │         │   intl    │
+│ }         │         │ }         │         │ }         │
+│ 直接使用   │         │ 直接使用   │         │ 直接使用   │
+└───────────┘         └───────────┘         └───────────┘
 ```
 
-## 两种使用模式
-
-根据应用架构的不同，`<%= packageScope %>/common-intl` 支持两种使用模式：
-
-| 模式         | 适用场景                                         | 示例应用                                                     |
-| ------------ | ------------------------------------------------ | ------------------------------------------------------------ |
-| 微前端模式   | qiankun 主子应用架构，主应用获取文案后子应用共享 | layout、conversation-v2、session、workorder、faq、permission |
-| 独立应用模式 | 独立运行的应用，自己获取和管理文案               | mico-cs-mobile                                               |
-
-### 微前端模式
-
-在 qiankun 微前端架构中，**主应用负责获取文案**，子应用直接使用共享的文案对象，无需重复初始化。
-
-**工作原理**：
+## 快速开始
 
-- 主应用调用 `initIntl()` 获取远程文案
-- 文案数据存储到 `window.__MICO_COMMON_INTL_TRANSLATIONS__`
-- 子应用直接使用 `intl` 对象，自动从 window 读取共享数据
+### 1. 配置 tag
 
-**主应用配置**（参考 `apps/layout/src/app.tsx`）：
+在 `src/intl.ts` 中修改 `tag` 为你的多语言中台标签：
 
 ```typescript
-import {
-  getCurrentLocale,
-  initIntl,
-  type ILang,
-} from "<%= packageScope %>/common-intl";
-import { Message } from "@mico-platform/ui";
-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",
-  },
+const { fetchMultilingualData, i18n } = initIntl({
+  tag: 'your_tag',   // 替换为多语言中台的标签
+  app_name: 'middle',
+  indexedDBParams: { dbName: 'mico_i18n_db' },
 });
-
-// 在应用渲染前加载多语言数据
-export function render(oldRender: () => void): void {
-  fetchMultilingualData()
-    .then(oldRender)
-    .catch((error: Error) => {
-      console.error("获取多语言文案失败", error);
-      oldRender(); // 失败时继续渲染，使用兜底文案
-    });
-}
 ```
 
-**子应用使用**（无需初始化）：
+### 2. 主应用接入
 
-```typescript
-// apps/conversation-v2、apps/session、apps/workorder 等子应用
-import { intl } from "<%= packageScope %>/common-intl";
-
-// 直接使用，文案来自主应用
-<h1>{intl.cs_web_workbench_conversation_record()}</h1>;
-```
-
-### 独立应用模式
-
-对于非 qiankun 架构的独立应用（如 H5 应用），需要自己调用 `initIntl()` 获取文案，并维护独立的文案文件。
-
-**独立应用配置**（参考 `apps/mico-cs-mobile/src/app.ts`）：
+主应用（`apps/layout`）在 `app.tsx` 的 `render` 函数中调用 `fetchMultilingualData`，确保渲染前完成多语言数据加载：
 
 ```typescript
-import { initIntl } from "<%= packageScope %>/common-intl";
-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) => console.error(msg),
-    warning: (msg: string) => console.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',
-  },
-});
+import { fetchMultilingualData, getCurrentLocale, type ILang } from '<%= packageScope %>/common-intl';
 
-// 在应用渲染前加载多语言数据
-// 如果是基于 umi 的项目，可以在 app.tsx 的 render 函数中调用加载函数 https://umijs.org/docs/api/runtime-config#render
 export function render(oldRender: () => void): void {
-  fetchMultilingualData()
+  fetchMultilingualData({
+    requestInstance: commonRequest,
+    messageInstance: {
+      error: micoUI.Message.error,
+      warning: micoUI.Message.warning,
+    },
+    lang: getCurrentLocale() as ILang,
+    localeRequestUrl: process.env.LOCALE_REQUEST_URL,
+  })
     .then(oldRender)
     .catch((error: Error) => {
       console.error('获取多语言文案失败', error);
-      // 即使失败也继续渲染，使用兜底文案
       oldRender();
     });
 }
 ```
 
-**独立应用的文案文件**（`apps/mico-cs-mobile/src/locales/index.ts`）：集中管理所有国际化文案
-
-```typescript
-import { i18n } from "<%= packageScope %>/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` 函数。
+### 3. 添加文案
 
-#### 参数
-
-| 参数                                   | 类型               | 必填 | 说明                                         |
-| -------------------------------------- | ------------------ | ---- | -------------------------------------------- |
-| `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`
-
-支持的语言常量对象：
+在 `src/intl.ts` 中添加新的翻译 key：
 
 ```typescript
-const LANG = {
-  ZH_CN: "zh_CN", // 简体中文
-  EN: "en", // 英语
-  AR: "ar", // 阿拉伯语
-  TR: "tr", // 土耳其语
-} as const;
+const intl = addIntl({
+  common_hello: () =>
+    i18n({ key: 'common_hello', defaultMessage: '你好' }),
+  // 添加新文案...
+}, i18n);
 ```
 
-### `LOCALE`
-
-`LANG` 的别名，用于兼容现有代码。
+## 子应用使用
 
-### `SUPPORTED_LOCALES`
+### 默认模式：共享主应用文案
 
-支持的语言列表数组：`['zh_CN', 'en', 'ar', 'tr']`
-
-### 类型定义
+子应用默认与主应用共享同一个 `tag`，直接导入即可使用，**无需调用 `initIntl`**：
 
 ```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;
-  };
-}
+import { intl } from '<%= packageScope %>/common-intl';
 
-// i18n 函数参数接口
-interface II18nParams {
-  key: string;
-  interpolations?: Array<string | number | undefined>;
-  defaultMessage: string;
-}
+intl.common_hello();
 ```
 
-## 导出清单
-
-| 导出                 | 类型 | 说明                                                      |
-| -------------------- | ---- | --------------------------------------------------------- |
-| `initIntl`           | 函数 | 初始化国际化模块，返回 `fetchMultilingualData` 函数       |
-| `i18n`               | 函数 | 翻译函数，用于获取单条翻译文案                            |
-| `intl`               | 对象 | PC 端主子应用共享的文案对象（仅供 layout 及其子应用使用） |
-| `LANG`               | 常量 | 支持的语言常量：`ZH_CN`、`EN`、`AR`、`TR`                 |
-| `LOCALE`             | 常量 | `LANG` 的别名，用于兼容                                   |
-| `SUPPORTED_LOCALES`  | 常量 | 支持的语言列表数组                                        |
-| `getCurrentLocale`   | 函数 | 获取当前语言环境（按优先级：URL > localStorage > 浏览器） |
-| `setLocaleToStorage` | 函数 | 设置语言到 localStorage                                   |
-| `ILang`              | 类型 | 语言类型定义                                              |
-| `TLocale`            | 类型 | `ILang` 的别名，用于兼容                                  |
-
-## 占位符规则
-
-翻译文案中的占位符使用大写字母对表示：
+主应用通过 `window` 暴露 `<%= packageScope %>/common-intl`，子应用通过 `externals` 复用，不会重复打包。
 
-| 占位符 | 对应 interpolations 索引 |
-| ------ | ------------------------ |
-| `%AA%` | `interpolations[0]`      |
-| `%BB%` | `interpolations[1]`      |
-| `%CC%` | `interpolations[2]`      |
-| ...    | ...                      |
-| `%ZZ%` | `interpolations[25]`     |
+### 独立 tag 模式
 
-### 示例
+如果子应用需要使用**独立的多语言标签**（例如子应用有自己的多语言文案），直接依赖 `@common-web/common-intl`，在子应用内自行调用 `initIntl`，不需要经过本中转包：
 
 ```typescript
-// 翻译文案: "共 %AA% 条记录，第 %BB% 页"
-i18n({
-  key: "pagination_info",
-  interpolations: [100, 1],
-  defaultMessage: `共 100 条记录，第 1 页`,
+// apps/my-subapp/src/locales/index.ts
+import { initIntl, addIntl } from '@common-web/common-intl';
+
+const { fetchMultilingualData, i18n } = initIntl({
+  tag: 'my_subapp_tag',
+  app_name: 'middle',
+  indexedDBParams: { dbName: 'my_subapp_i18n_db' },
 });
-// 输出: "共 100 条记录，第 1 页"
-```
 
-## 缓存策略
+export { fetchMultilingualData };
 
-1. **内存缓存**：翻译数据首先存储在 `window.__MICO_COMMON_INTL_TRANSLATIONS__` 全局变量中，保证 `i18n()` 函数的同步调用，同时支持微前端主子应用间的数据共享
-2. **IndexedDB 缓存**：同时持久化到 IndexedDB，支持离线访问和页面刷新后的快速加载
-3. **降级处理**：当 IndexedDB 不可用时（如某些 WebView 环境），仅使用内存缓存
+const intl = addIntl({
+  my_key: () => i18n({ key: 'my_key', defaultMessage: '我的文案' }),
+}, i18n);
 
-## 添加新翻译
+export default intl;
+```
 
-1. 在 `src/intl.ts` 中添加新的 key：
+> **注意：** 子应用使用独立 tag 模式时，必须移除子应用 config 文件中 `externals` 里的 `'<%= packageScope %>/common-intl': 'CommonIntl'` 配置，确保子应用打包自己的 `@common-web/common-intl` 副本，避免与主应用共享模块级状态。
 
-```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}`,
-    }),
-};
-```
+> `initIntl` 只管身份配置（tag、app_name、存储），`fetchMultilingualData` 管运行时依赖（请求实例、消息提示、语言、API 地址）。`i18n` 函数与 `tag` 绑定，不同 tag 的翻译数据互相隔离。
 
-2. 在业务代码中使用：
+## 常见问题
 
-```typescript
-import { intl } from "<%= packageScope %>/common-intl";
+### Q: 子应用需要调用 initIntl 吗？
 
-// 使用新 key
-intl.cs_web_your_new_key();
-intl.cs_web_your_new_key_aa("参数值");
-intl.cs_web_your_new_key_multi("值A", "值B");
-```
+默认不需要。主应用负责初始化和获取文案，子应用直接使用共享的 `intl` 对象。**仅当子应用需要与主应用不同的 tag** 时，再在子应用内**额外**调用一次 `initIntl`（可从本包 `import { initIntl } from '<%= packageScope %>/common-intl'`），并自行 `render` 拉取。
 
-3. 把 key 和兜底文案 defaultMessage 添加到 https://micoworld.feishu.cn/wiki/Ak4pwBl86ixhXyk39bKcgQbknTf?sheet=MzAybi ，并上传到翻译中台
+### Q: 翻译数据什么时候加载？
 
-## 开发命令
+在 UmiJS 的 `render` 钩子中调用 `fetchMultilingualData()`，确保在应用渲染前完成加载。
 
-```bash
-# 开发模式（监听文件变化）
-pnpm dev
+### Q: 如何添加新的翻译文案？
 
-# 构建
-pnpm build
-```
+在 `src/intl.ts` 中添加对应的函数，然后在代码中通过 `intl.xxx()` 调用。
 
-## 注意事项
+## 完整文档
 
-本项目暂时没有独立发包。各个业务应用 （/apps/\*） 通过 pnpm workspace 引入本项目，可参考 [/apps/mico-cs-mobile](../../apps/mico-cs-mobile/package.json)。原因：本项目代码量较少，暂时由各个业务应用各自把本项目打包到产物中，后续有必要时再优化。
+关于 `initIntl`、`fetchMultilingualData`、`i18n`、`addIntl` 的详细 API、类型定义、缓存策略、占位符规则等，请参阅：
 
-1. **不要直接调用 `i18n` 函数**：应通过 `intl.xxx()` 方式调用
-2. **参数类型**：插值参数支持 `string | number | undefined`。无插值时，`interpolations` 参数可以不传
-3. **默认文案**：每个 key 都需要提供 `defaultMessage` 作为后备
-4. **TypeScript 支持**：`intl` 对象有完整的类型提示
-5. **同步调用**：`i18n` 函数是同步的，从全局变量缓存读取数据，因此必须确保在 `fetchMultilingualData()` 完成后才能使用
-6. **离线支持**：即使网络请求失败，也会尝试从 IndexedDB 读取历史缓存，保证基本可用性
+**[@common-web/common-intl README](https://gitlab-vywrajy.micoworld.net/micocenter/mico-portal/portal-center/common-web/-/blob/release/0.0.9/packages/common-intl/README.md)**

package/generators/micro-react/templates/packages/common-intl/package.json

@@ -1,11 +1,8 @@
 {
   "name": "<%= packageScope %>/common-intl",
   "version": "0.0.1",
-  "description": "Portal common internationalization library",
+  "description": "通用国际化库 - re-exports @common-web/common-intl 并提供项目级文案",
   "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": "./src/index.ts",
@@ -13,17 +10,10 @@
     }
   },
   "files": [
-    "dist",
     "src"
   ],
-  "scripts": {
-    "dev": "vite build --watch",
-    "build": "vite build && tsc --emitDeclarationOnly"
-  },
-  "devDependencies": {
-    "typescript": "^5.8.3",
-    "vite": "^7.2.4",
-    "vite-plugin-dts": "^4.5.4"
+  "dependencies": {
+    "@common-web/common-intl": "0.3.1"
   },
   "keywords": [
     "i18n",

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

@@ -1,7 +1,6 @@
-export * from './utils';
+// 上游全量导出（含 initIntl、addIntl 等）；子应用需与主应用不同 tag 时可再次 initIntl，见 README「不同 tag」
+export * from '@common-web/common-intl';
 
-// LOCALE/TLocale 别名（为兼容现有代码）
-export { LANG as LOCALE, type ILang as TLocale } from './utils';
-
-// 导出 intl 对象
-export { default as intl } from './intl';
+// 默认 intl、fetchMultilingualData、i18n（均绑定 intl.ts 中的默认 tag）；主/子应用入口可 configureLocale
+export type { LocaleBridge } from './intl';
+export { configureLocale, default as intl, fetchMultilingualData, i18n } from './intl';