update: i18n

docs/collocation/i18n.md

@@ -16,18 +16,160 @@ uni-app 从 3.1.5 版本开始框架内置组件开始完善国际化支持，
 vue和js里的内容国际化是通行方案。
 uni-app基于vue.js，有成熟的i18n插件，[这里是uni-app开发者分享的i18n插件的使用](https://ask.dcloud.net.cn/article/35102)
 
-## pages.json的国际化
+## 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和原生导航栏里也有文字内容。这部分内容的国际化方案如下：
-- 底部tabbar，用uni.setTabBarItem的api动态设置文字；
-- 顶部的title，用uni.setNavigationBarTitle动态设置文字（如果每个页面都需要设置，可以使用 Vue.mixin）；如果App端用了titleNView的文字按钮，通用的做法是换成图标，如果必须使用文字，app端可用setstyle，参考[https://ask.dcloud.net.cn/article/35374](https://ask.dcloud.net.cn/article/35374)；h5端用dom操作可动态修改。
-- 当然也可以不使用原生导航栏，前端自定义title（渲染速度没有原生快），也不会涉及这些问题。
+
+项目根目录的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` 中支持配置默认语言，参见上面的示例，默认跟随系统语言
+
 
 ## 应用中原生ui界面的国际化
-应用中调用到相册选择、扫码、地图等包含界面的原生能力时，这些原生界面的ui无法在前端控制。
+应用中调用到相册选择、地图等包含界面的原生能力时，这些原生界面的ui无法在前端控制。
 - 地图部分，可以使用web-view组件内嵌google的web地图，也可以用uni-app的原生插件机制封装google原生地图sdk。
-- 扫码部分，App 3.1.5+ 已内置国际化，低版本可以不用uni封装好的界面API，而是使用plus.barcode，自定义扫码界面，[参考](https://ask.dcloud.net.cn/article/35036)
 - 其他原生ui界面如相册选择，无法国际化，可以自己开发一个原生插件来替代之。
 
 ## 应用名称及iOS隐私提示语的国际化
 云打包详见[https://ask.dcloud.net.cn/article/35860](https://ask.dcloud.net.cn/article/35860)
-离线打包自行在原生工程中配置。
\ No newline at end of file
+离线打包自行在原生工程中配置。
+
+
+## 语言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 平台因原生层限制，将自动重启，其他平台均实时变化，包括已打开的所有页面