报告与检查

批量迁移国际化时，建议把预览、报告和一致性检查作为固定流程。这样可以在写入前知道会改哪些文件，也可以在写入后检查源码引用和语言包是否匹配。

翻译报告

tf 和 tfo 都支持 -r, --report <file>：

hitf tf src\views\user\index.vue user -d -r .hitf\reports\user.json
hitf tfo src\views user -r .hitf\reports\user-folder.json

报告是 JSON 格式，适合人工审查、CI 上传或后续脚本处理：

{
  "mode": "dry-run",
  "summary": {
    "filesScanned": 1,
    "filesWithExtractions": 1,
    "replacements": 3,
    "written": 0,
    "skipped": 1,
    "failed": 0
  },
  "files": [
    {
      "file": "src/views/user/index.vue",
      "outputFile": ".hitf/lang/user/index.vue",
      "replacements": [
        {
          "text": "User Detail",
          "key": "user.user_detail",
          "context": "attribute",
          "start": 42,
          "end": 53
        }
      ]
    }
  ],
  "failedFiles": []
}

字段含义：

字段	说明
mode	dry-run 或 write
summary.filesScanned	实际扫描的文件数量
summary.filesWithExtractions	有取词结果的文件数量
summary.replacements	准备替换或已替换的文案数量
summary.written	已写入文件数量
summary.skipped	跳过文件数量
summary.failed	失败文件数量
files[].replacements	每个文件内的取词、key、上下文和位置
failedFiles	语法校验失败或处理失败的文件

Dry Run 与交互确认

只想预览，不写文件：

hitf tfo src\views user -d

预览输出示例：

  用户详情 → user.user_detail ~ src/views/user/index.vue:2:21
  登录 → user.login ~ src/views/user/index.vue:3:21

预览后再确认是否应用：

hitf tfo src\views user -i

两者都可以配合 -r, --report：

hitf tfo src\views user -d -r .hitf\reports\preview.json

失败汇总

文件夹翻译结束后会输出汇总：

Translation summary
  scanned: 12
  replacements: 35
  written: 10
  skipped: 1
  failed: 1

如果替换后的文件无法通过语法校验，工具会跳过该文件并记录失败原因，避免写入破坏语法的结果。

一致性检查

hitf tcheck 用于检查源码中的 $t(...)、this.$t(...)、t(...) 引用和 locale JSON 是否一致：

hitf tcheck src
hitf tcheck src -r .hitf\reports\tcheck.json

检查内容：

类型	说明
missing	源码引用了但所有语言包都不存在的 key
unused	语言包存在但源码没有引用的 key
inconsistent	某个 key 在部分 locale JSON 中缺失
invalid locale files	无法解析的 JSON 语言包

输出示例：

Translation check summary
  missing: 2
  unused: 0
  inconsistent: 0
  invalid locale files: 0
  missing hello
    src/App.vue:2:11
  missing welcome
    src/App.vue:3:9

tcheck 适合在批量迁移后执行，也适合放进 CI，阻止缺失语言包或 JSON 损坏进入主分支。