@xiaonoodles/meetfun-i18n 1.2.14

package/TROUBLESHOOTING.md

@@ -0,0 +1,280 @@
+# 故障排除指南
+
+## Vue2 项目报错：`export 'createI18n' was not found in 'vue-i18n'`
+
+### 问题描述
+
+在 Vue2 项目中使用 `meetfun-i18n/vue2` 时，遇到以下错误：
+
+```
+ERROR in ./node_modules/meetfun-i18n/dist/index.esm.js
+export 'createI18n' (imported as 'createI18n') was not found in 'vue-i18n'
+```
+
+### 原因
+
+这个错误说明打包工具（Webpack/uni-app）加载了 Vue3 版本的代码（`dist/index.esm.js`），而不是 Vue2 版本（`dist/vue2/index.esm.js`）。
+
+Vue3 的 vue-i18n@9 使用 `createI18n`，而 Vue2 的 vue-i18n@8 使用 `new VueI18n()`，这导致了不兼容。
+
+### 解决方案
+
+#### 方案 1：使用正确的引入路径（推荐）
+
+确保您的引入语句是：
+
+```javascript
+// ✅ 正确 - Vue2 项目
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+
+// ❌ 错误 - 这会加载 Vue3 版本
+import { createMeetFunI18n } from 'meetfun-i18n'
+```
+
+#### 方案 2：检查 package.json 中的版本
+
+确保安装了正确版本的依赖：
+
+```bash
+# 检查当前版本
+pnpm list vue vue-i18n
+
+# Vue2 项目应该是：
+# vue: ^2.7.x
+# vue-i18n: ^8.x.x
+
+# 如果版本不对，重新安装
+pnpm remove vue vue-i18n
+pnpm add vue@^2.7.0 vue-i18n@^8.0.0
+```
+
+#### 方案 3：清除缓存并重新安装
+
+```bash
+# 清除 node_modules
+rm -rf node_modules
+
+# 清除锁定文件（根据你的包管理器选择）
+rm package-lock.json  # npm
+rm yarn.lock          # yarn
+rm pnpm-lock.yaml     # pnpm
+
+# 重新安装
+pnpm install
+```
+
+#### 方案 4：Webpack 配置别名（适用于 uni-app）
+
+如果上述方法都不行，可以在 `vue.config.js` 或 Webpack 配置中添加别名：
+
+```javascript
+// vue.config.js
+module.exports = {
+  configureWebpack: {
+    resolve: {
+      alias: {
+        'meetfun-i18n/vue2': 'meetfun-i18n/vue2.js'
+      }
+    }
+  }
+}
+```
+
+### 验证是否正确加载
+
+创建一个测试文件：
+
+```javascript
+// test.js
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+console.log('导入成功:', typeof createMeetFunI18n)
+```
+
+如果输出 `导入成功: function`，说明加载正确。
+
+---
+
+## 类型定义找不到
+
+### 问题描述
+
+TypeScript 项目报错：找不到模块 `meetfun-i18n/vue2` 的类型定义。
+
+### 解决方案
+
+#### 方案 1：确保安装了最新版本
+
+```bash
+pnpm add meetfun-i18n@latest
+```
+
+#### 方案 2：在 tsconfig.json 中添加类型引用
+
+```json
+{
+  "compilerOptions": {
+    "types": ["meetfun-i18n/vue2"]
+  }
+}
+```
+
+#### 方案 3：手动指定类型
+
+在文件顶部添加：
+
+```typescript
+/// <reference types="meetfun-i18n/vue2" />
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+```
+
+---
+
+## uni-app 编译报错
+
+### 问题描述
+
+在 uni-app 项目中编译时报错。
+
+### 解决方案
+
+#### 方案 1：确保 HBuilderX 或 CLI 版本最新
+
+```bash
+# 如果使用 CLI
+npm update -g @vue/cli-service-global
+```
+
+#### 方案 2：检查 manifest.json 配置
+
+确保配置了正确的 Vue 版本：
+
+```json
+{
+  "vueVersion": "2"  // Vue2 项目
+}
+```
+
+#### 方案 3：清除编译缓存
+
+在 HBuilderX 中：
+1. 运行 -> 清除缓存
+2. 重新编译
+
+使用 CLI：
+```bash
+rm -rf unpackage
+npm run dev:mp-weixin  # 或其他平台
+```
+
+---
+
+## peerDependencies 警告
+
+### 问题描述
+
+安装时出现 peerDependencies 警告。
+
+### 解决方案
+
+这是正常的，因为包支持 Vue2 和 Vue3。确保您安装了正确版本的依赖即可：
+
+**Vue2 项目：**
+```bash
+pnpm add vue@^2.7.0 vue-i18n@^8.0.0
+```
+
+**Vue3 项目：**
+```bash
+pnpm add vue@^3.0.0 vue-i18n@^9.0.0
+```
+
+---
+
+## 运行时报错：`uni is not defined`
+
+### 问题描述
+
+在非 uni-app 项目中使用报错。
+
+### 解决方案
+
+本库依赖 uni-app 的 `uni` 全局对象，仅适用于 uni-app 项目。
+
+如果您需要在普通 Vue 项目中使用，可以：
+
+1. 使用原生的 vue-i18n
+2. 或者 mock `uni` 对象（不推荐）
+
+---
+
+## 构建产物体积过大
+
+### 问题描述
+
+打包后体积较大。
+
+### 解决方案
+
+#### 方案 1：启用 Tree Shaking
+
+确保使用 ES Module 导入：
+
+```javascript
+// ✅ 好 - 支持 Tree Shaking
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+
+// ❌ 不好
+const { createMeetFunI18n } = require('meetfun-i18n/vue2')
+```
+
+#### 方案 2：只导入需要的功能
+
+```javascript
+import { createMeetFunI18n, LANGUAGE_OPTIONS_CONFIGURATION } from 'meetfun-i18n/vue2'
+// 而不是：import * as i18n from 'meetfun-i18n/vue2'
+```
+
+---
+
+## 其他常见问题
+
+### Q: 可以在 Vue2 和 Vue3 混合项目中使用吗？
+
+A: 不建议。一个项目应该只使用一个版本的 Vue 和对应的 meetfun-i18n 版本。
+
+### Q: 升级到新版本后出现问题怎么办？
+
+A: 
+1. 查看 [CHANGELOG.md](./CHANGELOG.md) 了解破坏性更改
+2. 清除缓存和 node_modules
+3. 重新安装依赖
+
+### Q: 如何确认使用的是哪个版本？
+
+A: 在代码中添加调试信息：
+
+```javascript
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+console.log('meetfun-i18n version:', createMeetFunI18n.toString())
+```
+
+---
+
+## 获取帮助
+
+如果以上方法都无法解决问题，请：
+
+1. 检查 [GitHub Issues](https://github.com/meetfun/meetfun-i18n/issues)
+2. 提供以下信息创建新 Issue：
+   - Vue 版本
+   - vue-i18n 版本
+   - meetfun-i18n 版本
+   - 完整的错误信息
+   - 最小复现代码
+
+## 相关文档
+
+- [README.md](./README.md) - 完整使用文档
+- [VUE2_USAGE.md](./VUE2_USAGE.md) - Vue2 使用指南
+- [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) - 迁移指南
+

package/VERIFY_FIX.md

@@ -0,0 +1,272 @@
+# 修复验证指南
+
+## 📋 问题总结
+
+**错误信息：**
+```
+ERROR in ./node_modules/meetfun-i18n/dist/index.esm.js 1029:20-30
+export 'createI18n' (imported as 'createI18n') was not found in 'vue-i18n'
+```
+
+**根本原因：**
+Webpack 5 在处理 `import from 'meetfun-i18n/vue2'` 时，没有正确解析到 Vue2 版本的代码，而是加载了 Vue3 版本（`dist/index.esm.js`）。Vue3 版本使用 `createI18n`（vue-i18n@9），但您的项目安装的是 vue-i18n@8（只有 `default` 导出），因此报错。
+
+## ✅ 修复方案
+
+创建了物理的 `vue2/` 目录，确保 Webpack 能够正确解析子路径导入。
+
+## 🔍 验证步骤
+
+### 步骤 1: 重新发布包（维护者）
+
+```bash
+# 确保已构建
+pnpm build
+
+# 发布新版本 1.2.1
+npm publish
+```
+
+### 步骤 2: 在您的项目中更新（用户）
+
+```bash
+# 方式 1: 更新到最新版本
+pnpm update meetfun-i18n
+
+# 方式 2: 指定版本更新
+pnpm add meetfun-i18n@1.2.1
+
+# 方式 3: 强制重新安装
+pnpm remove meetfun-i18n
+pnpm add meetfun-i18n@latest
+```
+
+### 步骤 3: 验证文件结构
+
+更新后，检查 `node_modules/meetfun-i18n/` 是否包含：
+
+```bash
+ls node_modules/meetfun-i18n/vue2/
+
+# 应该看到以下文件：
+# ✅ package.json
+# ✅ index.js
+# ✅ index.mjs
+# ✅ index.d.ts
+```
+
+查看 `vue2/package.json` 内容：
+
+```bash
+cat node_modules/meetfun-i18n/vue2/package.json
+
+# 应该显示：
+{
+  "main": "../dist/vue2/index.js",
+  "module": "../dist/vue2/index.esm.js",
+  "types": "../dist/vue2/index.d.ts"
+}
+```
+
+### 步骤 4: 清除缓存
+
+```bash
+# 清除 node_modules（确保干净安装）
+rm -rf node_modules
+rm pnpm-lock.yaml
+
+# 重新安装
+pnpm install
+
+# 清除构建缓存
+rm -rf unpackage      # uni-app 项目
+rm -rf dist           # 如果有
+rm -rf .cache         # Webpack 缓存
+```
+
+### 步骤 5: 验证代码
+
+在您的 `src/locales/index.js` 中确认引入语句：
+
+```javascript
+// ✅ 正确的引入方式
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+
+// ❌ 错误 - 这会加载 Vue3 版本
+// import { createMeetFunI18n } from 'meetfun-i18n'
+```
+
+### 步骤 6: 添加调试代码
+
+临时添加以下代码来验证加载的版本：
+
+```javascript
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+
+console.log('✅ 导入成功')
+console.log('createMeetFunI18n:', typeof createMeetFunI18n)
+
+// 创建一个测试实例
+const testInstance = createMeetFunI18n(
+  { 'zh-Hans': {} }, 
+  {
+    queryLangDictHotData: async () => ({ data: {} }),
+    queryLangDictColdData: async () => ({ data: {} })
+  }
+)
+
+const i18n = testInstance.getI18n()
+console.log('i18n 实例类型:', i18n.constructor.name)
+console.log('是否有 t 方法:', typeof i18n.t)
+
+// 期望输出：
+// ✅ 导入成功
+// createMeetFunI18n: function
+// i18n 实例类型: VueI18n
+// 是否有 t 方法: function
+```
+
+### 步骤 7: 重新编译运行
+
+```bash
+# 重新运行开发服务器
+npm run dev
+
+# 或针对特定平台
+npm run dev:mp-weixin
+npm run dev:h5
+```
+
+## 🎯 预期结果
+
+### 成功标志
+
+1. ✅ 不再出现 `export 'createI18n' was not found` 错误
+2. ✅ 控制台输出显示 `i18n 实例类型: VueI18n`
+3. ✅ 项目正常编译和运行
+4. ✅ 翻译功能正常工作
+
+### 如果还是失败
+
+请检查以下内容：
+
+#### 1. 确认 vue-i18n 版本
+
+```bash
+pnpm list vue-i18n
+
+# Vue2 项目应该显示：
+# vue-i18n 8.x.x
+```
+
+如果不是 8.x.x，重新安装：
+
+```bash
+pnpm remove vue-i18n
+pnpm add vue-i18n@^8.0.0
+```
+
+#### 2. 检查引入路径
+
+确保所有文件都使用 `/vue2`：
+
+```bash
+# 搜索项目中的所有引入
+grep -r "from 'meetfun-i18n'" src/
+
+# 应该都是：
+# from 'meetfun-i18n/vue2'
+```
+
+#### 3. 检查 Webpack 配置
+
+如果项目有自定义的 `webpack.config.js` 或 `vue.config.js`，确保没有配置冲突：
+
+```javascript
+// vue.config.js
+module.exports = {
+  configureWebpack: {
+    resolve: {
+      // 确保这里没有关于 meetfun-i18n 的别名配置
+    }
+  }
+}
+```
+
+#### 4. 尝试直接路径
+
+作为临时测试，可以尝试直接引入：
+
+```javascript
+// 测试：直接引入 dist/vue2
+import { createMeetFunI18n } from 'meetfun-i18n/dist/vue2/index.esm.js'
+```
+
+如果这样能工作，说明是路径解析问题，请提供您的 Webpack 配置。
+
+## 📊 对比表
+
+| 检查项 | Vue3 版本（错误） | Vue2 版本（正确） |
+|--------|------------------|-------------------|
+| **引入路径** | `meetfun-i18n` | `meetfun-i18n/vue2` |
+| **加载文件** | `dist/index.esm.js` | `dist/vue2/index.esm.js` |
+| **i18n 创建** | `createI18n()` | `new VueI18n()` |
+| **实例类型** | `Composer` | `VueI18n` |
+| **vue-i18n 版本** | 9.x | 8.x |
+
+## 🆘 获取帮助
+
+如果以上步骤都完成了还是不行，请提供以下信息：
+
+1. **包版本信息：**
+   ```bash
+   pnpm list meetfun-i18n vue vue-i18n
+   ```
+
+2. **文件是否存在：**
+   ```bash
+   ls -la node_modules/meetfun-i18n/vue2/
+   ```
+
+3. **引入代码：**
+   ```javascript
+   // 粘贴您的 src/locales/index.js 的引入部分
+   ```
+
+4. **完整错误信息：**
+   ```
+   // 粘贴完整的错误堆栈
+   ```
+
+5. **项目环境：**
+   - uni-app 版本
+   - 使用的打包工具（HBuilderX / CLI）
+   - Node.js 版本
+
+## 📚 相关文档
+
+- [FIX_WEBPACK_RESOLUTION.md](./FIX_WEBPACK_RESOLUTION.md) - 技术细节
+- [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) - 故障排除
+- [VUE2_USAGE.md](./VUE2_USAGE.md) - Vue2 使用指南
+
+## ✨ 成功案例
+
+更新到 1.2.1 后，以下场景都应该正常工作：
+
+```javascript
+// ✅ ES Module 导入
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+
+// ✅ CommonJS 导入
+const { createMeetFunI18n } = require('meetfun-i18n/vue2')
+
+// ✅ TypeScript 类型
+import type { I18nConfig, ApiConfig } from 'meetfun-i18n/vue2'
+
+// ✅ 动态导入
+const module = await import('meetfun-i18n/vue2')
+
+// ✅ 默认导出
+import createMeetFunI18n from 'meetfun-i18n/vue2'
+```
+

package/VUE2_USAGE.md

@@ -0,0 +1,170 @@
+# Vue2 使用指南
+
+本库现在同时支持 Vue2 + vue-i18n@8 和 Vue3 + vue-i18n@9。
+
+## 安装
+
+```bash
+# 使用 pnpm
+pnpm add meetfun-i18n
+
+# Vue2 项目还需要安装
+pnpm add vue@^2.7.0 vue-i18n@^8.0.0
+
+# Vue3 项目需要安装
+pnpm add vue@^3.0.0 vue-i18n@^9.0.0
+```
+
+## Vue2 使用方式
+
+### 1. 引入方式
+
+Vue2 项目需要从 `meetfun-i18n/vue2` 引入：
+
+```javascript
+// Vue2 项目
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+```
+
+### 2. 完整示例
+
+```javascript
+// main.js
+import Vue from 'vue'
+import App from './App.vue'
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+
+// 引入本地语言包
+import zhHans from './locales/zh-Hans.json'
+import zhHant from './locales/zh-Hant.json'
+import en from './locales/en.json'
+
+// 引入 API 函数
+import { queryLangDictHotData, queryLangDictColdData } from './api/translate'
+
+// 创建基础语言包
+const baseMessages = {
+  'zh-Hans': zhHans,
+  'zh-Hant': zhHant,
+  en: en,
+}
+
+// 配置 API
+const apiConfig = {
+  queryLangDictHotData,
+  queryLangDictColdData,
+}
+
+// 创建 i18n 实例
+const i18nInstance = createMeetFunI18n(baseMessages, apiConfig, {
+  defaultLocale: 'zh-Hans',
+  defaultLangDictDomainCode: 'TALENTS',
+  systemCode: 'TALENTS_STUDENT',
+  debug: true,
+  onLocaleChanged: (payload) => {
+    console.log('语言已切换:', payload.targetLocale)
+  }
+})
+
+// 安装到 Vue
+Vue.use(i18nInstance.getI18n())
+
+// 挂载到 Vue 原型（可选，方便全局访问）
+Vue.prototype.$i18nInstance = i18nInstance
+
+new Vue({
+  i18n: i18nInstance.getI18n(),
+  render: h => h(App)
+}).$mount('#app')
+```
+
+### 3. 在组件中使用
+
+```vue
+<template>
+  <view>
+    <!-- 使用 vue-i18n 的 $t -->
+    <text>{{ $t('welcomeMessage') }}</text>
+    
+    <!-- 使用实例的 $t -->
+    <text>{{ i18nInstance.$t('welcomeMessage') }}</text>
+    
+    <!-- 切换语言 -->
+    <button @click="switchLanguage">切换语言</button>
+  </view>
+</template>
+
+<script>
+export default {
+  computed: {
+    i18nInstance() {
+      return this.$i18nInstance
+    }
+  },
+  methods: {
+    switchLanguage() {
+      this.$i18nInstance.switchLocale('en')
+    }
+  }
+}
+</script>
+```
+
+### 4. API 函数示例
+
+```javascript
+// api/translate.js
+import request from './request'
+
+/**
+ * 查询语言包热数据
+ */
+export function queryLangDictHotData({ systemCode }) {
+  return request.post('/api/lang-dict/hot', { systemCode })
+}
+
+/**
+ * 查询语言包冷数据
+ */
+export function queryLangDictColdData({ langDictColdDataCmdList }) {
+  return request.post('/api/lang-dict/cold', { langDictColdDataCmdList })
+}
+```
+
+## Vue3 使用方式
+
+Vue3 项目从主入口引入即可：
+
+```javascript
+// Vue3 项目
+import { createMeetFunI18n } from 'meetfun-i18n'
+```
+
+其他使用方式与 Vue2 相同。
+
+## 主要 API
+
+两个版本的 API 完全一致：
+
+- `$t(key, params?)` - 翻译函数
+- `switchLocale(locale)` - 切换语言
+- `getCurrentLocale()` - 获取当前语言
+- `fetchLangDictHotData()` - 获取热数据
+- `updateI18nMessages(data, saveToCache?)` - 更新语言包
+- `createI18nProxy(data, config?)` - 创建国际化代理对象
+- `getI18n()` - 获取 i18n 实例
+
+更多 API 请参考 [USAGE_EXAMPLE.md](./USAGE_EXAMPLE.md)
+
+## 版本要求
+
+- **Vue2**: Vue 2.7+ 和 vue-i18n 8.x
+- **Vue3**: Vue 3.x 和 vue-i18n 9.x
+
+## 注意事项
+
+1. Vue2 和 Vue3 项目需要使用不同的引入路径
+2. 确保安装了正确版本的 `vue` 和 `vue-i18n`
+3. API 函数的实现需要根据项目的实际情况调整
+4. Vue2 版本使用的是 vue-i18n 8.x 的旧版 API（legacy mode）
+