egg-i18n

egg-i18n

可以为你的应用提供多语言的特性

功能

• 支持多种语言独立配置，统一存放在 config/locale/*.js 下（ 兼容 config/locales/*.js ）；
• 提供 Middleware 为 View 提供 \_\_, gettext 函数获取多语言文案；
• 基于 URL 参数 locale 修改语言显示，同时会记录到 Cookie，下次请求会用 Cookie 里面的语言方案。

配置

默认处于关闭状态，你需要在 config/plugin.js 开启它：

// config/plugin.js
exports.i18n = {
  enable: true,
  package: 'egg-i18n',
};

你可以修改 config/config.default.js 来设定 i18n 的配置项：

// config/config.default.js
exports.i18n = {
  // 默认语言，默认 "en_US"
  defaultLocale: 'zh-CN',
  // URL 参数，默认 "locale"
  queryField: 'locale',
  // Cookie 记录的 key, 默认："locale"
  cookieField: 'locale',
  // Cookie 的 domain 配置，默认为空，代表当前域名有效
  cookieDomain: '',
  // Cookie 默认 `1y` 一年后过期， 如果设置为 Number，则单位为 ms
  cookieMaxAge: '1y',
};

其实大部分时候，你只需要修改一下 defaultLocale 设定默认的语言。

编写你的 I18n 多语言文件

// config/locale/zh-CN.js
module.exports = {
  "Email": "邮箱",
  "Welcome back, %s!": "欢迎回来，%s!",
  "Hello %s, how are you today?": "你好 %s, 今天过得咋样？",
};

// config/locale/en-US.js
module.exports = {
  "Email": "Email",
};

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

// config/locale/zh-CN.json
{
  "email": "邮箱",
  "login": "帐号",
  "createdAt": "注册时间"
}

使用 I18n 函数获取语言文本

I18n 为你提供 __ (Alias: gettext) 函数，让你可以轻松获得 locale 文件夹下面的多语言文本。

NOTE: __ 是两个下划线哦！

• ctx.__ = function (key, value[, value2, ...]): 类似 util.format 接口
• ctx.__ = function (key, values): 支持数组下标占位符方式，如

ctx.__('{0} {0} {1} {1}'), ['foo', 'bar'])
ctx.gettext('{0} {0} {1} {1}'), ['foo', 'bar'])
=>
foo foo bar bar

Controllers 下的使用示例

module.exports = function* () {
  this.body = {
    message: this.__('Welcome back, %s!', this.user.name)
    // 或者使用 gettext，如果觉得 __ 不好看的话
    // message: this.gettext('Welcome back, %s!', this.user.name)
    user: this.user,
  };
};

View 文件下的使用示例

<li>{{ __('Email') }}: {{ user.email }}</li>
<li>
  {{ __('Hello %s, how are you today?', user.name) }}
</li>
<li>
  {{ __('{0} {0} {1} {1}'), ['foo', 'bar']) }}
</li>

修改应用的默认语言

你可以用下面几种方式修改应用的当前语言（修改或会记录到 Cookie)，下次请求直接用设定好的语言。

优先级从上到下：

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

Changelog

3.0.0 (2025-01-11)

⚠ BREAKING CHANGES

• drop Node.js < 18.19.0 support

part of https://github.com/eggjs/egg/issues/3644

https://github.com/eggjs/egg/issues/5257

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

Summary by CodeRabbit

Based on the comprehensive changes, here are the updated release notes:

• New Features

  • Migrated package to TypeScript with improved type safety.

• Enhanced internationalization (i18n) support with more flexible configuration.

  • Added comprehensive GitHub Actions workflows for CI/CD.

• Improvements

  • Updated Node.js compatibility to version 18.19.0+.
  • Modernized module system with ES module support.
  • Refined configuration and localization mechanisms.

• Breaking Changes

  • Package renamed from egg-i18n to @eggjs/i18n.
  • Switched from CommonJS to ES module syntax.
  • Removed legacy configuration files and testing infrastructure.

• Chores

  • Cleaned up and simplified project structure.
  • Updated dependencies and development tooling.
  • Improved documentation and README.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Features

• support cjs and esm both by tshy (#14) (ccc8eaa)

2.1.1 / 2019-04-30

fixes

• [4d1c463] - fix: use ctx.__setLocale to set cookie (#12) (Yiyu He <[e-mail]>)

others

• [cfd25db] - test: assert locale cookie without domain (#11) (fengmk2 <[e-mail]>)
• [99c56c4] - test: node 12 (fengmk2 <[e-mail]>)

2.1.0 / 2019-04-28

features

• [ce59330] - feat: support ctx.locale setter (#10) (Yiyu He <[e-mail]>)

others

• [50322d6] - chore: add cookieDomain options description (#9) (fengmk2 <[e-mail]>)

2.0.0 / 2017-11-10

others

• [80e591d] - refactor: use async function and support egg@2 (#8) (Yiyu He <[e-mail]>)

1.2.0 / 2017-09-13

features

• [1117129] - feat: use config/locale/*.js as default I18N folder (#7) (tudou527 <[e-mail]>)

1.1.1 / 2017-04-19

• fix: config.i18n.dir should be config.i18n.dirs (#6)

1.1.0 / 2017-01-13

• feat: add ctx.locale getter (#5)
• deps: upgrade deps (#4)

1.0.2 / 2016-08-26

• fix: don't use bind (#3)

1.0.1 / 2016-08-16

• fix: use loader.getLoadUnits from egg-core (#2)

1.0.0 / 2016-08-02

• init version