docs(internationaliztion): refrator

document/components/docs/en-US/internationalization.md

@@ -2,65 +2,59 @@
 
 > New in 1.11.0+
 
-The cube-ui component uses Chinese internally by default. If you want to use another language, you need to set it in multiple languages. Take English as an example in main.js:
+All non-configurable copy files inside `cube-ui` are in Chinese, so if your application needs to do the corresponding international translation, then `1.11.0` is available for cube-ui provide ability to translate a component's copywriting, even this ability can be extended to your application.
 
-```js
-
-  // Full import
-  import Vue from 'vue'
-  import CubeUI from 'cube-ui'
-  import enUSMessages from 'cube-ui/src/locale/lang/en-US' // Built-in in cube-ui
-  import jaJPMessages from '../some/path/lang/ja-JP' // Import Japanese language by yourself
-  const Locale = CubeUI.Locale
-  Vue.use(CubeUI)
-  Locale.use('en-US', enUSMessages)
-  Locale.use('ja-JP', jaJPMessages)
-
-```
+## Internationalization within components
 
-Or, import by module
+Cube-ui is the Chinese language pack used by default and is already registered. The corresponding English language pack is also built into the cube-ui, but you need the following logic to register the language pack and switch to the corresponding language.
 
 ```js
-
-  // Only import ActionSheet
   import Vue from 'vue'
-  import { ActionSheet, Locale } from 'cube-ui'
+  import { Locale } from 'cube-ui'
   import enUSMessages from 'cube-ui/src/locale/lang/en-US'
 
   Vue.use(Locale)
+  // Switch to English and cache the current language pack
   Locale.use('en-US', enUSMessages)
-
 ```
 
-Cube-ui will watch the current language type, so it automatically renders once language type has changed, and caches the loaded translation. When the language type is switched and the language translation is already installed, cube-ui directly takes the cached copy. Similar pseudo code is as follows:
+Cube-ui will listen to the current language type, so it automatically renders the corresponding copy of the component, and caches the loaded copy. When the component language is switched, if the language pack is already installed, cube-ui directly takes the cached copy. Similar pseudo code is as follows:
 
 ```js
-
-  // Only import ActionSheet
   import Vue from 'vue'
-  import { ActionSheet, Locale } from 'cube-ui'
+  import { Locale } from 'cube-ui'
   import enUSMessages from 'cube-ui/src/locale/lang/en-US'
 
-  // Chinese translation by default
+  // Load Chinese language pack by default
   Vue.use(Locale)
 
-  // Click to switch English language translation
+  // Switch to English and need to import the English language pack
   one.click(() =>{
     Locale.use('en-US', enUSMessages)
   })
 
-  // Switch back to default
   another.click(() => {
-    // Take the translation from the cache
+    // load Chinese from cache
     Locale.use('zh-CN')
   })
-
 ```
 
-The default messages is as follows
+But maybe you have translation needs in other countries, such as Japanese and Korean, then you need to provide the language pack yourself and switch to the corresponding language. code show as below:
 
 ```js
+  import Vue from 'vue'
+  import { Locale } from 'cube-ui'
+  import jPMessages from '/somewhere/ja-JP.js' // Your own language
+
+  Vue.use(Locale)
+
+  // Switch to Japanese and need to import Japanese language packs
+  Locale.use('ja-JP', jPMessages)
+```
 
+The configuration item format of the language pack you import should be similar to the following. The default Chinese language pack is as follows:
+
+```js
   export default {
     cancel: '取消',
     confirm: '确认',
@@ -117,5 +111,75 @@ The default messages is as follows
       notWhitespace: '空白内容无效'
     }
   }
-
 ```
+
+## Internationalization of applications
+
+As mentioned above, cube-ui provides international capabilities for its own components, but this capability can be extended to your application in two steps:
+
+1. Import language packs
+
+  1. Import the language pack First, you must import the language pack, which should be the full set containing the cube-ui default language pack. For example, your language pack configuration might look like this:
+
+  ```js
+    // default.js
+    export default {
+      "application_key": "this is application text",
+
+      /* defaults of cube-ui*/
+      "cancel": "Cancel",
+      // ...ignore
+      "validator": {/* */}
+    }
+  ```
+
+  Then import the language pack in your app's entry file.
+
+  ```js
+    import Vue from 'vue'
+    import { Locale } from 'cube-ui'
+    import defaultMessages from 'default.js' // your own language
+
+    Vue.use(Locale)
+    Locale.use('zh-CN', defaultMessages)
+  ```
+
+2. Ability to inject translations through mixins inside components
+
+  At this time, you will find a `$cubeLang` and `$cubeMessages` attribute on `Vue.prototype`. The former is the current language, and this is a responsive attribute. The latter is the language pack content. You can inject all of your component instances with the ability of `mixin` provided by Vue.
+
+  Write a `mixin` file first:
+
+  ```js
+    // localeMixin.js
+    export default {
+      methods: {
+        $t (key) {
+          const lang = this.$cubeLang
+          const messages = this.$cubeMessages[lang]
+          return this.$cubeMessages[lang][key] || ''
+        }
+      }
+    }
+  ```
+
+  Then injecting into the corresponding component instance:
+
+  ```js
+    // dialog.vue
+    import LocaleMixin from 'localeMixin.js'
+
+    exports default {
+      mixins: [LocaleMixin]
+    }
+  ```
+
+  This way you can reference the `$t()` method in the template.
+
+  ```html
+    <template>
+      <div>{{$t('application_key')}}</div>
+    </template>
+  ```
+
+  This way `{{$t('application_key')}}` will be replaced with `"this is application text"`.

document/components/docs/zh-CN/internationalization.md

