@kne/fastify-intl-admin 0.1.0

package/libs/services/lang-type.js

@@ -0,0 +1,381 @@
+const fp = require('fastify-plugin');
+const omit = require('lodash/omit');
+const { normalizeListQuery } = require('../utils/list-query');
+
+module.exports = fp(async (fastify, options) => {
+  const { models } = fastify[options.name];
+  const { Op } = fastify.sequelize.Sequelize;
+  const { ensureHttpErrors } = require('../utils/http-errors');
+  const httpErrors = ensureHttpErrors(fastify);
+
+  const createdUserInclude = () => ({
+    model: options.getUserModel(),
+    as: 'createdUser'
+  });
+
+  const detail = async (authenticatePayload, { id }) => {
+    const record = await models.langType.findByPk(id);
+    if (!record) {
+      throw httpErrors.notFound('语言类型不存在');
+    }
+    return record;
+  };
+
+  const clearDefaultFlags = async excludeId => {
+    const defaults = await models.langType.findAll({
+      where: Object.assign({ isDefault: true }, excludeId != null ? { id: { [Op.ne]: excludeId } } : {})
+    });
+    for (const item of defaults) {
+      await item.update({ isDefault: false });
+    }
+  };
+
+  const create = async (authenticatePayload, data) => {
+    const code = String(data.code || '').trim();
+    if (!code) {
+      throw httpErrors.badRequest('语言编码不能为空');
+    }
+    const existing = await models.langType.findOne({ where: { code } });
+    if (existing) {
+      throw httpErrors.badRequest('语言编码已存在');
+    }
+    const count = await models.langType.count();
+    // 第一条自动设为默认
+    const isDefault = count === 0;
+    // 新建默认排到最后
+    const last = await models.langType.findOne({
+      order: [
+        ['sort', 'DESC'],
+        ['id', 'DESC']
+      ],
+      attributes: ['sort']
+    });
+    const sort = last == null ? 0 : (Number(last.sort) || 0) + 1;
+    return models.langType.create({
+      name: data.name,
+      code,
+      params: data.params,
+      description: data.description,
+      status: data.status || 'open',
+      sort,
+      isDefault,
+      userId: authenticatePayload && authenticatePayload.id
+    });
+  };
+
+  const save = async (authenticatePayload, { id, ...data }) => {
+    const record = await detail(authenticatePayload, { id });
+    const payload = omit(data, ['code', 'createdAt', 'updatedAt', 'id', 'isDefault', 'sort']);
+    await record.update(payload);
+    return record;
+  };
+
+  const remove = async (authenticatePayload, { id }) => {
+    const record = await detail(authenticatePayload, { id });
+    const relatedCount = await models.langLib.count({
+      where: { locale: record.code }
+    });
+    if (relatedCount > 0) {
+      throw httpErrors.badRequest('该语言类型仍有关联词条，无法删除');
+    }
+    const wasDefault = !!record.isDefault;
+    await record.destroy();
+    if (wasDefault) {
+      const next = await models.langType.findOne({
+        order: [['createdAt', 'ASC']]
+      });
+      if (next) {
+        await next.update({ isDefault: true });
+      }
+    }
+  };
+
+  const setStatus = async (authenticatePayload, { id, status }) => {
+    const record = await detail(authenticatePayload, { id });
+    await record.update({ status });
+  };
+
+  const setDefault = async (authenticatePayload, { id }) => {
+    const record = await detail(authenticatePayload, { id });
+    if (record.isDefault) {
+      return;
+    }
+    await clearDefaultFlags(record.id);
+    await record.update({ isDefault: true });
+  };
+
+  const listOrder = [
+    ['sort', 'ASC'],
+    ['createdAt', 'ASC'],
+    ['id', 'ASC']
+  ];
+
+  /** direction: 'up' | 'down'，与相邻项交换 sort */
+  const move = async (authenticatePayload, { id, direction }) => {
+    const dir = String(direction || '').toLowerCase();
+    if (dir !== 'up' && dir !== 'down') {
+      throw httpErrors.badRequest('direction 必须为 up 或 down');
+    }
+    const record = await detail(authenticatePayload, { id });
+    const rows = await models.langType.findAll({
+      order: listOrder,
+      attributes: ['id', 'sort']
+    });
+    const index = rows.findIndex(item => String(item.id) === String(record.id));
+    if (index < 0) {
+      throw httpErrors.notFound('语言类型不存在');
+    }
+    const targetIndex = dir === 'up' ? index - 1 : index + 1;
+    if (targetIndex < 0 || targetIndex >= rows.length) {
+      return { moved: false };
+    }
+    const neighbor = rows[targetIndex];
+    const currentSort = Number(record.sort) || 0;
+    const neighborSort = Number(neighbor.sort) || 0;
+    if (currentSort === neighborSort) {
+      await record.update({ sort: targetIndex });
+      await neighbor.update({ sort: index });
+    } else {
+      await record.update({ sort: neighborSort });
+      await neighbor.update({ sort: currentSort });
+    }
+    return { moved: true };
+  };
+
+  const getDefaultLocaleCode = async () => {
+    const record = await models.langType.findOne({ where: { isDefault: true } });
+    return record ? record.code : '';
+  };
+
+  const translateRemaining = async (authenticatePayload, { id, namespace, limit }) => {
+    const targetLang = await detail(authenticatePayload, { id });
+    if (targetLang.status !== 'open') {
+      throw httpErrors.badRequest('目标语言未启用，无法补译');
+    }
+    if (targetLang.isDefault) {
+      throw httpErrors.badRequest('默认语言无需补译');
+    }
+
+    const defaultLocale = await getDefaultLocaleCode();
+    if (!defaultLocale) {
+      throw httpErrors.badRequest('未设置默认语言，无法补译');
+    }
+    if (targetLang.code === defaultLocale) {
+      throw httpErrors.badRequest('默认语言无需补译');
+    }
+
+    const scopedNamespace = namespace != null ? String(namespace).trim() : '';
+    const defaultWhere = { locale: defaultLocale };
+    const targetWhere = { locale: targetLang.code };
+    if (scopedNamespace) {
+      defaultWhere.namespace = scopedNamespace;
+      targetWhere.namespace = scopedNamespace;
+    }
+
+    const defaultEntries = await models.langLib.findAll({
+      where: defaultWhere
+    });
+    if (defaultEntries.length === 0) {
+      throw httpErrors.badRequest(scopedNamespace ? `命名空间 ${scopedNamespace} 下默认语言暂无词条，无法补译` : '默认语言暂无词条，无法补译');
+    }
+
+    const existingTarget = await models.langLib.findAll({
+      where: targetWhere,
+      attributes: ['namespace', 'code']
+    });
+    const existingKeys = new Set(existingTarget.map(item => `${item.namespace}::${item.code}`));
+    const missingEntries = defaultEntries.filter(item => !existingKeys.has(`${item.namespace}::${item.code}`));
+    if (missingEntries.length === 0) {
+      throw httpErrors.badRequest(scopedNamespace ? `命名空间 ${scopedNamespace} 下该语言词条已全部翻译完成` : '该语言词条已全部翻译完成');
+    }
+
+    const userId = authenticatePayload && authenticatePayload.id;
+    const GLOBAL_NS = 'global';
+    const batchLimit = limit != null && Number.isFinite(Number(limit)) && Number(limit) > 0 ? Math.floor(Number(limit)) : null;
+
+    // 非 global 命名空间：优先从 global 同 code + 目标语言拉取
+    const needGlobalLookup = missingEntries.some(item => item.namespace !== GLOBAL_NS);
+    const globalTargetByCode = new Map();
+    if (needGlobalLookup) {
+      const codes = [...new Set(missingEntries.filter(item => item.namespace !== GLOBAL_NS).map(item => item.code))];
+      if (codes.length > 0) {
+        const globalTargets = await models.langLib.findAll({
+          where: {
+            namespace: GLOBAL_NS,
+            locale: targetLang.code,
+            code: { [Op.in]: codes }
+          }
+        });
+        globalTargets.forEach(item => {
+          const target = item.target != null ? String(item.target) : '';
+          if (target.trim()) {
+            globalTargetByCode.set(item.code, target);
+          }
+        });
+      }
+    }
+
+    const processable = [];
+    for (const source of missingEntries) {
+      const sourceTarget = source.target != null ? String(source.target) : '';
+      if (!sourceTarget.trim()) {
+        continue;
+      }
+      processable.push(source);
+    }
+
+    if (processable.length === 0) {
+      throw httpErrors.badRequest('没有可补译的默认语言源文案');
+    }
+
+    const batchSources = batchLimit ? processable.slice(0, batchLimit) : processable;
+    const remainingCount = processable.length - batchSources.length;
+
+    const copiedRows = [];
+    const llmSources = [];
+    const texts = {};
+
+    for (const source of batchSources) {
+      const sourceTarget = String(source.target);
+      const key = `${source.namespace}::${source.code}`;
+
+      if (source.namespace !== GLOBAL_NS && globalTargetByCode.has(source.code)) {
+        copiedRows.push({
+          namespace: source.namespace,
+          code: source.code,
+          locale: targetLang.code,
+          target: globalTargetByCode.get(source.code),
+          reviewStatus: 'approved',
+          reviewRemark: null,
+          status: 'open',
+          userId
+        });
+        continue;
+      }
+
+      texts[key] = sourceTarget;
+      llmSources.push({
+        key,
+        namespace: source.namespace,
+        code: source.code
+      });
+    }
+
+    const llmRows = [];
+    if (llmSources.length > 0) {
+      if (typeof options.generateTargets !== 'function') {
+        throw httpErrors.badRequest('未配置 generateTargets，无法补译');
+      }
+      const generated =
+        (await options.generateTargets({
+          locales: [targetLang.code],
+          defaultLocale,
+          texts
+        })) || {};
+      const translatedMap = generated[targetLang.code] && typeof generated[targetLang.code] === 'object' ? generated[targetLang.code] : {};
+
+      llmSources.forEach(item => {
+        llmRows.push({
+          namespace: item.namespace,
+          code: item.code,
+          locale: targetLang.code,
+          target: translatedMap[item.key] != null ? String(translatedMap[item.key]) : '',
+          reviewStatus: 'pending',
+          reviewRemark: null,
+          status: 'open',
+          userId
+        });
+      });
+    }
+
+    const rows = copiedRows.concat(llmRows);
+
+    let created;
+    if (typeof models.langLib.bulkCreate === 'function') {
+      created = await models.langLib.bulkCreate(rows);
+    } else {
+      created = [];
+      for (const row of rows) {
+        created.push(await models.langLib.create(row));
+      }
+    }
+
+    return {
+      createdCount: created.length,
+      copiedCount: copiedRows.length,
+      generatedCount: llmRows.length,
+      remainingCount,
+      remainingSkipped: missingEntries.length - processable.length,
+      totalProcessable: processable.length
+    };
+  };
+
+  const list = async (authenticatePayload, query) => {
+    const { filter, perPage, currentPage } = normalizeListQuery(query);
+    const where = {};
+    if (filter.status) {
+      where.status = filter.status;
+    }
+    if (filter.isDefault === true || filter.isDefault === 'true') {
+      where.isDefault = true;
+    }
+    if (filter.isDefault === false || filter.isDefault === 'false') {
+      where.isDefault = false;
+    }
+    if (filter.keyword) {
+      const keyword = `%${filter.keyword}%`;
+      where[Op.or] = [{ name: { [Op.iLike]: keyword } }, { code: { [Op.iLike]: keyword } }, { description: { [Op.iLike]: keyword } }];
+    }
+    const { rows, count } = await models.langType.findAndCountAll({
+      where,
+      include: [createdUserInclude()],
+      offset: perPage * (currentPage - 1),
+      limit: perPage,
+      order: listOrder
+    });
+
+    const localeWhere = {};
+    if (filter.namespace) {
+      localeWhere.namespace = filter.namespace;
+    }
+    const localeRows = await models.langLib.findAll({
+      where: localeWhere,
+      attributes: ['locale']
+    });
+    const entryCountByLocale = {};
+    for (const item of localeRows) {
+      const locale = item.locale;
+      entryCountByLocale[locale] = (entryCountByLocale[locale] || 0) + 1;
+    }
+    const defaultLang = rows.find(item => item.isDefault) || (await models.langType.findOne({ where: { isDefault: true } }));
+    const defaultLocale = defaultLang ? defaultLang.code : '';
+    const defaultEntryCount = defaultLocale ? entryCountByLocale[defaultLocale] || 0 : 0;
+
+    const pageData = rows.map(row => {
+      const json = typeof row.toJSON === 'function' ? row.toJSON() : { ...row };
+      return Object.assign(json, {
+        entryCount: entryCountByLocale[row.code] || 0,
+        defaultEntryCount
+      });
+    });
+
+    return {
+      pageData,
+      totalCount: count
+    };
+  };
+
+  Object.assign(fastify[options.name].services, {
+    langType: {
+      create,
+      detail,
+      save,
+      remove,
+      setStatus,
+      setDefault,
+      move,
+      translateRemaining,
+      list
+    }
+  });
+});

