@wsxjs/wsx-i18next 0.0.18

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WSXJS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# @wsxjs/wsx-i18next
+
+i18next integration for WSXJS components - 为 WSXJS 组件提供 i18next 国际化支持
+
+## 安装
+
+```bash
+npm install @wsxjs/wsx-i18next i18next
+```
+
+## 快速开始
+
+### 1. 初始化 i18n
+
+```typescript
+import { initI18n } from '@wsxjs/wsx-i18next';
+
+initI18n({
+    fallbackLng: 'en',
+    resources: {
+        en: {
+            common: { hello: 'Hello' },
+        },
+        zh: {
+            common: { hello: '你好' },
+        },
+    },
+});
+```
+
+### 2. 使用装饰器（推荐）
+
+```tsx
+/** @jsxImportSource @wsxjs/wsx-core */
+import { WebComponent, autoRegister } from '@wsxjs/wsx-core';
+import { i18n } from '@wsxjs/wsx-i18next';
+
+@i18n('common')
+@autoRegister({ tagName: 'my-component' })
+export class MyComponent extends WebComponent {
+    render() {
+        return <div>{this.t('hello')}</div>;
+    }
+}
+```
+
+### 3. 使用 useTranslation + @state
+
+```tsx
+/** @jsxImportSource @wsxjs/wsx-core */
+import { LightComponent, autoRegister, state } from '@wsxjs/wsx-core';
+import { i18n, useTranslation } from '@wsxjs/wsx-i18next';
+
+@autoRegister({ tagName: 'my-component' })
+export class MyComponent extends LightComponent {
+    private translation = useTranslation('common');
+    @state private currentLang: string = i18n.language;
+    private unsubscribe?: () => void;
+
+    protected onConnected(): void {
+        this.unsubscribe = i18n.on('languageChanged', (lng) => {
+            this.currentLang = lng;
+        });
+    }
+
+    protected onDisconnected(): void {
+        if (this.unsubscribe) {
+            this.unsubscribe();
+        }
+    }
+
+    render() {
+        return <div>{this.translation.t('hello')}</div>;
+    }
+}
+```
+
+### 4. 使用 Mixin
+
+```tsx
+/** @jsxImportSource @wsxjs/wsx-core */
+import { WebComponent, autoRegister } from '@wsxjs/wsx-core';
+import { withI18n } from '@wsxjs/wsx-i18next';
+
+@autoRegister({ tagName: 'my-component' })
+export class MyComponent extends withI18n(WebComponent, 'common') {
+    render() {
+        return <div>{this.t('hello')}</div>;
+    }
+}
+```
+
+## API
+
+### initI18n(config?)
+
+初始化 i18next 实例。
+
+### i18n (装饰器)
+
+为组件自动注入翻译功能。
+
+```tsx
+@i18n('namespace')
+export class MyComponent extends WebComponent {
+    render() {
+        return <div>{this.t('key')}</div>;
+    }
+}
+```
+
+### useTranslation(namespace?)
+
+创建翻译对象，API 与 react-i18next 兼容。
+
+### withI18n(Base, defaultNamespace?)
+
+为基类添加 i18n 支持的 mixin。
+
+## 响应式机制
+
+- `@i18n` 装饰器：自动订阅语言变化并触发重渲染
+- `useTranslation` + `@state`：手动订阅，通过更新 `@state` 触发重渲染
+- `withI18n`：自动订阅语言变化并触发重渲染
+
+## 更多信息
+
+查看 [RFC-0029](../../docs/rfcs/0029-i18next-integration.md) 了解完整设计。
+

package/dist/index.d.mts

