398 lines
8.7 KiB
Markdown
398 lines
8.7 KiB
Markdown
# x-vuei18n-s
|
||
|
||
一个为 UniApp-X 设计的国际化(i18n)插件，提供完整的多语言支持功能。
|
||
本库为tmui4x提供多语言支持，同时也是开源免费的，不需要tmui4x授权，您即可导入和下载使用
|
||
使用时请按照文档安装和使用。
|
||
使用方式几乎与源Vu8I18n一致基本没有变化，所以你看我下面的文档和看官方的文档都可以,但部分函数还是有差异的
|
||
[源官方文档链接](https://vue-i18n.intlify.dev/guide/essentials/started.html)
|
||
|
||
## 特性
|
||
|
||
- 🌍 多语言翻译支持
|
||
- 🔢 复数形式处理
|
||
- 📅 日期时间格式化
|
||
- 💰 数字格式化
|
||
- ⏰ 相对时间格式化
|
||
- 🎯 插值和参数替换
|
||
- 🔄 语言回退机制
|
||
- 📱 跨平台兼容
|
||
|
||
| Harmony | IOS | Android | WEB | 小程序 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 支持 | 支持 | 支持 | 支持 | 支持 |
|
||
|
||
## 安装
|
||
|
||
将插件复制到项目的 `uni_modules` 目录下即可。
|
||
地区语言代码标准见[打开链接](https://xnxy.github.io/2024/06/11/%E5%9B%BD%E9%99%85%E5%8C%96%E4%B8%AD%E5%B8%B8%E7%94%A8BCP-47%20Code%E5%92%8C%E8%AF%AD%E8%A8%80%E5%AF%B9%E7%85%A7%E8%A1%A8/)
|
||
|
||
## 在TMUI4x项目中使用
|
||
|
||
### 前置条件
|
||
你已经使用并安装tmui4x组件库，那么会自带集成，但需要你复制本插件到您的项目中，目录
|
||
```您的项目 > uni_modules > x-vuei18n-s```
|
||
接着安装语言包
|
||
```uts
|
||
import App from './App'
|
||
import {xui} from "@/uni_modules/tmx-ui/index.uts"
|
||
import {Tmui4xOptions} from "@/uni_modules/tmx-ui/interface.uts"
|
||
|
||
import en from "@/uni_modules/tmx-ui/localLanuage/en.json"
|
||
import zhHans from "@/uni_modules/tmx-ui/localLanuage/zh-Hans.json"
|
||
import zhHant from "@/uni_modules/tmx-ui/localLanuage/zh-Hant.json"
|
||
import ko from "@/uni_modules/tmx-ui/localLanuage/ko.json"
|
||
import ja from "@/uni_modules/tmx-ui/localLanuage/ja.json"
|
||
// 下方是组件的语言包，以及你自己定义的语言包与组件合并即可。共用一个实例。
|
||
const messages : UTSJSONObject = {
|
||
"en":{
|
||
...en,
|
||
"hellow":"Hi~"
|
||
},
|
||
"zh-Hans":{
|
||
...zhHans,
|
||
"hellow":"哈喽"
|
||
},
|
||
"zh-Hant":zhHant,
|
||
"ko":ko,
|
||
"ja":ja
|
||
}
|
||
import { createSSRApp } from 'vue'
|
||
export function createApp() {
|
||
const app = createSSRApp(App)
|
||
// 配置语言包
|
||
app.use(xui,{i18nOptions:{locale:"zh-Hans",messages}} as Tmui4xOptions)
|
||
return {
|
||
app
|
||
}
|
||
}
|
||
|
||
```
|
||
|
||
### 在Uvue内使用
|
||
|
||
#### 组合式模板内
|
||
```uts
|
||
import {xStore} from "@/uni_modules/tmx-ui/index.uts"
|
||
const i18n = xStore.xConfig.i18n
|
||
console.log(i18n.t('xx.x'))
|
||
```
|
||
uts内导入后可以在模板内使用
|
||
```vue
|
||
<x-text>{{i18n.t('xx.x')}}</x-text>
|
||
```
|
||
|
||
#### 选项式模板内
|
||
它已经集成了,不需要向组合式那样再导入.
|
||
```uts
|
||
export default {
|
||
methods:{
|
||
test():string{
|
||
return this!.i18n.t('xx.x')
|
||
}
|
||
}
|
||
}
|
||
```
|
||
它已经集成了,不需要向组合式那样再导入.
|
||
```vue
|
||
<x-text>{{i18n!.t('xx.x')}}</x-text>
|
||
```
|
||
|
||
### 在任意Uts中使用
|
||
|
||
```uts
|
||
import {xStore} from "@/uni_modules/tmx-ui/index.uts"
|
||
const i18n = xStore.xConfig.i18n
|
||
console.log(i18n.t('xx.x'))
|
||
```
|
||
|
||
|
||
## 作为插件集成到您应用中（非tmui4x项目）
|
||
|
||
### 前置条件
|
||
你需要在main.uts中安装插件
|
||
```uts
|
||
import { tmxI18n} from "@/uni_modules/x-vuei18n-s/index.uts"
|
||
import { I18nOptions} from "@/uni_modules/x-vuei18n-s/interface.uts"
|
||
|
||
const config = {locale:'zh'} as I18nOptions
|
||
app.use(tmxI18n,config)
|
||
|
||
```
|
||
|
||
**在下面的2和3取得的i18n均为多语言实例，你可以调用前面的实例方法动态添加语言或者切语言等**
|
||
|
||
### 1.在Vue模板内使用
|
||
|
||
```vue
|
||
<x-text>{{i18n.t('cnacel')}}</x-text>
|
||
```
|
||
### 2.在组合式代码内使用
|
||
|
||
```ts
|
||
import {getCurrentInstance} from "vue"
|
||
const i18n = getCurrentInstance()?.proxy?.$i18n()
|
||
//可选
|
||
console.log(i18n?.t('confirm'))
|
||
//断言
|
||
console.log(i18n!.t('confirm'))
|
||
```
|
||
|
||
### 3.在选项式代码内使用
|
||
|
||
```ts
|
||
export default {
|
||
methods:{
|
||
test():string{
|
||
return this!.i18n.t('confirm')
|
||
}
|
||
}
|
||
}
|
||
|
||
```
|
||
|
||
### 4.在任意文件中使用
|
||
这里说的是你脱离了vue模板，比如在非setup和选项式中使用时，前面的方式就不行了，因为前面是依赖于vue实例。
|
||
此种方式是只使用插件模式不需要在main.uts中app.use安装本插件，即可在任意位置导入使用。包括在vue模板内（不分组合式和选项都能用）
|
||
如果你想在模板内使用本方式
|
||
**不要再使用i18n变量名了**
|
||
因为本身在模板内就有全局的i18n。
|
||
|
||
任意uts代码中
|
||
```uts
|
||
import { $i18n } from "@/uni_modules/x-vuei18n-s/index.uts"
|
||
const la = $i18n()
|
||
// uts文件中就可以使用了。
|
||
console.log(la.t('xx.x.x.'))
|
||
//模板内
|
||
|
||
```
|
||
vue模板内
|
||
```uts
|
||
import { $i18n } from "@/uni_modules/x-vuei18n-s/index.uts"
|
||
const la = $i18n()
|
||
```
|
||
```vue
|
||
<x-text>{{la.t('xx.x.x.')}}</x-text>
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 基本使用
|
||
|
||
```typescript
|
||
import { $i18n} from "@/uni_modules/x-vuei18n-s/index.uts"
|
||
const i18n = $i18n();
|
||
```
|
||
|
||
|
||
```typescript
|
||
// 设置中文消息
|
||
const zhMessages: UTSJSONObject = {
|
||
'hello': '你好',
|
||
'welcome': '欢迎使用UniApp-X',
|
||
'user': {
|
||
'name': '用户名',
|
||
'age': '年龄'
|
||
},
|
||
'items': {
|
||
'apple': '苹果 | 苹果们 | {count}个苹果'
|
||
},
|
||
'greeting': '你好，{name}！'
|
||
}
|
||
|
||
// 设置英文消息
|
||
const enMessages: UTSJSONObject = {
|
||
'hello': 'Hello',
|
||
'welcome': 'Welcome to UniApp-X',
|
||
'user': {
|
||
'name': 'Username',
|
||
'age': 'Age'
|
||
},
|
||
'items': {
|
||
'apple': 'apple | apples | {count} of apple'
|
||
},
|
||
'greeting': 'Hello, {name}!'
|
||
}
|
||
i18n.mergeLocaleMessage('zh',zhMessages)
|
||
i18n.mergeLocaleMessage('en',enMessages)
|
||
// 设置当前语言
|
||
i18n.setLocale('zh')
|
||
```
|
||
|
||
## API 文档
|
||
|
||
### 创建实例
|
||
|
||
如果是在uvue模板内，可以参照文档尾部的使用方法。
|
||
|
||
```typescript
|
||
import { $i18n} from "@/uni_modules/x-vuei18n-s/index.uts"
|
||
const i18n = $i18n();
|
||
```
|
||
|
||
### 翻译方法 t()
|
||
|
||
基本翻译：
|
||
```typescript
|
||
i18n.t('hello') // '你好'
|
||
i18n.t('user.name') // '用户名'
|
||
```
|
||
|
||
带参数的翻译：
|
||
```typescript
|
||
i18n.t('greeting', { name: '张三' }) // '你好，张三！'
|
||
```
|
||
|
||
复数形式：
|
||
```typescript
|
||
i18n.t('items.apple', 1) // '苹果'
|
||
i18n.t('items.apple', 2) // '苹果们'
|
||
i18n.t('items.apple', 5, { count: 5 }) // '5个苹果'
|
||
```
|
||
|
||
### 数字格式化 n()
|
||
|
||
```typescript
|
||
// 基本数字格式化
|
||
i18n.n(1234.56) // '1234.56'
|
||
|
||
// 货币格式化
|
||
i18n.n(1234.56, null, {
|
||
style: 'currency',
|
||
currency: 'CNY'
|
||
}) // '¥1,234.56'
|
||
|
||
// 百分比格式化
|
||
i18n.n(0.85, null, {
|
||
style: 'percent'
|
||
}) // '85%'
|
||
```
|
||
|
||
### 日期时间格式化 d()
|
||
|
||
```typescript
|
||
const date = new Date()
|
||
|
||
// 基本日期格式化
|
||
i18n.d(date) // '2024/1/15'
|
||
|
||
// 自定义格式
|
||
i18n.d(date, null, {
|
||
year: 'numeric',
|
||
month: 'long',
|
||
day: 'numeric'
|
||
}) // '2024年1月15日'
|
||
|
||
// 时间格式化
|
||
i18n.d(date, null, {
|
||
hour: '2-digit',
|
||
minute: '2-digit',
|
||
second: '2-digit'
|
||
}) // '14:30:25'
|
||
```
|
||
|
||
### 相对时间格式化 rt()
|
||
|
||
```typescript
|
||
// 相对于当前时间
|
||
i18n.rt(new Date()) // '刚刚'
|
||
|
||
// 指定时间字符串
|
||
i18n.rt('2025-7-8 20:4:50', 'second') // '6个月后'
|
||
|
||
// 时间戳
|
||
i18n.rt(Date.now() + 3600000, 'minute') // '1小时后'
|
||
|
||
// 自动单位进阶
|
||
i18n.rt(Date.now() + 90000, 'second') // '1分钟后' (90秒自动转为分钟)
|
||
```
|
||
|
||
### 翻译键存在性检测 te()
|
||
|
||
```typescript
|
||
// 检测翻译键是否存在
|
||
i18n.te('hello') // true
|
||
i18n.te('user.name') // true
|
||
i18n.te('nonexistent.key') // false
|
||
|
||
// 检测指定语言中的翻译键
|
||
i18n.te('hello', 'zh') // true
|
||
i18n.te('hello', 'en') // true
|
||
i18n.te('hello', 'fr') // false (如果没有法语语言包)
|
||
|
||
// 检测嵌套键
|
||
i18n.te('user.settings.theme') // true
|
||
i18n.te('user.nonexistent') // false
|
||
```
|
||
|
||
### 语言管理
|
||
|
||
```typescript
|
||
// 获取当前语言
|
||
const currentLocale = i18n.getLocale() // 'zh'
|
||
|
||
// 设置语言
|
||
i18n.setLocale('en')
|
||
|
||
// 获取可用语言列表
|
||
const locales = i18n.availableLocales() // ['zh', 'en']
|
||
|
||
// 动态添加语言内容
|
||
i18n.mergeLocaleMessage('zh', {
|
||
'newKey': '新内容'
|
||
})
|
||
```
|
||
|
||
## 高级功能
|
||
|
||
### 复数规则自定义
|
||
|
||
```typescript
|
||
// pluralRule
|
||
const i18n.ops = (choice: number, choicesLength: number) => {
|
||
// 自定义复数规则
|
||
if (choicesLength === 2) {
|
||
return choice === 1 ? 1 : 0
|
||
}
|
||
return choice === 0 ? 0 : choice === 1 ? 1 : 2
|
||
}
|
||
}
|
||
```
|
||
|
||
### 回退语言设置
|
||
|
||
```typescript
|
||
i18n.setLocale('zh')
|
||
i18n.setFallbackLocale('en')
|
||
```
|
||
|
||
### 预定义格式
|
||
|
||
```typescript
|
||
// 数字格式预定义
|
||
i18n.ops.numberFormats.set('zh', new Map([
|
||
['currency', {
|
||
style: 'currency',
|
||
currency: 'CNY',
|
||
currencyDisplay: 'symbol'
|
||
}]
|
||
]))
|
||
|
||
// 使用预定义格式
|
||
i18n.n(1234.56, 'currency') // '¥1,234.56'
|
||
```
|
||
|
||
|
||
## 注意事项
|
||
|
||
1. 消息对象必须使用 `UTSJSONObject` 类型
|
||
2. 复数形式使用 `|` 分隔不同的形式
|
||
3. 插值参数使用 `{key}` 格式
|
||
4. 相对时间会自动选择最合适的单位
|
||
5. 支持嵌套的消息键（如 `user.name`）
|
||
|
||
|
||
## 许可证
|
||
|
||
请不要随意更改源码，你仅有使用权。
|