package/libs/utils/http-errors.js

@@ -0,0 +1,48 @@
+/**
+ * 构造带 statusCode 的 HTTP 错误（不依赖 @fastify/sensible）
+ * @param {number} statusCode
+ * @param {string} message
+ * @returns {Error}
+ */
+const createHttpError = (statusCode, message) => {
+  const error = new Error(message);
+  error.statusCode = statusCode;
+  return error;
+};
+
+/**
+ * @returns {{ badRequest: Function, notFound: Function, internalServerError: Function }}
+ */
+const createHttpErrors = () => ({
+  badRequest: message => createHttpError(400, message),
+  notFound: message => createHttpError(404, message),
+  internalServerError: message => createHttpError(500, message)
+});
+
+/**
+ * 确保 fastify 上有 httpErrors（优先沿用宿主 @fastify/sensible）
+ * @param {import('fastify').FastifyInstance} fastify
+ */
+const ensureHttpErrors = fastify => {
+  if (fastify.hasDecorator && fastify.hasDecorator('httpErrors') && fastify.httpErrors) {
+    return fastify.httpErrors;
+  }
+  if (fastify.httpErrors) {
+    return fastify.httpErrors;
+  }
+  const httpErrors = createHttpErrors();
+  if (typeof fastify.decorate === 'function') {
+    try {
+      fastify.decorate('httpErrors', httpErrors);
+    } catch (e) {
+      // 已存在则忽略
+    }
+  }
+  return fastify.httpErrors || httpErrors;
+};
+
+module.exports = {
+  createHttpError,
+  createHttpErrors,
+  ensureHttpErrors
+};

