@eggjs/i18n 3.0.1 → 4.0.0-beta.17

package/README.md

@@ -1,8 +1,6 @@
 # @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/)
@@ -10,8 +8,6 @@
 
 [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
@@ -66,16 +62,16 @@ export default {
 ```ts
 // config/locale/zh-CN.ts
 export default {
-  "Email": "邮箱",
-  "Welcome back, %s!": "欢迎回来，%s!",
-  "Hello %s, how are you today?": "你好 %s, 今天过得咋样？",
+  Email: '邮箱',
+  'Welcome back, %s!': '欢迎回来，%s!',
+  'Hello %s, how are you today?': '你好 %s, 今天过得咋样？',
 };
 ```
 
 ```ts
 // config/locale/en-US.ts
 export default {
-  "Email": "Email",
+  Email: 'Email',
 };
 ```
 
@@ -94,14 +90,14 @@ export default {
 
 I18n 为你提供 `__` (Alias: `gettext`) 函数，让你可以轻松获得 locale 文件夹下面的多语言文本。
 
-> NOTE: __ 是两个下划线哦！
+> 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']);
+ctx.__('{0} {0} {1} {1}', ['foo', 'bar']);
+ctx.gettext('{0} {0} {1} {1}', ['foo', 'bar']);
 
 =>
 foo foo bar bar
@@ -124,12 +120,8 @@ export default ctx => {
 
 ```html
 <li>{{ __('Email') }}: {{ user.email }}</li>
-<li>
-  {{ __('Hello %s, how are you today?', user.name) }}
-</li>
-<li>
-  {{ __('{0} {0} {1} {1}'), ['foo', 'bar']) }}
-</li>
+<li>{{ __('Hello %s, how are you today?', user.name) }}</li>
+<li>{{ __('{0} {0} {1} {1}', ['foo', 'bar']) }}</li>
 ```
 
 ### 修改应用的默认语言
@@ -152,6 +144,6 @@ Please open an issue [here](https://github.com/eggjs/egg/issues).
 
 ## Contributors
 
-[![Contributors](https://contrib.rocks/image?repo=eggjs/i18n)](https://github.com/eggjs/i18n/graphs/contributors)
+[![Contributors](https://contrib.rocks/image?repo=eggjs/egg)](https://github.com/eggjs/egg/graphs/contributors)
 
 Made with [contributors-img](https://contrib.rocks).

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

@@ -0,0 +1,12 @@
+import { Application } from "egg";
+
+//#region src/app/extend/application.d.ts
+declare const I18N_RESOURCES: unique symbol;
+declare class I18nApplication extends Application {
+  [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;
+}
+//#endregion
+export { I18N_RESOURCES, I18nApplication as default };

package/dist/app/extend/application.js

@@ -0,0 +1,48 @@
+import { isObject } from "../../utils.js";
+import { debuglog, format } from "node:util";
+import { Application } from "egg";
+
+//#region src/app/extend/application.ts
+const debug = debuglog("egg/i18n/app/extend/application");
+const I18N_RESOURCES = Symbol("Application i18n resources");
+var I18nApplication = class extends Application {
+	isSupportLocale(locale) {
+		return !!this[I18N_RESOURCES][locale];
+	}
+	gettext(locale, key, value, ...args) {
+		if (!locale || !key) return "";
+		let text = (this[I18N_RESOURCES][locale] || {})[key];
+		if (text === void 0) text = key;
+		debug("%s: %j => %j", locale, key, text);
+		if (!text) return "";
+		if (value === void 0) return text;
+		if (args.length === 0) {
+			if (isObject(value)) return formatWithObject(text, value);
+			if (Array.isArray(value)) return formatWithArray(text, value);
+			return format(text, value);
+		}
+		return format(text, value, ...args);
+	}
+	__(locale, key, value, ...args) {
+		return this.gettext(locale, key, value, ...args);
+	}
+};
+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];
+		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;
+		return original;
+	});
+}
+
+//#endregion
+export { I18N_RESOURCES, I18nApplication as default };

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

@@ -0,0 +1,76 @@
+import { Context } from "egg";
+
+//#region src/app/extend/context.d.ts
+declare 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;
+}
+//#endregion
+export { I18nContext as default };

package/dist/app/extend/context.js

@@ -0,0 +1,152 @@
+import { formatLocale } from "../../utils.js";
+import { debuglog } from "node:util";
+import { Context } from "egg";
+
+//#region src/app/extend/context.ts
+const debug = debuglog("egg/i18n/app/extend/context");
+var I18nContext = class extends 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);
+	}
+	__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 });
+		let locale = this.query[queryField];
+		let localeOrigin = "query";
+		if (!locale && cookieLocale) {
+			locale = cookieLocale;
+			localeOrigin = "cookie";
+		}
+		if (!locale) {
+			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 = formatLocale(l);
+					if (this.app.isSupportLocale(lang) || localeAlias[lang]) {
+						locale = lang;
+						localeOrigin = "header";
+						break;
+					}
+				}
+			} else {
+				locale = languages;
+				localeOrigin = "header";
+			}
+			if (!locale) {
+				locale = defaultLocale;
+				localeOrigin = "default";
+			}
+		}
+		if (locale in localeAlias) {
+			const originalLocale = locale;
+			locale = localeAlias[locale];
+			debug("Used alias, received %s but using %s", originalLocale, locale);
+		}
+		locale = formatLocale(locale);
+		if (!this.app.isSupportLocale(locale)) {
+			debug("Locale %s is not supported. Using default (%s)", locale, defaultLocale);
+			locale = defaultLocale;
+		}
+		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";
+		if (this.app.config.i18n.writeCookie && !this.headerSent) updateCookie(this, locale);
+	}
+};
+function updateCookie(ctx, locale) {
+	const { cookieMaxAge, cookieField, cookieDomain } = ctx.app.config.i18n;
+	const cookieOptions = {
+		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);
+}
+
+//#endregion
+export { I18nContext as default };

