更新记录

1.0.0（2026-06-12）

1.0.0

平台兼容性

uni-app(5.07)

hao-i18n 好国际化

专为 uni-app 打造的轻量级国际化多语言插件，支持 Vue2 / Vue3，覆盖 H5、小程序、App 全平台。

✨ 特性

• 零依赖 - 纯 JS 实现，不依赖 vue-i18n 等第三方库，体积仅 ~5KB
• 全平台 - 支持 H5、微信/支付宝/百度/字节/QQ 小程序、App
• 双版本 - 同时兼容 Vue2 和 Vue3
• 自动检测 - 自动识别系统语言，匹配最佳语言包
• 持久化 - 语言偏好自动保存到本地，下次启动自动恢复
• 嵌套 Key - 支持 home.title 点号分隔的嵌套键查找
• 参数插值 - 支持 {name}、{count} 等动态参数替换
• t-text 组件 - 内置翻译文本组件，语言切换自动刷新
• 动态扩展 - 支持运行时动态追加语言包
• 回调监听 - 支持语言切换事件回调

📦 安装

方式一：插件市场（推荐）

在 HBuilderX 中打开项目，进入 uni_modules 插件市场，搜索 hao-i18n，点击导入即可。

方式二：手动安装

将本目录（hao-i18n）复制到项目的 uni_modules/ 目录下。

🚀 快速开始

1. 引入插件

在 main.js 中引入并注册：

import Vue from 'vue'
import App from './App'
import i18nPlugin from '@/uni_modules/hao-i18n'

Vue.use(i18nPlugin)

const app = new Vue({
  ...App
})
app.$mount()

2. 使用翻译

在任意 .vue 文件中使用：

<template>
  <view>
    <!-- 方式一：使用 $t 方法 -->
    <text>{{ $t('home.title') }}</text>

    <!-- 方式二：使用 t-text 组件（推荐，语言切换自动刷新） -->
    <t-text path="home.welcome" />

    <!-- 带参数插值 -->
    <text>{{ $t('home.dynamic.greeting', { name: '小明', date: '2024-01-01' }) }}</text>
  </view>
</template>

3. 切换语言

// 在任意组件中
this.$i18n.setLocale('en')       // 切换到英文
this.$i18n.setLocale('zh-Hans')  // 切换到简体中文
this.$i18n.setLocale('ja')       // 切换到日文

// 获取当前语言
this.$i18n.getLocale()           // 'en'

// 获取所有可用语言
this.$i18n.getLocales()          // [{ code: 'zh-Hans', name: '简体中文' }, ...]

📖 配置项

Vue.use(i18nPlugin, {
  locale: 'zh-Hans',          // 默认语言（不传则自动检测）
  fallbackLocale: 'zh-Hans',  // 回退语言，当翻译缺失时使用
  messages: {},               // 自定义语言包
  localeNames: {}             // 自定义语言显示名称
})

自定义语言包

Vue.use(i18nPlugin, {
  messages: {
    'zh-Hans': {
      custom: {
        hello: '你好世界'
      }
    },
    'en': {
      custom: {
        hello: 'Hello World'
      }
    }
  },
  localeNames: {
    'zh-Hans': '简体中文',
    'en': 'English'
  }
})

动态追加语言包

this.$i18n.mergeMessages('fr', {
  home: { title: 'Bonjour le monde' }
})

🧩 t-text 组件

<template>
  <view>
    <!-- 基础用法 -->
    <t-text path="home.welcome" />

    <!-- 带参数 -->
    <t-text path="home.dynamic.greeting" :params="{ name: username, date: today }" />
  </view>
</template>

🌐 内置语言

🗂️ 语言包结构

语言包采用嵌套对象结构，推荐按模块命名空间组织：

├── app        # 应用通用
├── nav        # 导航
├── home       # 首页
├── form       # 表单
├── tips       # 提示信息
├── time       # 时间相关
└── settings   # 设置

每份语言包的 Key 结构保持一致，方便管理和翻译。

🔄 语言切换回调

// 监听语言切换
this.$i18n.onChange((locale) => {
  console.log('语言已切换至:', locale)
  // 这里可以更新导航栏标题等
  uni.setNavigationBarTitle({ title: this.$t('nav.home') })
})

// 组件销毁时自动移除监听，无需手动操作

⚠️ 注意事项

1. 导航栏标题 - pages.json 中的 navigationBarTitleText 是静态配置，需在页面生命周期中动态设置
2. tabBar 文案 - 暂不支持动态修改，需在 App 启动前确定语言
3. 组件名 - t-text 组件已在全局注册，无需手动引入
4. 小程序兼容 - 所有 API 均已适配小程序环境

📝 更新日志

v1.0.0

• 初始版本发布
• 支持 5 种内置语言
• 提供 t-text 组件
• 支持嵌套 Key 和参数插值
• 支持自动检测系统语言
• 支持语言偏好持久化

📄 License

MIT License

🙋 反馈与建议

欢迎提交 Issue 和 PR，帮助改进插件！