@@ -0,0 +1,114 @@
+import i18n$1, { TFunction, i18n } from 'i18next';
+export { default as i18nInstance } from 'i18next';
+import { WebComponent, LightComponent } from '@wsxjs/wsx-core';
+
+/**
+ * TypeScript 类型定义
+ */
+
+/**
+ * i18n 配置接口
+ */
+interface I18nConfig {
+    fallbackLng?: string;
+    debug?: boolean;
+    resources?: Record<string, Record<string, object>>;
+    backend?: {
+        loadPath?: string;
+    };
+    ns?: string[];
+    defaultNS?: string;
+    interpolation?: {
+        escapeValue?: boolean;
+    };
+}
+/**
+ * useTranslation 返回类型
+ */
+interface UseTranslationResponse {
+    t: TFunction;
+    i18n: i18n;
+    ready: boolean;
+}
+
+/**
+ * i18next 配置和初始化
+ */
+
+/**
+ * 初始化 i18next
+ * @param config 配置选项
+ * @returns i18n 实例
+ */
+declare function initI18n(config?: I18nConfig): typeof i18n$1;
+
+/**
+ * @i18n 装饰器 - 自动为组件注入翻译功能
+ */
+/**
+ * @i18n 装饰器 - 自动为组件注入翻译功能
+ *
+ * 使用方式：
+ * ```tsx
+ * @i18n('common')
+ * export class MyComponent extends WebComponent {
+ *     render() {
+ *         return <div>{this.t('welcome')}</div>;
+ *     }
+ * }
+ * ```
+ *
+ * @param namespace 命名空间，默认为 'common'
+ * @returns 类装饰器
+ */
+declare function i18nDecorator(namespace?: string): <T extends {
+    new (...args: any[]): any;
+}>(constructor: T) => T;
+
+/**
+ * useTranslation 函数（API 与 react-i18next 兼容）
+ */
+
+/**
+ * useTranslation - API 与 react-i18next 兼容的翻译函数
+ *
+ * **重要说明**：
+ * - 这不是 React hook，而是 WSXJS 的普通函数
+ * - API 设计参考 react-i18next，但实现方式完全不同
+ * - 在 WSXJS 中，需要配合 @state 或 @i18n 装饰器实现响应式
+ * - 不会自动响应语言变化，需要手动订阅 languageChanged 事件
+ *
+ * @param namespace 命名空间，默认为 'common'
+ * @returns 翻译对象
+ */
+declare function useTranslation(namespace?: string): UseTranslationResponse;
+
+/**
+ * Mixin API - 为基类添加 i18n 支持
+ */
+
+/**
+ * 为任何继承自 WebComponent 或 LightComponent 的类添加 i18n 支持
+ *
+ * 使用方式：
+ * ```tsx
+ * export class MyComponent extends withI18n(WebComponent, 'common') {
+ *     render() {
+ *         return <div>{this.t('welcome')}</div>;
+ *     }
+ * }
+ *
+ * export class MyLightComponent extends withI18n(LightComponent, 'common') {
+ *     render() {
+ *         return <div>{this.t('welcome')}</div>;
+ *     }
+ * }
+ * ```
+ *
+ * @param Base 基类（WebComponent 或 LightComponent）
+ * @param defaultNamespace 默认命名空间
+ * @returns 增强后的类
+ */
+declare function withI18n<T extends typeof WebComponent | typeof LightComponent>(Base: T, defaultNamespace?: string): T;
+
+export { type I18nConfig, type UseTranslationResponse, i18nDecorator as i18n, i18nDecorator, initI18n, useTranslation, withI18n };

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+import i18n$1, { TFunction, i18n } from 'i18next';
+export { default as i18nInstance } from 'i18next';
+import { WebComponent, LightComponent } from '@wsxjs/wsx-core';
+
+/**
+ * TypeScript 类型定义
+ */
+
+/**
+ * i18n 配置接口
+ */
+interface I18nConfig {
+    fallbackLng?: string;
+    debug?: boolean;
+    resources?: Record<string, Record<string, object>>;
+    backend?: {
+        loadPath?: string;
+    };
+    ns?: string[];
+    defaultNS?: string;
+    interpolation?: {
+        escapeValue?: boolean;
+    };
+}
+/**
+ * useTranslation 返回类型
+ */
+interface UseTranslationResponse {
+    t: TFunction;
+    i18n: i18n;
+    ready: boolean;
+}
+
+/**
+ * i18next 配置和初始化
+ */
+
+/**
+ * 初始化 i18next
+ * @param config 配置选项
+ * @returns i18n 实例
+ */
+declare function initI18n(config?: I18nConfig): typeof i18n$1;
+
+/**
+ * @i18n 装饰器 - 自动为组件注入翻译功能
+ */
+/**
+ * @i18n 装饰器 - 自动为组件注入翻译功能
+ *
+ * 使用方式：
+ * ```tsx
+ * @i18n('common')
+ * export class MyComponent extends WebComponent {
+ *     render() {
+ *         return <div>{this.t('welcome')}</div>;
+ *     }
+ * }
+ * ```
+ *
+ * @param namespace 命名空间，默认为 'common'
+ * @returns 类装饰器
+ */
+declare function i18nDecorator(namespace?: string): <T extends {
+    new (...args: any[]): any;
+}>(constructor: T) => T;
+
+/**
+ * useTranslation 函数（API 与 react-i18next 兼容）
+ */
+
+/**
+ * useTranslation - API 与 react-i18next 兼容的翻译函数
+ *
+ * **重要说明**：
+ * - 这不是 React hook，而是 WSXJS 的普通函数
+ * - API 设计参考 react-i18next，但实现方式完全不同
+ * - 在 WSXJS 中，需要配合 @state 或 @i18n 装饰器实现响应式
+ * - 不会自动响应语言变化，需要手动订阅 languageChanged 事件
+ *
+ * @param namespace 命名空间，默认为 'common'
+ * @returns 翻译对象
+ */
+declare function useTranslation(namespace?: string): UseTranslationResponse;
+
+/**
+ * Mixin API - 为基类添加 i18n 支持
+ */
+
+/**
+ * 为任何继承自 WebComponent 或 LightComponent 的类添加 i18n 支持
+ *
+ * 使用方式：
+ * ```tsx
+ * export class MyComponent extends withI18n(WebComponent, 'common') {
+ *     render() {
+ *         return <div>{this.t('welcome')}</div>;
+ *     }
+ * }
+ *
+ * export class MyLightComponent extends withI18n(LightComponent, 'common') {
+ *     render() {
+ *         return <div>{this.t('welcome')}</div>;
+ *     }
+ * }
+ * ```
+ *
+ * @param Base 基类（WebComponent 或 LightComponent）
+ * @param defaultNamespace 默认命名空间
+ * @returns 增强后的类
+ */
+declare function withI18n<T extends typeof WebComponent | typeof LightComponent>(Base: T, defaultNamespace?: string): T;
+
+export { type I18nConfig, type UseTranslationResponse, i18nDecorator as i18n, i18nDecorator, initI18n, useTranslation, withI18n };

