更新记录

2.0.0（2026-07-08） 下载此版本

• feat: 全面支持 uni-app（JS/TS 环境），两端 API 完全一致
• feat: 新增 te、tm、rt 方法，与 vue-i18n 对齐
• feat: 新增 addModifier、addPluralRule 方法，支持自定义修饰符和复数规则
• feat: 新增 availableLocales 响应式计算属性
• feat: 新增 useScope 选项，支持 global/parent/local 作用域
• feat: 新增 inheritLocale 选项，子 Composer 自动继承根实例语言
• feat: 新增 useStorage 选项，支持语言设置持久化
• feat: 重构为 ComposerClass 统一返回，所有方法支持默认参数省略
• feat: 目录重构 common/ → uvue/，与 vue/ 对应
• fix: 修复 compile 函数 listIndex 变量遮蔽 bug
• fix: 修复 fetchChoice 数组越界问题
• fix: 修复 install 在 APP-ANDROID 端需 definePlugin 包装的问题
• fix: 修复 t() 缺失翻译时返回空字符串，改为返回 key 本身
• fix: 删除无用的 errors.uts 和 warnings.uts

0.1.6（2026-03-12） 下载此版本

• fix: 修复在小程序无法读取locale问题

0.1.5（2026-02-03） 下载此版本

• 重构为class实现

平台兼容性

uni-app(5.13)

uni-app x(4.61)

lime-i18n 国际化插件

参考 vue-i18n 实现的国际化插件，同时支持 uni-app x（UTS 环境） 和 uni-app（JS/TS 环境），两端 API 完全一致。提供多语言切换、文本格式化、复数处理、日期时间本地化、数字格式化、TabBar 国际化等功能。

插件依赖：lime-shared

::: tip vue-i18n 优先 uni-app x 的 App 端原本不支持 vue-i18n，但升级到蒸汽模式（Vapor Mode）后已全面支持。建议优先使用 vue-i18n，获得完整的生态支持降低学习门槛。lime-i18n 作为 vue-i18n 的轻量替代。 :::

安装方法

1. 在 uni-app 插件市场中搜索并导入 lime-i18n
2. 导入后可能需要重新编译项目

::: tip 注意 lime-i18n 通过条件编译自动选择对应实现，用户无需关心底层差异：

• uni-app x → uvue/（UTS 强类型）
• uni-app → vue/（JS/TS） :::

代码演示

基础使用

1. 创建 i18n 实例

// locales/index.uts
import { createI18n } from '@/uni_modules/lime-i18n'
import zhCN from './zh-CN.json'
import enUS from './en-US.json'

const i18n = createI18n({
  locale: 'zh-CN',
  fallbackLocale: 'en-US',
  useStorage: true,  // 开启语言持久化
  messages: {
    'zh-CN': zhCN,
    'en-US': enUS
  }
})

export default i18n

2. 在应用中注册（可选）

// main.uts
import i18n from './locales'

export function createApp() {
  const app = createSSRApp(App)
  // 非 Vapor 模式下注册全局属性（$t/$tc/$d/$n）
  // Vapor 模式下不需要 app.use，但 import 不能省略
  // app.use(i18n)
  return { app }
}

3. 在组件中使用

import { useI18n } from '@/uni_modules/lime-i18n'

const i18n = useI18n()

// 简单翻译
const title = i18n.t('page.title')

// 带插值翻译
const welcome = i18n.t('message.welcome', { name: '张三' })

// 复数翻译
const appleCount = i18n.tc('apple', 10)

// 切换语言
i18n.locale.value = 'en-US'

在模板中：

<template>
  <view>
    <text>{{ i18n.t('page.title') }}</text>
    <text>{{ i18n.tc('apple', 10) }}</text>
  </view>
</template>

文本格式化

具名插值

// 语言包：{ message: { hello: '{msg} world' } }
i18n.t('message.hello', { msg: 'hello' })  // "hello world"

列表插值

// 语言包：{ message: { hello: '{0} world' } }
i18n.t('message.hello', ['hello'])  // "hello world"

链接消息

// 语言包：{ the_world: 'the world', dio: 'DIO:', linked: '@:message.dio @:message.the_world !!!!' }
i18n.t('message.linked')  // "DIO: the world !!!!"

内置修饰符

复数处理

// 语言包：{ car: 'car | cars', apple: 'no apples | one apple | {count} apples' }

i18n.tc('car', 1)   // "car"
i18n.tc('car', 2)   // "cars"
i18n.tc('apple', 0) // "no apples"

// 带插值
i18n.tc('apple', 10, { count: 10 })  // "10 apples"

日期时间格式化

