finovision-i18n 0.1.1

package/README.md

@@ -0,0 +1,85 @@
+# finovision-i18n
+
+i18next 运行时（精简版，参照 Coze `@coze-arch/i18n`）。
+
+**文案与类型**在兄弟包 [`finovision-i18n-resource`](../fv-i18n-resource)（等同 `studio-i18n-resource`），本包只负责 init + 类型安全的 `I18n.t()`。
+
+## 目录
+
+```text
+多语言测试/
+├── fv-i18n-resource/   # 文案 JSON + locale-data.d.ts + defaultConfig
+└── fv-i18n/            # 本包 finovision-i18n
+```
+
+## 安装与构建
+
+```bash
+# 先构建资源包
+cd ../fv-i18n-resource
+npm install
+npm run build
+
+# 再构建运行时（Rollup → dist/i18n.esm.js、dist/init.esm.js）
+cd ../fv-i18n
+npm install
+npm run build
+```
+
+开发调试可执行 `npm run build:dev`（不压缩）。
+
+产物（与 `finovision-i18n-resource` 对齐）：
+
+| 文件 | 说明 |
+|------|------|
+| `dist/i18n.esm.js` | ESM 主入口 |
+| `dist/i18n.cjs` | CJS 主入口 |
+| `dist/i18n.d.ts` | 主入口类型 |
+| `dist/init.d.ts` | `finovision-i18n/init` 类型（运行时代码与主入口相同 bundle） |
+
+`i18next`、`finovision-i18n-resource` 等为 **external**，不打进包内。
+
+## 单元测试
+
+```bash
+cd fv-i18n
+npm test
+```
+
+会先构建 `fv-i18n-resource`、刷新 `file:` 依赖、编译本包，再运行 `test/i18n.test.ts`（覆盖 `core` / `init` / `I18n` 与资源包联调）。
+
+```bash
+npm run test:unit   # 仅跑测试（需已 build）
+npm run typecheck
+```
+
+## Vue 用法
+
+```typescript
+// main.ts
+import { createApp } from 'vue';
+import { initI18nInstance, Locale } from 'finovision-i18n/init';
+import App from './App.vue';
+
+await initI18nInstance({
+  lng: (localStorage.getItem('i18next') as 'en' | 'zh-CN') ?? Locale.ZhCN,
+});
+
+createApp(App).mount('#app');
+```
+
+```vue
+<script setup lang="ts">
+import { I18n } from 'finovision-i18n';
+
+const title = I18n.t('404_title');
+const toast = I18n.t('AddSuccessToast', { name: 'Bot' });
+</script>
+```
+
+## 分层（对照 Coze）
+
+| Coze | 本仓库 |
+|------|--------|
+| studio-i18n-resource | `finovision-i18n-resource` |
+| intl + FlowIntl + raw | `finovision-i18n`（`core` + `i18n` + `init`） |

