zmdms-utils 0.0.72 → 0.0.74

package/dist/es/node_modules/react-i18next/dist/es/unescape.js

@@ -0,0 +1,27 @@
+const matchHtmlEntity = /&(?:amp|#38|lt|#60|gt|#62|apos|#39|quot|#34|nbsp|#160|copy|#169|reg|#174|hellip|#8230|#x2F|#47);/g;
+const htmlEntities = {
+  '&': '&',
+  '&': '&',
+  '&lt;': '<',
+  '&#60;': '<',
+  '&gt;': '>',
+  '&#62;': '>',
+  '&apos;': "'",
+  '&#39;': "'",
+  '&quot;': '"',
+  '&#34;': '"',
+  '&nbsp;': ' ',
+  '&#160;': ' ',
+  '&copy;': '©',
+  '&#169;': '©',
+  '&reg;': '®',
+  '&#174;': '®',
+  '&hellip;': '…',
+  '&#8230;': '…',
+  '&#x2F;': '/',
+  '&#47;': '/'
+};
+const unescapeHtmlEntity = m => htmlEntities[m];
+const unescape = text => text.replace(matchHtmlEntity, unescapeHtmlEntity);
+
+export { unescape };

package/dist/es/node_modules/react-i18next/dist/es/useTranslation.js

@@ -0,0 +1,112 @@
+import { useContext, useState, useRef, useEffect, useCallback } from 'react';
+import { I18nContext, ReportNamespaces } from './context.js';
+import { warnOnce, hasLoadedNamespace, loadLanguages, loadNamespaces, isString, isObject } from './utils.js';
+import { getI18n } from './i18nInstance.js';
+import { getDefaults } from './defaults.js';
+
+const usePrevious = (value, ignore) => {
+  const ref = useRef();
+  useEffect(() => {
+    ref.current = ignore ? ref.current : value;
+  }, [value, ignore]);
+  return ref.current;
+};
+const alwaysNewT = (i18n, language, namespace, keyPrefix) => i18n.getFixedT(language, namespace, keyPrefix);
+const useMemoizedT = (i18n, language, namespace, keyPrefix) => useCallback(alwaysNewT(i18n, language, namespace, keyPrefix), [i18n, language, namespace, keyPrefix]);
+const useTranslation = (ns, props = {}) => {
+  const {
+    i18n: i18nFromProps
+  } = props;
+  const {
+    i18n: i18nFromContext,
+    defaultNS: defaultNSFromContext
+  } = useContext(I18nContext) || {};
+  const i18n = i18nFromProps || i18nFromContext || getI18n();
+  if (i18n && !i18n.reportNamespaces) i18n.reportNamespaces = new ReportNamespaces();
+  if (!i18n) {
+    warnOnce(i18n, 'NO_I18NEXT_INSTANCE', 'useTranslation: You will need to pass in an i18next instance by using initReactI18next');
+    const notReadyT = (k, optsOrDefaultValue) => {
+      if (isString(optsOrDefaultValue)) return optsOrDefaultValue;
+      if (isObject(optsOrDefaultValue) && isString(optsOrDefaultValue.defaultValue)) return optsOrDefaultValue.defaultValue;
+      return Array.isArray(k) ? k[k.length - 1] : k;
+    };
+    const retNotReady = [notReadyT, {}, false];
+    retNotReady.t = notReadyT;
+    retNotReady.i18n = {};
+    retNotReady.ready = false;
+    return retNotReady;
+  }
+  if (i18n.options.react?.wait) warnOnce(i18n, 'DEPRECATED_OPTION', 'useTranslation: It seems you are still using the old wait option, you may migrate to the new useSuspense behaviour.');
+  const i18nOptions = {
+    ...getDefaults(),
+    ...i18n.options.react,
+    ...props
+  };
+  const {
+    useSuspense,
+    keyPrefix
+  } = i18nOptions;
+  let namespaces = ns || defaultNSFromContext || i18n.options?.defaultNS;
+  namespaces = isString(namespaces) ? [namespaces] : namespaces || ['translation'];
+  i18n.reportNamespaces.addUsedNamespaces?.(namespaces);
+  const ready = (i18n.isInitialized || i18n.initializedStoreOnce) && namespaces.every(n => hasLoadedNamespace(n, i18n, i18nOptions));
+  const memoGetT = useMemoizedT(i18n, props.lng || null, i18nOptions.nsMode === 'fallback' ? namespaces : namespaces[0], keyPrefix);
+  const getT = () => memoGetT;
+  const getNewT = () => alwaysNewT(i18n, props.lng || null, i18nOptions.nsMode === 'fallback' ? namespaces : namespaces[0], keyPrefix);
+  const [t, setT] = useState(getT);
+  let joinedNS = namespaces.join();
+  if (props.lng) joinedNS = `${props.lng}${joinedNS}`;
+  const previousJoinedNS = usePrevious(joinedNS);
+  const isMounted = useRef(true);
+  useEffect(() => {
+    const {
+      bindI18n,
+      bindI18nStore
+    } = i18nOptions;
+    isMounted.current = true;
+    if (!ready && !useSuspense) {
+      if (props.lng) {
+        loadLanguages(i18n, props.lng, namespaces, () => {
+          if (isMounted.current) setT(getNewT);
+        });
+      } else {
+        loadNamespaces(i18n, namespaces, () => {
+          if (isMounted.current) setT(getNewT);
+        });
+      }
+    }
+    if (ready && previousJoinedNS && previousJoinedNS !== joinedNS && isMounted.current) {
+      setT(getNewT);
+    }
+    const boundReset = () => {
+      if (isMounted.current) setT(getNewT);
+    };
+    if (bindI18n) i18n?.on(bindI18n, boundReset);
+    if (bindI18nStore) i18n?.store.on(bindI18nStore, boundReset);
+    return () => {
+      isMounted.current = false;
+      if (i18n) bindI18n?.split(' ').forEach(e => i18n.off(e, boundReset));
+      if (bindI18nStore && i18n) bindI18nStore.split(' ').forEach(e => i18n.store.off(e, boundReset));
+    };
+  }, [i18n, joinedNS]);
+  useEffect(() => {
+    if (isMounted.current && ready) {
+      setT(getT);
+    }
+  }, [i18n, keyPrefix, ready]);
+  const ret = [t, i18n, ready];
+  ret.t = t;
+  ret.i18n = i18n;
+  ret.ready = ready;
+  if (ready) return ret;
+  if (!ready && !useSuspense) return ret;
+  throw new Promise(resolve => {
+    if (props.lng) {
+      loadLanguages(i18n, props.lng, namespaces, () => resolve());
+    } else {
+      loadNamespaces(i18n, namespaces, () => resolve());
+    }
+  });
+};
+
+export { useTranslation };

package/dist/es/node_modules/react-i18next/dist/es/utils.js

@@ -0,0 +1,63 @@
+const warn = (i18n, code, msg, rest) => {
+  const args = [msg, {
+    code,
+    ...(rest || {})
+  }];
+  if (i18n?.services?.logger?.forward) {
+    return i18n.services.logger.forward(args, 'warn', 'react-i18next::', true);
+  }
+  if (isString(args[0])) args[0] = `react-i18next:: ${args[0]}`;
+  if (i18n?.services?.logger?.warn) {
+    i18n.services.logger.warn(...args);
+  } else if (console?.warn) {
+    console.warn(...args);
+  }
+};
+const alreadyWarned = {};
+const warnOnce = (i18n, code, msg, rest) => {
+  if (isString(msg) && alreadyWarned[msg]) return;
+  if (isString(msg)) alreadyWarned[msg] = new Date();
+  warn(i18n, code, msg, rest);
+};
+const loadedClb = (i18n, cb) => () => {
+  if (i18n.isInitialized) {
+    cb();
+  } else {
+    const initialized = () => {
+      setTimeout(() => {
+        i18n.off('initialized', initialized);
+      }, 0);
+      cb();
+    };
+    i18n.on('initialized', initialized);
+  }
+};
+const loadNamespaces = (i18n, ns, cb) => {
+  i18n.loadNamespaces(ns, loadedClb(i18n, cb));
+};
+const loadLanguages = (i18n, lng, ns, cb) => {
+  if (isString(ns)) ns = [ns];
+  if (i18n.options.preload && i18n.options.preload.indexOf(lng) > -1) return loadNamespaces(i18n, ns, cb);
+  ns.forEach(n => {
+    if (i18n.options.ns.indexOf(n) < 0) i18n.options.ns.push(n);
+  });
+  i18n.loadLanguages(lng, loadedClb(i18n, cb));
+};
+const hasLoadedNamespace = (ns, i18n, options = {}) => {
+  if (!i18n.languages || !i18n.languages.length) {
+    warnOnce(i18n, 'NO_LANGUAGES', 'i18n.languages were undefined or empty', {
+      languages: i18n.languages
+    });
+    return true;
+  }
+  return i18n.hasLoadedNamespace(ns, {
+    lng: options.lng,
+    precheck: (i18nInstance, loadNotPending) => {
+      if (options.bindI18n?.indexOf('languageChanging') > -1 && i18nInstance.services.backendConnector.backend && i18nInstance.isLanguageChangingTo && !loadNotPending(i18nInstance.isLanguageChangingTo, ns)) return false;
+    }
+  });
+};
+const isString = obj => typeof obj === 'string';
+const isObject = obj => typeof obj === 'object' && obj !== null;
+
+export { hasLoadedNamespace, isObject, isString, loadLanguages, loadNamespaces, warn, warnOnce };

package/dist/es/node_modules/void-elements/index.js

@@ -0,0 +1,23 @@
+/**
+ * This file automatically generated from `pre-publish.js`.
+ * Do not manually edit.
+ */
+
+var voidElements = {
+  "area": true,
+  "base": true,
+  "br": true,
+  "col": true,
+  "embed": true,
+  "hr": true,
+  "img": true,
+  "input": true,
+  "link": true,
+  "meta": true,
+  "param": true,
+  "source": true,
+  "track": true,
+  "wbr": true
+};
+
+export { voidElements as default };

package/dist/es/request.d.ts

@@ -57,7 +57,7 @@ interface IOtherOptions {
     /** 提示方法 外部传入 */
     messageWarning?: (msg: string, duration: number, callback?: () => void) => void;
     modalConfirm?: (msg: string, callback?: () => void) => void;
-    /** token相关值 */
+    /** @deprecated 租户ID，只有登录接口 需要 传递。 */
     TenantId?: string;
     /** auth值 */
     Authorization?: string;

package/dist/es/request.js

@@ -4,7 +4,7 @@ import { removeToken, getToken } from './auth.js';
 import { TOKEN_KEY } from './constants.js';
 
 var defaultOptions = {
-    TenantId: "000000",
+    // TenantId: "000000", // 租户ID不需要了
     Authorization: "Basic em1kbXM6em1kbXNfc2VjcmV0",
     timeout: 60000,
 };
@@ -39,8 +39,9 @@ var AxiosRequest = /** @class */ (function () {
     AxiosRequest.prototype.defaultSetting = function () {
         var _this = this;
         // 设置默认请求头
-        this.instanceAxios.defaults.headers.common["Tenant-Id"] =
-            this.otherOptions.TenantId;
+        // 租户ID只有登录的时候才需要传递
+        // this.instanceAxios.defaults.headers.common["Tenant-Id"] =
+        //   this.otherOptions.TenantId;
         this.instanceAxios.defaults.headers.common["Authorization"] =
             this.otherOptions.Authorization;
         if (this.otherOptions.commonHeaders) {

package/dist/es/src/locales/i18n.js

@@ -0,0 +1,16 @@
+import instance from '../../node_modules/i18next/dist/esm/i18next.js';
+import { initReactI18next } from '../../node_modules/react-i18next/dist/es/initReactI18next.js';
+
+/**
+ * 初始化逻辑
+ * - 本函数主要用于初始化 i18next 实例，同时使用 react-i18next 插件进行 react 组件的支持
+ * - 本函数的调用时机，一般是在项目的入口文件中进行调用，如 src/main.tsx 中
+ * @param options 参数 同i18next.init 第一个参数
+ * @param callback 参数 同i18next.init 第二个参数
+ * @returns
+ */
+function initLocale(options, callback) {
+    return instance.use(initReactI18next).init(options, callback);
+}
+
+export { instance as i18n, initLocale };

package/dist/es/src/locales/t-in-non-react.js

@@ -0,0 +1,54 @@
+import instance from '../../node_modules/i18next/dist/esm/i18next.js';
+import { getTFuncArgs } from './t-options.js';
+
+/**
+ * t 函数封装：
+ * - 本文件的几个 t 函数，主要用于弥补一些在 React 组件之外使用的场景
+ * - 常规情况下，在 react 组件中，更加推荐的是使用 react-i18next 包中的 t 函数，即 const { t } = useTranslate(); 形式
+ */
+/** 包裹一层 try-catch 的 t 函数 */
+var tryT = function (key, defaultValueOrOptions) {
+    var _a = getTFuncArgs(defaultValueOrOptions), defaultValue = _a.defaultValue, options = _a.options;
+    if (!key) {
+        // 情况1：键名为空，返回默认值或键名
+        console.error("tryT: \u8BF7\u4E0D\u8981\u4F20\u5165\u7A7A key \u503C\u8FDB\u884C i18n.t \u51FD\u6570\u6267\u884C\uFF0C\u8FD9\u5C06\u4F1A\u5BFC\u81F4\u76F4\u63A5\u8FD4\u56DE\u7A7A\u5B57\u7B26\u4E32\uFF01");
+        return defaultValue || key;
+    }
+    if (!instance.exists(key)) {
+        // 情况2：键名不存在，返回默认值或键名
+        console.error("tryT: i18n-key '".concat(key, "' \u4E0D\u5B58\u5728\uFF0C\u8BF7\u68C0\u67E5\u5BF9\u5E94\u7684 @/locales/resources/locales/xx.json \u4E2D\u662F\u5426\u5B58\u5728\u5BF9\u5E94\u503C"));
+        return defaultValue || key;
+    }
+    try {
+        // 情况3：尝试执行 i18n.t 函数
+        return instance.t(key, options);
+    }
+    catch (err) {
+        // 情况4：执行 i18n.t 函数异常，返回默认值或键名
+        console.error("tryT: i18n.t key=".concat(key, " \u51FD\u6570\u6267\u884C\u5F02\u5E38\uFF1Aerr="), err);
+        return defaultValue || key;
+    }
+};
+/**
+ * 同步版本的 i18n.t 函数（应对在 react 组件外使用的翻译函数）
+ * - 如果 i18n 未初始化，则返回默认值或键名
+ * - 如果 i18n 初始化后，键名不存在，则返回默认值或键名
+ * - 其他正常情况（已经初始化+键名存在），则返回翻译值
+ * @description 本函数为在非 react 组件中使用的翻译函数；（在react中请求使用 useTranslate() 返回的 t 函数）
+ * @param {string} key
+ * @param {TOpionsEx|string} defaultValue 必填值
+ * @returns {string}
+ * @example
+ *   const txt = t('someLocaleKey', '兜底默认值');
+ */
+function safeT(key, defaultValueOrOptions) {
+    if (instance.isInitialized) {
+        return tryT(key, defaultValueOrOptions);
+    }
+    // 异常情况：没有初始化完成时，返回默认值
+    var defaultValue = getTFuncArgs(defaultValueOrOptions).defaultValue;
+    console.warn("safeT: i18n is not initialized. Returning defaultValue(".concat(defaultValue, ") or origin key (").concat(key, ")."));
+    return defaultValue || key;
+}
+
+export { safeT };

package/dist/es/src/locales/t-options.js

@@ -0,0 +1,20 @@
+/**
+ * 获取 t 函数的参数
+ * @param {string | TOpionsEx} defaultValueOrOptions 默认值或者选项
+ * @returns { {defaultValue: string, options: TOpionsEx} } 默认值和选项
+ */
+function getTFuncArgs(defaultValueOrOptions) {
+    var options = null;
+    var defaultValue = "";
+    if (typeof defaultValueOrOptions === "string") {
+        defaultValue = defaultValueOrOptions;
+        options = { defaultValue: defaultValue };
+    }
+    else {
+        options = defaultValueOrOptions;
+        defaultValue = options.defaultValue;
+    }
+    return { defaultValue: defaultValue, options: options };
+}
+
+export { getTFuncArgs };

package/dist/es/src/locales/use-translation.js

@@ -0,0 +1,60 @@
+import { getTFuncArgs } from './t-options.js';
+import { useTranslation } from '../../node_modules/react-i18next/dist/es/useTranslation.js';
+
+/**
+ * 这里只是简单代理一下useTranslation，方便后续扩展或添加其他逻辑
+ * @param ns 命名空间 大多数情况下都不需要传入这个参数，除非你用到了命名空间。
+ * @param options 其他参数 大多数情况下，都不需要关注这个参数。
+ * options.keyPrefix 为所有翻译键添加前缀
+ *  // JSON 文件：{ "greeting": { "welcome": "Welcome" } }
+ *  const { t } = useTranslation('common', { keyPrefix: 'greeting' });
+ *  // 使用时省略前缀
+ *  t('welcome'); // 等价于 t('greeting:welcome')
+ * @returns { t, i18n, ready }
+ * t: 翻译方法
+ * i18n: i18next实例 访问 i18next 的完整 API（如切换语言、加载命名空间）
+ * i18n.changeLanguage('zh-CN'); 使用它切换语言，可以触发组件渲染。但是当前项目中是使用全局刷新的模式，来更新语言的。
+ * ready: 是否加载完成
+ */
+function useZtTranslation(ns, options) {
+    var _a = useTranslation(ns, options), _tOld = _a.t, i18n = _a.i18n, ready = _a.ready;
+    // 扩展t方法，用于处理嵌套的翻译键
+    var tEnhance = function (key, defaultValueOrOptions) {
+        var _a = getTFuncArgs(defaultValueOrOptions), defaultValue = _a.defaultValue, options = _a.options;
+        if (!key) {
+            // 情况1：键名为空，返回默认值或键名
+            console.error("tEnhance: \u8BF7\u4E0D\u8981\u4F20\u5165\u7A7A key \u503C\u8FDB\u884C t \u51FD\u6570\u6267\u884C\uFF0C\u8FD9\u5C06\u4F1A\u5BFC\u81F4\u76F4\u63A5\u8FD4\u56DE\u7A7A\u5B57\u7B26\u4E32\uFF01");
+            return defaultValue || key;
+        }
+        if (!i18n.exists(key)) {
+            // 情况2：键名不存在，返回默认值或键名
+            console.error("tEnhance: i18n-key '".concat(key, "' \u4E0D\u5B58\u5728\uFF0C\u8BF7\u68C0\u67E5\u5BF9\u5E94\u7684 @/locales/resources/locales/xx.json \u4E2D\u662F\u5426\u5B58\u5728\u5BF9\u5E94\u503C"));
+            return defaultValue || key;
+        }
+        try {
+            return _tOld(key, options);
+        }
+        catch (error) {
+            console.warn("tEnhance: t \u51FD\u6570\u6267\u884C\u5F02\u5E38\uFF0C\u8BF7\u68C0\u67E5! key=".concat(key, ", err="), error);
+            return defaultValue || key || "unknown";
+        }
+    };
+    return {
+        /**
+         * t函数的使用方式：基本上使用1、2两种方式就可以了。
+         * 1、t('key') // 基础用法
+         * 2、t('greeting', { name: 'John' }); // 对应 JSON: "greeting": "Hello {{name}}"
+         * 3、t('auth:login'); // 显式指定命名空间
+         *
+         * 关于t函数的第二个参数的说明。
+         * 为了防止一些异常情况，翻译失败。可以传入一个默认值。这个默认值就是原本的中文就行。
+         * 1、t('key', '默认值');
+         * 2、t('key', { defaultValue: '默认值', ...otherOptions });
+         */
+        t: tEnhance,
+        i18n: i18n,
+        ready: ready,
+    };
+}
+
+export { useZtTranslation as useTranslation };

package/dist/index.d.ts

@@ -18,3 +18,9 @@ export { imgToPdf } from './es/pdf.js';
 export { htmlToPdf } from './es/htmlToPdf.js';
 export { htmlPrint, imgPrint, pdfPrint, windowPrint } from './es/print.js';
 export { createWater, getDefaultContent, mergeWaterConfig } from './es/water.js';
+export { initLocale } from './es/locales/i18n.js';
+export { useTranslation } from './es/locales/use-translation.js';
+export { safeT } from './es/locales/t-in-non-react.js';
+export { Base64 } from 'js-base64';
+export { default as i18n } from 'i18next';
+export { Trans } from 'react-i18next';

package/dist/index.js

@@ -18,3 +18,9 @@ export { imgToPdf } from './es/pdf.js';
 export { htmlToPdf } from './es/htmlToPdf.js';
 export { htmlPrint, imgPrint, pdfPrint, windowPrint } from './es/print.js';
 export { createWater, getDefaultContent, mergeWaterConfig } from './es/water.js';
+export { initLocale } from './es/src/locales/i18n.js';
+export { useTranslation } from './es/src/locales/use-translation.js';
+export { safeT } from './es/src/locales/t-in-non-react.js';
+export { Base64 } from './es/node_modules/js-base64/base64.js';
+export { default as i18n } from './es/node_modules/i18next/dist/esm/i18next.js';
+export { Trans } from './es/node_modules/react-i18next/dist/es/Trans.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zmdms-utils",
-  "version": "0.0.72",
+  "version": "0.0.74",
   "description": "",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -36,9 +36,12 @@
     "crypto-js": "^4.1.1",
     "dayjs": "^1.11.10",
     "html2canvas": "^1.4.1",
+    "i18next": "^25.1.2",
+    "js-base64": "^3.7.7",
     "jspdf": "^2.5.1",
     "print-js": "^1.6.0",
     "qiankun": "^2.10.8",
+    "react-i18next": "^15.5.1",
     "rimraf": "^4.4.1",
     "rollup": "^3.20.2",
     "rollup-plugin-dts": "^5.3.0",

package/src/crypto.ts

@@ -1,5 +1,9 @@
 import CryptoJS from "crypto-js";
+import { Base64 } from "js-base64";
 
+/**
+ * 对称加密和hash
+ */
 export class Crypto {
   // 使用AesUtil.genAesKey()生成,需和后端配置保持一致
   private aesKey: string;
@@ -107,3 +111,5 @@ export class Crypto {
 }
 
 export const md5 = (str: string) => CryptoJS.MD5(str).toString().toLowerCase();
+
+export { Base64 };

package/src/index.ts

@@ -4,7 +4,7 @@ export { initMainApp, initGlobalError } from "./mainApp";
 export { getToken, setToken, removeToken, parseToken } from "./auth";
 export { AxiosRequest, type IOtherOptions, type IOptions } from "./request";
 export { getBaseUrl } from "./baseUrl";
-export { Crypto, md5 } from "./crypto";
+export { Crypto, md5, Base64 } from "./crypto";
 export {
   delay,
   emitter,
@@ -78,3 +78,6 @@ export { windowPrint, htmlPrint, imgPrint, pdfPrint } from "./print";
 
 // 水印相关
 export { createWater, mergeWaterConfig, getDefaultContent } from "./water";
+
+// 多语言相关
+export { initLocale, i18n, useTranslation, Trans, safeT } from "./locales";

package/src/locales/i18n.ts

@@ -0,0 +1,18 @@
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+
+type InitOptions = Parameters<typeof i18next.init>;
+
+/**
+ * 初始化逻辑
+ * - 本函数主要用于初始化 i18next 实例，同时使用 react-i18next 插件进行 react 组件的支持
+ * - 本函数的调用时机，一般是在项目的入口文件中进行调用，如 src/main.tsx 中
+ * @param options 参数 同i18next.init 第一个参数
+ * @param callback 参数 同i18next.init 第二个参数
+ * @returns
+ */
+function initLocale(options: InitOptions[0], callback?: InitOptions[1]) {
+  return i18next.use(initReactI18next).init(options, callback);
+}
+
+export { initLocale, i18next as i18n };

package/src/locales/index.ts

@@ -0,0 +1,8 @@
+// i18n实例 及 初始化方法
+export { i18n, initLocale } from "./i18n";
+
+// 代理的 useTranslation 函数
+export { useTranslation, Trans } from "./use-translation";
+
+// 导出 t 函数（应对在非 react 组件环境下进行使用的场景）
+export { safeT } from "./t-in-non-react";

package/src/locales/t-in-non-react.ts

@@ -0,0 +1,65 @@
+/**
+ * t 函数封装：
+ * - 本文件的几个 t 函数，主要用于弥补一些在 React 组件之外使用的场景
+ * - 常规情况下，在 react 组件中，更加推荐的是使用 react-i18next 包中的 t 函数，即 const { t } = useTranslate(); 形式
+ */
+import { i18n } from "./i18n";
+import type { TOpionsEx } from "./t-options";
+import { getTFuncArgs } from "./t-options";
+
+/** 包裹一层 try-catch 的 t 函数 */
+const tryT = (
+  key: string,
+  defaultValueOrOptions: string | TOpionsEx
+): string => {
+  const { defaultValue, options } = getTFuncArgs(defaultValueOrOptions);
+  if (!key) {
+    // 情况1：键名为空，返回默认值或键名
+    console.error(
+      `tryT: 请不要传入空 key 值进行 i18n.t 函数执行，这将会导致直接返回空字符串！`
+    );
+    return defaultValue || key;
+  }
+  if (!i18n.exists(key)) {
+    // 情况2：键名不存在，返回默认值或键名
+    console.error(
+      `tryT: i18n-key '${key}' 不存在，请检查对应的 @/locales/resources/locales/xx.json 中是否存在对应值`
+    );
+    return defaultValue || key;
+  }
+  try {
+    // 情况3：尝试执行 i18n.t 函数
+    return i18n.t(key, options);
+  } catch (err) {
+    // 情况4：执行 i18n.t 函数异常，返回默认值或键名
+    console.error(`tryT: i18n.t key=${key} 函数执行异常：err=`, err);
+    return defaultValue || key;
+  }
+};
+
+/**
+ * 同步版本的 i18n.t 函数（应对在 react 组件外使用的翻译函数）
+ * - 如果 i18n 未初始化，则返回默认值或键名
+ * - 如果 i18n 初始化后，键名不存在，则返回默认值或键名
+ * - 其他正常情况（已经初始化+键名存在），则返回翻译值
+ * @description 本函数为在非 react 组件中使用的翻译函数；（在react中请求使用 useTranslate() 返回的 t 函数）
+ * @param {string} key
+ * @param {TOpionsEx|string} defaultValue 必填值
+ * @returns {string}
+ * @example
+ *   const txt = t('someLocaleKey', '兜底默认值');
+ */
+export function safeT(
+  key: string,
+  defaultValueOrOptions: string | TOpionsEx
+): string {
+  if (i18n.isInitialized) {
+    return tryT(key, defaultValueOrOptions);
+  }
+  // 异常情况：没有初始化完成时，返回默认值
+  const { defaultValue } = getTFuncArgs(defaultValueOrOptions);
+  console.warn(
+    `safeT: i18n is not initialized. Returning defaultValue(${defaultValue}) or origin key (${key}).`
+  );
+  return defaultValue || key;
+}

package/src/locales/t-options.ts

@@ -0,0 +1,24 @@
+"use strict";
+import type { TOptions } from "i18next";
+
+export interface TOpionsEx extends TOptions {
+  defaultValue: string; // 必须填值
+}
+
+/**
+ * 获取 t 函数的参数
+ * @param {string | TOpionsEx} defaultValueOrOptions 默认值或者选项
+ * @returns { {defaultValue: string, options: TOpionsEx} } 默认值和选项
+ */
+export function getTFuncArgs(defaultValueOrOptions: string | TOpionsEx) {
+  let options: TOpionsEx | null = null;
+  let defaultValue = "";
+  if (typeof defaultValueOrOptions === "string") {
+    defaultValue = defaultValueOrOptions;
+    options = { defaultValue };
+  } else {
+    options = defaultValueOrOptions;
+    defaultValue = options.defaultValue;
+  }
+  return { defaultValue, options };
+}