ym-i18n-auto 流程说明

ym-i18n-auto 是一个 Vue 项目国际化采集工具：在 Git 提交时自动抽出 $lang() / $t() 里的中文源文，提交到 system-assistant 的 ingest 接口。前端只负责采集和提交源文，翻译、导入 PGS/JFS 由服务端后台任务处理。当前版本 1.2.14。

1. 它解决什么问题

以前：commit → 前端翻译 → 生成 Excel → 上传 PGS/JFS。

现在：commit → 抽中文源文 → POST ingest → 服务端翻译/去重 → 后台手动导入。

前端不再做翻译、查重、Excel。

2. 核心链路（日常主路径）

开发改 .vue/.js
    ↓
git commit
    ↓
.git/hooks/pre-commit          ← 不阻断 commit
    ↓
i18n-extract.mjs --diff        ← 对比暂存区 vs HEAD，抽出新增 $lang/$t
    ↓
与 i18n.json 去重（已有则跳过上传）
    ↓
后台异步 i18n-upload.mjs
    ↓
POST /system-assistant/api/v1/i18n/ingest
    ├─ 成功 → 清失败队列
    └─ 失败 → 写 .ym-i18n/upload-queue.json

不阻断 commit：提取或上传失败，Git 提交照样成功。失败文案进队列，之后用 retry-queue 重推。

3. 完整流程（从接入到补推）

① 接入：init

npx ym-i18n-auto init
# 或本地安装后
npx ymi18n init

交互配置：系统（PGS/JFS）、国家（id/vn/ph/br）、ingest token。然后：

1. 拷贝脚本到 .ym-i18n/
2. 生成 .ym-i18n/.env
3. 安装 .git/hooks/pre-commit
4. 写入 .gitignore（.ym-i18n/、log/、i18n.json）
5. 全量扫描建 i18n.json 基线

同时会安装 post-push 观察器：仅当成功推送 master 时，异步发送 Git URL 和前后 SHA 给 SA 作为候选。它不会确认标签已合入，也不会阻断 push；GitLab Push Webhook 才是合入 master 的权威来源。已有 post-push 会备份为 post-push.ym-i18n-original 并链式执行。

② 日常：每次 git commit

1. 只看暂存的 .vue/.js/.ts/.jsx/.tsx
2. git show :file vs HEAD:file，取本次新增的静态 $lang / $t / this.$lang
3. 已在 i18n.json 里的视为处理过，不再上传
4. 后台 POST ingest（带 git 用户名、project_name=pgs、country=vn 等）
5. 写 log/ym-i18n-*.log

③ 失败补救：retry-queue

读 .ym-i18n/upload-queue.json，再提交一次。任意失败都会入队（Node 版本、网络、token、脚本崩溃等）。

npx ymi18n retry-queue

旧命令名 retry 仍可用。

④ 区间补推：push-range

按起始/结束 commit 做 git diff，抽出新增中文 $lang/$t。

不与 i18n.json 去重（commit 时可能已写入本地，但服务端没收到）。

起止填同一个 hash = 只重推那一个 commit。

npx ymi18n push-range
npx ymi18n push-range --from c2e8f93 --to HEAD --confirm

也可按 git 作者补推：只提取这些作者自己的 commit，同样不与 i18n.json 去重。不加 --from/--to 时扫当前分支全部历史。多个作者用 , 或 ， 分隔。

npx ymi18n push-range --author gjb
npx ymi18n push-range --author gjb,zhangsan --confirm
npx ymi18n push-range --from c2e8f93 --to HEAD --author gjb --confirm

旧命令名 retrypush 仍可用。

⑤ 全量对账：reconcile

扫全项目缺失源文再提交，需 --confirm。

4. 目录与职责

tools/ym-i18n-auto/          npm 包源码（开发、发版）
  bin/cli.mjs                CLI：init / retry-queue / push-range ...
  bin/i18n-extract.mjs       提取：$lang/$t 正则 + git diff
  bin/i18n-upload.mjs        提交 ingest + 失败队列
  bin/i18n-master-push.mjs   master 推送候选事件观察器
  hooks/pre-commit           Git hook 模板
  hooks/post-push            Git push 观察器模板
  .env.example

项目接入后（运行时，不提交 git）
  .ym-i18n/.env              URL / token / system / country
  .ym-i18n/i18n-*.mjs        脚本副本
  .ym-i18n/upload-queue.json 失败队列
  i18n.json                  本地基线（去重用）
  log/ym-i18n-*.log          运行日志
  .git/hooks/pre-commit      已安装的 hook
  .git/hooks/post-push       保留原 Hook 的 master 推送观察 shim

5. 用到的技术

| 层 | 技术 | 作用 | |----|------|------| | 运行时 | Node.js ≥ 18 | ESM（.mjs），原生 fetch | | CLI | Node 标准库 | fs / path / readline / child_process | | 进程 | spawnSync | 传 $lang 等参数，避免 Windows cmd 吃掉 $ | | Git | git diff --cached、git show、git rev-parse | 增量、区间、单 commit（~1 父提交） | | 提取 | 正则 | $lang('…') / $t("…") / 模板字符串 / this.$lang | | 中文过滤 | Unicode 范围 | [\u4e00-\u9fff…] | | Hook | Bash + nohup | 后台上传、不挡 commit | | 配置 | .env | YM_I18N_URL / TOKEN / SYSTEM / COUNTRY | | 鉴权 | HTTP Header | X-I18N-Ingest-Token + Authorization: Bearer | | 接口 | REST JSON | POST …/api/v1/i18n/ingest | | 发布 | npm | 包名 ym-i18n-auto，bin：ymi18n / ym-i18n-auto | | 零运行时依赖 | 无 xlsx、无 axios | 只靠 Node 内置 |

服务端（不在本包内）：ingest → staging → consume 去重 → 翻译 → 后台任务手动导入 PGS/JFS。

6. 提交 ingest 的数据

{
  "git_name": "gjb",
  "git_email": "…",
  "git_url": "[email protected]:group/project.git",
  "sha": "74d858e0a1b2c3d4e5f678901234567890abcdef",
  "project_name": "pgs",
  "system_type": "PGS",
  "country": "id",
  "source_lang": "zh",
  "strings": ["客户订单号", "…"],
  "string_list": [
    {
      "path": "pages/org-perfor/target/components/addTarget.vue",
      "array": ["指标定义/公式2026年"]
    }
  ]
}

path 为相对仓库根目录（与 .git 同级）的文件路径；sha 为本次 commit 的完整哈希；project_name 来自 YM_I18N_SYSTEM；越南码统一为 vn。

7. 三条路径对比

| | commit 自动 | retry-queue | push-range | |--|-------------|---------------|--------------| | 源 | 本次暂存 diff | 失败队列 | commit 区间 diff，或 --author 下该作者的各 commit | | 对 i18n.json 去重 | 是 | 否（队列原样） | 否 | | 典型场景 | 日常开发 | 网络/Node 失败后补推 | 漏提交的历史区间 / 按 git 作者补推 |

8. 使用方式

# 首次
npx ym-i18n-auto init

# 日常：正常 git commit 即可

# 本地安装后
npx ymi18n retry-queue
npx ymi18n push-range
npx ymi18n push-range --author gjb

公司镜像没有这个包时，安装要指定官方源：

npm i -D ym-i18n-auto --registry=https://registry.npmjs.org

本地装好后，npx ymi18n … 走 node_modules，一般不用再加 --registry。

本地安装后不要直接敲 ymi18n（不在系统 PATH 里），应使用：

npx ymi18n retry-queue
# 或
npm run i18n:retry-queue   # 需在 package.json scripts 中配置