package/dist/index.js

@@ -0,0 +1,172 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  i18n: () => i18nDecorator,
+  i18nDecorator: () => i18nDecorator,
+  i18nInstance: () => import_i18next.default,
+  initI18n: () => initI18n,
+  useTranslation: () => useTranslation,
+  withI18n: () => withI18n
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/i18n.ts
+var import_i18next = __toESM(require("i18next"));
+var import_i18next_browser_languagedetector = __toESM(require("i18next-browser-languagedetector"));
+var import_i18next_http_backend = __toESM(require("i18next-http-backend"));
+function initI18n(config = {}) {
+  import_i18next.default.use(import_i18next_http_backend.default).use(import_i18next_browser_languagedetector.default).init({
+    fallbackLng: "en",
+    debug: false,
+    interpolation: {
+      escapeValue: false
+    },
+    backend: {
+      loadPath: "/locales/{{lng}}/{{ns}}.json"
+    },
+    ns: ["common", "home", "docs", "examples"],
+    defaultNS: "common",
+    ...config
+  });
+  return import_i18next.default;
+}
+
+// src/decorator.ts
+function i18nDecorator(namespace = "common") {
+  return function(constructor) {
+    class I18nEnhanced extends constructor {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      constructor(...args) {
+        super(...args);
+        this._i18nNamespace = namespace;
+      }
+      // 注入 t 方法
+      t(key, options) {
+        return import_i18next.default.t(key, { ns: this._i18nNamespace, ...options });
+      }
+      // 注入 i18n 实例
+      get i18n() {
+        return import_i18next.default;
+      }
+      // 生命周期：组件连接时订阅语言变化
+      onConnected() {
+        super.onConnected?.();
+        const handler = () => {
+          if (this.rerender) {
+            this.rerender();
+          }
+        };
+        this._languageChangedHandler = handler;
+        const unsubscribe = import_i18next.default.on("languageChanged", handler);
+        if (typeof unsubscribe === "function") {
+          this._i18nUnsubscribe = unsubscribe;
+        } else {
+          this._i18nUnsubscribe = () => {
+            if (typeof import_i18next.default.off === "function") {
+              import_i18next.default.off("languageChanged", handler);
+            }
+          };
+        }
+      }
+      // 生命周期：组件断开时取消订阅
+      onDisconnected() {
+        if (this._i18nUnsubscribe && typeof this._i18nUnsubscribe === "function") {
+          try {
+            this._i18nUnsubscribe();
+          } catch {
+            const handler = this._languageChangedHandler;
+            if (handler && typeof import_i18next.default.off === "function") {
+              import_i18next.default.off("languageChanged", handler);
+            }
+          }
+          this._i18nUnsubscribe = void 0;
+        } else {
+          const handler = this._languageChangedHandler;
+          if (handler && typeof import_i18next.default.off === "function") {
+            import_i18next.default.off("languageChanged", handler);
+          }
+        }
+        if (this._languageChangedHandler) {
+          delete this._languageChangedHandler;
+        }
+        super.onDisconnected?.();
+      }
+    }
+    Object.setPrototypeOf(I18nEnhanced, constructor);
+    Object.defineProperty(I18nEnhanced, "name", {
+      value: constructor.name,
+      writable: false
+    });
+    return I18nEnhanced;
+  };
+}
+
+// src/hooks.ts
+function useTranslation(namespace = "common") {
+  const t = (key, options) => {
+    return import_i18next.default.t(key, { ns: namespace, ...options });
+  };
+  return {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    t,
+    i18n: import_i18next.default,
+    ready: import_i18next.default.isInitialized
+  };
+}
+
+// src/mixin.ts
+function withI18n(Base, defaultNamespace = "common") {
+  return class extends Base {
+    t(key, namespace, options) {
+      return import_i18next.default.t(key, { ns: namespace || defaultNamespace, ...options });
+    }
+    get i18n() {
+      return import_i18next.default;
+    }
+    onConnected() {
+      import_i18next.default.on("languageChanged", () => {
+        if (this.rerender) {
+          this.rerender();
+        }
+      });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  i18n,
+  i18nDecorator,
+  i18nInstance,
+  initI18n,
+  useTranslation,
+  withI18n
+});

package/dist/index.mjs

@@ -0,0 +1,130 @@
+// src/i18n.ts
+import i18n from "i18next";
+import LanguageDetector from "i18next-browser-languagedetector";
+import Backend from "i18next-http-backend";
+function initI18n(config = {}) {
+  i18n.use(Backend).use(LanguageDetector).init({
+    fallbackLng: "en",
+    debug: false,
+    interpolation: {
+      escapeValue: false
+    },
+    backend: {
+      loadPath: "/locales/{{lng}}/{{ns}}.json"
+    },
+    ns: ["common", "home", "docs", "examples"],
+    defaultNS: "common",
+    ...config
+  });
+  return i18n;
+}
+
+// src/decorator.ts
+function i18nDecorator(namespace = "common") {
+  return function(constructor) {
+    class I18nEnhanced extends constructor {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      constructor(...args) {
+        super(...args);
+        this._i18nNamespace = namespace;
+      }
+      // 注入 t 方法
+      t(key, options) {
+        return i18n.t(key, { ns: this._i18nNamespace, ...options });
+      }
+      // 注入 i18n 实例
+      get i18n() {
+        return i18n;
+      }
+      // 生命周期：组件连接时订阅语言变化
+      onConnected() {
+        super.onConnected?.();
+        const handler = () => {
+          if (this.rerender) {
+            this.rerender();
+          }
+        };
+        this._languageChangedHandler = handler;
+        const unsubscribe = i18n.on("languageChanged", handler);
+        if (typeof unsubscribe === "function") {
+          this._i18nUnsubscribe = unsubscribe;
+        } else {
+          this._i18nUnsubscribe = () => {
+            if (typeof i18n.off === "function") {
+              i18n.off("languageChanged", handler);
+            }
+          };
+        }
+      }
+      // 生命周期：组件断开时取消订阅
+      onDisconnected() {
+        if (this._i18nUnsubscribe && typeof this._i18nUnsubscribe === "function") {
+          try {
+            this._i18nUnsubscribe();
+          } catch {
+            const handler = this._languageChangedHandler;
+            if (handler && typeof i18n.off === "function") {
+              i18n.off("languageChanged", handler);
+            }
+          }
+          this._i18nUnsubscribe = void 0;
+        } else {
+          const handler = this._languageChangedHandler;
+          if (handler && typeof i18n.off === "function") {
+            i18n.off("languageChanged", handler);
+          }
+        }
+        if (this._languageChangedHandler) {
+          delete this._languageChangedHandler;
+        }
+        super.onDisconnected?.();
+      }
+    }
+    Object.setPrototypeOf(I18nEnhanced, constructor);
+    Object.defineProperty(I18nEnhanced, "name", {
+      value: constructor.name,
+      writable: false
+    });
+    return I18nEnhanced;
+  };
+}
+
+// src/hooks.ts
+function useTranslation(namespace = "common") {
+  const t = (key, options) => {
+    return i18n.t(key, { ns: namespace, ...options });
+  };
+  return {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    t,
+    i18n,
+    ready: i18n.isInitialized
+  };
+}
+
+// src/mixin.ts
+function withI18n(Base, defaultNamespace = "common") {
+  return class extends Base {
+    t(key, namespace, options) {
+      return i18n.t(key, { ns: namespace || defaultNamespace, ...options });
+    }
+    get i18n() {
+      return i18n;
+    }
+    onConnected() {
+      i18n.on("languageChanged", () => {
+        if (this.rerender) {
+          this.rerender();
+        }
+      });
+    }
+  };
+}
+export {
+  i18nDecorator as i18n,
+  i18nDecorator,
+  i18n as i18nInstance,
+  initI18n,
+  useTranslation,
+  withI18n
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@wsxjs/wsx-i18next",
+  "version": "0.0.18",
+  "description": "i18next integration for WSXJS components",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wsxjs/wsxjs.git",
+    "directory": "packages/wsx-i18next"
+  },
+  "author": "Albert Li <albert.li@wsxjs.com>",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "src",
+    "!**/__tests__",
+    "!**/test"
+  ],
+  "keywords": [
+    "wsx",
+    "i18next",
+    "i18n",
+    "internationalization",
+    "web-components",
+    "typescript"
+  ],
+  "dependencies": {
+    "i18next": "^23.0.0",
+    "i18next-browser-languagedetector": "^7.0.0",
+    "i18next-http-backend": "^2.0.0",
+    "@wsxjs/wsx-core": "0.0.18"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "i18next": "^23.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --tsconfig tsconfig.json",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch --tsconfig tsconfig.json",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist coverage"
+  }
+}

