@zfqh/uview-x 0.0.5 → 0.0.7

package/utils/locale.ts

@@ -1,304 +1,444 @@
-import { ref } from 'vue';
-import type { Ref } from 'vue';
-import { createI18n as _createI18n } from 'vue-i18n';
-import type { I18n, I18nOptions } from 'vue-i18n';
-import { getBuiltinMessage, mergeDefaultMessages } from '../locales';
-
-/**
- * 国际化能力（默认中文 + 可选语言包 + 4 个公共 API）。
- *
- * 默认语言只有简体中文（`zh-Hans`），`createI18n` 只注入并深合并内置中文；
- * 英文等其他语言为独立语言包（`locales/en.ts`），由使用方显式引入后合并进 `messages`。
- *
- * 公共 API（由 `utils/index.ts` 导出到包入口）：
- * `createI18n`、`getLocale`、`getLocaleMessage`、`setLocale`。
- *
- * 其余导出（`localeState`、`getI18nGlobal`、`getI18nMessages`、`appTranslate`、`unwrapI18nValue`
- * 与 `I18nMessageValue` / `I18nMessages` / `I18nGlobalLike`）是包内实现的 internal helper，
- * 供 components / hooks / locales 深引用，不进入 barrel 与 `types/index.d.ts`。
- */
-
-/** i18n 消息树：值为字符串，或继续嵌套的对象 */
-export type I18nMessageValue = string | { [key: string]: I18nMessageValue };
-
-/** 语言包：语言 → 消息树 */
-export type I18nMessages = Record<string, I18nMessageValue>;
-
-/** 兼容 vue-i18n legacy / composition 两种 global 形态的运行时视图 */
-export interface I18nGlobalLike {
-  t: (key: string, values?: Record<string, string | number>) => string;
-  locale: string | { value: string };
-  messages: I18nMessages | { value: I18nMessages };
-}
-
-interface RefLike<T> {
-  value: T;
-}
-
-/**
- * `uni` 全局对象的最小运行时视图（含 i18n 实例挂载点）。
- *
- * 对外 `$i18n` 声明在 `types/index.d.ts`；这里再留一份最小结构，保证其他包深引用
- * `@zfqh/uview-x/utils/locale`（不会加载本包 types 入口）时仍能编译。
- * 纯 Node / 单测环境可能没有 `uni` 全局，所有访问都要容错。
- */
-interface UniWithI18n {
-  $i18n?: I18n;
-  getStorageSync?: (key: string) => unknown;
-  setStorageSync?: (key: string, value: unknown) => void;
-  getLocale?: () => string;
-  setLocale?: (locale: string) => void;
-  getAppBaseInfo?: () => { appLanguage?: string; language?: string };
-}
-
-/** 读取 uni 全局对象；不存在时返回 undefined */
-function getUni(): UniWithI18n | undefined {
-  return typeof uni === 'undefined' ? undefined : (uni as unknown as UniWithI18n);
-}
-
-/** 读取挂到 `uni.$i18n` 上的 i18n 实例 */
-function getUniI18n(): I18n | undefined {
-  const uniApi = getUni();
-  return uniApi ? uniApi.$i18n : undefined;
-}
-
-/** 语言持久化 key：App 端切换语言可能触发重启，必须先落盘 */
-const STORAGE_KEY = 'UNI_LOCALE';
-
-/** 回退语言（内部使用，不对外导出） */
-const fallbackLocale = 'zh-Hans';
-
-/** 读取上次选择的语言；storage 不可用或无有效值时返回空字符串 */
-function readStorageLocale(): string {
-  const uniApi = getUni();
-  if (uniApi && typeof uniApi.getStorageSync === 'function') {
-    try {
-      const stored: unknown = uniApi.getStorageSync(STORAGE_KEY);
-      if (typeof stored === 'string' && stored) {
-        return stored;
-      }
-    } catch (e) {
-      // storage 不可用时忽略，继续走系统语言
-    }
-  }
-  // #ifdef WEB || H5
-  // H5 nvue 页面上下文可能拿到非共享的 uni 存储视图，浏览器 localStorage 仍为同一来源
-  if (typeof localStorage !== 'undefined') {
-    try {
-      const stored = localStorage.getItem(STORAGE_KEY);
-      if (stored) {
-        return stored;
-      }
-    } catch (e) {
-      // localStorage 不可用时忽略
-    }
-  }
-  // #endif
-  return '';
-}
-
-/**
- * 获取当前语言。
- *
- * 顺序：
- * 1. 本地存储 `UNI_LOCALE`（用户上次通过 `setLocale` 选择的语言）；
- * 2. `uni.getLocale()`（H5 / 小程序 / 经典 App）；
- * 3. `uni.getAppBaseInfo().appLanguage`（uni-app x App）；
- * 4. `uni.getAppBaseInfo().language`（经典端已废弃字段，兜底）；
- * 5. `zh-Hans`。
- */
-export function getLocale(): string {
-  const stored = readStorageLocale();
-  if (stored) {
-    return stored;
-  }
-  const uniApi = getUni();
-  if (uniApi && typeof uniApi.getLocale === 'function') {
-    const systemLocale = uniApi.getLocale();
-    if (systemLocale) {
-      return systemLocale;
-    }
-  }
-  if (uniApi && typeof uniApi.getAppBaseInfo === 'function') {
-    const info = uniApi.getAppBaseInfo();
-    const systemLocale = info.appLanguage || info.language;
-    if (systemLocale) {
-      return systemLocale;
-    }
-  }
-  return fallbackLocale;
-}
-
-/** 初始语言（内部使用，不对外导出） */
-const defaultLocale: string = getLocale();
-
-/**
- * 当前语言的内部响应式状态（internal，不进 barrel）。
- *
- * - 无 i18n 实例时是 `appTranslate` / `useI18n` 的唯一语言来源；
- * - 创建实例时用 `opts.locale` 初始化，`setLocale` 时同步更新，保证语言切换后组件重新渲染。
- */
-export const localeState: Ref<string> = ref<string>(defaultLocale);
-
-/** 兼容 vue-i18n legacy（字符串）与 composition（Ref）两种模式，取出实际值 */
-export function unwrapI18nValue<T>(value: T | { value: T }): T {
-  if (value !== null && typeof value === 'object' && 'value' in value) {
-    return (value as RefLike<T>).value;
-  }
-  return value as T;
-}
-
-function isI18nGlobalLike(value: unknown): value is I18nGlobalLike {
-  if (!value || typeof value !== 'object') {
-    return false;
-  }
-  return typeof (value as I18nGlobalLike).t === 'function';
-}
-
-/** 当前 `uni.$i18n.global` 的运行时视图；实例不存在时返回 undefined */
-export function getI18nGlobal(): I18nGlobalLike | undefined {
-  const global = getUniI18n()?.global;
-  return isI18nGlobalLike(global) ? global : undefined;
-}
-
-/** APP 下不支持动态变量，需要重写占位符替换 */
-function replacePlaceholders(str: string, values?: Record<string, string | number>): string {
-  if (!values || typeof str !== 'string') {
-    return str;
-  }
-  let out = str;
-  for (const k of Object.keys(values)) {
-    out = out.split(`{${k}}`).join(String(values[k]));
-  }
-  return out;
-}
-
-/** 按 `a.b.c` 路径从语言包中取消息 */
-function getMessage(messages: I18nMessages, locale: string, key: string): string | undefined {
-  const segments = String(key).split('.');
-  let current: I18nMessageValue | undefined = messages[locale];
-  for (const segment of segments) {
-    if (current == null || typeof current === 'string') {
-      return undefined;
-    }
-    current = current[segment];
-  }
-  return typeof current === 'string' ? current : undefined;
-}
-
-/**
- * 翻译（App / 小程序 / 无 i18n 实例时的统一实现）。
- *
- * locale 优先级：storage `UNI_LOCALE` → `uni.$i18n.global.locale` → 内部 `localeState` → `zh-Hans`；
- * 消息优先级：全局语言包（当前语言 → 中文回退）→ 内置中文默认语言包 → key。
- * 其他语言（如英文）由使用方在 `createI18n` 中显式合并，未合并时回退中文。
- * storage 优先用于 nvue 等页面上下文模块副本不同、实例未共享的场景（setLocale 已先落盘）。
- */
-export function appTranslate(key: string, values?: Record<string, string | number>): string {
-  const global = getI18nGlobal();
-  const messages = unwrapI18nValue(global?.messages) || {};
-  const globalLocale = String(unwrapI18nValue(global?.locale) || '');
-  const locale = readStorageLocale() || globalLocale || localeState.value || fallbackLocale;
-  const message = getMessage(messages, locale, key) || getMessage(messages, fallbackLocale, key);
-  if (message) {
-    return replacePlaceholders(message, values);
-  }
-  const builtin = getBuiltinMessage(locale, key, values) || getBuiltinMessage(fallbackLocale, key, values);
-  return builtin || key;
-}
-
-/**
- * 创建 i18n 实例并挂到 `uni.$i18n`。
- *
- * - 只注入内置默认中文：`mergeDefaultMessages(opts.messages)` 仅深合并 `zh-Hans`，
- *   用户同名 key 优先；其他 locale（如显式引入的 `en`）原样透传，不做内置补全；
- * - 未显式传 `fallbackLocale` 时默认 `zh-Hans`，未合并的语言回退中文；
- * - App 端不依赖 vue-i18n 注入，直接把 `global.t` 替换为包内 `appTranslate`；
- * - 用 `opts.locale` 初始化内部 `localeState`，无实例时也能保持语言一致。
- */
-export function createI18n(opts: I18nOptions): I18n {
-  const mergedMessages: I18nMessages = mergeDefaultMessages(opts.messages as I18nMessages | undefined);
-  const mergedOptions: I18nOptions = {
-    ...opts,
-    // 默认回退中文；显式传入的值（含 false）优先
-    fallbackLocale: opts.fallbackLocale ?? fallbackLocale,
-    // #ifdef WEB || H5
-    // vue-i18n 9.1.9 的 globalInjection 默认 false；H5 开启后 app.use(i18n) 会注入
-    // `app.config.globalProperties.$i18n`，useI18n 才能检测到实例并走 vue-i18n 分支
-    //（可显式传 globalInjection: false 关闭；App / 小程序不需要，保持 vue-i18n 默认）
-    globalInjection: opts.globalInjection !== false,
-    // #endif
-    messages: mergedMessages,
-  } as unknown as I18nOptions;
-  const i18n: I18n = _createI18n(mergedOptions);
-  // #ifdef APP
-  i18n.global.t = appTranslate as unknown as typeof i18n.global.t;
-  // #endif
-  const uniApi = getUni();
-  if (uniApi) {
-    uniApi.$i18n = i18n;
-  }
-  if (typeof opts.locale === 'string' && opts.locale) {
-    localeState.value = opts.locale;
-  }
-  return i18n;
-}
-
-/** 当前语言包（兼容 composition 模式的 Ref；internal，不进 barrel） */
-export function getI18nMessages(): I18nMessages {
-  const messages = unwrapI18nValue(getI18nGlobal()?.messages);
-  return messages || {};
-}
-
-/**
- * 设置当前语言。
- *
- * 顺序（关键，防止 App 端重启后丢失语言）：
- * 1. 更新内部 `localeState`；
- * 2. 更新项目自己的 `uni.$i18n.global.locale`（兼容 WritableComputedRef 写 `.value` / legacy 字符串）；
- * 3. 写入 storage 的 `UNI_LOCALE`；
- * 4. 最后才调用 `uni.setLocale`（App 端可能引起重启，此时前两步已落盘）。
- *
- * 注意：`useI18n()` 返回的 `locale` 的 setter 只更新 `global.locale` / `localeState`，不会调用本函数；
- * 需要持久化 / 通知系统时请显式调用 `setLocale`。
- */
-export function setLocale(locale: string): void {
-  localeState.value = locale;
-  const global = getI18nGlobal();
-  if (global) {
-    try {
-      const target: unknown = global.locale;
-      if (target && typeof target === 'object' && 'value' in target) {
-        (target as RefLike<string>).value = locale;
-      } else {
-        global.locale = locale;
-      }
-    } catch (e) {
-      // 实例不可写时忽略，继续持久化
-    }
-  }
-  const uniApi = getUni();
-  if (uniApi && typeof uniApi.setStorageSync === 'function') {
-    try {
-      uniApi.setStorageSync(STORAGE_KEY, locale);
-    } catch (e) {
-      // storage 不可用时忽略
-    }
-  }
-  if (uniApi && typeof uniApi.setLocale === 'function') {
-    try {
-      uniApi.setLocale(locale);
-    } catch (e) {
-      // App 端 setLocale 可能触发重启 / 平台不支持，忽略
-    }
-  }
-}
-
-/**
- * 按当前语言取词（公共 API）。
- * 统一走 `appTranslate`（优先读 `uni.$i18n` 语言包，其次默认中文语言包），
- * 避免小程序端 vue-i18n runtime-only 构建缺少消息编译器导致翻译空白 / 占位符不插值。
- */
-export function getLocaleMessage(key: string, values?: Record<string, string | number>): string {
-  return appTranslate(key, values);
-}
+import { ref } from 'vue';
+import type { Ref } from 'vue';
+import { createI18n as _createI18n } from 'vue-i18n';
+import type { I18n, I18nOptions as VueI18nOptions } from 'vue-i18n';
+import { registerI18nConfigHandler } from './config';
+import en from '../locales/en';
+
+/**
+ * 国际化能力（默认英文 + 可选语言包 + 4 个公共 API）。
+ *
+ * 默认组件语言为 `en`，内置 `en` 语言包；其他语言包由使用方显式引入后通过
+ * `setConfig({ i18n })` / `app.use(UviewX, { i18n })` 合并。
+ *
+ * 公共 API（由根入口 index.ts 导出）：
+ * `createI18n`、`getLocale`、`getLocaleMessage`、`setLocale`。
+ *
+ * 其余导出（`configureI18n`、`localeState`、`getI18nGlobal`、`getI18nMessages`、`appTranslate`、
+ * `unwrapI18nValue` 与相关类型）是包内实现的 internal helper，供 components / hooks / locales 深引用，
+ * 不进入根入口与 `types/index.d.ts`。
+ */
+
+/** 单语言扁平语言包 */
+export type LocaleMessages = Record<string, string>;
+
+/** 语言包：locale -> 扁平 key 映射 */
+export type UViewI18nMessages = Record<string, LocaleMessages>;
+
+/** 内部组件语言包：默认只包含 en，可由 setConfig / 插件 options 合并 */
+export const componentMessages: Record<string, LocaleMessages> = {
+  en: { ...en },
+};
+
+function mergeLocaleMessages(base: LocaleMessages, patch: LocaleMessages): LocaleMessages {
+  return { ...base, ...patch };
+}
+
+/** 把 locale -> 扁平 messages 合并进内部组件语言包 */
+export function mergeComponentMessages(messages?: UViewI18nMessages): void {
+  if (!messages) {
+    return;
+  }
+  for (const locale of Object.keys(messages)) {
+    const incoming = messages[locale];
+    if (!incoming || typeof incoming !== 'object') {
+      continue;
+    }
+    componentMessages[locale] = mergeLocaleMessages(componentMessages[locale] || {}, incoming);
+  }
+}
+
+/**
+ * 生成 createI18n 使用的合并 messages（返回新对象，不修改入参）。
+ *
+ * - 以内置 `en` + 已配置的组件语言包为基础；
+ * - 用户传入的同 locale 扁平 key 覆盖已有文案。
+ */
+export function mergeDefaultMessages(userMessages?: UViewI18nMessages): UViewI18nMessages {
+  const merged: UViewI18nMessages = {};
+  for (const locale of Object.keys(componentMessages)) {
+    merged[locale] = { ...componentMessages[locale] };
+  }
+  if (userMessages) {
+    for (const locale of Object.keys(userMessages)) {
+      const incoming = userMessages[locale];
+      if (!incoming || typeof incoming !== 'object') {
+        continue;
+      }
+      merged[locale] = mergeLocaleMessages(merged[locale] || {}, incoming);
+    }
+  }
+  return merged;
+}
+
+/** 组件初始化 i18n 配置（字段与 createI18n 对齐） */
+export interface UViewI18nOptions {
+  /** 组件语言，默认 'en' */
+  locale?: string;
+  /** 组件回退语言，默认 'en' */
+  fallbackLocale?: string;
+  /** locale -> 扁平组件文案 */
+  messages?: UViewI18nMessages;
+}
+
+/** createI18n 选项：messages 使用扁平 locale 包，其余与 vue-i18n 一致 */
+export interface UViewCreateI18nOptions extends Omit<VueI18nOptions, 'messages'> {
+  messages?: UViewI18nMessages;
+}
+
+/** vue-i18n 实例内的 messages（内部已转换为嵌套结构） */
+export type I18nGlobalMessages = Record<string, Record<string, unknown>>;
+
+/** 兼容 vue-i18n legacy / composition 两种 global 形态的运行时视图 */
+export interface I18nGlobalLike {
+  t: (key: string, values?: Record<string, string | number>) => string;
+  locale: string | { value: string };
+  messages: I18nGlobalMessages | { value: I18nGlobalMessages };
+}
+
+interface RefLike<T> {
+  value: T;
+}
+
+/** 语言持久化 key：App 端切换语言可能触发重启，必须先落盘 */
+const STORAGE_KEY = 'UNI_LOCALE';
+
+/** 默认/回退语言（内部使用） */
+const fallbackLocale = 'en';
+
+/** 当前组件默认语言与回退语言（由 setConfig / 插件 options 更新） */
+let componentLocale = 'en';
+let componentFallbackLocale = 'en';
+
+/** 读取上次选择的语言；storage 不可用或无有效值时返回空字符串 */
+function readStorageLocale(): string {
+  if (typeof uni !== 'undefined' && typeof uni.getStorageSync === 'function') {
+    try {
+      const stored: unknown = uni.getStorageSync(STORAGE_KEY);
+      if (typeof stored === 'string' && stored) {
+        return stored;
+      }
+    } catch (e) {
+      // storage 不可用时忽略，继续走系统语言
+    }
+  }
+  // #ifdef WEB || H5
+  // H5 nvue 页面上下文可能拿到非共享的 uni 存储视图，浏览器 localStorage 仍为同一来源
+  if (typeof localStorage !== 'undefined') {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY);
+      if (stored) {
+        return stored;
+      }
+    } catch (e) {
+      // localStorage 不可用时忽略
+    }
+  }
+  // #endif
+  return '';
+}
+
+/**
+ * 获取当前系统语言。
+ *
+ * 顺序：
+ * 1. 本地存储 `UNI_LOCALE`（用户上次通过 `setLocale` 选择的语言）；
+ * 2. `uni.getLocale()`；
+ * 3. `uni.getAppBaseInfo().appLanguage`；
+ * 4. `en`。
+ */
+export function getLocale(): string {
+  const stored = readStorageLocale();
+  if (stored) {
+    return stored;
+  }
+  if (typeof uni !== 'undefined' && typeof uni.getLocale === 'function') {
+    const systemLocale = uni.getLocale();
+    if (systemLocale) {
+      return systemLocale;
+    }
+  }
+  if (typeof uni !== 'undefined' && typeof uni.getAppBaseInfo === 'function') {
+    const info = uni.getAppBaseInfo() as { appLanguage?: string };
+    const systemLocale = info.appLanguage;
+    if (systemLocale) {
+      return systemLocale;
+    }
+  }
+  return fallbackLocale;
+}
+
+/** 当前组件语言状态（internal，不进 barrel） */
+export const localeState: Ref<string> = ref<string>(readStorageLocale() || componentLocale);
+
+/**
+ * 应用组件 i18n 初始化配置（internal）。
+ *
+ * - 更新组件默认/回退语言；
+ * - 合并扁平 locale 包；
+ * - storage 中已有用户选择时优先于默认 locale。
+ */
+export function configureI18n(options: UViewI18nOptions = {}): void {
+  if (options.locale) {
+    componentLocale = options.locale;
+  }
+  if (options.fallbackLocale) {
+    componentFallbackLocale = options.fallbackLocale;
+  }
+  if (options.messages) {
+    mergeComponentMessages(options.messages);
+  }
+  localeState.value = readStorageLocale() || componentLocale;
+}
+
+// setConfig 位于 utils/config.ts，通过注册处理器避免 config ↔ locale 值循环
+registerI18nConfigHandler(configureI18n);
+
+/** 兼容 vue-i18n legacy（字符串）与 composition（Ref）两种模式，取出实际值 */
+export function unwrapI18nValue<T>(value: T | { value: T }): T {
+  if (value !== null && typeof value === 'object' && 'value' in value) {
+    return (value as RefLike<T>).value;
+  }
+  return value as T;
+}
+
+function isI18nGlobalLike(value: unknown): value is I18nGlobalLike {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  return typeof (value as I18nGlobalLike).t === 'function';
+}
+
+/** 当前 `uni.$i18n.global` 的运行时视图；实例不存在时返回 undefined */
+export function getI18nGlobal(): I18nGlobalLike | undefined {
+  if (typeof uni === 'undefined') {
+    return undefined;
+  }
+  const global = uni.$i18n?.global;
+  return isI18nGlobalLike(global) ? global : undefined;
+}
+
+/** APP 下不支持动态变量，需要重写占位符替换 */
+function replacePlaceholders(str: string, values?: Record<string, string | number>): string {
+  if (!values || typeof str !== 'string') {
+    return str;
+  }
+  let out = str;
+  for (const k of Object.keys(values)) {
+    out = out.split(`{${k}}`).join(String(values[k]));
+  }
+  return out;
+}
+
+/**
+ * 读取组件内置文案（含已合并的初始化 messages）；按扁平 key 查找并替换 `{name}` 占位符。
+ *
+ * 找不到时返回空字符串，由调用方继续回退到 key。
+ */
+export function getBuiltinMessage(locale: string, key: string, values?: Record<string, string | number>): string {
+  const messages = componentMessages[locale];
+  if (!messages) {
+    return '';
+  }
+  return replacePlaceholders(messages[key] || '', values);
+}
+
+/**
+ * 用 `t` 构建 async-validator 的校验消息对象（结构与 `components/uv-form/valid.ts` 的 `newMessages()` 对齐）。
+ *
+ * 显式 `rules[].message` 仍由校验器优先使用；这里只提供默认文案。
+ */
+export function buildFormValidationMessages(t: (key: string) => string): Record<string, unknown> {
+  const typeMessage = (type: string): string => t(`uv.form.types.${type}`);
+  const lengthMessages = (type: string): Record<string, string> => ({
+    len: t(`uv.form.${type}.len`),
+    min: t(`uv.form.${type}.min`),
+    max: t(`uv.form.${type}.max`),
+    range: t(`uv.form.${type}.range`),
+  });
+  return {
+    default: t('uv.form.default'),
+    required: t('uv.form.required'),
+    enum: t('uv.form.enum'),
+    whitespace: t('uv.form.whitespace'),
+    date: {
+      format: t('uv.form.date.format'),
+      parse: t('uv.form.date.parse'),
+      invalid: t('uv.form.date.invalid'),
+    },
+    types: {
+      string: typeMessage('string'),
+      method: typeMessage('method'),
+      array: typeMessage('array'),
+      object: typeMessage('object'),
+      number: typeMessage('number'),
+      date: typeMessage('date'),
+      boolean: typeMessage('boolean'),
+      integer: typeMessage('integer'),
+      float: typeMessage('float'),
+      regexp: typeMessage('regexp'),
+      email: typeMessage('email'),
+      url: typeMessage('url'),
+      hex: typeMessage('hex'),
+    },
+    string: lengthMessages('string'),
+    number: lengthMessages('number'),
+    array: lengthMessages('array'),
+    pattern: {
+      mismatch: t('uv.form.pattern.mismatch'),
+    },
+  };
+}
+
+/** 按 `a.b.c` 路径从 vue-i18n 实例 messages 中取消息 */
+function getNestedMessage(messages: I18nGlobalMessages, locale: string, key: string): string | undefined {
+  const segments = String(key).split('.');
+  let current: unknown = messages[locale];
+  for (const segment of segments) {
+    if (current == null || typeof current === 'string') {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return typeof current === 'string' ? current : undefined;
+}
+
+/**
+ * 翻译（App / 小程序 / 无 i18n 实例时的统一实现）。
+ *
+ * locale 优先级：storage `UNI_LOCALE` → `uni.$i18n.global.locale` → 内部 `localeState` → `componentLocale`；
+ * 消息优先级：实例 messages（若存在）→ 内置/初始化扁平语言包 → 配置 fallback → key。
+ */
+export function appTranslate(key: string, values?: Record<string, string | number>): string {
+  const global = getI18nGlobal();
+  const messages = unwrapI18nValue(global?.messages) || {};
+  const globalLocale = String(unwrapI18nValue(global?.locale) || '');
+  const locale = readStorageLocale() || globalLocale || localeState.value || componentLocale;
+  const fallback = componentFallbackLocale;
+  const message = getNestedMessage(messages, locale, key) || getNestedMessage(messages, fallback, key);
+  if (message) {
+    return replacePlaceholders(message, values);
+  }
+  const builtin = getBuiltinMessage(locale, key, values) || getBuiltinMessage(fallback, key, values);
+  return builtin || key;
+}
+
+/** 把扁平 locale 包转换为 vue-i18n 需要的嵌套结构 */
+function toNestedMessages(messages: UViewI18nMessages): I18nGlobalMessages {
+  const nested: I18nGlobalMessages = {};
+  for (const locale of Object.keys(messages)) {
+    const target: Record<string, unknown> = {};
+    for (const key of Object.keys(messages[locale])) {
+      const segments = key.split('.');
+      let current = target;
+      for (let i = 0; i < segments.length - 1; i++) {
+        const segment = segments[i];
+        const next = current[segment];
+        if (typeof next !== 'object' || next === null) {
+          current[segment] = {};
+        }
+        current = current[segment] as Record<string, unknown>;
+      }
+      current[segments[segments.length - 1]] = messages[locale][key];
+    }
+    nested[locale] = target;
+  }
+  return nested;
+}
+
+/**
+ * 创建 i18n 实例并挂到 `uni.$i18n`。
+ *
+ * - locale：显式 `opts.locale` 优先，否则使用当前组件 locale（默认 `en`）；
+ * - fallback：显式 `opts.fallbackLocale` 优先，否则使用当前组件 fallback；
+ * - messages：内置 `en` + 已配置组件语言包 + `opts.messages`，按扁平 key 覆盖后转嵌套传给 vue-i18n；
+ * - App 端不依赖 vue-i18n 注入，直接把 `global.t` 替换为包内 `appTranslate`。
+ */
+export function createI18n(opts: UViewCreateI18nOptions = {}): I18n {
+  const locale = typeof opts.locale === 'string' && opts.locale ? opts.locale : componentLocale;
+  const fallback = opts.fallbackLocale ?? componentFallbackLocale;
+  const flatMessages = mergeDefaultMessages(opts.messages);
+  const mergedOptions: UViewI18nOptions = {
+    ...opts,
+    locale,
+    fallbackLocale: fallback,
+    // #ifdef WEB || H5
+    // vue-i18n 9.1.9 的 globalInjection 默认 false；H5 开启后 app.use(i18n) 会注入
+    // `app.config.globalProperties.$i18n`，useI18n 才能检测到实例并走 vue-i18n 分支
+    //（可显式传 globalInjection: false 关闭；App / 小程序不需要，保持 vue-i18n 默认）
+    globalInjection: opts.globalInjection !== false,
+    // #endif
+    messages: toNestedMessages(flatMessages),
+  } as unknown as UViewI18nOptions;
+  const i18n: I18n = _createI18n(mergedOptions);
+  // #ifdef APP
+  i18n.global.t = appTranslate as unknown as typeof i18n.global.t;
+  // #endif
+  if (typeof uni !== 'undefined') {
+    uni.$i18n = i18n;
+  }
+  componentLocale = locale;
+  if (typeof fallback === 'string') {
+    componentFallbackLocale = fallback;
+  }
+  localeState.value = locale;
+  return i18n;
+}
+
+/** 当前实例语言包（内部已转换为嵌套结构；internal，不进 barrel） */
+export function getI18nMessages(): I18nGlobalMessages {
+  const messages = unwrapI18nValue(getI18nGlobal()?.messages);
+  return messages || {};
+}
+
+/**
+ * 设置当前语言。
+ *
+ * 顺序（关键，防止 App 端重启后丢失语言）：
+ * 1. 更新内部 `localeState`；
+ * 2. 更新项目自己的 `uni.$i18n.global.locale`（兼容 WritableComputedRef 写 `.value` / legacy 字符串）；
+ * 3. 写入 storage 的 `UNI_LOCALE`；
+ * 4. 最后才调用 `uni.setLocale`（App 端可能引起重启，此时前两步已落盘）。
+ *
+ * 注意：`useI18n()` 返回的 `locale` 的 setter 只更新 `global.locale` / `localeState`，不会调用本函数；
+ * 需要持久化 / 通知系统时请显式调用 `setLocale`。
+ */
+export function setLocale(locale: string): void {
+  localeState.value = locale;
+  const global = getI18nGlobal();
+  if (global) {
+    try {
+      const target: unknown = global.locale;
+      if (target && typeof target === 'object' && 'value' in target) {
+        (target as RefLike<string>).value = locale;
+      } else {
+        global.locale = locale;
+      }
+    } catch (e) {
+      // 实例不可写时忽略，继续持久化
+    }
+  }
+  if (typeof uni !== 'undefined' && typeof uni.setStorageSync === 'function') {
+    try {
+      uni.setStorageSync(STORAGE_KEY, locale);
+    } catch (e) {
+      // storage 不可用时忽略
+    }
+  }
+  if (typeof uni !== 'undefined' && typeof uni.setLocale === 'function') {
+    try {
+      uni.setLocale(locale);
+    } catch (e) {
+      // App 端 setLocale 可能触发重启 / 平台不支持，忽略
+    }
+  }
+}
+
+/**
+ * 按当前语言取词（公共 API）。
+ * 统一走 `appTranslate`（优先读 `uni.$i18n` 语言包，其次默认/初始化语言包），
+ * 避免小程序端 vue-i18n runtime-only 构建缺少消息编译器导致翻译空白 / 占位符不插值。
+ */
+export function getLocaleMessage(key: string, values?: Record<string, string | number>): string {
+  return appTranslate(key, values);
+}