package/dist/{commonjs/app.d.ts → app.d.ts}

@@ -1,5 +1,7 @@
-import type { ILifecycleBoot } from '@eggjs/core';
-import type I18nApplication from './app/extend/application.js';
+import { Application, ILifecycleBoot } from "egg";
+
+//#region src/app.d.ts
+
 /**
  * I18n 国际化
  *
@@ -47,10 +49,10 @@ import type I18nApplication from './app/extend/application.js';
  * }
  * ```
  */
-export default class I18n implements ILifecycleBoot {
-    private readonly app;
-    constructor(app: I18nApplication & {
-        locals: Record<string, any>;
-    });
-    didLoad(): Promise<void>;
+declare class I18n implements ILifecycleBoot {
+  private readonly app;
+  constructor(app: Application);
+  didLoad(): Promise<void>;
 }
+//#endregion
+export { I18n as default };

package/dist/app.js

@@ -0,0 +1,96 @@
+import { formatLocale } from "./utils.js";
+import { loadLocaleResources } from "./locales.js";
+import path from "node:path";
+import { debuglog } from "node:util";
+import { exists } from "utility";
+import { ms } from "humanize-ms";
+
+//#region src/app.ts
+const debug = debuglog("egg/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": "注册时间"
+* }
+* ```
+*/
+var I18n = class {
+	app;
+	constructor(app) {
+		this.app = app;
+	}
+	async didLoad() {
+		const i18nConfig = this.app.config.i18n;
+		i18nConfig.defaultLocale = formatLocale(i18nConfig.defaultLocale);
+		i18nConfig.cookieMaxAge = ms(i18nConfig.cookieMaxAge);
+		i18nConfig.dirs = Array.isArray(i18nConfig.dirs) ? i18nConfig.dirs : [];
+		for (const unit of this.app.loader.getLoadUnits()) {
+			let localePath = path.join(unit.path, "config/locale");
+			/**
+			* 优先选择 `config/locale` 目录下的多语言文件，不存在时再选择 `config/locales` 目录
+			* 避免 2 个目录同时存在时可能导致的冲突
+			*/
+			if (!await exists(localePath)) localePath = path.join(unit.path, "config/locales");
+			i18nConfig.dirs.push(localePath);
+		}
+		debug("app.config.i18n.dirs:", i18nConfig.dirs);
+		await loadLocaleResources(this.app, i18nConfig);
+		const app = this.app;
+		function gettextInContext(key, ...args) {
+			return app.ctxStorage.getStore().gettext(key, ...args);
+		}
+		Object.defineProperties(app.locals, {
+			__: {
+				value: gettextInContext,
+				enumerable: true
+			},
+			gettext: {
+				value: gettextInContext,
+				enumerable: true
+			}
+		});
+	}
+};
+
+//#endregion
+export { I18n as default };

package/{src/types.ts → dist/config/config.default.d.ts}

@@ -1,8 +1,5 @@
-/**
- * I18n options
- * @member Config#i18n
- */
-export interface I18nConfig {
+//#region src/config/config.default.d.ts
+interface I18nConfig {
   /**
    * 默认语言是美式英语，毕竟支持多语言，基本都是以英语为母板
    * 默认值是 `en_US`
@@ -50,31 +47,8 @@ export interface I18nConfig {
    */
   writeCookie: boolean;
 }
-
-declare module '@eggjs/core' {
-  // add EggAppConfig overrides types
-  interface EggAppConfig {
-    i18n: I18nConfig;
-  }
-
-  interface Context {
-    /**
-     * get and set current request locale
-     * @member Context#locale
-     * @return {String} lower case locale string, e.g.: 'zh-cn', 'en-us'
-     */
-    locale: string;
-
-    gettext(key: string, value?: any, ...args: any[]): string;
-    __(key: string, value?: any, ...args: any[]): string;
-
-    __getLocale(): string;
-    __setLocale(l: string): void;
-  }
-
-  interface EggCore {
-    isSupportLocale(locale: string): boolean;
-    gettext(locale: string, key: string, value?: any, ...args: any[]): string;
-    __(locale: string, key: string, value?: any, ...args: any[]): string;
-  }
-}
+declare const _default: {
+  i18n: I18nConfig;
+};
+//#endregion
+export { I18nConfig, _default as default };

package/dist/config/config.default.js

@@ -0,0 +1,15 @@
+//#region src/config/config.default.ts
+var config_default_default = { i18n: {
+	defaultLocale: "en_US",
+	dirs: [],
+	queryField: "locale",
+	cookieField: "locale",
+	cookieDomain: "",
+	cookieMaxAge: "1y",
+	localeAlias: {},
+	writeCookie: true,
+	dir: void 0
+} };
+
+//#endregion
+export { config_default_default as default };

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/index.js

@@ -0,0 +1,4 @@
+import "./app/extend/application.js";
+import "./app/extend/context.js";
+
+export {  };

package/dist/locales.d.ts

@@ -0,0 +1,7 @@
+import { I18nConfig } from "./config/config.default.js";
+import { Application } from "egg";
+
+//#region src/locales.d.ts
+declare function loadLocaleResources(app: Application, options: I18nConfig): Promise<void>;
+//#endregion
+export { loadLocaleResources };

package/dist/locales.js

@@ -0,0 +1,53 @@
+import { formatLocale, isObject } from "./utils.js";
+import { I18N_RESOURCES } from "./app/extend/application.js";
+import path from "node:path";
+import { debuglog } from "node:util";
+import { exists, readJSON } from "utility";
+import fs from "node:fs/promises";
+import ini from "ini";
+import yaml from "js-yaml";
+import { importModule } from "@eggjs/utils";
+
+//#region src/locales.ts
+const debug = debuglog("egg/i18n/locales");
+async function loadLocaleResources(app, options) {
+	const localeDirs = options.dirs;
+	const resources = {};
+	if (options.dir && !localeDirs.includes(options.dir)) {
+		app.deprecate("[@eggjs/i18n] `config.i18n.dir` is deprecated, please use `config.i18n.dirs` instead");
+		localeDirs.push(options.dir);
+	}
+	for (const dir of localeDirs) {
+		if (!await exists(dir)) continue;
+		const names = await fs.readdir(dir);
+		for (const name of names) {
+			const filepath = path.join(dir, name);
+			const locale = formatLocale(name.split(".")[0]);
+			let resource = {};
+			if (name.endsWith(".js") || name.endsWith(".ts")) resource = flattening(await importModule(filepath, { importDefaultOnly: true }));
+			else if (name.endsWith(".json")) resource = flattening(await readJSON(filepath));
+			else if (name.endsWith(".properties")) resource = ini.parse(await fs.readFile(filepath, "utf8"));
+			else if (name.endsWith(".yml") || name.endsWith(".yaml")) resource = flattening(yaml.load(await fs.readFile(filepath, "utf8")));
+			resources[locale] = resources[locale] || {};
+			Object.assign(resources[locale], resource);
+		}
+	}
+	debug("Init locales with %j, got %j resources", options, Object.keys(resources));
+	app[I18N_RESOURCES] = resources;
+}
+function flattening(data) {
+	const result = {};
+	function deepFlat(data$1, prefix) {
+		for (const key in data$1) {
+			const value = data$1[key];
+			const k = prefix ? prefix + "." + key : key;
+			if (isObject(value)) deepFlat(value, k);
+			else result[k] = String(value);
+		}
+	}
+	deepFlat(data, "");
+	return result;
+}
+
+//#endregion
+export { loadLocaleResources };

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+import { I18nConfig } from "./config/config.default.js";
+
+//#region src/types.d.ts
+declare module 'egg' {
+  interface EggAppConfig {
+    /**
+     * I18n options
+     * @member Config#i18n
+     */
+    i18n: I18nConfig;
+  }
+  interface Application {
+    isSupportLocale(locale: string): boolean;
+    gettext(locale: string, key: string, value?: any, ...args: any[]): string;
+    __(locale: string, key: string, value?: any, ...args: any[]): string;
+  }
+  interface Context {
+    /**
+     * get and set current request locale
+     * @member Context#locale
+     * @return {String} lower case locale string, e.g.: 'zh-cn', 'en-us'
+     */
+    locale: string;
+    gettext(key: string, value?: any, ...args: any[]): string;
+    __(key: string, value?: any, ...args: any[]): string;
+    __getLocale(): string;
+    __setLocale(l: string): void;
+  }
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {  };

package/dist/utils.d.ts

@@ -0,0 +1,5 @@
+//#region src/utils.d.ts
+declare function isObject(obj: any): boolean;
+declare function formatLocale(locale: string): string;
+//#endregion
+export { formatLocale, isObject };

package/dist/utils.js

@@ -0,0 +1,10 @@
+//#region src/utils.ts
+function isObject(obj) {
+	return Object.prototype.toString.call(obj) === "[object Object]";
+}
+function formatLocale(locale) {
+	return locale.replaceAll("_", "-").toLowerCase();
+}
+
+//#endregion
+export { formatLocale, isObject };