i18n.md 9.5 KB
Newer Older
1
uni-app的国际化,即多语言,分为应用部分和框架部分。
Q
qiang 已提交
2

3 4
- 应用部分,即开发者自己的代码里涉及的界面部分
- 框架部分,即uni-app内置组件和API涉及界面的部分
Q
qiang 已提交
5

6
不同端的国际化方案也有差异,uni-app 自 3.1.5起,App 和 H5 支持框架国际化。小程序平台的国际化依赖于小程序平台框架自身。一般而言海外用户更多使用的是App和H5。
Q
qiang 已提交
7

8
可以在HBuilderX新建项目里选择`Hello i18n`示例或者插件市场查看[https://ext.dcloud.net.cn/plugin?id=6462](https://ext.dcloud.net.cn/plugin?id=6462)
Q
qiang 已提交
9

10
## vue界面和js内容的国际化
Q
qiang 已提交
11

12
vue和js里的内容国际化是与web通行的方案。
d-u-a's avatar
d-u-a 已提交
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89

main.js 引入并初始化 VueI18n

```js
// 国际化 json 文件,文件内容详见下面的示例
import en from './en.json'
import zhHans from './zh-Hans.json'
import zhHant from './zh-Hant.json'
const messages = {
	en,
	'zh-Hans': zhHans,
	'zh-Hant': zhHant
}

let i18nConfig = {
  locale: uni.getLocale(),// 获取已设置的语言
  messages
}

// VUE2
// #ifndef VUE3
import Vue from 'vue'
import VueI18n from 'vue-i18n'
Vue.use(VueI18n)
const i18n = new VueI18n(i18nConfig)
Vue.config.productionTip = false
App.mpType = 'app'
const app = new Vue({
  i18n,
  ...App
})
app.$mount()
// #endif

// VUE3
// #ifdef VUE3
import { createSSRApp } from 'vue'
import { createI18n } from 'vue-i18n'
const i18n = createI18n(i18nConfig)
export function createApp() {
  const app = createSSRApp(App)
  app.use(i18n)
  return {
    app
  }
}
// #endif
```

国际化json文件内容

```json
{
  "index.title": "Hello i18n"
}
```

页面模板中使用 `$t()` 获取,并传递国际化json文件中定义的key,js中使用 `this.$t('')`

```html
<template>
  <view class="container">
    <view class="title">{{$t('index.title')}}</view>
  </view>
</template>

<script>
  export default {
    data() {
      return {
      }
    }
  }
</script>
```

注意:页面中设置语言后需要调用 `this.$i18n.locale = 'zh-Hans'` 后生效
Q
qiang 已提交
90

d-u-a's avatar
d-u-a 已提交
91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115
## nvue页面国际化@nvue

nvue 目前的国际化方案需要在每个页面单独引入uni-i18n,后续框架会抹平差异,抹平差异后和 vue 页面一样只需要在 main.js 中引入


```js
<script>
  import {
    initVueI18n
  } from '@dcloudio/uni-i18n'

  // const messages = {} 此处内容省略,和 vue 全局引入的写法一致

  const { t } = initVueI18n(messages)

  export default {
    data() {
      return {
      }
    }
  }
</script>
```


116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194
## pages.json 国际化@pages

pages.json不属于vue页面,其中的原生tabbar和原生导航栏里也有文字内容。这部分内容的国际化方案如下:

项目根目录的locale目录下配置语言json文件,locale/`语言地区代码`.json,如:en.json,zh-Hans.json,zh-Hant.json

```
├── locale
│   ├── en.json
│   ├── zh-Hans.json
│   └── zh-Hant.json
```

语言文件示例(zh-Hans.json)

```json
{
  "app.name": "Hello uni-app",
  "index.title": "首页"
}
```

pages.json 示例

```json
{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "%index.title%" // locale目录下 语言地区代码.json 文件中定义的 key,使用 %% 占位
      }
    }
  ],
  "tabBar": {
    "list": [{
        "pagePath": "pages/index/index",
        "text": "%index.home%"
      }
    ]
  }
}
```

pages.json 支持以下属性配置国际化信息

- navigationBarTitleText
- titleNView->titleText
- titleNView->searchInput->placeholder
- tabBar->list->text

注:小程序下不支持这种国际化方案,也可以使用设置tabbar和navigationbar的API来设置文字。或者废弃原生tabbar和navigationbar,使用自定义方式。


## 框架内置组件和API国际化

uni-app 有内置的基础组件,比如picker,或者与界面相关的API,比如showModal。这些界面包含的文字也需要国际化。

自 3.1.5 版本起,App和H5平台内置的基础组件和接口相关的文字内容支持国际化。

这部分国际化,提供了2种策略,有自动策略,也有自定义方案。

### 自动适配手机或浏览器语言 

uni-app 基础组件和API,内置如下语言:

* 中文简体
* 中文繁体
* 英语
* 法语
* 西班牙语

内置组件和接口显示会根据系统语言环境自动切换,未支持的系统语言环境会显示为英文。

> uni-ui在1.4.8版本后也支持国际化

### 自定义国际化内容@uni-framework

如果自动适配语言不满足你的需求,比如需要预置的5种语言外的更多语言。那么可以使用自定义方案。在指定目录创建指定文件,用同名词条来替换。
d-u-a's avatar
d-u-a 已提交
195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265

项目根目录支持 `locale` 目录,locale/uni-app.`语言地区代码`.json,如:uni-app.en.json,uni-app.zh-Hans.json,uni-app.zh-Hant.json


```
├── locale
│   ├── uni-app.en.json
│   ├── uni-app.zh-Hans.json
│   └── uni-app.zh-Hant.json
```

uni-app.zh-Hans.json 文件

```json
{
  "common": {
    "uni.app.quit": "再按一次退出应用",
    "uni.async.error": "连接服务器超时,点击屏幕重试",
    "uni.showActionSheet.cancel": "取消",
    "uni.showToast.unpaired": "请注意 showToast 与 hideToast 必须配对使用",
    "uni.showLoading.unpaired": "请注意 showLoading 与 hideLoading 必须配对使用",
    "uni.showModal.cancel": "取消",
    "uni.showModal.confirm": "确定",
    "uni.chooseImage.cancel": "取消",
    "uni.chooseImage.sourceType.album": "从相册选择",
    "uni.chooseImage.sourceType.camera": "拍摄",
    "uni.chooseVideo.cancel": "取消",
    "uni.chooseVideo.sourceType.album": "从相册选择",
    "uni.chooseVideo.sourceType.camera": "拍摄",
    "uni.previewImage.cancel": "取消",
    "uni.previewImage.button.save": "保存图像",
    "uni.previewImage.save.success": "保存图像到相册成功",
    "uni.previewImage.save.fail": "保存图像到相册失败",
    "uni.setClipboardData.success": "内容已复制",
    "uni.scanCode.title": "扫码",
    "uni.scanCode.album": "相册",
    "uni.scanCode.fail": "识别失败",
    "uni.scanCode.flash.on": "轻触照亮",
    "uni.scanCode.flash.off": "轻触关闭",
    "uni.startSoterAuthentication.authContent": "指纹识别中...",
    "uni.picker.done": "完成",
    "uni.picker.cancel": "取消",
    "uni.video.danmu": "弹幕",
    "uni.video.volume": "音量",
    "uni.button.feedback.title": "问题反馈",
    "uni.button.feedback.send": "发送"
  },
  "ios": {},
  "android": {}
}
```



## manifest.json 国际化@manifest

和 pages.json 一致,在项目根目录增加 locale/uni-app.`语言地区代码`.json 文件,然后在 `manifest.json` 中使用 %% 占位

```json
{
  "name" : "%app.name%",
  "appid" : "",
  "description" : "",
  "versionName" : "1.0.0",
  "versionCode" : "100",
  "locale": "zh-Hans" // 设置默认语言,
}
```

`manifest.json` 中支持配置默认语言,参见上面的示例,默认跟随系统语言

d-u-a's avatar
d-u-a 已提交
266 267 268 269 270 271 272 273 274 275 276 277 278 279

## 小程序国际化@miniprogram

已支持

- 页面
- 组件

不支持

- pages.json,可以通过调用API来设置,例如更改标题 `uni.setNavigationBarTitle()`
- tabbar 不支持动态修改内容,但是可以通过自定义tabbar的方式,详情: [https://uniapp.dcloud.net.cn/collocation/pages?id=custom-tab-bar](https://uniapp.dcloud.net.cn/collocation/pages?id=custom-tab-bar)


d-u-a's avatar
d-u-a 已提交
280 281 282 283
## schema 国际化@schema

HBuilderX 3.3.0+

284 285
schema中涉及字段的显示名称、错误格式提示语,这些也需要国际化。

d-u-a's avatar
d-u-a 已提交
286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344
在项目根目录 uniCloud/database/locale/{数据库表名}/`语言地区代码`.json 文件,然后在 `*.schema.json` 文件中使用 %% 占位

```
├─uniCloud
│  ├─cloudfunctions
│  └─database
│      │  hello.schema.json
│      └─locale
│          └─hello
│              en.json
│              zh-Hans.json
```

hello.schema.json 文件内容

```json
// 文档教程: https://uniapp.dcloud.net.cn/uniCloud/schema
{
  "bsonType": "object",
  "required": [],
  "permission": {
    "read": false,
    "create": false,
    "update": false,
    "delete": false
  },
  "properties": {
    "_id": {
      "description": "ID"
    },
    "name": {
      "bsonType": "string",
      "label": "%name%",
      "errorMessage": {
        "format": "{label}%name.format%"
      }
    }
  }
}
```

en.json 文件内容

```json
{
  "name": "Name",
  "name.format": " invalid format"
}
```

zh-Hans 文件内容

```json
{
  "name": "姓名",
  "name.format": "格式无效"
}
```

Q
qiang 已提交
345

346 347 348 349
## App第三方SDK界面的国际化
uni-app App端sdk国际化依赖于sdk自身,一般而言推荐直接使用适配海外的SDK。

如map的sdk,海外可直接使用google地图。相关插件在插件市场均可搜到。
Q
qiang 已提交
350 351 352

## 应用名称及iOS隐私提示语的国际化
云打包详见[https://ask.dcloud.net.cn/article/35860](https://ask.dcloud.net.cn/article/35860)
d-u-a's avatar
d-u-a 已提交
353 354 355 356 357
离线打包自行在原生工程中配置。


## 语言API

358 359
uni-app内置了一批与国际化相关的API和生命周期,如下:

d-u-a's avatar
d-u-a 已提交
360 361 362 363 364 365 366 367 368 369 370 371 372 373 374
[uni.getLocale](/api/ui/locale?id=getlocale)

获取当前区域设置(语言)

[uni.setLocale](/api/ui/locale?id=setlocale)

设置当前区域设置(语言)

[uni.onLocaleChange](/api/ui/locale?id=onlocalechange)

当前区域设置(语言)发生变化时,触发回调


## 国际化示例项目@helloi18n

375
HBuilderX 3.3 起,新建项目可以直接选择`hello i18n`模板,或者去插件市场查阅[https://ext.dcloud.net.cn/plugin?id=6462](https://ext.dcloud.net.cn/plugin?id=6462)
d-u-a's avatar
d-u-a 已提交
376 377

**注意:**
378
- Android 平台因原生层限制,将自动重启。其他平台均实时变化,包括已打开的所有页面