package/src/decorator.ts

@@ -0,0 +1,125 @@
+/**
+ * @i18n 装饰器 - 自动为组件注入翻译功能
+ */
+
+import { i18n } from "./i18n";
+
+/**
+ * @i18n 装饰器 - 自动为组件注入翻译功能
+ *
+ * 使用方式：
+ * ```tsx
+ * @i18n('common')
+ * export class MyComponent extends WebComponent {
+ *     render() {
+ *         return <div>{this.t('welcome')}</div>;
+ *     }
+ * }
+ * ```
+ *
+ * @param namespace 命名空间，默认为 'common'
+ * @returns 类装饰器
+ */
+export function i18nDecorator(namespace: string = "common") {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return function <T extends { new (...args: any[]): any }>(constructor: T) {
+        class I18nEnhanced extends constructor {
+            // 使用 public 而不是 private，因为导出的匿名类类型限制
+            public _i18nNamespace!: string;
+            public _i18nUnsubscribe?: () => void;
+
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            constructor(...args: any[]) {
+                super(...args);
+                // 初始化命名空间
+                this._i18nNamespace = namespace;
+            }
+
+            // 注入 t 方法
+            public t(key: string, options?: object): string {
+                return i18n.t(key, { ns: this._i18nNamespace, ...options });
+            }
+
+            // 注入 i18n 实例
+            public get i18n() {
+                return i18n;
+            }
+
+            // 生命周期：组件连接时订阅语言变化
+            public onConnected(): void {
+                // 先调用父类的 onConnected（如果存在）
+                super.onConnected?.();
+
+                // 创建回调函数并保存引用，以便后续取消订阅
+                const handler = (() => {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    if ((this as any).rerender) {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        (this as any).rerender();
+                    }
+                }) as () => void;
+
+                // 保存回调引用以便取消订阅
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                (this as any)._languageChangedHandler = handler;
+
+                // 订阅语言变化事件
+                const unsubscribe = i18n.on("languageChanged", handler);
+
+                // 如果返回的是函数，直接使用；否则使用 off 方法
+                if (typeof unsubscribe === "function") {
+                    this._i18nUnsubscribe = unsubscribe;
+                } else {
+                    // 如果 i18n.on 返回的不是函数，创建一个取消订阅函数
+                    // 使用 off 方法（如果可用）或空函数
+                    this._i18nUnsubscribe = () => {
+                        if (typeof i18n.off === "function") {
+                            i18n.off("languageChanged", handler);
+                        }
+                    };
+                }
+            }
+
+            // 生命周期：组件断开时取消订阅
+            public onDisconnected(): void {
+                // 取消 i18n 订阅
+                if (this._i18nUnsubscribe && typeof this._i18nUnsubscribe === "function") {
+                    try {
+                        this._i18nUnsubscribe();
+                    } catch {
+                        // 如果 unsubscribe 调用失败，尝试使用 off 方法（如果可用）
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const handler = (this as any)._languageChangedHandler;
+                        if (handler && typeof i18n.off === "function") {
+                            i18n.off("languageChanged", handler);
+                        }
+                    }
+                    this._i18nUnsubscribe = undefined;
+                } else {
+                    // 如果 unsubscribe 不是函数，尝试使用 off 方法（如果可用）
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const handler = (this as any)._languageChangedHandler;
+                    if (handler && typeof i18n.off === "function") {
+                        i18n.off("languageChanged", handler);
+                    }
+                }
+                // 清理回调引用
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                if ((this as any)._languageChangedHandler) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    delete (this as any)._languageChangedHandler;
+                }
+
+                // 调用父类的 onDisconnected（如果存在）
+                super.onDisconnected?.();
+            }
+        }
+        // 复制静态属性和方法
+        Object.setPrototypeOf(I18nEnhanced, constructor);
+        Object.defineProperty(I18nEnhanced, "name", {
+            value: constructor.name,
+            writable: false,
+        });
+        return I18nEnhanced as T;
+    };
+}