package/dist/i18n.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("i18next-icu"),t=require("i18next"),n=require("i18next-browser-languagedetector"),r=require("finovision-i18n-resource");class a{constructor(){this.initialized=!1,this.instance=t.createInstance(),this.instance.use(e)}get isInitialized(){return this.initialized}registerPlugins(e){e.forEach(e=>this.instance.use(e))}setup(e){return new Promise((t,n)=>{this.instance.init({keySeparator:!1,...e},(e,r)=>{this.initialized=!e,e?n(e):t(r)})})}getLanguage(){return this.instance.language}setLanguage(e,t){this.instance.changeLanguage(a.normalizeLng(e),t)}setLanguageAsync(e){return this.instance.changeLanguage(a.normalizeLng(e))}static normalizeLng(e){return"en-US"===e?"en":e}translate(e,t,n){return this.initialized?e?.trim()?String(void 0!==n?this.instance.t(e,n,t??{}):this.instance.t(e,t??{})):"":n??e}}const i=new a,s=i.instance,o=new class{get language(){return i.getLanguage()}setLang(e,t){i.setLanguage(e,t)}setLangAsync(e){return i.setLanguageAsync(e)}t(e,t,n){return i.translate(e,t,n)}};Object.defineProperty(exports,"DEFAULT_I18N_NAMESPACE",{enumerable:!0,get:()=>r.DEFAULT_I18N_NAMESPACE}),Object.defineProperty(exports,"Locale",{enumerable:!0,get:()=>r.Locale}),Object.defineProperty(exports,"SUPPORTED_LOCALES",{enumerable:!0,get:()=>r.SUPPORTED_LOCALES}),Object.defineProperty(exports,"buildDefaultConfig",{enumerable:!0,get:()=>r.buildDefaultConfig}),Object.defineProperty(exports,"defaultConfig",{enumerable:!0,get:()=>r.defaultConfig}),Object.defineProperty(exports,"loadLocale",{enumerable:!0,get:()=>r.loadLocale}),exports.I18n=o,exports.I18nCore=a,exports.getLanguage=function(){return i.getLanguage()},exports.i18nCore=i,exports.i18nextInstance=s,exports.initI18nInstance=async function(e){const{lng:t=r.Locale.ZhCN,detect:a=!0,ns:s=r.DEFAULT_I18N_NAMESPACE,...o}=e??{};a&&i.registerPlugins([n]),await i.setup({lng:t,fallbackLng:t,ns:s,defaultNS:s,resources:r.defaultConfig,...a?{detection:{order:["querystring","localStorage","navigator"],lookupQuerystring:"lng",lookupLocalStorage:"i18next",caches:["localStorage"]}}:{},react:{useSuspense:!1},keySeparator:!1,...o})},exports.normalizeLng=function(e){return a.normalizeLng(e)},exports.registerPlugins=function(e){i.registerPlugins(e)},exports.setLanguage=function(e,t){i.setLanguage(e,t)},exports.setLanguageAsync=function(e){return i.setLanguageAsync(e)},exports.setupI18next=function(e){return i.setup(e)},exports.translate=function(e,t,n){return i.translate(e,t,n)};

package/dist/i18n.d.ts

@@ -0,0 +1,62 @@
+import * as i18next from 'i18next';
+import { i18n, Module, InitOptions, TFunction, Callback } from 'i18next';
+import { I18nKeysNoOptionsType, I18nKeysHasOptionsType, LocaleData, I18nOptionsMap, SupportedLocale } from 'finovision-i18n-resource';
+export { DEFAULT_I18N_NAMESPACE, I18nKeysHasOptionsType, I18nKeysNoOptionsType, I18nOptionsMap, InterpolationValue, Locale, LocaleData, SUPPORTED_LOCALES, SupportedLocale, buildDefaultConfig, defaultConfig, loadLocale } from 'finovision-i18n-resource';
+
+type I18nOptions<K extends LocaleData> = K extends keyof I18nOptionsMap ? I18nOptionsMap[K] : never;
+declare class TypedI18n {
+    get language(): string;
+    setLang(lng: string, callback?: () => void): void;
+    setLangAsync(lng: string): Promise<i18next.TFunction<"translation", undefined>>;
+    t<K extends I18nKeysNoOptionsType>(key: K, options?: Record<string, unknown>, fallback?: string): string;
+    t<K extends I18nKeysHasOptionsType>(key: K, options: I18nOptions<K>, fallback?: string): string;
+}
+declare const I18n: TypedI18n;
+
+/**
+ * 初始化配置：已知字段 + 其余 i18next 选项（顶层透传，无需包在 extra 里）
+ */
+interface I18nConfig extends Record<string, unknown> {
+    /** 初始语言，默认 `Locale.ZhCN` */
+    lng?: SupportedLocale;
+    /** i18next 命名空间，默认 {@link DEFAULT_I18N_NAMESPACE} */
+    ns?: string;
+    /**
+     * 是否启用浏览器语言检测（querystring、localStorage、navigator）
+     * 默认 `true`
+     */
+    detect?: boolean;
+}
+/** 在 createApp / mount 之前 await 一次 */
+declare function initI18nInstance(options?: I18nConfig): Promise<void>;
+
+/** i18next 实例封装，全应用共享单例 */
+declare class I18nCore {
+    readonly instance: i18n;
+    private initialized;
+    constructor();
+    /** 是否已完成 init */
+    get isInitialized(): boolean;
+    registerPlugins(plugins: Module[] | unknown[]): void;
+    setup(config: InitOptions): Promise<TFunction>;
+    getLanguage(): string;
+    setLanguage(lng: string, callback?: Callback): void;
+    setLanguageAsync(lng: string): Promise<TFunction>;
+    /** en-US → en */
+    static normalizeLng(lng: string): string;
+    translate(key: string, options?: Record<string, unknown>, fallback?: string): string;
+}
+/** 全局唯一 i18next 内核实例 */
+declare const i18nCore: I18nCore;
+/** 兼容旧版函数式 API，委托给 {@link i18nCore} */
+declare function registerPlugins(plugins: Module[] | unknown[]): void;
+declare function setupI18next(config: InitOptions): Promise<TFunction>;
+declare function getLanguage(): string;
+declare function setLanguage(lng: string, callback?: Callback): void;
+declare function setLanguageAsync(lng: string): Promise<TFunction>;
+declare function normalizeLng(lng: string): string;
+declare function translate(key: string, options?: Record<string, unknown>, fallback?: string): string;
+declare const i18nextInstance: i18n;
+
+export { I18n, I18nCore, getLanguage, i18nCore, i18nextInstance, initI18nInstance, normalizeLng, registerPlugins, setLanguage, setLanguageAsync, setupI18next, translate };
+export type { I18nConfig };