const i18n = createI18n({
  datetimeFormats: {
    'en-US': {
      short: { year: 'numeric', month: 'short', day: 'numeric' },
      long: { year: 'numeric', month: 'short', day: 'numeric', weekday: 'short', hour: 'numeric', minute: 'numeric' }
    }
  }
})

i18n.d(new Date())            // 默认格式
i18n.d(new Date(), 'short')  // 指定格式
i18n.d(new Date(), 'long', 'zh-CN')  // 指定语言

数字格式化

const i18n = createI18n({
  numberFormats: {
    'en-US': {
      currency: { style: 'currency', currency: 'USD' },
      percent: { style: 'percent', useGrouping: false }
    }
  }
})

i18n.n(10000)                  // 默认格式
i18n.n(10000, 'currency')     // 货币格式
i18n.n(0.99123, 'percent')    // 百分比格式

TabBar 国际化

const i18n = useI18n()

// 设置 TabBar 文本
i18n.setTabBar('zh-CN', ['首页', '分类', '我的'])
i18n.setTabBar('en-US', ['Home', 'Category', 'Me'])

// 切换语言时自动更新 TabBar
i18n.locale.value = 'en-US'

延迟加载语言包

const i18n = useI18n()

setTimeout(() => {
  i18n.setLocaleMessage('ja-JP', jaJP)
}, 5000)

自定义修饰符

// 两端通用方式（推荐）
i18n.addModifier('snakeCase', (str: string): string => str.split(' ').join('_'))

// uni-app（JS/TS）也可直接在 options 中传入
const i18n = createI18n({
  modifiers: {
    snakeCase: (str: string): string => str.split(' ').join('_')
  }
})

自定义复数规则

function customRule(choice: number, choicesLength: number): number {
  if (choice == 0) return 0
  const teen = choice > 10 && choice < 20
  const endsWithOne = choice % 10 == 1
  if (!teen && endsWithOne) return 1
  if (!teen && choice % 10 >= 2 && choice % 10 <= 4) return 2
  return choicesLength < 4 ? 2 : 3
}

// 两端通用方式（推荐）
i18n.addPluralRule('ru', customRule)

// uni-app（JS/TS）也可直接在 options 中传入
const i18n = createI18n({
  pluralizationRules: { ru: customRule }
})

API 文档

createI18n(options)

创建 i18n 实例，返回 UvueI18n。

useI18n(options)

获取 Composer 实例，返回 ComposerClass。

注意： 请勿解构返回值，直接通过实例调用方法（i18n.t('key')），解构会丢失 this 绑定。

ComposerClass 方法

翻译方法

格式化方法

语言包管理

格式管理

TabBar 管理

自定义规则

UvueI18n 实例

与 vue-i18n 的关系

uni-app x App 端原本不支持 vue-i18n，升级到蒸汽模式后已全面支持。现在只要启用了蒸汽模式，所有端都可以直接使用 vue-i18n。 lime-i18n 与 vue-i18n 的关键差异：

建议优先选择 vue-i18n：

• 已启用蒸汽模式，所有端均可直接使用
• 获得完整的消息编译器、DevTools、SSR 等生态支持
• 已有 vue-i18n 使用经验，零学习成本

选择 lime-i18n 的场景：

• 需要 TabBar 国际化、useStorage 持久化等 uni-app 特有功能
• 尚未启用蒸汽模式的项目

Vue2 使用说明

插件使用了组合式 API，如需在 Vue2 项目中使用，请按照官方教程配置。

// vue2
import Vue from 'vue'
import VueCompositionAPI from '@vue/composition-api'
Vue.use(VueCompositionAPI)

快速预览

导入插件后，可以直接使用以下标签查看演示效果：

<!-- 代码位于 uni_modules/lime-i18n/components/lime-i18n/ -->
<lime-i18n />

插件标签说明

文档链接

📚 组件详细文档请访问以下站点：

• 国际化组件文档 - 站点1
• 国际化组件文档 - 站点2
• 国际化组件文档 - 站点3

注意事项

1. APP 端（uni-app x 原生） 不支持 Intl.DateTimeFormat 和 Intl.NumberFormat，日期和数字格式化功能受限；uni-app（Web/小程序）完整支持
2. UTS 环境下 options.modifiers 和 options.pluralizationRules 不会生效（UTSJSONObject 无法携带函数），请使用 addModifier / addPluralRule 方法
3. Vapor 模式下 app.config.globalProperties 不再有效，模板中无法使用 $t() 等，请使用 useI18n() 组合式 API
4. 不要解构 useI18n() 返回值，直接通过实例调用方法
5. import i18n from './locales' 不能省略，即使不调用 app.use(i18n)，也需要 import 以确保 createI18n() 被执行

useScope 说明

平台差异

支持与赞赏

如果你觉得本插件解决了你的问题，可以考虑支持作者：

支付宝赞助	微信赞助