package/src/hooks.ts

@@ -0,0 +1,33 @@
+/**
+ * useTranslation 函数（API 与 react-i18next 兼容）
+ */
+
+import { i18n } from "./i18n";
+import type { UseTranslationResponse } from "./types";
+
+/**
+ * useTranslation - API 与 react-i18next 兼容的翻译函数
+ *
+ * **重要说明**：
+ * - 这不是 React hook，而是 WSXJS 的普通函数
+ * - API 设计参考 react-i18next，但实现方式完全不同
+ * - 在 WSXJS 中，需要配合 @state 或 @i18n 装饰器实现响应式
+ * - 不会自动响应语言变化，需要手动订阅 languageChanged 事件
+ *
+ * @param namespace 命名空间，默认为 'common'
+ * @returns 翻译对象
+ */
+export function useTranslation(namespace: string = "common"): UseTranslationResponse {
+    // 创建一个包装函数，保持 API 兼容性
+    const t = (key: string, options?: object): string => {
+        // 每次调用 t() 时，i18n.t() 会使用当前的 i18n.language
+        // 所以只要组件重渲染，就会得到新的翻译
+        return i18n.t(key, { ns: namespace, ...options });
+    };
+    return {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        t: t as any,
+        i18n,
+        ready: i18n.isInitialized,
+    };
+}