package/dist/i18n.esm.js

@@ -0,0 +1 @@
+import n from"i18next-icu";import e from"i18next";import t from"i18next-browser-languagedetector";import{defaultConfig as i,DEFAULT_I18N_NAMESPACE as a,Locale as r}from"finovision-i18n-resource";export{DEFAULT_I18N_NAMESPACE,Locale,SUPPORTED_LOCALES,buildDefaultConfig,defaultConfig,loadLocale}from"finovision-i18n-resource";class s{constructor(){this.initialized=!1,this.instance=e.createInstance(),this.instance.use(n)}get isInitialized(){return this.initialized}registerPlugins(n){n.forEach(n=>this.instance.use(n))}setup(n){return new Promise((e,t)=>{this.instance.init({keySeparator:!1,...n},(n,i)=>{this.initialized=!n,n?t(n):e(i)})})}getLanguage(){return this.instance.language}setLanguage(n,e){this.instance.changeLanguage(s.normalizeLng(n),e)}setLanguageAsync(n){return this.instance.changeLanguage(s.normalizeLng(n))}static normalizeLng(n){return"en-US"===n?"en":n}translate(n,e,t){return this.initialized?n?.trim()?String(void 0!==t?this.instance.t(n,t,e??{}):this.instance.t(n,e??{})):"":t??n}}const g=new s;function o(n){g.registerPlugins(n)}function u(n){return g.setup(n)}function c(){return g.getLanguage()}function l(n,e){g.setLanguage(n,e)}function L(n){return g.setLanguageAsync(n)}function f(n){return s.normalizeLng(n)}function h(n,e,t){return g.translate(n,e,t)}const m=g.instance,d=new class{get language(){return g.getLanguage()}setLang(n,e){g.setLanguage(n,e)}setLangAsync(n){return g.setLanguageAsync(n)}t(n,e,t){return g.translate(n,e,t)}};async function p(n){const{lng:e=r.ZhCN,detect:s=!0,ns:o=a,...u}=n??{};s&&g.registerPlugins([t]),await g.setup({lng:e,fallbackLng:e,ns:o,defaultNS:o,resources:i,...s?{detection:{order:["querystring","localStorage","navigator"],lookupQuerystring:"lng",lookupLocalStorage:"i18next",caches:["localStorage"]}}:{},react:{useSuspense:!1},keySeparator:!1,...u})}export{d as I18n,s as I18nCore,c as getLanguage,g as i18nCore,m as i18nextInstance,p as initI18nInstance,f as normalizeLng,o as registerPlugins,l as setLanguage,L as setLanguageAsync,u as setupI18next,h as translate};

