@eggjs/i18n 3.0.0

package/src/app.ts

@@ -0,0 +1,99 @@
+import path from 'node:path';
+import { debuglog } from 'node:util';
+import { loadLocaleResources } from './locales.js';
+import { exists } from 'utility';
+import { ms } from 'humanize-ms';
+import type { ILifecycleBoot } from '@eggjs/core';
+import type I18nApplication from './app/extend/application.js';
+import { formatLocale } from './utils.js';
+
+const debug = 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": "注册时间"
+ * }
+ * ```
+ */
+
+export default class I18n implements ILifecycleBoot {
+  private readonly app;
+
+  constructor(app: I18nApplication & { locals: Record<string, any> }) {
+    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 : [];
+    // 按 egg > 插件 > 框架 > 应用的顺序遍历 config/locale(config/locales) 目录，加载所有配置文件
+    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: string, ...args: any[]) {
+      const ctx = app.ctxStorage.getStore()!;
+      return ctx.gettext(key, ...args);
+    }
+    // 在 view 中使用 `__(key, value, ...args)`
+    this.app.locals.gettext = gettextInContext;
+    this.app.locals.__ = gettextInContext;
+  }
+}

package/src/config/config.default.ts

@@ -0,0 +1,15 @@
+import type { I18nConfig } from '../types.js';
+
+export default {
+  i18n: {
+    defaultLocale: 'en_US',
+    dirs: [],
+    queryField: 'locale',
+    cookieField: 'locale',
+    cookieDomain: '',
+    cookieMaxAge: '1y',
+    localeAlias: {},
+    writeCookie: true,
+    dir: undefined,
+  } as I18nConfig,
+};

package/src/index.ts

@@ -0,0 +1 @@
+import './types.js';

package/src/locales.ts

@@ -0,0 +1,73 @@
+import { debuglog } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import ini from 'ini';
+import yaml from 'js-yaml';
+import { exists, readJSON } from 'utility';
+import { importModule } from '@eggjs/utils';
+import type { I18nConfig } from './types.js';
+import I18nApplication, { I18N_RESOURCES } from './app/extend/application.js';
+import { formatLocale, isObject } from './utils.js';
+
+const debug = debuglog('@eggjs/i18n/locales');
+
+export async function loadLocaleResources(app: I18nApplication, options: I18nConfig) {
+  const localeDirs = options.dirs;
+  const resources: Record<string, Record<string, string>> = {};
+
+  if (options.dir && !localeDirs.includes(options.dir)) {
+    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);
+      // support en_US.js => en-US.js
+      const locale = formatLocale(name.split('.')[0]);
+      let resource: Record<string, string> = {};
+
+      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: any) {
+  const result: Record<string, string> = {};
+
+  function deepFlat(data: any, prefix: string) {
+    for (const key in data) {
+      const value = data[key];
+      const k = prefix ? prefix + '.' + key : key;
+      if (isObject(value)) {
+        deepFlat(value, k);
+      } else {
+        result[k] = String(value);
+      }
+    }
+  }
+
+  deepFlat(data, '');
+
+  return result;
+}

package/src/types.ts

@@ -0,0 +1,80 @@
+/**
+ * I18n options
+ * @member Config#i18n
+ */
+export interface I18nConfig {
+  /**
+   * 默认语言是美式英语，毕竟支持多语言，基本都是以英语为母板
+   * 默认值是 `en_US`
+   */
+  defaultLocale: string;
+  /**
+   * 多语言资源文件存放路径，不建议修改
+   * 默认值是 `[]`
+   */
+  dirs: string[];
+  /**
+   * @deprecated please use `dirs` instead
+   */
+  dir?: string;
+  /**
+   * 设置当前语言的 query 参数字段名，默认通过 `query.locale` 获取
+   * 如果你想修改为 `query.lang`，那么请通过修改此配置实现
+   * 默认值是 `locale`
+   */
+  queryField: string;
+  /**
+   * 如果当前请求用户语言有变化，都会设置到 cookie 中保持着，
+   * 默认是存储在key 为 locale 的 cookie 中
+   * 默认值是 `locale`
+   */
+  cookieField: string;
+  /**
+   * 存储 locale 的 cookie domain 配置，默认不设置，为当前域名才有效
+   * 默认值是 `''`
+   */
+  cookieDomain: string;
+  /**
+   * cookie 默认一年后过期，如果设置为 Number，则单位为 ms
+   * 默认值是 `'1y'`
+   */
+  cookieMaxAge: string | number;
+  /**
+   * locale 别名，比如 zh_CN => cn
+   * 默认值是 `{}`
+   */
+  localeAlias: Record<string, string>;
+  /**
+   * 是否写入 cookie
+   * 默认值是 `true`
+   */
+  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;
+  }
+}

package/src/typings/index.d.ts

@@ -0,0 +1,4 @@
+// make sure to import egg typings and let typescript know about it
+// @see https://github.com/whxaxes/blog/issues/11
+// and https://www.typescriptlang.org/docs/handbook/declaration-merging.html
+import 'egg';

package/src/utils.ts

@@ -0,0 +1,8 @@
+export function isObject(obj: any) {
+  return Object.prototype.toString.call(obj) === '[object Object]';
+}
+
+export function formatLocale(locale: string) {
+  // support zh_CN, en_US => zh-CN, en-US
+  return locale.replace('_', '-').toLowerCase();
+}