package/libs/utils/i18n-file.js

@@ -0,0 +1,134 @@
+const DEFAULT_NAMESPACE = 'global';
+
+/**
+ * 解析 .i18n 文件名。
+ * - `namespace.locale.i18n` → { namespace, locale }
+ * - `locale.i18n` → { namespace: 'global', locale }
+ * @param {string} filename
+ * @returns {{ namespace: string, locale: string }}
+ */
+const parseFilename = filename => {
+  const name = String(filename || '')
+    .trim()
+    .split(/[/\\]/)
+    .pop();
+  if (!name) {
+    throw new Error('文件名不能为空');
+  }
+
+  const withNs = name.match(/^(.+)\.([^.]+)\.i18n$/i);
+  if (withNs) {
+    const namespace = withNs[1].trim();
+    const locale = withNs[2].trim();
+    if (!namespace || !locale) {
+      throw new Error(`无效的 i18n 文件名: ${name}`);
+    }
+    return { namespace, locale };
+  }
+
+  const localeOnly = name.match(/^([^.]+)\.i18n$/i);
+  if (localeOnly) {
+    const locale = localeOnly[1].trim();
+    if (!locale) {
+      throw new Error(`无效的 i18n 文件名: ${name}`);
+    }
+    return { namespace: DEFAULT_NAMESPACE, locale };
+  }
+
+  throw new Error(`无效的 i18n 文件名: ${name}`);
+};
+
+/**
+ * 构建导出文件名：`{namespace}.{locale}.i18n`
+ * @param {string} namespace
+ * @param {string} locale
+ * @returns {string}
+ */
+const buildFilename = (namespace, locale) => `${namespace}.${locale}.i18n`;
+
+const escapeTarget = target =>
+  String(target == null ? '' : target)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"');
+
+const unescapeTarget = target => String(target == null ? '' : target).replace(/\\(.)/g, (_, ch) => ch);
+
+/**
+ * 解析正文：每行 `code="target"`；空行忽略；目标值支持 `\"` / `\\` 转义。
+ * @param {string} content
+ * @returns {Array<{ code: string, target: string }>}
+ */
+const parseContent = content => {
+  const text = String(content == null ? '' : content);
+  const entries = [];
+  const linePattern = /^(.+?)="((?:\\.|[^"\\])*)"$/;
+
+  text.split(/\r?\n/).forEach(line => {
+    const raw = line.trim();
+    if (!raw) {
+      return;
+    }
+    const matched = raw.match(linePattern);
+    if (!matched) {
+      throw new Error(`无效的词条行: ${raw}`);
+    }
+    const code = matched[1].trim();
+    if (!code) {
+      throw new Error(`无效的词条行: ${raw}`);
+    }
+    entries.push({
+      code,
+      target: unescapeTarget(matched[2])
+    });
+  });
+  return entries;
+};
+
+/**
+ * 将词条列表序列化为正文：`code="target"`
+ * @param {Array<{ code: string, target?: string }>} entries
+ * @returns {string}
+ */
+const buildContent = (entries = []) => entries.map(item => `${item.code}="${escapeTarget(item.target)}"`).join('\n');
+
+/**
+ * 按 namespace+locale 分组为导出文件列表。
+ * @param {Array<{ namespace: string, locale: string, code: string, target?: string }>} rows
+ * @returns {Array<{ filename: string, content: string }>}
+ */
+const groupRowsToFiles = (rows = []) => {
+  const groups = new Map();
+  rows.forEach(row => {
+    const namespace = row.namespace;
+    const locale = row.locale;
+    if (!namespace || !locale) {
+      return;
+    }
+    const key = `${namespace}\0${locale}`;
+    if (!groups.has(key)) {
+      groups.set(key, {
+        namespace,
+        locale,
+        entries: []
+      });
+    }
+    groups.get(key).entries.push({
+      code: row.code,
+      target: row.target == null ? '' : row.target
+    });
+  });
+
+  return Array.from(groups.values()).map(({ namespace, locale, entries }) => ({
+    filename: buildFilename(namespace, locale),
+    content: buildContent(entries)
+  }));
+};
+
+module.exports = {
+  DEFAULT_NAMESPACE,
+  parseFilename,
+  buildFilename,
+  parseContent,
+  buildContent,
+  groupRowsToFiles
+};

