docs: (core/i18n): [translate] Done (#1194)

docs/source/en/core/i18n.md

@@ -0,0 +1,137 @@
+title: I18n Internationalization
+---
+
+For developing the multi-language application, build-in I18n support by [egg-i18n](https://github.com/eggjs/egg-i18n) plugin 
+
+## Default Language 
+
+Default `en-US`. Assume that we want to switch the default language to Simplified Chinese：
+
+```js
+// config/config.default.js
+exports.i18n = {
+  defaultLocale: 'zh-CN',
+};
+```
+
+## Switch Language
+
+Here we have some ways to switch the application's current language (Modified records will set to the cookie `locale`), the next request will use the language setting directly.
+
+Priority from high to low:
+
+1. query: `/?locale=en-US`
+2. cookie: `locale=zh-TW`
+3. header: `Accept-Language: zh-CN,zh;q=0.5`
+
+If want to modify parameter name of query or cookie 
+
+```js
+// config/config.default.js
+exports.i18n = {
+  queryField: 'locale',
+  cookieField: 'locale',
+  // Cookie default expired after one year, the unit is ms if set as Number
+  cookieMaxAge: '1y',
+};
+```
+
+## Writing I18n Multi-language Documents
+
+Configuration of multi-language are independent, stored in `config/locales/*.js`
+
+```
+- config/locales/
+  - en-US.js
+  - zh-CN.js
+  - zh-TW.js
+```
+
+Not only take effects in the application directory, but also in the directory of framework or plugin `config/locales` 
+
+ __Note: It's locales, not locals.__
+
+Example:
+
+```js
+// config/locales/zh-CN.js
+module.exports = {
+  Email: '邮箱',
+};
+```
+
+Or using JSON file:
+
+```json
+// config/locales/zh-CN.json
+{
+  "Email": "邮箱"
+}
+```
+
+## Getting Multi-language Texts
+
+Use `__` (Alias: `gettext`) function to get the multi-language texts under locales directory
+
+__Note: `__` is two underscores__
+
+Take above multi-language configuration as example:
+
+```js
+ctx.__('Email')
+// zh-CN => 邮箱
+// en-US => Email
+```
+
+If texts contain format function like `%s`，`%j`, we can call by the way similar to [`util.format()`](https://nodejs.org/api/util.html#util_util_format_format_args)
+
+```js
+// config/locales/zh-CN.js
+module.exports = {
+  'Welcome back, %s!': '欢迎回来，%s!',
+};
+
+ctx.__('Welcome back, %s!', 'Shawn');
+// zh-CN => 欢迎回来，Shawn!
+// en-US => Welcome back, Shawn!
+```
+
+Support array, subscript and placeholder, such as
+
+```js
+// config/locales/zh-CN.js
+module.exports = {
+  'Hello {0}! My name is {1}.': '你好 {0}! 我的名字叫 {1}。',
+};
+
+ctx.__('Hello {0}! My name is {1}.', ['foo', 'bar'])
+// zh-CN => 你好 foo！我的名字叫 bar。
+// en-US => Hello foo! My name is bar.
+```
+
+### Use in Controller
+
+```js
+module.exports = function* (ctx) {
+  ctx.body = {
+    message: ctx.__('Welcome back, %s!', ctx.user.name)
+    // or use gettext, it is a alias of __ function
+    // message: ctx.gettext('Welcome back', ctx.user.name)
+    user: ctx.user,
+  };
+};
+```
+
+### Use in View
+
+Assume we are using template engine [Nunjucks](https://github.com/eggjs/egg-view-nunjucks)
+
+```html
+<li>{{ __('Email') }}: {{ user.email }}</li>
+<li>
+  {{ __('Welcome back, %s!', user.name) }}
+</li>
+<li>
+  {{ __('Hello {0}! My name is {1}.', ['foo', 'bar']) }}
+</li>
+```