gc_i18n 1.5.10 → 1.5.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gc_i18n",
-  "version": "1.5.10",
+  "version": "1.5.11",
   "type": "module",
   "main": "./lib/gc_i18n.umd.js",
   "module": "./lib/gc_i18n.es.js",
@@ -8,13 +8,27 @@
     ".": {
       "import": "./lib/gc_i18n.es.js",
       "require": "./lib/gc_i18n.umd.js"
-    }
+    },
+    "./gc_i18n.css": "./lib/gc_i18n.css",
+    "./style.css": "./lib/gc_i18n.css",
+    "./lib/gc_i18n.css": "./lib/gc_i18n.css"
   },
+  "files": [
+    "lib",
+    "lang",
+    "packages"
+  ],
+  "sideEffects": [
+    "*.css",
+    "**/*.css"
+  ],
   "scripts": {
     "dev": "vite",
     "dev:unit": "vite --mode unit --port 8080",
     "dev:template": "vite --mode template --port 8081",
     "build": "vite build",
+    "verify:package": "node scripts/verify-package.cjs",
+    "prepack": "pnpm build && pnpm verify:package",
     "preview": "vite preview",
     "cnpm": "cnpm sync gc_i18n"
   },

package/.qoder/repowiki/zh/content/API /345/217/202/350/200/203.md"