package/dist/init.d.ts

@@ -0,0 +1,33 @@
+import { I18nKeysNoOptionsType, I18nKeysHasOptionsType, LocaleData, I18nOptionsMap, SupportedLocale } from 'finovision-i18n-resource';
+export { I18nKeysHasOptionsType, I18nKeysNoOptionsType, I18nOptionsMap, Locale, LocaleData, SupportedLocale } from 'finovision-i18n-resource';
+import * as i18next from 'i18next';
+
+type I18nOptions<K extends LocaleData> = K extends keyof I18nOptionsMap ? I18nOptionsMap[K] : never;
+declare class TypedI18n {
+    get language(): string;
+    setLang(lng: string, callback?: () => void): void;
+    setLangAsync(lng: string): Promise<i18next.TFunction<"translation", undefined>>;
+    t<K extends I18nKeysNoOptionsType>(key: K, options?: Record<string, unknown>, fallback?: string): string;
+    t<K extends I18nKeysHasOptionsType>(key: K, options: I18nOptions<K>, fallback?: string): string;
+}
+declare const I18n: TypedI18n;
+
+/**
+ * 初始化配置：已知字段 + 其余 i18next 选项（顶层透传，无需包在 extra 里）
+ */
+interface I18nConfig extends Record<string, unknown> {
+    /** 初始语言，默认 `Locale.ZhCN` */
+    lng?: SupportedLocale;
+    /** i18next 命名空间，默认 {@link DEFAULT_I18N_NAMESPACE} */
+    ns?: string;
+    /**
+     * 是否启用浏览器语言检测（querystring、localStorage、navigator）
+     * 默认 `true`
+     */
+    detect?: boolean;
+}
+/** 在 createApp / mount 之前 await 一次 */
+declare function initI18nInstance(options?: I18nConfig): Promise<void>;
+
+export { I18n, initI18nInstance };
+export type { I18nConfig };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "finovision-i18n",
+  "version": "0.1.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Simplified i18next runtime with type-safe t() (uses finovision-i18n-resource)",
+  "type": "module",
+  "main": "./dist/i18n.cjs",
+  "module": "./dist/i18n.esm.js",
+  "types": "./dist/i18n.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/i18n.d.ts",
+      "import": "./dist/i18n.esm.js",
+      "require": "./dist/i18n.cjs"
+    },
+    "./init": {
+      "types": "./dist/init.d.ts",
+      "import": "./dist/i18n.esm.js",
+      "require": "./dist/i18n.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "clean": "node -e \"import('node:fs').then(fs=>fs.rmSync('dist',{recursive:true,force:true}))\"",
+    "build": "npm run clean && cross-env NODE_ENV=production rollup -c",
+    "build:dev": "npm run clean && rollup -c",
+    "build:resource": "npm run build --prefix ../fv-i18n-resource",
+    "reinstall:resource": "npm install",
+    "pretest": "npm run build:resource && npm run reinstall:resource && npm run build:dev",
+    "test": "tsx --test test/*.test.ts",
+    "test:unit": "tsx --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "finovision-i18n-resource": "file:../fv-i18n-resource",
+    "i18next": "^23.16.0",
+    "i18next-browser-languagedetector": "^8.0.4",
+    "i18next-icu": "^2.3.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-node-resolve": "^15.3.0",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.1.0",
+    "@types/node": "^22.10.0",
+    "cross-env": "^7.0.3",
+    "rollup": "^4.27.0",
+    "rollup-plugin-dts": "^6.1.1",
+    "tslib": "^2.8.0",
+    "tsx": "^4.19.0",
+    "typescript": "~5.8.2"
+  },
+  "license": "MIT"
+}