package/libs/utils/list-query.js

@@ -0,0 +1,58 @@
+const FLAT_FILTER_KEYS = ['keyword', 'locale', 'reviewStatus', 'status', 'code', 'namespace', 'isDefault'];
+
+/**
+ * 归一化列表查询：兼容顶层 flat 字段与 filter 对象。
+ * @param {object} query
+ * @returns {{ filter: object, perPage: number, currentPage: number }}
+ */
+const normalizeListQuery = (query = {}) => {
+  const filter = Object.assign({}, query.filter || {});
+  FLAT_FILTER_KEYS.forEach(key => {
+    if (query[key] !== undefined && query[key] !== null && query[key] !== '' && filter[key] === undefined) {
+      filter[key] = query[key];
+    }
+  });
+  const perPage = Number(query.perPage) > 0 ? Number(query.perPage) : 20;
+  const currentPage = Number(query.currentPage) > 0 ? Number(query.currentPage) : 1;
+  return { filter, perPage, currentPage };
+};
+
+/**
+ * 将 body 中的 id / ids 归一为 id 数组。
+ * @param {{ id?: string|number, ids?: Array<string|number> }} body
+ * @returns {Array<string|number>}
+ */
+const normalizeIds = ({ id, ids } = {}) => {
+  if (Array.isArray(ids) && ids.length > 0) {
+    return ids;
+  }
+  if (id !== undefined && id !== null && id !== '') {
+    return [id];
+  }
+  return [];
+};
+
+/**
+ * 从可能为对象的 locale 字段取出语言 code。
+ * @param {string|{id?: string, value?: string, name?: string}|null} locale
+ * @returns {string|null}
+ */
+const normalizeLocaleValue = locale => {
+  if (locale == null) {
+    return null;
+  }
+  if (typeof locale === 'string') {
+    return locale;
+  }
+  if (typeof locale === 'object') {
+    return locale.value || locale.id || locale.name || null;
+  }
+  return String(locale);
+};
+
+module.exports = {
+  normalizeListQuery,
+  normalizeIds,
+  normalizeLocaleValue,
+  FLAT_FILTER_KEYS
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@kne/fastify-intl-admin",
+  "version": "0.1.0",
+  "description": "Fastify 业务插件：国际化语言类型与语言库管理（lang-type / lang-lib）",
+  "main": "index.js",
+  "scripts": {
+    "init": "husky",
+    "build:md": "npx @kne/md-doc",
+    "start:md": "npx @kne/md-doc --watch",
+    "prettier": "prettier --config .prettierrc --write '{libs/**/*,index}.{js,jsx,ts,tsx,json,css,scss}'",
+    "lint-staged": "npx lint-staged",
+    "test": "mocha test/**/*.test.js",
+    "test:coverage": "nyc --reporter=html --reporter=text mocha test/**/*.test.js"
+  },
+  "lint-staged": {
+    "{libs/**/*,index}.{js,jsx,ts,tsx,json,css,scss}": [
+      "prettier --config .prettierrc --write",
+      "git add"
+    ]
+  },
+  "files": [
+    "index.js",
+    "libs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kne-union/fastify-intl-admin.git"
+  },
+  "keywords": [
+    "fastify",
+    "i18n",
+    "intl",
+    "lang",
+    "translation",
+    "admin"
+  ],
+  "author": "linzp",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/kne-union/fastify-intl-admin/issues"
+  },
+  "homepage": "https://github.com/kne-union/fastify-intl-admin#readme",
+  "dependencies": {
+    "lodash": "^4.17.21"
+  },
+  "peerDependencies": {
+    "@kne/fastify-namespace": "*",
+    "@kne/fastify-sequelize": "*",
+    "fastify-plugin": ">=5"
+  },
+  "devDependencies": {
+    "@fastify/env": "^5.0.2",
+    "@kne/fastify-namespace": "*",
+    "@kne/fastify-sequelize": "^3.0.6",
+    "chai": "^6.2.2",
+    "fastify": "^5.4.0",
+    "fastify-plugin": "^5.0.1",
+    "husky": "^9.0.11",
+    "mocha": "^11.7.5",
+    "nodemon": "^3.1.3",
+    "nyc": "^17.1.0",
+    "prettier": "^3.2.5",
+    "sinon": "^21.0.0",
+    "sqlite3": "^5.1.7"
+  }
+}