@eggjs/i18n 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Alibaba Group Holding Limited and other contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# @eggjs/i18n
+
+[![NPM version][npm-image]][npm-url]
+[![Node.js CI](https://github.com/eggjs/i18n/actions/workflows/nodejs.yml/badge.svg)](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]
+[![Node.js Version](https://img.shields.io/node/v/@eggjs/i18n.svg?style=flat)](https://nodejs.org/en/download/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](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
+<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`
+
+## Questions & Suggestions
+
+Please open an issue [here](https://github.com/eggjs/egg/issues).
+
+## License
+
+[MIT](LICENSE)
+
+## Contributors
+
+[![Contributors](https://contrib.rocks/image?repo=eggjs/i18n)](https://github.com/eggjs/i18n/graphs/contributors)
+
+Made with [contributors-img](https://contrib.rocks).

package/dist/commonjs/app/extend/application.d.ts

@@ -0,0 +1,8 @@
+import { EggCore } from '@eggjs/core';
+export declare const I18N_RESOURCES: unique symbol;
+export default class I18nApplication extends EggCore {
+    [I18N_RESOURCES]: Record<string, Record<string, string>>;
+    isSupportLocale(locale: string): boolean;
+    gettext(locale: string, key: string, value?: any, ...args: any[]): string;
+    __(locale: string, key: string, value?: any, ...args: any[]): string;
+}

package/dist/commonjs/app/extend/application.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.I18N_RESOURCES = void 0;
+const node_util_1 = require("node:util");
+const core_1 = require("@eggjs/core");
+const utils_js_1 = require("../../utils.js");
+const debug = (0, node_util_1.debuglog)('@eggjs/i18n/app/extend/application');
+exports.I18N_RESOURCES = Symbol('Application i18n resources');
+class I18nApplication extends core_1.EggCore {
+    isSupportLocale(locale) {
+        return !!this[exports.I18N_RESOURCES][locale];
+    }
+    gettext(locale, key, value, ...args) {
+        if (!locale || !key) {
+            // __()
+            // __('en')
+            return '';
+        }
+        const resource = this[exports.I18N_RESOURCES][locale] || {};
+        let text = resource[key];
+        if (text === undefined) {
+            text = key;
+        }
+        debug('%s: %j => %j', locale, key, text);
+        if (!text) {
+            return '';
+        }
+        if (value === undefined) {
+            // __(locale, key)
+            return text;
+        }
+        if (args.length === 0) {
+            if ((0, utils_js_1.isObject)(value)) {
+                // __(locale, key, object)
+                // __('zh', '{a} {b} {b} {a}', {a: 'foo', b: 'bar'})
+                // =>
+                // foo bar bar foo
+                return formatWithObject(text, value);
+            }
+            if (Array.isArray(value)) {
+                // __(locale, key, array)
+                // __('zh', '{0} {1} {1} {0}', ['foo', 'bar'])
+                // =>
+                // foo bar bar foo
+                return formatWithArray(text, value);
+            }
+            // __(locale, key, value)
+            return (0, node_util_1.format)(text, value);
+        }
+        // __(locale, key, value1, ...)
+        return (0, node_util_1.format)(text, value, ...args);
+    }
+    __(locale, key, value, ...args) {
+        return this.gettext(locale, key, value, ...args);
+    }
+}
+exports.default = I18nApplication;
+const ARRAY_INDEX_RE = /\{(\d+)\}/g;
+function formatWithArray(text, values) {
+    return text.replace(ARRAY_INDEX_RE, (original, matched) => {
+        const index = parseInt(matched);
+        if (index < values.length) {
+            return values[index];
+        }
+        // not match index, return original text
+        return original;
+    });
+}
+const Object_INDEX_RE = /\{(.+?)\}/g;
+function formatWithObject(text, values) {
+    return text.replace(Object_INDEX_RE, (original, matched) => {
+        const value = values[matched];
+        if (value) {
+            return value;
+        }
+        // not match index, return original text
+        return original;
+    });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBwbGljYXRpb24uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvYXBwL2V4dGVuZC9hcHBsaWNhdGlvbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQSx5Q0FBNkM7QUFDN0Msc0NBQXNDO0FBQ3RDLDZDQUEwQztBQUUxQyxNQUFNLEtBQUssR0FBRyxJQUFBLG9CQUFRLEVBQUMsb0NBQW9DLENBQUMsQ0FBQztBQUVoRCxRQUFBLGNBQWMsR0FBRyxNQUFNLENBQUMsNEJBQTRCLENBQUMsQ0FBQztBQUVuRSxNQUFxQixlQUFnQixTQUFRLGNBQU87SUFHbEQsZUFBZSxDQUFDLE1BQWM7UUFDNUIsT0FBTyxDQUFDLENBQUMsSUFBSSxDQUFDLHNCQUFjLENBQUMsQ0FBQyxNQUFNLENBQUMsQ0FBQztJQUN4QyxDQUFDO0lBRUQsT0FBTyxDQUFDLE1BQWMsRUFBRSxHQUFXLEVBQUUsS0FBVyxFQUFFLEdBQUcsSUFBVztRQUM5RCxJQUFJLENBQUMsTUFBTSxJQUFJLENBQUMsR0FBRyxFQUFFLENBQUM7WUFDcEIsT0FBTztZQUNQLFdBQVc7WUFDWCxPQUFPLEVBQUUsQ0FBQztRQUNaLENBQUM7UUFFRCxNQUFNLFFBQVEsR0FBRyxJQUFJLENBQUMsc0JBQWMsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxJQUFJLEVBQUUsQ0FBQztRQUVwRCxJQUFJLElBQUksR0FBRyxRQUFRLENBQUMsR0FBRyxDQUFDLENBQUM7UUFDekIsSUFBSSxJQUFJLEtBQUssU0FBUyxFQUFFLENBQUM7WUFDdkIsSUFBSSxHQUFHLEdBQUcsQ0FBQztRQUNiLENBQUM7UUFFRCxLQUFLLENBQUMsY0FBYyxFQUFFLE1BQU0sRUFBRSxHQUFHLEVBQUUsSUFBSSxDQUFDLENBQUM7UUFDekMsSUFBSSxDQUFDLElBQUksRUFBRSxDQUFDO1lBQ1YsT0FBTyxFQUFFLENBQUM7UUFDWixDQUFDO1FBRUQsSUFBSSxLQUFLLEtBQUssU0FBUyxFQUFFLENBQUM7WUFDeEIsa0JBQWtCO1lBQ2xCLE9BQU8sSUFBSSxDQUFDO1FBQ2QsQ0FBQztRQUNELElBQUksSUFBSSxDQUFDLE1BQU0sS0FBSyxDQUFDLEVBQUUsQ0FBQztZQUN0QixJQUFJLElBQUEsbUJBQVEsRUFBQyxLQUFLLENBQUMsRUFBRSxDQUFDO2dCQUNwQiwwQkFBMEI7Z0JBQzFCLG9EQUFvRDtnQkFDcEQsS0FBSztnQkFDTCxrQkFBa0I7Z0JBQ2xCLE9BQU8sZ0JBQWdCLENBQUMsSUFBSSxFQUFFLEtBQUssQ0FBQyxDQUFDO1lBQ3ZDLENBQUM7WUFFRCxJQUFJLEtBQUssQ0FBQyxPQUFPLENBQUMsS0FBSyxDQUFDLEVBQUUsQ0FBQztnQkFDekIseUJBQXlCO2dCQUN6Qiw4Q0FBOEM7Z0JBQzlDLEtBQUs7Z0JBQ0wsa0JBQWtCO2dCQUNsQixPQUFPLGVBQWUsQ0FBQyxJQUFJLEVBQUUsS0FBSyxDQUFDLENBQUM7WUFDdEMsQ0FBQztZQUVELHlCQUF5QjtZQUN6QixPQUFPLElBQUEsa0JBQU0sRUFBQyxJQUFJLEVBQUUsS0FBSyxDQUFDLENBQUM7UUFDN0IsQ0FBQztRQUVELCtCQUErQjtRQUMvQixPQUFPLElBQUEsa0JBQU0sRUFBQyxJQUFJLEVBQUUsS0FBSyxFQUFFLEdBQUcsSUFBSSxDQUFDLENBQUM7SUFDdEMsQ0FBQztJQUVELEVBQUUsQ0FBQyxNQUFjLEVBQUUsR0FBVyxFQUFFLEtBQVcsRUFBRSxHQUFHLElBQVc7UUFDekQsT0FBTyxJQUFJLENBQUMsT0FBTyxDQUFDLE1BQU0sRUFBRSxHQUFHLEVBQUUsS0FBSyxFQUFFLEdBQUcsSUFBSSxDQUFDLENBQUM7SUFDbkQsQ0FBQztDQUNGO0FBMURELGtDQTBEQztBQUVELE1BQU0sY0FBYyxHQUFHLFlBQVksQ0FBQztBQUNwQyxTQUFTLGVBQWUsQ0FBQyxJQUFZLEVBQUUsTUFBYTtJQUNsRCxPQUFPLElBQUksQ0FBQyxPQUFPLENBQUMsY0FBYyxFQUFFLENBQUMsUUFBUSxFQUFFLE9BQU8sRUFBRSxFQUFFO1FBQ3hELE1BQU0sS0FBSyxHQUFHLFFBQVEsQ0FBQyxPQUFPLENBQUMsQ0FBQztRQUNoQyxJQUFJLEtBQUssR0FBRyxNQUFNLENBQUMsTUFBTSxFQUFFLENBQUM7WUFDMUIsT0FBTyxNQUFNLENBQUMsS0FBSyxDQUFDLENBQUM7UUFDdkIsQ0FBQztRQUNELHdDQUF3QztRQUN4QyxPQUFPLFFBQVEsQ0FBQztJQUNsQixDQUFDLENBQUMsQ0FBQztBQUNMLENBQUM7QUFFRCxNQUFNLGVBQWUsR0FBRyxZQUFZLENBQUM7QUFDckMsU0FBUyxnQkFBZ0IsQ0FBQyxJQUFZLEVBQUUsTUFBMkI7SUFDakUsT0FBTyxJQUFJLENBQUMsT0FBTyxDQUFDLGVBQWUsRUFBRSxDQUFDLFFBQVEsRUFBRSxPQUFPLEVBQUUsRUFBRTtRQUN6RCxNQUFNLEtBQUssR0FBRyxNQUFNLENBQUMsT0FBTyxDQUFDLENBQUM7UUFDOUIsSUFBSSxLQUFLLEVBQUUsQ0FBQztZQUNWLE9BQU8sS0FBSyxDQUFDO1FBQ2YsQ0FBQztRQUNELHdDQUF3QztRQUN4QyxPQUFPLFFBQVEsQ0FBQztJQUNsQixDQUFDLENBQUMsQ0FBQztBQUNMLENBQUMifQ==

package/dist/commonjs/app/extend/context.d.ts

@@ -0,0 +1,72 @@
+import { Context } from '@eggjs/core';
+export default class I18nContext extends Context {
+    /**
+     * get current request locale
+     * @member Context#locale
+     * @return {String} lower case locale string, e.g.: 'zh-cn', 'en-us'
+     */
+    get locale(): string;
+    set locale(l: string);
+    /**
+     * `ctx.__` 的别名。
+     * @see {@link Context#__}
+     * @function Context#gettext
+     */
+    gettext(key: string, value?: any, ...args: any[]): string;
+    /**
+     * 如果开启了 I18n 多语言功能，那么会出现此 API，通过它可以获取到当前请求对应的本地化数据。
+     *
+     * 详细使用说明，请查看 {@link I18n}
+     * - `ctx.__ = function (key, value[, value2, ...])`: 类似 `util.format` 接口
+     * - `ctx.__ = function (key, values)`: 支持数组下标占位符方式，如
+     * - `__` 的别名是 `gettext(key, value)`
+     *
+     * > NOTE: __ 是两个下划线哦！
+     * @function Context#__
+     * @example
+     * ```js
+     * ctx.__('{0} {0} {1} {1}'), ['foo', 'bar'])
+     * ctx.gettext('{0} {0} {1} {1}'), ['foo', 'bar'])
+     * =>
+     * foo foo bar bar
+     * ```
+     * ##### Controller 下的使用示例
+     *
+     * ```js
+     * 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 文件下的使用示例
+     *
+     * ```html
+     * <li>{{ __('Email') }}: {{ user.email }}</li>
+     * <li>
+     *   {{ __('Hello %s, how are you today?', user.name) }}
+     * </li>
+     * <li>
+     *   {{ __('{0} {0} {1} {1}'), ['foo', 'bar']) }}
+     * </li>
+     * ```
+     *
+     * ##### locale 参数获取途径
+     *
+     * 优先级从上到下：
+     *
+     * - query: `/?locale=en-US`
+     * - cookie: `locale=zh-TW`
+     * - header: `Accept-Language: zh-CN,zh;q=0.5`
+     */
+    __(key: string, value?: any, ...args: any[]): string;
+    __locale: string;
+    __getLocale(): string;
+    __localeOrigin: string;
+    __getLocaleOrigin(): string;
+    __setLocale(locale: string): void;
+}

package/dist/commonjs/app/extend/context.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_util_1 = require("node:util");
+const core_1 = require("@eggjs/core");
+const utils_js_1 = require("../../utils.js");
+const debug = (0, node_util_1.debuglog)('@eggjs/i18n/app/extend/context');
+class I18nContext extends core_1.Context {
+    /**
+     * get current request locale
+     * @member Context#locale
+     * @return {String} lower case locale string, e.g.: 'zh-cn', 'en-us'
+     */
+    get locale() {
+        return this.__getLocale();
+    }
+    set locale(l) {
+        this.__setLocale(l);
+    }
+    /**
+     * `ctx.__` 的别名。
+     * @see {@link Context#__}
+     * @function Context#gettext
+     */
+    gettext(key, value, ...args) {
+        return this.app.gettext(this.locale, key, value, ...args);
+    }
+    /**
+     * 如果开启了 I18n 多语言功能，那么会出现此 API，通过它可以获取到当前请求对应的本地化数据。
+     *
+     * 详细使用说明，请查看 {@link I18n}
+     * - `ctx.__ = function (key, value[, value2, ...])`: 类似 `util.format` 接口
+     * - `ctx.__ = function (key, values)`: 支持数组下标占位符方式，如
+     * - `__` 的别名是 `gettext(key, value)`
+     *
+     * > NOTE: __ 是两个下划线哦！
+     * @function Context#__
+     * @example
+     * ```js
+     * ctx.__('{0} {0} {1} {1}'), ['foo', 'bar'])
+     * ctx.gettext('{0} {0} {1} {1}'), ['foo', 'bar'])
+     * =>
+     * foo foo bar bar
+     * ```
+     * ##### Controller 下的使用示例
+     *
+     * ```js
+     * 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 文件下的使用示例
+     *
+     * ```html
+     * <li>{{ __('Email') }}: {{ user.email }}</li>
+     * <li>
+     *   {{ __('Hello %s, how are you today?', user.name) }}
+     * </li>
+     * <li>
+     *   {{ __('{0} {0} {1} {1}'), ['foo', 'bar']) }}
+     * </li>
+     * ```
+     *
+     * ##### locale 参数获取途径
+     *
+     * 优先级从上到下：
+     *
+     * - query: `/?locale=en-US`
+     * - cookie: `locale=zh-TW`
+     * - header: `Accept-Language: zh-CN,zh;q=0.5`
+     */
+    __(key, value, ...args) {
+        return this.gettext(key, value, ...args);
+    }
+    // 1. query: /?locale=en-US
+    // 2. cookie: locale=zh-TW
+    // 3. header: Accept-Language: zh-CN,zh;q=0.5
+    __getLocale() {
+        if (this.__locale) {
+            return this.__locale;
+        }
+        const { localeAlias, defaultLocale, cookieField, queryField, writeCookie } = this.app.config.i18n;
+        const cookieLocale = this.cookies.get(cookieField, { signed: false });
+        // 1. Query
+        let locale = this.query[queryField];
+        let localeOrigin = 'query';
+        // 2. Cookie
+        if (!locale) {
+            locale = cookieLocale;
+            localeOrigin = 'cookie';
+        }
+        // 3. Header
+        if (!locale) {
+            // Accept-Language: zh-CN,zh;q=0.5
+            // Accept-Language: zh-CN
+            let languages = this.acceptsLanguages();
+            if (languages) {
+                if (Array.isArray(languages)) {
+                    if (languages[0] === '*') {
+                        languages = languages.slice(1);
+                    }
+                    if (languages.length > 0) {
+                        for (const l of languages) {
+                            const lang = (0, utils_js_1.formatLocale)(l);
+                            if (this.app.isSupportLocale(lang) || localeAlias[lang]) {
+                                locale = lang;
+                                localeOrigin = 'header';
+                                break;
+                            }
+                        }
+                    }
+                }
+                else {
+                    locale = languages;
+                    localeOrigin = 'header';
+                }
+            }
+            // all missing, set it to defaultLocale
+            if (!locale) {
+                locale = defaultLocale;
+                localeOrigin = 'default';
+            }
+        }
+        // cookie alias
+        if (locale in localeAlias) {
+            const originalLocale = locale;
+            locale = localeAlias[locale];
+            debug('Used alias, received %s but using %s', originalLocale, locale);
+        }
+        locale = (0, utils_js_1.formatLocale)(locale);
+        // validate locale
+        if (!this.app.isSupportLocale(locale)) {
+            debug('Locale %s is not supported. Using default (%s)', locale, defaultLocale);
+            locale = defaultLocale;
+        }
+        // if header not send, set the locale cookie
+        if (writeCookie && cookieLocale !== locale && !this.headerSent) {
+            updateCookie(this, locale);
+        }
+        debug('Locale: %s from %s', locale, localeOrigin);
+        this.__locale = locale;
+        this.__localeOrigin = localeOrigin;
+        return locale;
+    }
+    __getLocaleOrigin() {
+        if (this.__localeOrigin) {
+            return this.__localeOrigin;
+        }
+        this.__getLocale();
+        return this.__localeOrigin;
+    }
+    __setLocale(locale) {
+        this.__locale = locale;
+        this.__localeOrigin = 'set';
+        updateCookie(this, locale);
+    }
+}
+exports.default = I18nContext;
+function updateCookie(ctx, locale) {
+    const { cookieMaxAge, cookieField, cookieDomain } = ctx.app.config.i18n;
+    const cookieOptions = {
+        // make sure browser javascript can read the cookie
+        httpOnly: false,
+        maxAge: cookieMaxAge,
+        signed: false,
+        domain: cookieDomain,
+        overwrite: true,
+    };
+    ctx.cookies.set(cookieField, locale, cookieOptions);
+    debug('Saved cookie with locale %s, options: %j', locale, cookieOptions);
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29udGV4dC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uL3NyYy9hcHAvZXh0ZW5kL2NvbnRleHQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7QUFBQSx5Q0FBcUM7QUFDckMsc0NBQXNDO0FBQ3RDLDZDQUE4QztBQUU5QyxNQUFNLEtBQUssR0FBRyxJQUFBLG9CQUFRLEVBQUMsZ0NBQWdDLENBQUMsQ0FBQztBQUV6RCxNQUFxQixXQUFZLFNBQVEsY0FBTztJQUM5Qzs7OztPQUlHO0lBQ0gsSUFBSSxNQUFNO1FBQ1IsT0FBTyxJQUFJLENBQUMsV0FBVyxFQUFFLENBQUM7SUFDNUIsQ0FBQztJQUVELElBQUksTUFBTSxDQUFDLENBQVM7UUFDbEIsSUFBSSxDQUFDLFdBQVcsQ0FBQyxDQUFDLENBQUMsQ0FBQztJQUN0QixDQUFDO0lBRUQ7Ozs7T0FJRztJQUNILE9BQU8sQ0FBQyxHQUFXLEVBQUUsS0FBVyxFQUFFLEdBQUcsSUFBVztRQUM5QyxPQUFPLElBQUksQ0FBQyxHQUFHLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxNQUFNLEVBQUUsR0FBRyxFQUFFLEtBQUssRUFBRSxHQUFHLElBQUksQ0FBQyxDQUFDO0lBQzVELENBQUM7SUFFRDs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztPQWlERztJQUNILEVBQUUsQ0FBQyxHQUFXLEVBQUUsS0FBVyxFQUFFLEdBQUcsSUFBVztRQUN6QyxPQUFPLElBQUksQ0FBQyxPQUFPLENBQUMsR0FBRyxFQUFFLEtBQUssRUFBRSxHQUFHLElBQUksQ0FBQyxDQUFDO0lBQzNDLENBQUM7SUFHRCwyQkFBMkI7SUFDM0IsMEJBQTBCO0lBQzFCLDZDQUE2QztJQUM3QyxXQUFXO1FBQ1QsSUFBSSxJQUFJLENBQUMsUUFBUSxFQUFFLENBQUM7WUFDbEIsT0FBTyxJQUFJLENBQUMsUUFBUSxDQUFDO1FBQ3ZCLENBQUM7UUFFRCxNQUFNLEVBQUUsV0FBVyxFQUFFLGFBQWEsRUFBRSxXQUFXLEVBQUUsVUFBVSxFQUFFLFdBQVcsRUFBRSxHQUFHLElBQUksQ0FBQyxHQUFHLENBQUMsTUFBTSxDQUFDLElBQUksQ0FBQztRQUNsRyxNQUFNLFlBQVksR0FBRyxJQUFJLENBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxXQUFXLEVBQUUsRUFBRSxNQUFNLEVBQUUsS0FBSyxFQUFFLENBQUMsQ0FBQztRQUV0RSxXQUFXO1FBQ1gsSUFBSSxNQUFNLEdBQUcsSUFBSSxDQUFDLEtBQUssQ0FBQyxVQUFVLENBQVcsQ0FBQztRQUM5QyxJQUFJLFlBQVksR0FBRyxPQUFPLENBQUM7UUFFM0IsWUFBWTtRQUNaLElBQUksQ0FBQyxNQUFNLEVBQUUsQ0FBQztZQUNaLE1BQU0sR0FBRyxZQUFZLENBQUM7WUFDdEIsWUFBWSxHQUFHLFFBQVEsQ0FBQztRQUMxQixDQUFDO1FBRUQsWUFBWTtRQUNaLElBQUksQ0FBQyxNQUFNLEVBQUUsQ0FBQztZQUNaLGtDQUFrQztZQUNsQyx5QkFBeUI7WUFDekIsSUFBSSxTQUFTLEdBQUcsSUFBSSxDQUFDLGdCQUFnQixFQUFFLENBQUM7WUFDeEMsSUFBSSxTQUFTLEVBQUUsQ0FBQztnQkFDZCxJQUFJLEtBQUssQ0FBQyxPQUFPLENBQUMsU0FBUyxDQUFDLEVBQUUsQ0FBQztvQkFDN0IsSUFBSSxTQUFTLENBQUMsQ0FBQyxDQUFDLEtBQUssR0FBRyxFQUFFLENBQUM7d0JBQ3pCLFNBQVMsR0FBRyxTQUFTLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQyxDQUFDO29CQUNqQyxDQUFDO29CQUNELElBQUksU0FBUyxDQUFDLE1BQU0sR0FBRyxDQUFDLEVBQUUsQ0FBQzt3QkFDekIsS0FBSyxNQUFNLENBQUMsSUFBSSxTQUFTLEVBQUUsQ0FBQzs0QkFDMUIsTUFBTSxJQUFJLEdBQUcsSUFBQSx1QkFBWSxFQUFDLENBQUMsQ0FBQyxDQUFDOzRCQUM3QixJQUFJLElBQUksQ0FBQyxHQUFHLENBQUMsZUFBZSxDQUFDLElBQUksQ0FBQyxJQUFJLFdBQVcsQ0FBQyxJQUFJLENBQUMsRUFBRSxDQUFDO2dDQUN4RCxNQUFNLEdBQUcsSUFBSSxDQUFDO2dDQUNkLFlBQVksR0FBRyxRQUFRLENBQUM7Z0NBQ3hCLE1BQU07NEJBQ1IsQ0FBQzt3QkFDSCxDQUFDO29CQUNILENBQUM7Z0JBQ0gsQ0FBQztxQkFBTSxDQUFDO29CQUNOLE1BQU0sR0FBRyxTQUFTLENBQUM7b0JBQ25CLFlBQVksR0FBRyxRQUFRLENBQUM7Z0JBQzFCLENBQUM7WUFDSCxDQUFDO1lBRUQsdUNBQXVDO1lBQ3ZDLElBQUksQ0FBQyxNQUFNLEVBQUUsQ0FBQztnQkFDWixNQUFNLEdBQUcsYUFBYSxDQUFDO2dCQUN2QixZQUFZLEdBQUcsU0FBUyxDQUFDO1lBQzNCLENBQUM7UUFDSCxDQUFDO1FBRUQsZUFBZTtRQUNmLElBQUksTUFBTSxJQUFJLFdBQVcsRUFBRSxDQUFDO1lBQzFCLE1BQU0sY0FBYyxHQUFHLE1BQU0sQ0FBQztZQUM5QixNQUFNLEdBQUcsV0FBVyxDQUFDLE1BQU0sQ0FBQyxDQUFDO1lBQzdCLEtBQUssQ0FBQyxzQ0FBc0MsRUFBRSxjQUFjLEVBQUUsTUFBTSxDQUFDLENBQUM7UUFDeEUsQ0FBQztRQUVELE1BQU0sR0FBRyxJQUFBLHVCQUFZLEVBQUMsTUFBTSxDQUFDLENBQUM7UUFFOUIsa0JBQWtCO1FBQ2xCLElBQUksQ0FBQyxJQUFJLENBQUMsR0FBRyxDQUFDLGVBQWUsQ0FBQyxNQUFNLENBQUMsRUFBRSxDQUFDO1lBQ3RDLEtBQUssQ0FBQyxnREFBZ0QsRUFBRSxNQUFNLEVBQUUsYUFBYSxDQUFDLENBQUM7WUFDL0UsTUFBTSxHQUFHLGFBQWEsQ0FBQztRQUN6QixDQUFDO1FBRUQsNENBQTRDO1FBQzVDLElBQUksV0FBVyxJQUFJLFlBQVksS0FBSyxNQUFNLElBQUksQ0FBQyxJQUFJLENBQUMsVUFBVSxFQUFFLENBQUM7WUFDL0QsWUFBWSxDQUFDLElBQUksRUFBRSxNQUFNLENBQUMsQ0FBQztRQUM3QixDQUFDO1FBQ0QsS0FBSyxDQUFDLG9CQUFvQixFQUFFLE1BQU0sRUFBRSxZQUFZLENBQUMsQ0FBQztRQUNsRCxJQUFJLENBQUMsUUFBUSxHQUFHLE1BQU0sQ0FBQztRQUN2QixJQUFJLENBQUMsY0FBYyxHQUFHLFlBQVksQ0FBQztRQUNuQyxPQUFPLE1BQU0sQ0FBQztJQUNoQixDQUFDO0lBR0QsaUJBQWlCO1FBQ2YsSUFBSSxJQUFJLENBQUMsY0FBYyxFQUFFLENBQUM7WUFDeEIsT0FBTyxJQUFJLENBQUMsY0FBYyxDQUFDO1FBQzdCLENBQUM7UUFDRCxJQUFJLENBQUMsV0FBVyxFQUFFLENBQUM7UUFDbkIsT0FBTyxJQUFJLENBQUMsY0FBYyxDQUFDO0lBQzdCLENBQUM7SUFFRCxXQUFXLENBQUMsTUFBYztRQUN4QixJQUFJLENBQUMsUUFBUSxHQUFHLE1BQU0sQ0FBQztRQUN2QixJQUFJLENBQUMsY0FBYyxHQUFHLEtBQUssQ0FBQztRQUM1QixZQUFZLENBQUMsSUFBSSxFQUFFLE1BQU0sQ0FBQyxDQUFDO0lBQzdCLENBQUM7Q0FDRjtBQTNLRCw4QkEyS0M7QUFFRCxTQUFTLFlBQVksQ0FBQyxHQUFZLEVBQUUsTUFBYztJQUNoRCxNQUFNLEVBQUUsWUFBWSxFQUFFLFdBQVcsRUFBRSxZQUFZLEVBQUUsR0FBRyxHQUFHLENBQUMsR0FBRyxDQUFDLE1BQU0sQ0FBQyxJQUFJLENBQUM7SUFDeEUsTUFBTSxhQUFhLEdBQUc7UUFDcEIsbURBQW1EO1FBQ25ELFFBQVEsRUFBRSxLQUFLO1FBQ2YsTUFBTSxFQUFFLFlBQXNCO1FBQzlCLE1BQU0sRUFBRSxLQUFLO1FBQ2IsTUFBTSxFQUFFLFlBQVk7UUFDcEIsU0FBUyxFQUFFLElBQUk7S0FDaEIsQ0FBQztJQUNGLEdBQUcsQ0FBQyxPQUFPLENBQUMsR0FBRyxDQUFDLFdBQVcsRUFBRSxNQUFNLEVBQUUsYUFBYSxDQUFDLENBQUM7SUFDcEQsS0FBSyxDQUFDLDBDQUEwQyxFQUFFLE1BQU0sRUFBRSxhQUFhLENBQUMsQ0FBQztBQUMzRSxDQUFDIn0=

package/dist/commonjs/app.d.ts

@@ -0,0 +1,56 @@
+import type { ILifecycleBoot } from '@eggjs/core';
+import type I18nApplication from './app/extend/application.js';
+/**
+ * I18n 国际化
+ *
+ * 通过设置 Plugin 配置 `i18n: true`，开启多语言支持。
+ *
+ * #### 语言文件存储路径
+ *
+ * 统一存放在 `config/locale/*.js` 下（ 兼容`config/locales/*.js` ），如包含英文，简体中文，繁体中文的语言文件：
+ *
+ * ```
+ * - config/locale/
+ *   - en-US.js
+ *   - zh-CN.js
+ *   - zh-TW.js
+ * ```
+ * @class I18n
+ * @param {App} app Application object.
+ * @example
+ *
+ * #### I18n 文件内容
+ *
+ * ```js
+ * // config/locale/zh-CN.js
+ * module.exports = {
+ *   "Email": "邮箱",
+ *   "Welcome back, %s!": "欢迎回来, %s!",
+ *   "Hello %s, how are you today?": "你好 %s, 今天过得咋样？",
+ * };
+ * ```
+ *
+ * ```js
+ * // config/locale/en-US.js
+ * module.exports = {
+ *   "Email": "Email",
+ * };
+ * ```
+ * 或者也可以用 JSON 格式的文件:
+ *
+ * ```js
+ * // config/locale/zh-CN.json
+ * {
+ *   "email": "邮箱",
+ *   "login": "帐号",
+ *   "createdAt": "注册时间"
+ * }
+ * ```
+ */
+export default class I18n implements ILifecycleBoot {
+    private readonly app;
+    constructor(app: I18nApplication & {
+        locals: Record<string, any>;
+    });
+    didLoad(): Promise<void>;
+}

package/dist/commonjs/app.js

@@ -0,0 +1,95 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = __importDefault(require("node:path"));
+const node_util_1 = require("node:util");
+const locales_js_1 = require("./locales.js");
+const utility_1 = require("utility");
+const humanize_ms_1 = require("humanize-ms");
+const utils_js_1 = require("./utils.js");
+const debug = (0, node_util_1.debuglog)('@eggjs/i18n/app');
+/**
+ * I18n 国际化
+ *
+ * 通过设置 Plugin 配置 `i18n: true`，开启多语言支持。
+ *
+ * #### 语言文件存储路径
+ *
+ * 统一存放在 `config/locale/*.js` 下（ 兼容`config/locales/*.js` ），如包含英文，简体中文，繁体中文的语言文件：
+ *
+ * ```
+ * - config/locale/
+ *   - en-US.js
+ *   - zh-CN.js
+ *   - zh-TW.js
+ * ```
+ * @class I18n
+ * @param {App} app Application object.
+ * @example
+ *
+ * #### I18n 文件内容
+ *
+ * ```js
+ * // config/locale/zh-CN.js
+ * module.exports = {
+ *   "Email": "邮箱",
+ *   "Welcome back, %s!": "欢迎回来, %s!",
+ *   "Hello %s, how are you today?": "你好 %s, 今天过得咋样？",
+ * };
+ * ```
+ *
+ * ```js
+ * // config/locale/en-US.js
+ * module.exports = {
+ *   "Email": "Email",
+ * };
+ * ```
+ * 或者也可以用 JSON 格式的文件:
+ *
+ * ```js
+ * // config/locale/zh-CN.json
+ * {
+ *   "email": "邮箱",
+ *   "login": "帐号",
+ *   "createdAt": "注册时间"
+ * }
+ * ```
+ */
+class I18n {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    async didLoad() {
+        const i18nConfig = this.app.config.i18n;
+        i18nConfig.defaultLocale = (0, utils_js_1.formatLocale)(i18nConfig.defaultLocale);
+        i18nConfig.cookieMaxAge = (0, humanize_ms_1.ms)(i18nConfig.cookieMaxAge);
+        i18nConfig.dirs = Array.isArray(i18nConfig.dirs) ? i18nConfig.dirs : [];
+        // 按 egg > 插件 > 框架 > 应用的顺序遍历 config/locale(config/locales) 目录，加载所有配置文件
+        for (const unit of this.app.loader.getLoadUnits()) {
+            let localePath = node_path_1.default.join(unit.path, 'config/locale');
+            /**
+             * 优先选择 `config/locale` 目录下的多语言文件，不存在时再选择 `config/locales` 目录
+             * 避免 2 个目录同时存在时可能导致的冲突
+             */
+            if (!(await (0, utility_1.exists)(localePath))) {
+                localePath = node_path_1.default.join(unit.path, 'config/locales');
+            }
+            i18nConfig.dirs.push(localePath);
+        }
+        debug('app.config.i18n.dirs:', i18nConfig.dirs);
+        await (0, locales_js_1.loadLocaleResources)(this.app, i18nConfig);
+        const app = this.app;
+        function gettextInContext(key, ...args) {
+            const ctx = app.ctxStorage.getStore();
+            return ctx.gettext(key, ...args);
+        }
+        // 在 view 中使用 `__(key, value, ...args)`
+        this.app.locals.gettext = gettextInContext;
+        this.app.locals.__ = gettextInContext;
+    }
+}
+exports.default = I18n;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBwLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2FwcC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7OztBQUFBLDBEQUE2QjtBQUM3Qix5Q0FBcUM7QUFDckMsNkNBQW1EO0FBQ25ELHFDQUFpQztBQUNqQyw2Q0FBaUM7QUFHakMseUNBQTBDO0FBRTFDLE1BQU0sS0FBSyxHQUFHLElBQUEsb0JBQVEsRUFBQyxpQkFBaUIsQ0FBQyxDQUFDO0FBRTFDOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBOENHO0FBRUgsTUFBcUIsSUFBSTtJQUNOLEdBQUcsQ0FBQztJQUVyQixZQUFZLEdBQXNEO1FBQ2hFLElBQUksQ0FBQyxHQUFHLEdBQUcsR0FBRyxDQUFDO0lBQ2pCLENBQUM7SUFFRCxLQUFLLENBQUMsT0FBTztRQUNYLE1BQU0sVUFBVSxHQUFHLElBQUksQ0FBQyxHQUFHLENBQUMsTUFBTSxDQUFDLElBQUksQ0FBQztRQUN4QyxVQUFVLENBQUMsYUFBYSxHQUFHLElBQUEsdUJBQVksRUFBQyxVQUFVLENBQUMsYUFBYSxDQUFDLENBQUM7UUFDbEUsVUFBVSxDQUFDLFlBQVksR0FBRyxJQUFBLGdCQUFFLEVBQUMsVUFBVSxDQUFDLFlBQVksQ0FBQyxDQUFDO1FBRXRELFVBQVUsQ0FBQyxJQUFJLEdBQUcsS0FBSyxDQUFDLE9BQU8sQ0FBQyxVQUFVLENBQUMsSUFBSSxDQUFDLENBQUMsQ0FBQyxDQUFDLFVBQVUsQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQztRQUN4RSxzRUFBc0U7UUFDdEUsS0FBSyxNQUFNLElBQUksSUFBSSxJQUFJLENBQUMsR0FBRyxDQUFDLE1BQU0sQ0FBQyxZQUFZLEVBQUUsRUFBRSxDQUFDO1lBQ2xELElBQUksVUFBVSxHQUFHLG1CQUFJLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxJQUFJLEVBQUUsZUFBZSxDQUFDLENBQUM7WUFDdkQ7OztlQUdHO1lBQ0gsSUFBSSxDQUFDLENBQUMsTUFBTSxJQUFBLGdCQUFNLEVBQUMsVUFBVSxDQUFDLENBQUMsRUFBRSxDQUFDO2dCQUNoQyxVQUFVLEdBQUcsbUJBQUksQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLElBQUksRUFBRSxnQkFBZ0IsQ0FBQyxDQUFDO1lBQ3RELENBQUM7WUFDRCxVQUFVLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxVQUFVLENBQUMsQ0FBQztRQUNuQyxDQUFDO1FBRUQsS0FBSyxDQUFDLHVCQUF1QixFQUFFLFVBQVUsQ0FBQyxJQUFJLENBQUMsQ0FBQztRQUVoRCxNQUFNLElBQUEsZ0NBQW1CLEVBQUMsSUFBSSxDQUFDLEdBQUcsRUFBRSxVQUFVLENBQUMsQ0FBQztRQUVoRCxNQUFNLEdBQUcsR0FBRyxJQUFJLENBQUMsR0FBRyxDQUFDO1FBQ3JCLFNBQVMsZ0JBQWdCLENBQUMsR0FBVyxFQUFFLEdBQUcsSUFBVztZQUNuRCxNQUFNLEdBQUcsR0FBRyxHQUFHLENBQUMsVUFBVSxDQUFDLFFBQVEsRUFBRyxDQUFDO1lBQ3ZDLE9BQU8sR0FBRyxDQUFDLE9BQU8sQ0FBQyxHQUFHLEVBQUUsR0FBRyxJQUFJLENBQUMsQ0FBQztRQUNuQyxDQUFDO1FBQ0QsdUNBQXVDO1FBQ3ZDLElBQUksQ0FBQyxHQUFHLENBQUMsTUFBTSxDQUFDLE9BQU8sR0FBRyxnQkFBZ0IsQ0FBQztRQUMzQyxJQUFJLENBQUMsR0FBRyxDQUFDLE1BQU0sQ0FBQyxFQUFFLEdBQUcsZ0JBQWdCLENBQUM7SUFDeEMsQ0FBQztDQUNGO0FBdkNELHVCQXVDQyJ9