https://github.com/eggjs/i18n
i18n plugin for egg
https://github.com/eggjs/i18n
egg-plugin i18n
Last synced: 5 months ago
JSON representation
i18n plugin for egg
- Host: GitHub
- URL: https://github.com/eggjs/i18n
- Owner: eggjs
- License: mit
- Created: 2016-07-24T01:51:29.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2025-01-12T02:04:19.000Z (about 1 year ago)
- Last Synced: 2025-10-05T14:02:01.616Z (5 months ago)
- Topics: egg-plugin, i18n
- Language: TypeScript
- Homepage:
- Size: 50.8 KB
- Stars: 41
- Watchers: 8
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-egg - egg-i18n - 多语言。   (仓库 / [内置插件](https://eggjs.org/zh-cn/basics/plugin.html#%E6%8F%92%E4%BB%B6%E5%88%97%E8%A1%A8))
README
# @eggjs/i18n
[![NPM version][npm-image]][npm-url]
[](https://github.com/eggjs/i18n/actions/workflows/nodejs.yml)
[![Test coverage][codecov-image]][codecov-url]
[![Known Vulnerabilities][snyk-image]][snyk-url]
[![npm download][download-image]][download-url]
[](https://nodejs.org/en/download/)
[](https://makeapullrequest.com)
[npm-image]: https://img.shields.io/npm/v/@eggjs/i18n.svg?style=flat-square
[npm-url]: https://npmjs.org/package/@eggjs/i18n
[codecov-image]: https://img.shields.io/codecov/c/github/eggjs/i18n.svg?style=flat-square
[codecov-url]: https://codecov.io/github/eggjs/i18n?branch=master
[snyk-image]: https://snyk.io/test/npm/@eggjs/i18n/badge.svg?style=flat-square
[snyk-url]: https://snyk.io/test/npm/@eggjs/i18n
[download-image]: https://img.shields.io/npm/dm/@eggjs/i18n.svg?style=flat-square
[download-url]: https://npmjs.org/package/@eggjs/i18n
可以为你的应用提供多语言的特性
## 功能
- 支持多种语言独立配置，统一存放在 config/locale/\*.js 下（ 兼容 `config/locales/*.js` ）；
- 提供 Middleware 为 View 提供 `\_\_`, `gettext` 函数获取多语言文案；
- 基于 URL 参数 `locale` 修改语言显示，同时会记录到 Cookie，下次请求会用 Cookie 里面的语言方案。
## 配置
默认处于关闭状态，你需要在 `config/plugin.ts` 开启它：
```ts
// config/plugin.ts
export default {
i18n: {
enable: true,
package: '@eggjs/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,
};
};
```
### View 文件下的使用示例
```html
{{ __('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](LICENSE)
## Contributors
[](https://github.com/eggjs/i18n/graphs/contributors)
Made with [contributors-img](https://contrib.rocks).