generator-mico-cli 0.2.29 → 0.2.31

package/generators/subapp-react/index.js

@@ -168,6 +168,8 @@ module.exports = class extends Generator {
       const templateData = {
         appName: this.appName,
         AppName: this.appNamePascal,
+        // 用于 MFSU mfName 等需要合法 JS 标识符的场景（不允许 `-`）
+        appNameSnake: this.appName.replace(/-/g, '_'),
         packageScope: this.packageScope,
         devPort: this.devPort,
         micoUiVersion: `^${micoUiVer}`,

package/generators/subapp-react/templates/homepage/README.md

@@ -64,7 +64,7 @@ PORT=8001
 │   ├── app.tsx              # Umi 运行时配置
 │   ├── assets/              # 静态资源
 │   ├── common/              # 公共模块
-│   │   ├── logger.ts        # 日志工具
+│   │   ├── logger.ts        # 日志工具（与 layout 一致：生产首屏 `?debug=1` 可开全量 log/info/warn）
 │   │   ├── mainApp.ts       # 主应用通信
 │   │   └── request.ts       # 请求封装
 │   ├── pages/               # 页面组件
@@ -75,6 +75,10 @@ PORT=8001
 └── tsconfig.json
 ```
 
+## 日志（logger）
+
+与 monorepo 内 **layout** 的 `src/common/logger.ts` 规则对齐：生产默认静默 `log`/`info`/`warn`，`error` 仍输出；首屏 URL 带 **`?debug=1`**（或 `debug=true` / `yes`）可在模块加载时打开全量日志。详见主应用文档 `apps/layout/docs/arch-日志与常量.md`（生成项目后路径以仓库为准）。
+
 ## 微前端配置
 
 本应用作为 qiankun 子应用运行，关键配置：

package/generators/subapp-react/templates/homepage/config/config.dev.ts

@@ -61,6 +61,26 @@ const config: ReturnType<typeof defineConfig> = {
     // @mico-platform/ui 基础样式（使用运行时解析的最新版本号，避免 latest 标签）
     `https://cdn-portal.micoplatform.com/portal-center/mico-ui/${MICO_UI_VERSION}/ui/dist/css/mico-ui.min.css`,
   ],
+
+  /**
+   * @name MFSU 配置
+   * @description
+   * - mfName: 唯一名隔离微前端 runtime，避免多应用共存时 MFSU 容器冲突
+   * - exclude:
+   *   - `@mico-platform/theme`：theme 子路径解析
+   *   - `@mico-platform/ui`：尽量与主应用一起编译
+   *   - `<%= packageScope %>/*`：workspace 包走 webpack 编译，开发态可在 DevTools 直接定位到 packages/* 源码
+   * - shared: React 单例，确保 MFSU 预打包里的组件（如 UI 库）与应用共用同一份 React，否则 useContext 报 null
+   * @doc https://umijs.org/docs/api/config#mfsu
+   */
+  mfsu: {
+    mfName: 'mf_<%= appNameSnake %>',
+    exclude: ['@mico-platform/theme', '@mico-platform/ui', /^<%= packageScope %>\//],
+    shared: {
+      react: { singleton: true },
+      'react-dom': { singleton: true },
+    },
+  },
 };
 
 export default defineConfig(config);

package/generators/subapp-react/templates/homepage/config/config.ts

@@ -76,6 +76,16 @@ const config: ReturnType<typeof defineConfig> = {
    */
   layout: false,
 
+  /**
+   * @name 国际化插件（与 layout 一致；intl 未命中 key 时读 src/locales）
+   * @doc https://umijs.org/docs/max/i18n
+   */
+  locale: {
+    default: 'zh-CN',
+    antd: false,
+    baseNavigator: false,
+  },
+
   /**
    * @name 其他配置
    */
@@ -108,21 +118,6 @@ const config: ReturnType<typeof defineConfig> = {
    * @description 使用 @mico-platform/ui 的 babel preset，实现组件与图标的按需加载
    */
   extraBabelPresets: ['@mico-platform/ui/babel-preset'],
-
-  /**
-   * @name MFSU 配置
-   * @description
-   * - exclude: theme 子路径解析；ui 尽量与主应用一起编译
-   * - shared: React 单例，确保 MFSU 预打包里的组件（如 UI 库）与应用共用同一份 React，否则 useContext 报 null
-   * @doc https://umijs.org/docs/guides/mfsu
-   */
-  mfsu: {
-    exclude: ['@mico-platform/theme', '@mico-platform/ui'],
-    shared: {
-      react: { singleton: true },
-      'react-dom': { singleton: true },
-    },
-  },
 };
 
 export default defineConfig(config);

package/generators/subapp-react/templates/homepage/docs/feature-/345/233/275/351/231/205/345/214/226.md

@@ -0,0 +1,124 @@
+# 国际化（common-intl 与 Umi 兜底）
+
+> 创建时间：2026-04-07
+
+## 功能概述
+
+子应用通过 **`<%= packageScope %>/common-intl`**（生产环境常与主应用 **externals 共享**）拉取中台文案；**未命中 key** 时回落到 **Umi `src/locales`**。可选在工程内配置 **独立 `initIntl`**（独立 tag / IndexedDB），与主应用默认实例隔离。语言与主应用对齐：qiankun 下优先主应用注入的 `locale`，否则与 layout 相同的 URL / `umi_locale` / 浏览器规则（见 `getSubappCurrentLocale`）。
+
+## 技术方案
+
+### 技术栈
+
+- Umi Max `locale` 插件 + `src/locales/zh-CN.ts`、`en-US.ts`
+- `<%= packageScope %>/common-intl`：`configureLocale`、`i18n`、`fetchMultilingualData`、`initIntl`（独立实例时）
+- 统一入口：`useSubappIntl`（合并逻辑对齐主应用 `useLayoutIntl`）
+
+### 核心实现
+
+1. **`app.tsx`**：最早调用 `configureLocale`，使包内 `getLocale`/`setLocale` 与 `getSubappCurrentLocale` 一致；导出 Umi 运行时 `locale.getLocale`；在 `render` 中按条件调用中台 `fetchMultilingualData`（默认 tag 与可选的独立 intl 实例并行）。
+2. **`useSubappIntl`**：若 `subappIntlConfig` 有效则优先 **独立实例** `i18n`；否则在未启用中台时仅用 Umi，启用时优先包内 **`i18n`**；与 `defaultMessage` 比较后决定是否采用 Umi 译文。
+3. **`subappIntlConfig.ts`**：默认返回 `undefined`；返回含 **`tag`、`app_name`** 的对象即启用独立 intl（见 `subappOwnIntl.ts` 内 `initIntl`）。
+
+## 文件清单
+
+### 新增 / 模块目录
+
+| 文件路径 | 说明 |
+| --- | --- |
+| `src/common/intl/subappIntlConfig.ts` | 独立 intl 配置入口 `getSubappIntlInitOptions()` |
+| `src/common/intl/subappOwnIntl.ts` | 条件 `initIntl`、独立 `fetchMultilingualData` |
+| `src/common/intl/useSubappIntl.ts` | 页面统一 Hook |
+| `src/common/intl/intlRuntime.ts` | `isCommonIntlEnabled`（`window.__MICO_CONFIG__.intl` / `commonIntl`） |
+| `src/common/intl/types.ts` | `IMicoConfigCommonIntl` |
+| `src/common/intl/index.ts` | 对外导出 |
+| `src/common/intl/localeMapping.ts` | Umi locale ↔ `ILang`（模板已存在） |
+| `src/common/intl/subappLocale.ts` | 当前 Umi 风格 locale（模板已存在） |
+| `src/locales/zh-CN.ts` | Umi 兜底文案 |
+| `src/locales/en-US.ts` | Umi 兜底文案 |
+
+### 修改
+
+| 文件路径 | 说明 |
+| --- | --- |
+| `config/config.ts` | 开启 `locale` 插件 |
+| `src/app.tsx` | `configureLocale`、`export const locale`、`render` 预拉取 |
+| `src/pages/index.tsx` | 国际化示例区（可选参考） |
+| `typings.d.ts` | `__MICO_CONFIG__.intl` / `commonIntl` 类型 |
+
+## API / 组件接口
+
+### `useSubappIntl`
+
+```typescript
+const {
+  formatMessage,       // 与 layout useLayoutIntl 相同签名
+  commonIntlEnabled,   // 是否启用中台（有效 tag + app_name）
+  locale,              // 当前 Umi 风格 locale 字符串
+  subappOwnIntl,       // 是否启用子应用独立 initIntl
+  subappOwnIntlTag,    // 独立 tag（未启用时为 undefined）
+} = useSubappIntl();
+```
+
+**参数说明**：无入参；`formatMessage` 第二参数为插值对象，与 `useIntl().formatMessage` 一致。
+
+### `getSubappIntlInitOptions`
+
+返回 `undefined` 表示使用包默认实例；返回 `ISubappIntlInitOptions` 时需至少包含 **`tag`**、**`app_name`**，可选 **`indexedDBParams`**（与 `packages/common-intl` README 一致）。
+
+## 使用示例
+
+```tsx
+import { useSubappIntl } from '@/common/intl';
+
+export default function Page() {
+  const { formatMessage, commonIntlEnabled, locale, subappOwnIntl, subappOwnIntlTag } =
+    useSubappIntl();
+
+  return (
+    <p>
+      {formatMessage(
+        { id: 'page.subapp.home.title', defaultMessage: '标题' },
+      )}
+    </p>
+  );
+}
+```
+
+独立 intl（节选，`subappIntlConfig.ts`）：
+
+```typescript
+export function getSubappIntlInitOptions() {
+  return {
+    tag: 'my_subapp_tag',
+    app_name: 'middle',
+    indexedDBParams: { dbName: 'my_subapp_i18n_db' },
+  };
+}
+```
+
+启用独立 tag 且生产仍使用 `externals` 指向主应用 `CommonIntl` 时，需评估与上游 **多实例 / 单例** 语义是否冲突，详见 **`generators/micro-react/templates/packages/common-intl/README.md`**「不同 tag」。
+
+## 设计决策
+
+| 决策点 | 选择 | 理由 |
+| --- | --- | --- |
+| 统一 Hook | `useSubappIntl` 对齐 `useLayoutIntl` | 与主应用行为一致，intl 与 Umi 兜底规则可维护 |
+| 独立 intl 配置 | 单一入口 `getSubappIntlInitOptions` | 默认关闭，按需开启，避免误初始化 |
+| 预拉取 | `render` 内并行 fetch 默认 tag + 独立实例 | 首屏前尽量拉齐中台数据，失败仍渲染 |
+
+## 已知限制与待改进
+
+- 独立 intl 与 **externals 共享同一 `common-intl` 运行时** 时的边界行为以 **上游包** 为准；若需完全隔离，可能需调整打包策略（见 common-intl README）。
+- `LOCALE_REQUEST_URL` 未配置时，行为依赖上游 `fetchMultilingualData` 实现。
+
+## 注意事项
+
+- 主应用通过 qiankun 注入的 **`locale`** 会参与 `getSubappCurrentLocale`；独立运行依赖本地存储与 URL。
+- 中台未配置时 **`commonIntlEnabled`** 为 `false`，页面仅走 Umi `locales`。
+
+## 相关文档
+
+- [packages/common-intl README](../../../../micro-react/templates/packages/common-intl/README.md)
+- [子应用国际化（CLI 仓库总览）](../../../../../docs/feat-subapp-国际化翻译.md)
+- [Layout 国际化](../../../../../docs/feat-layout-国际化翻译.md)

package/generators/subapp-react/templates/homepage/package.json

@@ -20,7 +20,8 @@
     "@umijs/max": "^4.4.8",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "<%= packageScope %>/common-intl": "workspace:*"
+    "<%= packageScope %>/common-intl": "workspace:*",
+    "<%= packageScope %>/shared": "workspace:*"
   },
   "devDependencies": {
     "@mico-platform/ui": "<%= micoUiVersion %>",

package/generators/subapp-react/templates/homepage/src/app.tsx

@@ -7,18 +7,113 @@
  * 自定义函数请放在 @/common/mainApp.ts 中
  *
  * 国际化使用：
- * 子应用默认共享主应用的 intl，直接导入即可：
+ * 子应用默认共享主应用的 intl（同 tag），直接导入即可：
  *   import { intl } from '<%= packageScope %>/common-intl';
  *   intl.common_hello();
- * 如需独立 tag，直接依赖 @common-web/common-intl 自行调用 initIntl，
- * 参考 packages/common-intl/README.md
+ * 独立 intl：在 `src/common/intl/subappIntlConfig.ts` 填写 `getSubappIntlInitOptions()`；
+ * 页面统一用 `useSubappIntl`（intl 优先，未命中走子应用 Umi locales）。
+ *
+ * common-intl 的 getLocale/setLocale 与 Umi locale / 主应用 props.locale 对齐：入口调用 configureLocale（见下）。
  */
 
-import React from 'react';
+import {
+  configureLocale,
+  fetchMultilingualData,
+  type ILang,
+} from '<%= packageScope %>/common-intl';
+import { Message } from '@mico-platform/ui';
+import type { ReactNode } from 'react';
 import { history } from '@umijs/max';
 import { SentryErrorBoundary } from '@common-web/sentry';
 import { appLogger } from './common/logger';
+import { configureRequest } from '<%= packageScope %>/shared/services';
 import { type IMicroAppProps, setMainAppProps } from './common/mainApp';
+import { request } from './common/request';
+import { setLocaleToStorage } from './common/locale';
+import {
+  getSubappOwnFetchMultilingualData,
+  ilangToUmiLocale,
+  isCommonIntlEnabled,
+  umiLocaleToILang,
+} from './common/intl';
+import { getSubappCurrentLocale } from './common/intl/subappLocale';
+
+// 子应用：将本地 request（自动桥接主应用 / 独立 umi）注入 shared 包，供共享服务层（getRequest）使用
+// 注意：模块顶层注入，request 函数引用稳定；运行期由 request 内部根据是否处于 qiankun 选用 main / umi
+configureRequest(request as <T = unknown>(url: string, options?: Record<string, unknown>) => Promise<T>);
+
+// 子应用：common-intl initIntl 与 Umi `umi_locale` / 主应用注入 locale 对齐（与 layout app.tsx 同理）
+configureLocale({
+  getLocale: () => umiLocaleToILang(getSubappCurrentLocale()),
+  setLocale: (lang: ILang) => {
+    setLocaleToStorage(ilangToUmiLocale(lang));
+  },
+});
+
+/**
+ * @name 运行时国际化（Umi locale 插件）
+ * @see https://umijs.org/docs/max/i18n#%E8%BF%90%E8%A1%8C%E6%97%B6%E9%85%8D%E7%BD%AE
+ */
+export const locale = {
+  getLocale() {
+    return getSubappCurrentLocale();
+  },
+};
+
+/**
+ * 中台文案预加载：默认 tag 与（可选）子应用独立 intl tag 并行拉取，失败仍渲染。
+ * @see generators/micro-react/templates/apps/layout/src/app.tsx render
+ */
+export function render(oldRender: () => void): void {
+  const ownFetch = getSubappOwnFetchMultilingualData();
+  const tasks: Promise<unknown>[] = [];
+
+  if (isCommonIntlEnabled()) {
+    tasks.push(
+      fetchMultilingualData({
+        requestInstance: request as (
+          url: string,
+          options?: unknown,
+        ) => Promise<unknown>,
+        messageInstance: {
+          error: Message.error,
+          warning: Message.warning,
+        },
+        lang: umiLocaleToILang(getSubappCurrentLocale()) as ILang,
+        localeRequestUrl: process.env.LOCALE_REQUEST_URL,
+      }),
+    );
+  }
+
+  if (ownFetch) {
+    tasks.push(
+      ownFetch({
+        requestInstance: request as (
+          url: string,
+          options?: unknown,
+        ) => Promise<unknown>,
+        messageInstance: {
+          error: Message.error,
+          warning: Message.warning,
+        },
+        lang: umiLocaleToILang(getSubappCurrentLocale()) as ILang,
+        localeRequestUrl: process.env.LOCALE_REQUEST_URL,
+      }),
+    );
+  }
+
+  if (tasks.length === 0) {
+    oldRender();
+    return;
+  }
+
+  Promise.all(tasks)
+    .then(() => oldRender())
+    .catch((error: Error) => {
+      console.error('获取多语言文案失败', error);
+      oldRender();
+    });
+}
 
 /** 与 layout parser.findRouteByPath 一致：根路径 "/" 保持不变 */
 function stripTrailingSlash(path: string): string {
@@ -110,6 +205,6 @@ export async function getInitialState() {
   };
 }
 
-export function rootContainer(container: React.ReactNode) {
+export function rootContainer(container: ReactNode) {
   return <SentryErrorBoundary>{container}</SentryErrorBoundary>;
 }

package/generators/subapp-react/templates/homepage/src/common/intl/index.ts

@@ -0,0 +1,15 @@
+export { isCommonIntlEnabled, getCommonIntlConfig } from './intlRuntime';
+export type { IMicoConfigCommonIntl } from './types';
+export {
+  getSubappIntlInitOptions,
+  type ISubappIntlInitOptions,
+} from './subappIntlConfig';
+export {
+  getSubappOwnFetchMultilingualData,
+  getSubappOwnI18n,
+  getSubappOwnIntlTag,
+  isSubappOwnIntlEnabled,
+} from './subappOwnIntl';
+export { useSubappIntl } from './useSubappIntl';
+export { ilangToUmiLocale, umiLocaleToILang } from './localeMapping';
+export { getSubappCurrentLocale } from './subappLocale';

package/generators/subapp-react/templates/homepage/src/common/intl/intlRuntime.ts

@@ -0,0 +1,14 @@
+import type { IMicoConfigCommonIntl } from './types';
+
+/**
+ * 是否启用多语言中台拉取：以 __MICO_CONFIG__.intl 或 commonIntl 含有效 tag、app_name 为准
+ */
+export function isCommonIntlEnabled(): boolean {
+  const c = getCommonIntlConfig();
+  return !!(c?.tag && c?.app_name);
+}
+
+export function getCommonIntlConfig(): IMicoConfigCommonIntl | undefined {
+  const w = window.__MICO_CONFIG__;
+  return w?.intl ?? w?.commonIntl;
+}

package/generators/subapp-react/templates/homepage/src/common/intl/localeMapping.ts

@@ -0,0 +1,24 @@
+import { LANG, type ILang } from '<%= packageScope %>/common-intl';
+import type { SupportedLocale } from '@/common/locale';
+import { LOCALE } from '@/common/locale';
+
+/** 与 packages/common-intl/src/umiLocaleBridge.ts、layout localeMapping 保持一致 */
+const UMI_TO_ILANG: Record<SupportedLocale, ILang> = {
+  [LOCALE.ZH_CN]: LANG.ZH_CN,
+  [LOCALE.EN_US]: LANG.EN,
+};
+
+export function umiLocaleToILang(locale: SupportedLocale): ILang {
+  return UMI_TO_ILANG[locale] ?? LANG.EN;
+}
+
+const ILANG_TO_UMI: Partial<Record<ILang, SupportedLocale>> = {
+  [LANG.ZH_CN]: LOCALE.ZH_CN,
+  [LANG.EN]: LOCALE.EN_US,
+  [LANG.AR]: LOCALE.EN_US,
+  [LANG.TR]: LOCALE.EN_US,
+};
+
+export function ilangToUmiLocale(lang: ILang): SupportedLocale {
+  return ILANG_TO_UMI[lang] ?? LOCALE.EN_US;
+}

package/generators/subapp-react/templates/homepage/src/common/intl/subappIntlConfig.ts

@@ -0,0 +1,28 @@
+/**
+ * 子应用独立 intl（与主应用不同 tag / 独立 IndexedDB）时，在此返回 initIntl 参数。
+ * 默认 `undefined`：使用 <%= packageScope %>/common-intl 包内默认实例（与主应用 externals 共享）。
+ *
+ * 启用方式：返回含有效 `tag`、`app_name` 的对象（与 packages/common-intl README 一致）。
+ */
+export interface ISubappIntlInitOptions {
+  tag: string;
+  app_name: string;
+  indexedDBParams?: {
+    dbName?: string;
+    dbVersion?: number;
+    storeName?: string;
+    keyPathKey?: string;
+  };
+}
+
+export function getSubappIntlInitOptions():
+  | ISubappIntlInitOptions
+  | undefined {
+  return undefined;
+  // 如果需要启用独立 intl，请取消注释并修改 tag 和 app_name
+  // return {
+  //   tag: 'cs_fe_mobile',
+  //   app_name: 'middle',
+  //   indexedDBParams: { dbName: 'mico_cs_mobile_i18n_db' },
+  // };
+}

package/generators/subapp-react/templates/homepage/src/common/intl/subappLocale.ts

@@ -0,0 +1,18 @@
+import { getCurrentLocale, type SupportedLocale, SUPPORTED_LOCALES } from '@/common/locale';
+import { getMainAppProps } from '@/common/mainApp';
+
+function isSupportedLocale(value: string | undefined): value is SupportedLocale {
+  return !!value && (SUPPORTED_LOCALES as readonly string[]).includes(value);
+}
+
+/**
+ * 子应用当前 Umi 风格 locale：qiankun 下优先主应用 MicroAppLoader 注入的 `locale`，
+ * 否则与主应用相同规则（URL / umi_locale / 浏览器）。
+ */
+export function getSubappCurrentLocale(): SupportedLocale {
+  const fromMain = getMainAppProps()?.locale;
+  if (isSupportedLocale(fromMain)) {
+    return fromMain;
+  }
+  return getCurrentLocale();
+}

package/generators/subapp-react/templates/homepage/src/common/intl/subappOwnIntl.ts

@@ -0,0 +1,63 @@
+import { initIntl, type ILang } from '<%= packageScope %>/common-intl';
+import { setLocaleToStorage } from '@/common/locale';
+import { getSubappIntlInitOptions } from './subappIntlConfig';
+import { ilangToUmiLocale, umiLocaleToILang } from './localeMapping';
+import { getSubappCurrentLocale } from './subappLocale';
+
+type TI18nFn = (opts: {
+  key: string;
+  defaultMessage: string;
+  interpolations?: (string | number | boolean)[];
+}) => string;
+
+type TFetchFn = (params: {
+  requestInstance: (url: string, options?: unknown) => Promise<unknown>;
+  messageInstance: { error: (msg: string) => void; warning: (msg: string) => void };
+  lang: ILang;
+  localeRequestUrl?: string;
+}) => Promise<unknown>;
+
+function createSubappOwnIntl(): {
+  i18nFn: TI18nFn | null;
+  fetchFn: TFetchFn | null;
+  tag: string | undefined;
+} {
+  const opts = getSubappIntlInitOptions();
+  if (!opts?.tag || !opts.app_name) {
+    return { i18nFn: null, fetchFn: null, tag: undefined };
+  }
+
+  const { fetchMultilingualData, i18n } = initIntl({
+    ...opts,
+    getLocale: () => umiLocaleToILang(getSubappCurrentLocale()),
+    setLocale: (lang: ILang) => {
+      setLocaleToStorage(ilangToUmiLocale(lang));
+    },
+  });
+
+  return {
+    i18nFn: i18n as TI18nFn,
+    fetchFn: fetchMultilingualData as TFetchFn,
+    tag: opts.tag,
+  };
+}
+
+const subappOwnIntlRuntime = createSubappOwnIntl();
+
+export function isSubappOwnIntlEnabled(): boolean {
+  return subappOwnIntlRuntime.i18nFn != null;
+}
+
+export function getSubappOwnIntlTag(): string | undefined {
+  return subappOwnIntlRuntime.tag;
+}
+
+/** 独立 intl 实例的 i18n；未配置时为 `null` */
+export function getSubappOwnI18n(): TI18nFn | null {
+  return subappOwnIntlRuntime.i18nFn;
+}
+
+/** 与默认 tag 的 fetch 相同入参；未配置独立 intl 时为 `null` */
+export function getSubappOwnFetchMultilingualData(): TFetchFn | null {
+  return subappOwnIntlRuntime.fetchFn;
+}

package/generators/subapp-react/templates/homepage/src/common/intl/types.ts

@@ -0,0 +1,14 @@
+/**
+ * 运行时 common-intl 配置（见 window.__MICO_CONFIG__.intl，兼容 commonIntl）
+ */
+export interface IMicoConfigCommonIntl {
+  /** 多语言中台 tag */
+  tag: string;
+  app_name: string;
+  indexedDBParams?: {
+    dbName?: string;
+    dbVersion?: number;
+    storeName?: string;
+    keyPathKey?: string;
+  };
+}

package/generators/subapp-react/templates/homepage/src/common/intl/useSubappIntl.ts

@@ -0,0 +1,61 @@
+import { i18n } from '<%= packageScope %>/common-intl';
+import { useIntl } from '@umijs/max';
+import { getSubappCurrentLocale } from './subappLocale';
+import { isCommonIntlEnabled } from './intlRuntime';
+import { getSubappOwnI18n, isSubappOwnIntlEnabled, getSubappOwnIntlTag } from './subappOwnIntl';
+
+/**
+ * 子应用统一国际化 Hook：
+ * - 配置了 {@link getSubappIntlInitOptions} 时：优先独立 intl 实例的 `i18n`，无命中再 Umi
+ * - 否则与 layout `useLayoutIntl` 一致：未启用 commonIntl 时仅 Umi；启用后包内 `i18n` 优先，无命中再 Umi
+ */
+export function useSubappIntl() {
+  const umiIntl = useIntl();
+  const commonIntlEnabled = isCommonIntlEnabled();
+  const locale = getSubappCurrentLocale();
+  const subappOwnIntl = isSubappOwnIntlEnabled();
+  const ownI18n = getSubappOwnI18n();
+  const subappOwnIntlTag = getSubappOwnIntlTag();
+
+  const formatMessage = (
+    descriptor: { id: string; defaultMessage?: string },
+    values?: Record<string, string | number | boolean | Date | null | undefined>,
+  ): string => {
+    const dm = descriptor.defaultMessage ?? descriptor.id;
+    const fromUmi = umiIntl.formatMessage(descriptor, values);
+
+    if (subappOwnIntl && ownI18n) {
+      const fromOwn = ownI18n({
+        key: descriptor.id,
+        defaultMessage: dm,
+      });
+      if (fromOwn === dm && fromUmi !== fromOwn) {
+        return fromUmi;
+      }
+      return fromOwn;
+    }
+
+    if (!commonIntlEnabled) {
+      return fromUmi;
+    }
+
+    const fromIntl = i18n({
+      key: descriptor.id,
+      defaultMessage: dm,
+    });
+    if (fromIntl === dm && fromUmi !== fromIntl) {
+      return fromUmi;
+    }
+    return fromIntl;
+  };
+
+  return {
+    commonIntlEnabled,
+    formatMessage,
+    locale,
+    /** 是否启用子应用内独立 initIntl 配置 */
+    subappOwnIntl,
+    /** 独立 intl 的 tag（仅 subappOwnIntl 为 true 时有值） */
+    subappOwnIntlTag,
+  };
+}