package/src/core.ts

@@ -0,0 +1,114 @@
+import ICU from 'i18next-icu';
+import i18next, {
+  type Callback,
+  type i18n,
+  type InitOptions,
+  type Module,
+  type TFunction,
+} from 'i18next';
+
+/** i18next 实例封装，全应用共享单例 */
+export class I18nCore {
+  readonly instance: i18n;
+  private initialized = false;
+
+  constructor() {
+    this.instance = i18next.createInstance();
+    this.instance.use(ICU);
+  }
+
+  /** 是否已完成 init */
+  get isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  registerPlugins(plugins: Module[] | unknown[]): void {
+    plugins.forEach((p) => this.instance.use(p as Module));
+  }
+
+  setup(config: InitOptions): Promise<TFunction> {
+    return new Promise((resolve, reject) => {
+      this.instance.init(
+        {
+          keySeparator: false,
+          ...config,
+        },
+        (err, t) => {
+          this.initialized = !err;
+          if (err) reject(err);
+          else resolve(t);
+        },
+      );
+    });
+  }
+
+  getLanguage(): string {
+    return this.instance.language;
+  }
+
+  setLanguage(lng: string, callback?: Callback): void {
+    this.instance.changeLanguage(I18nCore.normalizeLng(lng), callback);
+  }
+
+  setLanguageAsync(lng: string): Promise<TFunction> {
+    return this.instance.changeLanguage(I18nCore.normalizeLng(lng));
+  }
+
+  /** en-US → en */
+  static normalizeLng(lng: string): string {
+    return lng === 'en-US' ? 'en' : lng;
+  }
+
+  translate(
+    key: string,
+    options?: Record<string, unknown>,
+    fallback?: string,
+  ): string {
+    if (!this.initialized) {
+      return fallback ?? key;
+    }
+    if (!key?.trim()) return '';
+    if (fallback !== undefined) {
+      return String(this.instance.t(key, fallback, options ?? {}));
+    }
+    return String(this.instance.t(key, options ?? {}));
+  }
+}
+
+/** 全局唯一 i18next 内核实例 */
+export const i18nCore = new I18nCore();
+
+/** 兼容旧版函数式 API，委托给 {@link i18nCore} */
+export function registerPlugins(plugins: Module[] | unknown[]): void {
+  i18nCore.registerPlugins(plugins);
+}
+
+export function setupI18next(config: InitOptions): Promise<TFunction> {
+  return i18nCore.setup(config);
+}
+
+export function getLanguage(): string {
+  return i18nCore.getLanguage();
+}
+
+export function setLanguage(lng: string, callback?: Callback): void {
+  i18nCore.setLanguage(lng, callback);
+}
+
+export function setLanguageAsync(lng: string): Promise<TFunction> {
+  return i18nCore.setLanguageAsync(lng);
+}
+
+export function normalizeLng(lng: string): string {
+  return I18nCore.normalizeLng(lng);
+}
+
+export function translate(
+  key: string,
+  options?: Record<string, unknown>,
+  fallback?: string,
+): string {
+  return i18nCore.translate(key, options, fallback);
+}
+
+export const i18nextInstance = i18nCore.instance;

package/src/i18n.ts