@@ -1,585 +0,0 @@
-# API 参考
-
-<cite>
-**本文档中引用的文件**   
-- [package.json](file://package.json) - *版本信息，从1.4.3升级到1.4.4*
-- [packages/index.js](file://packages/index.js) - *库的入口点，包含初始化逻辑和setRouter方法*
-- [lib/gc_i18n.es.js](file://lib/gc_i18n.es.js) - *在最近的提交中更新，包含setRouter方法*
-- [i18nUtils.ts](file://packages/libs/i18nUtils.ts) - *在最近的提交中更新*
-- [service.js](file://packages/libs/service.js) - *在最近的提交中更新，包含关键逻辑变更*
-- [utils.js](file://packages/libs/utils.js) - *在最近的提交中更新，包含 mergeArraysByKey 函数*
-- [src/main.js](file://src/main.js) - *应用入口，展示如何集成gc_i18n*
-- [src/router/index.js](file://src/router/index.js) - *路由配置示例*
-</cite>
-
-## 更新摘要
-**变更内容**   
-- 版本从 1.4.3 升级到 1.4.4
-- 新增 `setRouter` 方法，支持延迟设置Vue Router实例
-- 增强的路由守卫功能，自动集成模态框关闭和翻译键收集
-- 更新了 `packages/index.js` 中路由守卫的 `closeModal` 功能集成
-- 更新了 `gc_i18n.es.js` 中 `$t` 方法的文档，详细说明了其新的查找优先级
-- 更新了 `utils.js` 中 `mergeArraysByKey` 函数的文档
-- 修正了 `service.js` 中 `fetchTranslate` 和 `getTranslate` 方法的返回值描述
-- 更新了所有受影响部分的源代码引用，以反映最新的文件状态
-
-## 目录
-1. [简介](#简介)
-2. [核心 API 概述](#核心-api-概述)
-3. [packages/index.js 公共方法](#packagesindexjs-公共方法)
-4. [lib/gc_i18n.es.js 公共方法](#libgc_i18nesjs-公共方法)
-5. [i18nUtils.ts 工具函数](#i18nutilsts-工具函数)
-6. [service.js 异步接口](#servicesjs-异步接口)
-7. [使用示例与最佳实践](#使用示例与最佳实践)
-8. [错误处理与限制](#错误处理与限制)
-
-## 简介
-本 API 参考文档详细描述了 `gc_i18n` 国际化库的核心功能与接口。文档涵盖 `packages/index.js` 和 `lib/gc_i18n.es.js` 暴露的公共方法、`i18nUtils.ts` 中的工具函数以及 `service.js` 提供的异步服务接口。目标是为开发者提供一份全面、准确且易于理解的参考，以支持国际化功能的集成与开发。
-
-## 核心 API 概述
-`gc_i18n` 库通过 Vue 3 的插件机制提供国际化支持。其核心功能包括：
-- **翻译功能**：通过 `$t` 方法在模板或代码中获取翻译文本。
-- **语言切换**：通过 `$changeLocale` 方法动态切换当前语言环境。
-- **路由器集成**：通过 `setRouter` 方法设置Vue Router实例，自动初始化路由守卫。
-- **语言包管理**：通过 `service.js` 提供的接口从后端获取和更新翻译资源。
-- **工具支持**：提供静态分析工具函数，用于提取项目中的翻译键。
-- **模态框关闭**：通过 `closeModal` 方法统一管理 SweetAlert2 模态框的关闭。
-
-**Section sources**
-- [packages/index.js](file://packages/index.js)
-- [lib/gc_i18n.es.js](file://lib/gc_i18n.es.js)
-- [service.js](file://packages/libs/service.js)
-- [i18nUtils.ts](file://packages/libs/i18nUtils.ts)
-
-## packages/index.js 公共方法
-`packages/index.js` 作为库的主要入口点，提供了完整的国际化功能实现。该类通过构造函数接收配置选项，并提供多种公共方法供开发者使用。
-
-### 构造函数 (I18n)
-构造函数初始化国际化实例，支持多种配置选项。
-
-**方法签名**
-```typescript
-constructor(options?: {
-  router?: any;
-  appCode?: string;
-  messages?: Record<string, any>;
-  token?: string;
-  orgCode?: string;
-  loginRouteName?: string;
-  login?: boolean;
-  keyboard?: string;
-  locale?: string;
-  env?: string;
-  dev?: boolean;
-})
-```
-
-**参数**
-- **router**: `any` (可选) - Vue Router 实例，允许延迟设置
-- **appCode**: `string` (可选) - 应用唯一标识码
-- **messages**: `Record<string, any>` (可选) - 本地消息覆盖
-- **token**: `string` (可选) - 认证令牌
-- **orgCode**: `string` (可选) - 组织代码，用于生成JWT
-- **loginRouteName**: `string` (可选, 默认: `"login"`) - 登录路由名称
-- **login**: `boolean` (可选) - 是否启用登录功能
-- **keyboard**: `string` (可选, 默认: `"ctrl+shift+l"`) - 快捷键配置
-- **locale**: `string` (可选) - 默认语言环境
-- **env**: `string` (可选) - 环境配置 (`"dev"|"local"|其他"`)
-- **dev**: `boolean` (可选) - 开发模式开关
-
-**返回值**
-- `I18n` - 初始化后的国际化实例
-
-**使用示例**
-```javascript
-import I18n from 'gc_i18n';
-
-const i18n = new I18n({
-  appCode: 'YOUR_APP_CODE',
-  router: vueRouter,
-  locale: 'zh-CN'
-});
-```
-
-**Section sources**
-- [packages/index.js:81-139](file://packages/index.js#L81-L139)
-
-### setRouter (设置路由器)
-设置Vue Router实例，支持延迟设置。该方法会自动初始化路由守卫。
-
-**方法签名**
-```typescript
-setRouter(router: any): I18n
-```
-
-**参数**
-- **router**: `any` - Vue Router 实例
-
-**返回值**
-- `I18n` - 返回当前实例，支持链式调用
-
-**副作用**
-- 设置 `this.router` 属性
-- 调用 `initRouterGuards()` 初始化路由守卫
-- 支持链式调用返回当前实例
-
-**使用限制**
-- 该方法支持延迟设置，即可以在实例创建后任意时间设置router
-- 如果router已经存在，会直接初始化路由守卫
-- 返回当前实例，便于链式调用
-
-**错误处理建议**
-- 确保传入的router是有效的Vue Router实例
-- 在调用前检查router实例的状态
-- 如需重新初始化，可再次调用此方法
-
-**Section sources**
-- [packages/index.js:221-230](file://packages/index.js#L221-L230)
-
-### initRouterGuards (初始化路由守卫)
-初始化路由守卫，自动处理模态框关闭、翻译键收集和语言切换。
-
-**方法签名**
-```typescript
-initRouterGuards(): void
-```
-
-**参数**
-- 无参数
-
-**返回值**
-- `void` - 无返回值
-
-**副作用**
-- 注册 `beforeEach` 和 `afterEach` 路由守卫
-- 自动关闭 SweetAlert2 弹窗
-- 收集翻译键并更新 `translationKeys`
-- 设置当前路由名称
-- 更新 `I18N_CONFIG` 中的 `routerName`
-
-**增强功能**
-- **自动模态框管理**：在路由切换时自动调用 `closeModal()`
-- **翻译键收集**：自动收集当前页面使用的翻译键
-- **异步组件支持**：支持动态导入的异步组件
-- **登录路由检测**：自动识别登录路由并收集特殊翻译键
-- **路由名称跟踪**：维护当前路由名称以便 `$t` 方法使用
-
-**使用限制**
-- 仅在 `router` 存在时执行
-- 防止重复注册路由守卫
-- 处理异步组件加载错误
-
-**错误处理建议**
-- 捕获异步组件加载异常
-- 处理路由守卫注册冲突
-- 确保 `configInstance` 存在时才调用 `closeModal()`
-
-**Section sources**
-- [packages/index.js:232-335](file://packages/index.js#L232-L335)
-
-## lib/gc_i18n.es.js 公共方法
-`lib/gc_i18n.es.js` 作为库的核心，通过向 Vue 应用实例的 `config.globalProperties` 挂载方法来暴露其公共 API。这些方法在 Vue 组件的模板和 `setup` 函数中均可直接使用。
-
-### $t (翻译方法)
-此方法用于根据给定的键（key）查找并返回对应的翻译文本。
-
-**方法签名**
-```typescript
-$t(key: string, defaultValue?: string): string
-```
-
-**参数**
-- **key**: `string` - 翻译资源的唯一标识符
-- **defaultValue**: `string` (可选) - 当翻译不存在时的默认值
-
-**返回值**
-- `string` - 与 `key` 对应的翻译文本。如果未找到匹配的翻译，则返回原始 `key`。
-
-**副作用**
-- 无直接副作用。其行为依赖于当前激活的语言环境和已加载的翻译资源。
-- 在内部，它会将 `key` 记录到 `translationKeySet` 中，用于后续的翻译键收集。
-
-**查找优先级**
-该方法的查找逻辑已更新，优先级为：
-1. `当前路由名.key` - 首选，针对特定路由的翻译
-2. `common.key` - 次选，通用翻译
-3. `key` - 最后选择，基础翻译
-
-**使用限制**
-- `key` 必须是字符串类型。
-- 该方法依赖于 `init` 过程中加载的语言包，若语言包未正确加载，可能返回不准确的翻译。
-
-**错误处理建议**
-- 在调用 `$t` 前，确保 `init` 过程已完成。
-- 在开发环境中，检查控制台日志以确认是否存在未找到的翻译键。
-
-**Section sources**
-- [lib/gc_i18n.es.js:2954-2971](file://lib/gc_i18n.es.js#L2954-L2971)
-
-### $changeLocale (切换语言方法)
-此方法用于动态更改当前应用的语言环境。
-
-**方法签名**
-```typescript
-$changeLocale(locale: string): Promise<void>
-```
-
-**参数**
-- **locale**: `string` - 目标语言环境的代码，例如 `"en-US"` 或 `"zh-CN"`。
-
-**返回值**
-- `Promise<void>` - 一个 Promise，当语言环境切换完成并重新加载相关资源后 resolve。
-
-**副作用**
-- 触发应用的重新渲染，以反映新的语言环境。
-- 发起网络请求以获取新的语言包。
-- 更新 `store2` 中的 `I18N_LANGUAGE` 值。
-
-**使用限制**
-- `locale` 必须是 `availableLocales` 数组中包含的有效语言代码。
-- 频繁调用可能导致性能下降。
-
-**错误处理建议**
-- 使用 `try-catch` 包裹异步调用，以捕获可能的网络错误。
-- 提供用户友好的错误提示，例如"切换语言失败，请稍后重试"。
-
-**Section sources**
-- [lib/gc_i18n.es.js:2979-2981](file://lib/gc_i18n.es.js#L2979-L2981)
-
-### closeModal (关闭模态框方法)
-此方法用于统一关闭 SweetAlert2 弹窗，确保模态框的正确销毁和资源清理。
-
-**方法签名**
-```typescript
-closeModal(): void
-```
-
-**参数**
-- 无参数
-
-**返回值**
-- `void` - 无返回值
-
-**副作用**
-- 关闭当前显示的 SweetAlert2 弹窗
-- 清理弹窗相关的事件监听器和 DOM 元素
-- 触发 `willClose` 和 `didClose` 事件回调
-- 释放内存资源，防止内存泄漏
-
-**使用限制**
-- 仅在 SweetAlert2 弹窗处于激活状态时有效
-- 调用后会触发弹窗的销毁流程，无法恢复
-
-**错误处理建议**
-- 确保在调用前检查弹窗是否已激活
-- 监听 `willClose` 和 `didClose` 事件以处理关闭后的逻辑
-- 在路由切换时自动调用此方法，避免弹窗残留
-
-**Section sources**
-- [lib/gc_i18n.es.js:1340-1350](file://lib/gc_i18n.es.js#L1340-L1350)
-
-## i18nUtils.ts 工具函数
-`i18nUtils.ts` 文件提供了一个用于静态分析的工具函数，帮助开发者管理和审计翻译资源。
-
-### extractTranslationKeys (提取翻译键)
-此函数用于从 Vue 组件定义中提取所有使用的 `$t` 函数的键。
-
-**TypeScript 签名**
-```typescript
-function extractTranslationKeys(component: any): string[]
-```
-
-**参数**
-- **component**: `any` - 一个 Vue 组件的选项对象，通常包含 `template`, `render`, `setup`, `methods` 等属性。
-
-**返回值**
-- `string[]` - 一个包含所有唯一翻译键的字符串数组。
-
-**实现细节**
-- 该函数使用正则表达式 `/(\$t|_ctx\.\$t)\s*$$\s*(['"])([^'"]+?)\1/gs` 来匹配代码中 `$t(...)` 或 `_ctx.$t(...)` 的调用。
-- 它会递归地解析组件的 `template`、`render` 函数、`setup` 函数、`methods` 以及嵌套的子组件，以确保不遗漏任何翻译键。
-- 最终结果通过 `Set` 去重，保证返回的键数组是唯一的。
-
-**使用场景**
-- 构建工具中，用于生成缺失翻译键的报告。
-- 开发者手动检查组件，以确保所有翻译键都已定义。
-
-**Section sources**
-- [i18nUtils.ts:1-54](file://packages/libs/i18nUtils.ts#L1-L54)
-
-## service.js 异步接口
-`service.js` 封装了与后端语言服务通信的异步接口，负责获取和管理翻译数据。
-
-### getLanguagesWithCache (获取支持的语言列表 - 带缓存)
-获取系统支持的所有语言环境列表，并提供本地缓存功能。
-
-**方法签名**
-```typescript
-getLanguagesWithCache({ baseUrl, token, appCode, isRemote }: { 
-  baseUrl: string; 
-  token: string; 
-  appCode: string; 
-  isRemote?: boolean; 
-}): Promise<any[]>
-```
-
-**参数**
-- **baseUrl**: `string` - 后端服务的基础 URL。
-- **token**: `string` - 用于身份验证的授权令牌。
-- **appCode**: `string` - 应用的唯一标识码。
-- **isRemote**: `boolean` (可选, 默认: `false`) - 是否强制从远程获取，跳过缓存。
-
-**返回值**
-- `Promise<any[]>` - 一个 Promise，resolve 时返回包含支持语言列表的数组。每个语言对象包含 `langCode` 和 `langName` 字段。
-
-**副作用**
-- 读取和写入本地存储（`store2`），以缓存语言列表。
-- 可能发起网络请求。
-
-**使用限制**
-- 依赖于 `store2` 和 `lodash-es` 库。
-- 当 `isRemote` 为 `false` 且缓存存在时，不会发起网络请求。
-
-**错误处理建议**
-- 确保 `store2` 正常工作，本地存储空间充足。
-- 处理网络请求失败的情况，提供降级方案（如使用缓存数据）。
-
-**Section sources**
-- [service.js:19-61](file://packages/libs/service.js#L19-L61)
-
-### getLanguages (获取支持的语言列表)
-获取系统支持的所有语言环境列表。
-
-**方法签名**
-```typescript
-getLanguages({ baseUrl, token, appCode }: { baseUrl: string; token: string; appCode: string }): Promise<any>
-```
-
-**参数**
-- **baseUrl**: `string` - 后端服务的基础 URL。
-- **token**: `string` - 用于身份验证的授权令牌。
-- **appCode**: `string` - 应用的唯一标识码。
-
-**返回值**
-- `Promise<any>` - 一个 Promise，resolve 时返回包含支持语言列表的响应对象。
-
-**Section sources**
-- [service.js:63-72](file://packages/libs/service.js#L63-L72)
-
-### fetchTranslate (获取翻译数据)
-根据应用代码、语言等信息，从后端获取翻译数据。
-
-**方法签名**
-```typescript
-fetchTranslate({ appCode, language, lastPullDate, baseUrl, token }: { 
-  appCode: string; 
-  language?: string; 
-  lastPullDate?: string; 
-  baseUrl: string; 
-  token: string; 
-}): Promise<any>
-```
-
-**参数**
-- **appCode**: `string` - 应用的唯一标识码。
-- **language**: `string` (可选, 默认: `"zh-CN"`) - 目标语言。
-- **lastPullDate**: `string` (可选) - 上次拉取数据的时间戳，用于增量更新。
-- **baseUrl**: `string` - 后端服务的基础 URL。
-- **token**: `string` - 用于身份验证的授权令牌。
-
-**返回值**
-- `Promise<any>` - 一个 Promise，resolve 时返回包含翻译数据的对象。如果请求成功，`res.data.result` 为 0，则返回 `res.data.retVal`；否则返回整个 `res` 对象。
-
-**Section sources**
-- [service.js:74-101](file://packages/libs/service.js#L74-L101)
-
-### getTranslate (获取翻译数据 - 增强版)
-此方法是 `fetchTranslate` 的增强版，它结合了本地存储（`store2`）来实现数据缓存和增量更新。
-
-**方法签名**
-```typescript
-getTranslate({ baseUrl, appCode, language, token, routerName }: { 
-  baseUrl: string; 
-  appCode: string; 
-  language?: string; 
-  token: string; 
-  routerName: string; 
-}): Promise<any>
-```
-
-**参数**
-- 参数与 `fetchTranslate` 类似。
-- **routerName**: `string` - 当前路由的名称，用于 `mergeArraysByKey` 函数。
-
-**返回值**
-- `Promise<any>` - 一个 Promise，resolve 时返回合并后的翻译数据数组。
-
-**副作用**
-- 读取和写入本地存储（`store2`），以缓存翻译数据和 `lastPullDate`。
-- 可能发起网络请求。
-- 调用 `mergeArraysByKey` 函数合并数据。
-
-**使用限制**
-- 依赖于 `store2` 和 `lodash-es` 库。
-- 逻辑较为复杂，涉及缓存合并。
-
-**错误处理建议**
-- 确保 `store2` 正常工作，本地存储空间充足。
-- 处理网络请求失败的情况，提供降级方案（如使用缓存数据）。
-
-**更新** 该方法的行为已更新，当从后端获取到 `common` 类型的翻译时，会移除当前路由中同名的翻译数据。
-
-**Section sources**
-- [service.js:133-186](file://packages/libs/service.js#L133-L186)
-
-### userDicts (用户词典)
-提交用户自定义的翻译词典。
-
-**方法签名**
-```typescript
-userDicts({ data, token, baseUrl }: { data: any; token: string; baseUrl: string }): Promise<any>
-```
-
-**参数**
-- **data**: `any` - 用户词典数据。
-- **token**: `string` - 授权令牌。
-- **baseUrl**: `string` - 基础 URL。
-
-**返回值**
-- `Promise<any>` - 请求的响应。
-
-**Section sources**
-- [service.js:112-121](file://packages/libs/service.js#L112-L121)
-
-### saveTranslate (保存翻译)
-批量保存翻译数据。
-
-**方法签名**
-```typescript
-saveTranslate({ data, token, baseUrl }: { data: any; token: string; baseUrl: string }): Promise<any>
-```
-
-**参数**
-- **data**: `any` - 要保存的翻译数据。
-- **token**: `string` - 授权令牌。
-- **baseUrl**: `string` - 基础 URL。
-
-**返回值**
-- `Promise<any>` - 请求的响应。
-
-**Section sources**
-- [service.js:123-132](file://packages/libs/service.js#L123-L132)
-
-## 使用示例与最佳实践
-
-### 基本初始化
-```javascript
-import { createApp } from 'vue';
-import I18n from 'gc_i18n';
-import router from './router';
-
-const app = createApp(App);
-
-// 创建国际化实例
-const i18n = new I18n({
-  appCode: 'YOUR_APP_CODE',
-  router: router,
-  locale: 'zh-CN'
-});
-
-// 安装插件
-app.use(i18n);
-```
-
-### 延迟设置路由器
-```javascript
-import { createApp } from 'vue';
-import I18n from 'gc_i18n';
-import router from './router';
-
-const app = createApp(App);
-
-// 先创建国际化实例，稍后再设置router
-const i18n = new I18n({
-  appCode: 'YOUR_APP_CODE',
-  locale: 'zh-CN'
-});
-
-// 稍后设置router
-i18n.setRouter(router);
-
-// 安装插件
-app.use(i18n);
-```
-
-### 在 Vue 模板中使用 $t
-```vue
-<template>
-  <h1>{{ $t("welcome_message") }}</h1>
-  <p>{{ $t("description") }}</p>
-</template>
-```
-
-### 在 JavaScript 中切换语言
-```javascript
-import { getCurrentInstance } from 'vue';
-
-export default {
-  setup() {
-    const { proxy } = getCurrentInstance();
-
-    const changeLanguage = async (lang) => {
-      try {
-        await proxy.$changeLocale(lang);
-        // 语言切换成功后的逻辑
-      } catch (error) {
-        console.error('切换语言失败:', error);
-      }
-    };
-
-    return { changeLanguage };
-  }
-}
-```
-
-### 提取组件中的翻译键
-```javascript
-import { extractTranslationKeys } from './i18nUtils';
-
-const MyComponent = {
-  template: '<div>{{ $t("hello") }}</div>',
-  methods: {
-    greet() {
-      console.log(this.$t("greeting"));
-    }
-  }
-};
-
-const keys = extractTranslationKeys(MyComponent);
-console.log(keys); // 输出: ["hello", "greeting"]
-```
-
-### 路由守卫中集成 closeModal
-```javascript
-// 在路由守卫中自动关闭模态框
-this.router.beforeEach(async (to, from, next) => {
-  // 自动关闭配置中心弹窗
-  this.configInstance && this.configInstance.closeModal();
-  // 其他路由逻辑...
-});
-```
-
-## 错误处理与限制
-- **网络错误**: `service.js` 中的所有异步方法都可能因网络问题而失败。务必使用 `try-catch` 或 `.catch()` 处理 Promise 拒绝。
-- **缓存失效**: `getTranslate` 依赖本地存储。如果用户清除浏览器数据，缓存将丢失，需要重新下载完整语言包。
-- **类型安全**: `extractTranslationKeys` 的参数类型为 `any`，缺乏严格的类型检查，使用时需确保传入的是有效的组件对象。
-- **性能**: 频繁调用 `$changeLocale` 会导致应用重新渲染，应避免在短时间内多次调用。
-- **逻辑变更**: `getTranslate` 方法现在会移除 `common` 键覆盖的当前路由数据，这可能会影响某些依赖于特定键的组件。
-- **参数变更**: `fetchTranslate` 函数已移除 `page` 参数，使用时请注意更新调用方式。
-- **端点标准化**: 所有翻译服务端点已标准化为 `/i18n-web/...` 结构，确保了后端服务的一致性。
-- **模态框管理**: 新增的 `closeModal` 方法提供了统一的 SweetAlert2 弹窗管理，避免了弹窗残留问题。
-- **路由守卫增强**: `setRouter` 方法和增强的路由守卫功能提供了更完善的路由集成体验。
-- **延迟设置支持**: `setRouter` 方法支持延迟设置，提高了库的灵活性。
-- **版本更新** 本版本为 1.4.4，包含上述重要变更，特别是路由守卫中自动调用 `closeModal` 的功能集成。
-
-**版本更新** 本版本为 1.4.4，包含上述重要变更，特别是路由守卫中自动调用 `closeModal` 的功能集成。