# @eggjs/i18n 中文文档
规范地址：https://npmcn.com/package/%40eggjs/i18n/
版本：4\.1\.0
npm 元数据更新时间：2026-10-07T08:19:31.037Z
中文译文更新时间：2026-11-13T09:45:28.695Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40eggjs/i18n
原文对照：https://npmcn.com/package/%40eggjs/i18n/?lang=original
项目主页：https://github.com/eggjs/egg/tree/next/plugins/i18n#readme
源码仓库：https://github.com/eggjs/egg
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：25.5 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>= 22\.18\.0
- 运行依赖：5 个
- peer 依赖：egg 4\.2\.0
- 首次发布：2025-01-11T16:53:58.127Z
- 最新版本发布：2026-10-07T08:19:30.670Z
- 近 30 天下载量：5096（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：53（近 12 个月 33 个）
## 中文简介
鸡蛋的 i18n 插件
## 安装
```sh
npm install @eggjs/i18n
```
也可以使用：`pnpm add @eggjs/i18n`、`yarn add @eggjs/i18n`、`bun add @eggjs/i18n`
## README
# @eggjs/i18n
[](https://npmjs.org/package/@eggjs/i18n) [](https://snyk.io/test/npm/@eggjs/i18n) [](https://npmjs.org/package/@eggjs/i18n) [](https://nodejs.org/en/download/) [](https://makeapullrequest.com/)
可以为你的应用提供多语言的特性
## 功能
- 支持多种语言独立配置，统一存放在 config/locale/\*.js 下（ 兼容 `config/locales/*.js` ）；
- 提供 Middleware 为 View 提供 `\_\_`, `gettext` 函数获取多语言文案；
- 基于 URL 参数 `locale` 修改语言显示，同时会记录到 Cookie，下次请求会用 Cookie 里面的语言方案。
## 配置
egg 内置插件 `i18n` 默认开启。
你可以修改 `config/config.default.ts` 来设定 i18n 的配置项：
```ts
// config/config.default.ts
export default {
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 多语言文件
```ts
// config/locale/zh-CN.ts
export default {
Email: '邮箱',
'Welcome back, %s!': '欢迎回来，%s!',
'Hello %s, how are you today?': '你好 %s, 今天过得咋样？',
};
```
```ts
// config/locale/en-US.ts
export default {
Email: 'Email',
};
```
或者也可以用 JSON 格式的文件：
```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)`: 支持数组下标占位符方式，如
```ts
ctx.__('{0} {0} {1} {1}', ['foo', 'bar']);
ctx.gettext('{0} {0} {1} {1}', ['foo', 'bar']);
=>
foo foo bar bar
```
### Controllers 下的使用示例
```ts
export default ctx => {
ctx.body = {
message: ctx.__('Welcome back, %s!', ctx.user.name)
// 或者使用 gettext，如果觉得 __ 不好看的话
// message: this.gettext('Welcome back, %s!', ctx.user.name)
user: ctx.user,
};
};
```
### HttpController 下的使用示例
```ts
import { HTTPController, HTTPMethod, HTTPMethodEnum, HTTPContext, Context } from 'egg';
@HTTPController()
export default class I18nController {
@HTTPMethod({ method: HTTPMethodEnum.GET, path: '/i18n' })
async getI18n(@HTTPContext() ctx: Context) {
return { message: ctx.__('Welcome back, %s!', ctx.user.name) };
}
}
```
### View 文件下的使用示例
```html
{{ __('Email') }}: {{ user.email }}
{{ __('Hello %s, how are you today?', user.name) }}
{{ __('{0} {0} {1} {1}', ['foo', 'bar']) }}
```
### 修改应用的默认语言
你可以用下面几种方式修改应用的当前语言（修改或会记录到 Cookie），下次请求直接用设定好的语言。
优先级从上到下：
- query: `/?locale=en-US`
- cookie: `locale=zh-TW`
- header: `Accept-Language: zh-CN,zh;q=0.5`
## Questions & Suggestions
Please open an issue [here](https://github.com/eggjs/egg/issues).
## License
[MIT](https://npmcn.com/package/%40eggjs/i18n/LICENSE)
## Contributors
[](https://github.com/eggjs/egg/graphs/contributors)
Made with [contributors-img](https://contrib.rocks/).
## 常见问题
### @eggjs/i18n 是什么？
鸡蛋的 i18n 插件
### 如何安装 @eggjs/i18n？
在项目目录运行 npm install @eggjs/i18n，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：egg（4\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @eggjs/i18n 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @eggjs/i18n 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @eggjs/i18n 需要什么版本的 Node\.js？
package\.json 的 engines 字段要求 Node\.js \>= 22\.18\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。
### @eggjs/i18n 可以商用吗？
@eggjs/i18n 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @eggjs/i18n 的下载量有多少？
根据 npm 官方下载统计，@eggjs/i18n 在 2026/10/13 – 2026/11/11 这 30 天内被下载 5,096 次，日均约 170 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @eggjs/i18n 还在维护吗？
最新版本 4\.1\.0 发布于 2026/10/07（1 个月前）；至今共发布 53 个版本，其中过去 12 个月发布了 33 个；首次发布于 2025/01/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。