@@ -2,65 +2,59 @@
 
 > 1.11.0 新增
 
-cube-ui 组件内部默认使用中文，若希望使用其他语言，则需要进行多语言设置。以英文为例，在 main.js 中：
+cube-ui 内部所有非可配置的文案，都是中文的形式，所以如果你的应用是需要做对应的国际化文案翻译，那么 cube-ui  `1.11.0` 这个版本是提供了给 cube-ui 组件的文案翻译的能力，甚至这种能力也能延伸至你的应用。
 
-```js
-
-  // 完整引入 cube-ui
-  import Vue from 'vue'
-  import CubeUI from 'cube-ui'
-  import enUSMessages from 'cube-ui/src/locale/lang/en-US' // cube-ui 内置
-  import jaJPMessages from '../some/path/lang/ja-JP' // 自己引入日语语言包
-  const Locale = CubeUI.Locale
-  Vue.use(CubeUI)
-  Locale.use('en-US', enUSMessages)
-  Locale.use('ja-JP', jaJPMessages)
-
-```
+## 组件内部的国际化
 
-或者按需引入
+cube-ui 默认是用的中文语言包，并且已经注册了。cube-ui 内部也内置了对应的英文语言包，但是你需要如下的逻辑来注册语言包，同时切换至对应的语言。
 
 ```js
-
-  // 按需引入 ActionSheet
   import Vue from 'vue'
-  import { ActionSheet, Locale } from 'cube-ui'
+  import { Locale } from 'cube-ui'
   import enUSMessages from 'cube-ui/src/locale/lang/en-US'
 
   Vue.use(Locale)
+  // 切换至英语，并且缓存当前语言包
   Locale.use('en-US', enUSMessages)
-
 ```
 
 cube-ui 会监听当前的语言类型，因此自动渲染组件对应的文案，同时缓存加载过的文案，在做组件语言切换的时候，如果语言包已经安装，cube-ui 直接取缓存的文案。类似伪代码如下：
 
 ```js
-
-  // 按需引入 ActionSheet
   import Vue from 'vue'
-  import { ActionSheet, Locale } from 'cube-ui'
+  import { Locale } from 'cube-ui'
   import enUSMessages from 'cube-ui/src/locale/lang/en-US'
 
   // 默认加载中文语言包
   Vue.use(Locale)
 
-  // 点击切换英文语言包
+  // 切换至英语，并且需要导入英语语言包
   one.click(() =>{
     Locale.use('en-US', enUSMessages)
   })
 
-  // 再次切换回中文语言包
   another.click(() => {
-    // 直接从缓存取
+    // 从缓存取之前的语言包
     Locale.use('zh-CN')
   })
-
 ```
 
-默认的中文语言包如下
+但是可能你有其他国家的翻译需求，比如日语、韩语，那么你需要自己提供语言包，并且切换至对应语言。代码如下：
 
 ```js
+  import Vue from 'vue'
+  import { Locale } from 'cube-ui'
+  import jPMessages from '/somewhere/ja-JP.js' // 自己的语言包
+
+  Vue.use(Locale)
+
+  // 切换至日语，并且需要导入日语语言包
+  Locale.use('ja-JP', jPMessages)
+```
 
+你导入的语言包的配置项形式应该与下面相仿，默认的中文语言包如下：
+
+```js
   export default {
     cancel: '取消',
     confirm: '确认',
@@ -117,5 +111,75 @@ cube-ui 会监听当前的语言类型，因此自动渲染组件对应的文案
       notWhitespace: '空白内容无效'
     }
   }
-
 ```
+
+## 应用内的组件化
+
+如上面所述，cube-ui 给自己的组件提供了国际化的能力，但是这种能力也能延伸至你的应用，分两步进行：
+
+1. **导入语言包**
+
+  首先，得导入语言包，这个语言包应该是包含 cube-ui 默认语言包的全集。比如你的语言包配置可能如下：
+
+  ```js
+    // default.js
+    export default {
+      "application_key": "这是我应用的翻译",
+
+      /* cube-ui 的默认配置*/
+      "cancel": "Cancel",
+      // ...忽略中间部分的配置，
+      "validator": {/* */}
+    }
+  ```
+
+  接着在你应用的入口文件导入这个语言包。
+
+  ```js
+    import Vue from 'vue'
+    import { Locale } from 'cube-ui'
+    import defaultMessages from 'default.js' // 自己的语言包
+
+    Vue.use(Locale)
+    Locale.use('zh-CN', defaultMessages)
+  ```
+
+2. **在组件内部通过 mixins 注入翻译的能力**
+
+  这个时候，你会发现 `Vue.prototype` 上面有个 `$cubeLang` 与 `$cubeMessages` 属性。前者是当前语言，这个是响应式的属性。后者是语言包内容。可以通过 Vue 提供的 `mixin` 的能力注入到你所有的组件实例当中。
+
+  先编写一个 mixin 文件：
+
+  ```js
+    // localeMixin.js
+    export default {
+      methods: {
+        $t (key) {
+          const lang = this.$cubeLang
+          const messages = this.$cubeMessages[lang]
+          return this.$cubeMessages[lang][key] || ''
+        }
+      }
+    }
+  ```
+
+  后注入到对应的组件实例。
+
+  ```js
+    // dialog.vue
+    import LocaleMixin from 'localeMixin.js'
+
+    exports default {
+      mixins: [LocaleMixin]
+    }
+  ```
+
+  这样就可以在 template 引用 `$t()` 方法了
+
+  ```html
+    <template>
+      <div>{{$t('application_key')}}</div>
+    </template>
+  ```
+
+  最后 `{{$t('application_key')}}` 就会被替换成 `"这是我应用的翻译"` 文本了。