• 国际化（I18n）
  • 默认语言
  • 切换语言
  • 编写 I18n 多语言文件
  • 获取多语言文本
    • Controller 中使用
    • View 中使用

    国际化（I18n）

    为了方便开发多语言应用，框架内置了国际化（I18n）支持，由 egg-i18n 插件提供。

    默认语言

    默认语言是 en-US。假设我们想修改默认语言为简体中文：

    1. // config/config.default.js
    2. exports.i18n = {
    3.   defaultLocale: 'zh-CN',
    4. };

    切换语言

    我们可以通过下面几种方式修改应用的当前语言（修改后会记录到 locale 这个 Cookie），下次请求直接用设定好的语言。

    优先级从高到低：

    1. query: /?locale=en-US
    2. cookie: locale=zh-TW
    3. header: Accept-Language: zh-CN,zh;q=0.5

    如果想修改 query 或者 Cookie 参数名称：

    1. // config/config.default.js
    2. exports.i18n = {
    3.   queryField: 'locale',
    4.   cookieField: 'locale',
    5.   // Cookie 默认一年后过期， 如果设置为 Number，则单位为 ms
    6.   cookieMaxAge: '1y',
    7. };

    编写 I18n 多语言文件

    多种语言的配置是独立的，统一存放在 config/locale/*.js 下。

    1. - config/locale/
    2.   - en-US.js
    3.   - zh-CN.js
    4.   - zh-TW.js

    不仅对于应用目录生效，在框架，插件的 config/locale 目录下同样生效。

    注意单词拼写，是 locale 不是 locals。

    例如：

    1. // config/locale/zh-CN.js
    2. module.exports = {
    3.   Email: '邮箱',
    4. };

    或者也可以用 JSON 格式的文件：

    1. // config/locale/zh-CN.json
    2. {
    3.   "Email": "邮箱"
    4. }

    获取多语言文本

    我们可以使用 __ (Alias: gettext) 函数获取 locale 文件夹下面的多语言文本。

    注意: __ 是两个下划线

    以上面配置过的多语言为例：

    1. ctx.__('Email')
    2. // zh-CN => 邮箱
    3. // en-US => Email

    如果文本中含有 %s，%j 等 format 函数，可以按照 util.format() 类似的方式调用：

    1. // config/locale/zh-CN.js
    2. module.exports = {
    3.   'Welcome back, %s!': '欢迎回来，%s!',
    4. };
    6. ctx.__('Welcome back, %s!', 'Shawn');
    7. // zh-CN => 欢迎回来，Shawn!
    8. // en-US => Welcome back, Shawn!

    同时支持数组下标占位符方式，例如：

    1. // config/locale/zh-CN.js
    2. module.exports = {
    3.   'Hello {0}! My name is {1}.': '你好 {0}! 我的名字叫 {1}。',
    4. };
    6. ctx.__('Hello {0}! My name is {1}.', ['foo', 'bar'])
    7. // zh-CN => 你好 foo！我的名字叫 bar。
    8. // en-US => Hello foo! My name is bar.

    Controller 中使用

    1. class HomeController extends Controller {
    2.   async index() {
    3.     const ctx = this.ctx;
    4.     ctx.body = {
    5.       message: ctx.__('Welcome back, %s!', ctx.user.name)
    6.       // 或者使用 gettext，gettext 是 __ 函数的 alias
    7.       // message: ctx.gettext('Welcome back', ctx.user.name)
    8.       user: ctx.user,
    9.     };
    10.   }
    11. }

    View 中使用

    假设我们使用的模板引擎是 Nunjucks

    1. <li>{{ __('Email') }}: {{ user.email }}</li>
    2. <li>
    3.   {{ __('Welcome back, %s!', user.name) }}
    4. </li>
    5. <li>
    6.   {{ __('Hello {0}! My name is {1}.', ['foo', 'bar']) }}
    7. </li>