i18n.md

使用uni-app做出海App的开发者越来越多，大家都关心国际化的问题。

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

uni-app 从 3.1.5 版本开始框架内置组件开始完善国际化支持，这些组件内置如下语言：

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

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

## 应用内容国际化
vue和js里的内容国际化是通行方案。
uni-app基于vue.js，有成熟的i18n插件，[这里是uni-app开发者分享的i18n插件的使用](https://ask.dcloud.net.cn/article/35102)

## uni-app 框架国际化@uni-framework

项目根目录支持 `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": {}
}
```


## 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


## 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` 中支持配置默认语言，参见上面的示例，默认跟随系统语言

## schema 国际化@schema

HBuilderX 3.3.0+

在项目根目录 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": "格式无效"
}
```


## 应用中原生ui界面的国际化
应用中调用到相册选择、地图等包含界面的原生能力时，这些原生界面的ui无法在前端控制。
- 地图部分，可以使用web-view组件内嵌google的web地图，也可以用uni-app的原生插件机制封装google原生地图sdk。
- 其他原生ui界面如相册选择，无法国际化，可以自己开发一个原生插件来替代之。

## 应用名称及iOS隐私提示语的国际化
云打包详见[https://ask.dcloud.net.cn/article/35860](https://ask.dcloud.net.cn/article/35860)
离线打包自行在原生工程中配置。


## 语言API

[uni.getLocale](/api/ui/locale?id=getlocale)

获取当前区域设置（语言）

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

设置当前区域设置（语言）

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

当前区域设置（语言）发生变化时，触发回调


## 国际化示例项目@helloi18n

Github: [hello i18n](https://github.com/dcloudio/hello-i18n.git)


**注意：**
- 小程序平台暂不支持动态变化，编译时仅生成默认语言json配置
- Android 平台因原生层限制，将自动重启，其他平台均实时变化，包括已打开的所有页面