package/src/i18n.ts

@@ -0,0 +1,35 @@
+/**
+ * i18next 配置和初始化
+ */
+
+import i18n from "i18next";
+import LanguageDetector from "i18next-browser-languagedetector";
+import Backend from "i18next-http-backend";
+import type { I18nConfig } from "./types";
+
+/**
+ * 初始化 i18next
+ * @param config 配置选项
+ * @returns i18n 实例
+ */
+export function initI18n(config: I18nConfig = {}): typeof i18n {
+    i18n.use(Backend)
+        .use(LanguageDetector)
+        .init({
+            fallbackLng: "en",
+            debug: false,
+            interpolation: {
+                escapeValue: false,
+            },
+            backend: {
+                loadPath: "/locales/{{lng}}/{{ns}}.json",
+            },
+            ns: ["common", "home", "docs", "examples"],
+            defaultNS: "common",
+            ...config,
+        });
+
+    return i18n;
+}
+
+export { i18n };

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @wsxjs/wsx-i18next - i18next integration for WSXJS components
+ *
+ * 为 WSXJS 组件提供 i18next 国际化支持
+ */
+
+// 导出 i18n 实例和初始化函数
+import { i18n as i18nInstance, initI18n } from "./i18n";
+export { i18nInstance, initI18n };
+
+// 导出装饰器（使用 i18n 作为装饰器名称，方便使用）
+import { i18nDecorator } from "./decorator";
+export { i18nDecorator as i18n, i18nDecorator };
+
+// 导出 hooks
+export { useTranslation } from "./hooks";
+
+// 导出 mixin
+export { withI18n } from "./mixin";
+
+// 导出类型
+export type { I18nConfig, UseTranslationResponse } from "./types";

