@xiaonoodles/meetfun-i18n 1.2.14

package/FIX_WEBPACK_RESOLUTION.md

@@ -0,0 +1,245 @@
+# Webpack 5 路径解析修复说明
+
+## 问题根源
+
+Webpack 5 在处理 npm 包的子路径导入时，默认不会完全遵循 `package.json` 的 `exports` 字段。当使用 `import from 'meetfun-i18n/vue2'` 时，Webpack 会尝试查找物理路径 `node_modules/meetfun-i18n/vue2`。
+
+## 解决方案
+
+创建了一个真实的 `vue2/` 目录，其中包含：
+
+### 目录结构
+
+```
+meetfun-i18n/
+├── dist/
+│   ├── index.js              # Vue3 版本
+│   ├── index.esm.js
+│   └── vue2/
+│       ├── index.js          # Vue2 实际代码
+│       └── index.esm.js
+├── vue2/                     # ← 新增物理目录
+│   ├── package.json          # 指向 dist/vue2
+│   ├── index.js              # CommonJS 入口
+│   ├── index.mjs             # ES Module 入口
+│   └── index.d.ts            # TypeScript 类型
+└── package.json
+```
+
+### vue2/package.json
+
+```json
+{
+  "main": "../dist/vue2/index.js",
+  "module": "../dist/vue2/index.esm.js",
+  "types": "../dist/vue2/index.d.ts"
+}
+```
+
+这个文件告诉 Webpack：
+- CommonJS (`require`) → 使用 `../dist/vue2/index.js`
+- ES Module (`import`) → 使用 `../dist/vue2/index.esm.js`
+- TypeScript → 使用 `../dist/vue2/index.d.ts`
+
+### vue2/index.js (CommonJS 入口)
+
+```javascript
+module.exports = require('../dist/vue2/index.js')
+```
+
+### vue2/index.mjs (ES Module 入口)
+
+```javascript
+export * from '../dist/vue2/index.esm.js'
+export { default } from '../dist/vue2/index.esm.js'
+```
+
+## 工作原理
+
+现在当您使用：
+```javascript
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+```
+
+Webpack 会：
+1. 找到 `node_modules/meetfun-i18n/vue2` 目录
+2. 读取 `vue2/package.json`
+3. 根据模块类型选择：
+   - ES Module → `vue2/index.mjs` → `dist/vue2/index.esm.js`
+   - CommonJS → `vue2/index.js` → `dist/vue2/index.js`
+4. 最终加载正确的 Vue2 版本代码
+
+## 多层保护
+
+我们提供了多种方式确保兼容性：
+
+### 1. 根目录入口文件
+```
+vue2.js       # CommonJS
+vue2.mjs      # ES Module  
+vue2.d.ts     # TypeScript
+```
+
+### 2. vue2 目录
+```
+vue2/
+├── package.json
+├── index.js
+├── index.mjs
+└── index.d.ts
+```
+
+### 3. package.json exports
+```json
+{
+  "exports": {
+    "./vue2": {
+      "types": "./vue2.d.ts",
+      "import": "./vue2.mjs",
+      "require": "./vue2.js"
+    }
+  }
+}
+```
+
+无论打包工具采用哪种解析策略，都能正确找到 Vue2 版本的代码。
+
+## 验证方法
+
+### 1. 检查文件是否存在
+
+```bash
+ls node_modules/meetfun-i18n/vue2/
+# 应该看到：
+# index.js  index.mjs  index.d.ts  package.json
+```
+
+### 2. 检查是否加载正确
+
+在您的代码中添加：
+
+```javascript
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+
+// 创建一个测试实例
+const i18n = createMeetFunI18n({}, {
+  queryLangDictHotData: () => {},
+  queryLangDictColdData: () => {}
+})
+
+const instance = i18n.getI18n()
+
+// 检查实例类型
+console.log('i18n 类型:', instance.constructor.name)
+// Vue2 应该输出: VueI18n
+// Vue3 会输出: Composer
+
+console.log('是否有 t 方法:', typeof instance.t)
+// Vue2 应该输出: function
+```
+
+### 3. 清除缓存后重新安装
+
+```bash
+# 删除 node_modules
+rm -rf node_modules
+
+# 删除锁文件
+rm pnpm-lock.yaml
+
+# 重新安装
+pnpm install
+
+# 清除构建缓存
+rm -rf unpackage  # uni-app
+rm -rf .cache     # Webpack
+
+# 重新运行
+npm run dev
+```
+
+## 常见问题
+
+### Q: 为什么需要这么多入口文件？
+
+A: 不同的打包工具和配置有不同的模块解析策略：
+- **现代打包工具**（支持 exports）→ 使用 package.json exports
+- **Webpack 5**（部分支持）→ 查找物理目录 vue2/
+- **老版本工具** → 使用根目录的 vue2.js/vue2.mjs
+
+这种多层设计确保最大兼容性。
+
+### Q: 如果还是报错怎么办？
+
+A: 尝试以下步骤：
+
+1. **完全重新安装**
+   ```bash
+   rm -rf node_modules pnpm-lock.yaml
+   pnpm install
+   ```
+
+2. **清除所有缓存**
+   ```bash
+   rm -rf unpackage .cache dist
+   ```
+
+3. **检查 vue-i18n 版本**
+   ```bash
+   pnpm list vue-i18n
+   # Vue2 项目应该是 8.x.x
+   ```
+
+4. **强制安装正确版本**
+   ```bash
+   pnpm add vue-i18n@^8.0.0 --force
+   ```
+
+### Q: TypeScript 提示找不到模块？
+
+A: 在 `tsconfig.json` 中添加：
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "esModuleInterop": true
+  }
+}
+```
+
+## 更新步骤
+
+用户需要更新到最新版本：
+
+```bash
+# 更新包
+pnpm update meetfun-i18n
+
+# 或指定版本
+pnpm add meetfun-i18n@1.2.1
+
+# 验证安装
+ls node_modules/meetfun-i18n/vue2/
+```
+
+## 测试结果
+
+更新后，以下导入应该都能正常工作：
+
+```javascript
+// ✅ 所有这些方式都应该能工作
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+const { createMeetFunI18n } = require('meetfun-i18n/vue2')
+
+// ✅ TypeScript 也能正确识别类型
+import type { I18nConfig } from 'meetfun-i18n/vue2'
+```
+
+## 相关文档
+
+- [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) - 故障排除完整指南
+- [TEST_IMPORT.md](./TEST_IMPORT.md) - 导入测试说明
+- [VUE2_USAGE.md](./VUE2_USAGE.md) - Vue2 使用指南
+

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 meetfun
+
+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/MIGRATION_GUIDE.md

@@ -0,0 +1,253 @@
+# Vue2/Vue3 迁移指南
+
+本文档帮助您在 Vue2 和 Vue3 项目之间迁移使用 meetfun-i18n。
+
+## 快速对比
+
+| 特性 | Vue2 | Vue3 |
+|------|------|------|
+| **引入方式** | `import { createMeetFunI18n } from 'meetfun-i18n/vue2'` | `import { createMeetFunI18n } from 'meetfun-i18n'` |
+| **Vue 版本** | Vue 2.7+ | Vue 3.x |
+| **vue-i18n 版本** | 8.x | 9.x |
+| **安装方式** | `Vue.use(i18n)` | `app.use(i18n)` |
+| **API 使用** | 完全相同 ✅ | 完全相同 ✅ |
+
+## Vue2 项目示例
+
+### 1. 安装依赖
+
+```bash
+pnpm add meetfun-i18n vue@^2.7.0 vue-i18n@^8.0.0
+```
+
+### 2. 初始化
+
+```javascript
+// src/locales/index.js
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+import zhHans from './zh-Hans.json'
+import en from './en.json'
+import { queryLangDictHotData, queryLangDictColdData } from '@/api/translate'
+
+const baseMessages = {
+  'zh-Hans': zhHans,
+  en: en,
+}
+
+const apiConfig = {
+  queryLangDictHotData,
+  queryLangDictColdData,
+}
+
+export default createMeetFunI18n(baseMessages, apiConfig, {
+  defaultLocale: 'zh-Hans',
+  systemCode: 'YOUR_SYSTEM_CODE',
+})
+```
+
+### 3. 在 main.js 中安装
+
+```javascript
+// main.js
+import Vue from 'vue'
+import App from './App.vue'
+import i18nInstance from './locales'
+
+// 安装 vue-i18n
+Vue.use(i18nInstance.getI18n())
+
+// 可选：挂载到原型
+Vue.prototype.$i18nInstance = i18nInstance
+
+new Vue({
+  i18n: i18nInstance.getI18n(),
+  render: h => h(App)
+}).$mount('#app')
+```
+
+### 4. 在组件中使用
+
+```vue
+<template>
+  <view>
+    <text>{{ $t('welcomeMessage') }}</text>
+    <button @click="changeLanguage">切换语言</button>
+  </view>
+</template>
+
+<script>
+export default {
+  methods: {
+    changeLanguage() {
+      this.$i18nInstance.switchLocale('en')
+    }
+  }
+}
+</script>
+```
+
+## Vue3 项目示例
+
+### 1. 安装依赖
+
+```bash
+pnpm add meetfun-i18n vue@^3.0.0 vue-i18n@^9.0.0
+```
+
+### 2. 初始化
+
+```typescript
+// src/locales/index.ts
+import { createMeetFunI18n } from 'meetfun-i18n'
+import zhHans from './zh-Hans.json'
+import en from './en.json'
+import { queryLangDictHotData, queryLangDictColdData } from '@/api/translate'
+
+const baseMessages = {
+  'zh-Hans': zhHans,
+  en: en,
+}
+
+const apiConfig = {
+  queryLangDictHotData,
+  queryLangDictColdData,
+}
+
+export default createMeetFunI18n(baseMessages, apiConfig, {
+  defaultLocale: 'zh-Hans',
+  systemCode: 'YOUR_SYSTEM_CODE',
+})
+```
+
+### 3. 在 main.ts 中安装
+
+```typescript
+// main.ts
+import { createSSRApp } from 'vue'
+import App from './App.vue'
+import i18nInstance from './locales'
+
+export function createApp() {
+  const app = createSSRApp(App)
+  
+  // 安装 vue-i18n
+  app.use(i18nInstance.getI18n())
+  
+  return {
+    app,
+  }
+}
+```
+
+### 4. 在组件中使用
+
+```vue
+<template>
+  <view>
+    <text>{{ $t('welcomeMessage') }}</text>
+    <button @click="changeLanguage">切换语言</button>
+  </view>
+</template>
+
+<script setup lang="ts">
+import i18nInstance from '@/locales'
+
+const changeLanguage = () => {
+  i18nInstance.switchLocale('en')
+}
+</script>
+```
+
+## 从 Vue2 迁移到 Vue3
+
+如果您的项目正在从 Vue2 升级到 Vue3，只需要：
+
+### 步骤 1：更新引入路径
+
+```typescript
+// 之前 (Vue2)
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+
+// 之后 (Vue3)
+import { createMeetFunI18n } from 'meetfun-i18n'
+```
+
+### 步骤 2：更新依赖
+
+```bash
+# 卸载 Vue2 相关依赖
+pnpm remove vue@2 vue-i18n@8
+
+# 安装 Vue3 相关依赖
+pnpm add vue@^3.0.0 vue-i18n@^9.0.0
+```
+
+### 步骤 3：更新 main 文件
+
+```typescript
+// 之前 (Vue2)
+import Vue from 'vue'
+Vue.use(i18nInstance.getI18n())
+Vue.prototype.$i18nInstance = i18nInstance
+
+// 之后 (Vue3)
+import { createSSRApp } from 'vue'
+const app = createSSRApp(App)
+app.use(i18nInstance.getI18n())
+app.config.globalProperties.$i18nInstance = i18nInstance
+```
+
+### 步骤 4：更新组件语法
+
+```vue
+<!-- 之前 (Vue2 Options API) -->
+<script>
+export default {
+  data() {
+    return {
+      text: this.$i18nInstance.$t('hello')
+    }
+  }
+}
+</script>
+
+<!-- 之后 (Vue3 Composition API) -->
+<script setup lang="ts">
+import { ref } from 'vue'
+import i18nInstance from '@/locales'
+
+const text = ref(i18nInstance.$t('hello'))
+</script>
+```
+
+## 注意事项
+
+1. **引入路径**：这是唯一的区别，Vue2 必须从 `meetfun-i18n/vue2` 引入
+2. **API 使用**：所有 API 方法在两个版本中完全相同
+3. **类型支持**：两个版本都提供完整的 TypeScript 类型定义
+4. **功能特性**：所有功能特性在两个版本中保持一致
+
+## 常见问题
+
+### Q: 可以在同一个项目中同时使用 Vue2 和 Vue3 版本吗？
+
+A: 不可以。一个项目只能使用一个版本。请根据项目使用的 Vue 版本选择对应的引入路径。
+
+### Q: 如果引入错误的版本会怎样？
+
+A: 会出现类型错误或运行时错误。Vue3 项目使用 `/vue2` 路径会导致 vue-i18n 版本不匹配。
+
+### Q: 两个版本的性能有差异吗？
+
+A: 性能主要取决于 Vue 和 vue-i18n 的版本，本库在两个版本中的性能表现一致。
+
+### Q: API 函数的实现需要改变吗？
+
+A: 不需要。API 函数的实现在两个版本中完全相同。
+
+## 相关文档
+
+- [README.md](./README.md) - 完整的使用文档
+- [VUE2_USAGE.md](./VUE2_USAGE.md) - Vue2 详细使用指南
+- [USAGE_EXAMPLE.md](./USAGE_EXAMPLE.md) - 更多使用示例
+