展示全部

# 国际化

uni-app x的国际化，即多语言，分2种情况：

固定一种外语：这种方式很简单，自己直接写就可以
动态切换语言：内置多种语言，根据条件动态切换。这种略微复杂，需要仔细读下文。

首先需要分清楚，一个应用分为开发者的代码，和uni-app x框架代码2部分。它们都涉及国际化。

开发者代码：即开发者自己的代码里涉及的界面部分
框架部分：即uni-app x内置组件和API涉及界面的部分

# 开发者代码的国际化

这里的国际化指动态切换语言。如果是写死一种语言，直接在代码里写就好了。

# App平台

vue-i18n这个vue插件库还没有适配uts，但自己实现一个语言替换机制也不难。

推荐使用这个插件来解决动态语言切换，lime-i18n

# Web平台

Web平台可以使用标准的vue-i18n插件。

main.uts 引入并初始化 VueI18n。（注意写条件编译，避免App平台报错）

// 国际化 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
}

import { createSSRApp } from 'vue'
import { createI18n } from 'vue-i18n'// v9.x
const i18n = createI18n(i18nConfig)
export function createApp() {
  const app = createSSRApp(App)
  app.use(i18n)
  return {
    app
  }
}

示例源码如下，请查看 pre > code 标签中的内容

// 国际化 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
}

import { createSSRApp } from 'vue'
import { createI18n } from 'vue-i18n'// v9.x
const i18n = createI18n(i18nConfig)
export function createApp() {
  const app = createSSRApp(App)
  app.use(i18n)
  return {
    app
  }
}

国际化json文件内容

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

示例源码如下，请查看 pre > code 标签中的内容

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

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

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

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

示例源码如下，请查看 pre > code 标签中的内容

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

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

注意：页面中设置语言后需要调用 this.$i18n.locale = 'zh-Hans' 后生效

# pages.json 国际化

Web平台和App平台，可以通过设置tabbar和navigationbar的API来设置文字。

Web平台还额外支持如下使用方式：