package/src/mixin.ts

@@ -0,0 +1,54 @@
+/**
+ * Mixin API - 为基类添加 i18n 支持
+ */
+
+import { i18n } from "./i18n";
+import type { WebComponent, LightComponent } from "@wsxjs/wsx-core";
+
+/**
+ * 为任何继承自 WebComponent 或 LightComponent 的类添加 i18n 支持
+ *
+ * 使用方式：
+ * ```tsx
+ * export class MyComponent extends withI18n(WebComponent, 'common') {
+ *     render() {
+ *         return <div>{this.t('welcome')}</div>;
+ *     }
+ * }
+ *
+ * export class MyLightComponent extends withI18n(LightComponent, 'common') {
+ *     render() {
+ *         return <div>{this.t('welcome')}</div>;
+ *     }
+ * }
+ * ```
+ *
+ * @param Base 基类（WebComponent 或 LightComponent）
+ * @param defaultNamespace 默认命名空间
+ * @returns 增强后的类
+ */
+export function withI18n<T extends typeof WebComponent | typeof LightComponent>(
+    Base: T,
+    defaultNamespace: string = "common"
+): T {
+    return class extends Base {
+        protected t(key: string, namespace?: string, options?: object): string {
+            return i18n.t(key, { ns: namespace || defaultNamespace, ...options });
+        }
+
+        protected get i18n() {
+            return i18n;
+        }
+
+        protected onConnected(): void {
+            // 订阅语言变化事件，自动触发重渲染
+            i18n.on("languageChanged", () => {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                if ((this as any).rerender) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    (this as any).rerender();
+                }
+            });
+        }
+    } as T;
+}

package/src/types.ts

@@ -0,0 +1,31 @@
+/**
+ * TypeScript 类型定义
+ */
+
+import type { TFunction, i18n as I18nType } from "i18next";
+
+/**
+ * i18n 配置接口
+ */
+export interface I18nConfig {
+    fallbackLng?: string;
+    debug?: boolean;
+    resources?: Record<string, Record<string, object>>;
+    backend?: {
+        loadPath?: string;
+    };
+    ns?: string[];
+    defaultNS?: string;
+    interpolation?: {
+        escapeValue?: boolean;
+    };
+}
+
+/**
+ * useTranslation 返回类型
+ */
+export interface UseTranslationResponse {
+    t: TFunction;
+    i18n: I18nType;
+    ready: boolean;
+}