@@ -0,0 +1,50 @@
+/**
+ * 类型安全 I18n 门面（等同 Coze FlowIntl，类型来自 finovision-i18n-resource）
+ */
+import type {
+  I18nOptionsMap,
+  I18nKeysHasOptionsType,
+  I18nKeysNoOptionsType,
+  LocaleData,
+} from 'finovision-i18n-resource';
+
+import { i18nCore } from './core';
+
+type I18nOptions<K extends LocaleData> = K extends keyof I18nOptionsMap
+  ? I18nOptionsMap[K]
+  : never;
+
+class TypedI18n {
+  get language(): string {
+    return i18nCore.getLanguage();
+  }
+
+  setLang(lng: string, callback?: () => void): void {
+    i18nCore.setLanguage(lng, callback);
+  }
+
+  setLangAsync(lng: string) {
+    return i18nCore.setLanguageAsync(lng);
+  }
+
+  t<K extends I18nKeysNoOptionsType>(
+    key: K,
+    options?: Record<string, unknown>,
+    fallback?: string,
+  ): string;
+  t<K extends I18nKeysHasOptionsType>(
+    key: K,
+    options: I18nOptions<K>,
+    fallback?: string,
+  ): string;
+  t<K extends LocaleData>(
+    key: K,
+    options?: I18nOptions<K> | Record<string, unknown>,
+    fallback?: string,
+  ): string {
+    return i18nCore.translate(key, options, fallback);
+  }
+}
+
+export const I18n = new TypedI18n();
+export { TypedI18n };

package/src/index.ts

@@ -0,0 +1,32 @@
+export { I18n } from './i18n';
+export { initI18nInstance, type I18nConfig } from './init';
+export {
+  I18nCore,
+  i18nCore,
+  normalizeLng,
+  translate,
+  getLanguage,
+  setLanguage,
+  setLanguageAsync,
+  registerPlugins,
+  setupI18next,
+  i18nextInstance,
+} from './core';
+
+export type {
+  I18nOptionsMap,
+  I18nKeysHasOptionsType,
+  I18nKeysNoOptionsType,
+  LocaleData,
+  SupportedLocale,
+  InterpolationValue,
+} from 'finovision-i18n-resource';
+
+export {
+  defaultConfig,
+  DEFAULT_I18N_NAMESPACE,
+  Locale,
+  SUPPORTED_LOCALES,
+  loadLocale,
+  buildDefaultConfig,
+} from 'finovision-i18n-resource';

package/src/init.ts

@@ -0,0 +1,74 @@
+/**
+ * 应用入口初始化
+ */
+import LanguageDetector from 'i18next-browser-languagedetector';
+import {
+  defaultConfig,
+  DEFAULT_I18N_NAMESPACE,
+  Locale,
+  type SupportedLocale,
+} from 'finovision-i18n-resource';
+
+import { i18nCore } from './core';
+import { I18n } from './i18n';
+
+export type {
+  I18nKeysNoOptionsType,
+  I18nKeysHasOptionsType,
+  LocaleData,
+  I18nOptionsMap,
+  SupportedLocale,
+  Locale,
+} from 'finovision-i18n-resource';
+
+/**
+ * 初始化配置：已知字段 + 其余 i18next 选项（顶层透传，无需包在 extra 里）
+ */
+export interface I18nConfig extends Record<string, unknown> {
+  /** 初始语言，默认 `Locale.ZhCN` */
+  lng?: SupportedLocale;
+  /** i18next 命名空间，默认 {@link DEFAULT_I18N_NAMESPACE} */
+  ns?: string;
+  /**
+   * 是否启用浏览器语言检测（querystring、localStorage、navigator）
+   * 默认 `true`
+   */
+  detect?: boolean;
+}
+
+/** 在 createApp / mount 之前 await 一次 */
+export async function initI18nInstance(options?: I18nConfig): Promise<void> {
+  const {
+    lng = Locale.ZhCN,
+    detect = true,
+    ns = DEFAULT_I18N_NAMESPACE,
+    ...rest
+  } = options ?? {};
+
+  if (detect) {
+    i18nCore.registerPlugins([LanguageDetector]);
+  }
+
+  await i18nCore.setup({
+    lng,
+    fallbackLng: lng,
+    ns,
+    defaultNS: ns,
+    resources: defaultConfig,
+    ...(detect
+      ? {
+          detection: {
+            order: ['querystring', 'localStorage', 'navigator'],
+            lookupQuerystring: 'lng',
+            lookupLocalStorage: 'i18next',
+            caches: ['localStorage'],
+          },
+        }
+      : {}),
+    react: { useSuspense: false },
+    keySeparator: false,
+    ...rest,
+  });
+}
+
+export { I18n };