项目根目录的locale目录下配置语言json文件，locale/[语言标签](#lantag).json，如：en.json，zh-Hans.json，zh-Hant.json

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

示例源码如下，请查看 pre > code 标签中的内容

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

语言文件示例（zh-Hans.json）

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

示例源码如下，请查看 pre > code 标签中的内容

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

pages.json 示例

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

示例源码如下，请查看 pre > code 标签中的内容

{
  "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

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

uni-app x 的部分组件和API涉及界面，框架内置支持的国际化语言，如果手机os或浏览器语言在这些内置国际化语言列表中会自适应。如果不在5种内，会默认为英文。

app-Android平台
- 中文简体
- 中文繁体
- 英语
- 法语(HBuilderX 4.25及以上版本支持)
- 西班牙语(HBuilderX 4.25及以上版本支持)
app-iOS平台
- 中文简体
- 中文繁体(HBuilderX 4.25及以上版本支持)
- 英语(HBuilderX 4.25及以上版本支持)
- 法语(HBuilderX 4.25及以上版本支持)
- 西班牙语(HBuilderX 4.25及以上版本支持)
web平台
- 中文简体
- 中文繁体
- 英语
- 法语
- 西班牙语

涉及界面的组件和API包括：

uni.showModal：默认的确定和取消按钮文字，会根据os和浏览器的语言自适应。也可以在API中通过参数自己指定文字。
uni.showActionSheet：取消按钮文字，会根据os和浏览器的语言自适应。
uni.chooseImage 、uni.chooseVideo：
- app平台弹出的拍摄和从相册选择的actionsheet方式的选择框文字不支持国际化，但可以设置sourceType参数值为单项，自己弹出选择框来处理。
  - 拍摄 打开的是系统相机界面，在app平台跟随系统语言，不受uni-app x内置国际化语言列表限制
  - 从相册选择 分系统相册和自定义相册。系统相册的国际化是根据手机OS的语言设置。自定义相册界面，在uni-app x内置国际化语言列表可配置。
- 小程序这部分的国际化大多跟随小程序宿主的语言
uni.chooseMedia：
- app平台弹出系统媒体选择界面，使用的是当前系统的语言。

# manifest.json 国际化

HBuilderX5.0及以上版本 app-android/app-ios平台云端打包支持设置国际化

manifest.json 文件的国际化与 pages.json 一样，在项目根目录的locale目录下配置语言json文件，locale/[语言标签](#lantag).json，如下：

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

示例源码如下，请查看 pre > code 标签中的内容

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

语言文件示例（zh-Hans.json）：

{
  "app.name": "你好UniX"
}

示例源码如下，请查看 pre > code 标签中的内容

{
  "app.name": "你好UniX"
}

# 应用名称

在manifest.json可视化界面的“应用名称”中配置为 %app.name% 。

或在源码视图中配置如下：

{
	"name": "%app.name%",
  "app.ios.des.camera": "拍照功能需要使用摄像头"
}

示例源码如下，请查看 pre > code 标签中的内容

{
	"name": "%app.name%",
  "app.ios.des.camera": "拍照功能需要使用摄像头"
}

配置后需提交云端打包生效。

注意
app-android、app-ios平台离线打包需在原生工程中配置应用的国际化名称。

# app-ios平台隐私信息许可描述

iOS平台应用的隐私信息访问的许可描述中的提示文字，也可在manifest.json中配置国际化。
在可视化界面 “iOS App配置” 的 “隐私信息访问的许可描述” 对应的项中配置，如 “摄像头（NSCameraUsageDescription）” 项配置为 %app.ios.des.camera% 。

或在源码视图中配置 “摄像头（NSCameraUsageDescription）” 如下：

{
	"app-ios": {
		"distribute": {
			"privacyDescription": {
				"NSCameraUsageDescription": "%app.ios.des.camera%"
			}
		}
	}
}

示例源码如下，请查看 pre > code 标签中的内容

{
	"app-ios": {
		"distribute": {
			"privacyDescription": {
				"NSCameraUsageDescription": "%app.ios.des.camera%"
			}
		}
	}
}

配置后需提交云端打包生效。

注意
app-ios平台暂不支持配置Info.plist文件中其他信息的国际化配置，有此特殊需求离线打包可在原生XCode工程中配置。

# uniCloud国际化

注：大陆以外的终端用户访问uniCloud，开通阿里云的海外加速后可以提高访问速度。详见

# DB Schema 国际化

uniCloud的 DB Schema 中涉及字段的显示名称、错误格式提示语，这些也需要国际化。

在项目根目录 uniCloud/database/locale/{数据库表名}/[语言标签](#lantag).json 文件，然后在 *.schema.json 文件中使用 %% 占位

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

示例源码如下，请查看 pre > code 标签中的内容

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

hello.schema.json 文件内容

// 文档教程: https://doc.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%"
      }
    }
  }
}

示例源码如下，请查看 pre > code 标签中的内容

// 文档教程: https://doc.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 文件内容

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

示例源码如下，请查看 pre > code 标签中的内容

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

zh-Hans 文件内容

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

示例源码如下，请查看 pre > code 标签中的内容

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

# App第三方SDK界面的国际化

Web平台内置支持Google地图。

其他如海外的支付、登录等app sdk，需自行开发插件或去插件市场搜索。

# 语言API

uni-app内置获取os或浏览器语言的API。

# Web平台还支持以下更多功能

Web平台注意要区分系统语言和应用语言的概念。

可以得到设备OS的语言、运行宿主host的语言以及应用自身的语言。

uni.getLocale

获取应用当前使用的语言

uni.setLocale

设置应用语言

uni.onLocaleChange

当前应用语言发生变化时，触发回调。也就是uni.setLocale执行时。

# 语言标签

语言标签由一个或多个子标签（subtags）组成，用连字号(-)分隔，子标签只能由基本拉丁字母或数字组成。处理逻辑遵循 BCP 47 规范。

语言标签通常为两个或三个字母，参考ISO 639规范

语言代码-地区代码，地区代码为两个字母，参考ISO 3166-2规范

常见语言标签示例：

标签	含义	使用场景
zh	中文（泛指）	通用中文内容
zh-Hans	简体中文	简体文本（不指定地区）
zh-Hans-SG	中文，简体，新加坡	新加坡简体中文
zh-Hant	繁体中文	繁体文本（不指定地区）
zh-Hant-HK	中文，繁体，香港	香港繁体中文
zh-Hant-TW	中文，繁体，台湾	台湾繁体中文
en	英文	-
en-US	英文，美国	-