翻译单文件

hitf tf 用于翻译一个文件。它会提取源语言文案、生成 key、写入语言包，并把源文件中的文案替换为国际化调用。

默认兼容中文源码项目。配置 locales: ["en-US", "zh-CN", "ja-JP"] 后，可以提取英文文案并翻译到 zh-CN 和 ja-JP。

基本命令

hitf tf views\demo\index.vue

支持常见文件类型：

类型	说明
.vue	Vue SFC，包含 <template>、<script>、<script setup>
.js / .ts	JavaScript 和 TypeScript 业务代码
.jsx / .tsx	React JSX / TSX
.json	JSON 文案值

基本选项

hitf tf src\views\demo\index.vue demo -d
hitf tf src\views\demo\index.vue demo -i
hitf tf src\views\demo\index.vue demo -r .hitf\reports\demo.json
hitf tf apps\main\src\views\index.vue home -p main

选项	简写	说明
-n, --name <name>	-n	国际化对象 key（默认使用父级目录名）
-p, --project <project>	-p	outDir 为对象时指定项目
-d, --dry-run	-d	列出所有提取的中文文本及其位置，不执行翻译
-i, --interactive	-i	预览后询问是否应用
-r, --report <file>	-r	写入 JSON 翻译报告
-v, --verbose	-v	输出详细日志

预览模式

-d / --dry-run 列出所有提取的中文文本及其在源码中的位置（文件:行:列），不执行翻译：

hitf tf src\views\demo\index.vue -d

输出示例：

  合适 → src.suitable ~ src/views/demo/index.vue:2:21
  测试 → src.test ~ src/views/demo/index.vue:3:21

取词范围

会提取用户可见或运行时展示的文案：

message.success('Save successfully')
toast('Copied')

const item = {
  label: 'User Name',
  title: 'User Detail',
  placeholder: 'Enter username',
  description: 'Please select a user'
}

支持逻辑表达式里的兜底文案：

const text = data?.text || 'Default text'
const desc = data?.description ?? 'No description'

Vue 模板中也支持：

{{ data?.text || 'Default text' }}
{{ data?.description ?? 'No description' }}

解构默认值和函数参数默认值默认不取，避免把类型/数据结构兜底误认为 UI 文案：

const { propertyName = 'User name' } = objectToDestruct
function submit(label = 'Save') {}

Vue 模板

文本节点会替换为 $t：

<button>登录</button>

<button>{{ $t('demo.login') }}</button>

插值旁边的中文会保留表达式边界：

<h1>留言（{{ remarkList ? remarkList.length : 0 }}）</h1>

<h1>{{ $t('demo.leave_a_message') }}（{{ remarkList ? remarkList.length : 0 }}）</h1>

属性

用户可见属性会被翻译：

<input placeholder="请输入用户名" />

<input :placeholder="$t('demo.please_enter_username')" />

资源路径属性不会翻译，避免破坏文件引用：

<img src="@/assets/images/ssHome/供应商总数量1.png" alt="供应商总数量" />

<img src="@/assets/images/ssHome/供应商总数量1.png" :alt="$t('demo.total_number_of_suppliers')" />

当前建议跳过的资源属性包括 src、srcset、href、poster。

样式相关内容会跳过，包括 class、动态 class、行内 style 和 <style> 块：

<div class="user-card" :style="{ color: 'red' }">用户详情</div>

<style lang="scss" scoped>
.user-card {}
</style>

JavaScript 字符串

脚本中的源语言字符串会替换为翻译函数调用：

const title = '登录'

const title = t('demo.login')

英文源码示例：

{
  "translationSetting": {
    "locales": ["en-US", "zh-CN", "ja-JP"]
  }
}

<button>Login</button>

<button>{{ $t('demo.login') }}</button>

正则中的中文属于匹配规则，不建议自动翻译：

const regex = /中文|English/giu

已处理过的 $t(...)、this.$t(...)、t(...) 会跳过，Vue2 的 this.$t 会保留支持。

JSX

JSX 文本会替换为 {t(...)}：

<h1>留言（{remarkList ? remarkList.length : 0}）</h1>

<h1>{t('jsxAll.leave_a_message')}（{remarkList ? remarkList.length : 0}）</h1>

长段自然语言应尽量作为一个完整文案处理，避免按逗号、句号拆成过多 key。

JSX/TSX 中 className、style、事件属性、type、role、data-*、aria-* 会跳过；自定义展示属性可以提取，例如：

<Comp title="User Detail" label="User Name" />

Vue SFC 中的 <script setup lang="jsx"> 和 <script setup lang="tsx"> 也会按 JSX/TSX 解析，支持 render function 和 defineComponent 中返回的 JSX 文案。

忽略注释

临时不希望处理的代码可以用忽略注释：

// @hitf-i18n-ignore-next
message.success('Keep original')

/* @hitf-i18n-ignore-start */
const a = 'Keep original'
const b = 'Keep original too'
/* @hitf-i18n-ignore-end */

Vue 模板：

<!-- @hitf-i18n-ignore-next -->
<div>保持原文</div>

整文件忽略：

// @hitf-i18n-ignore-file

输出

翻译后通常会产生两类变化：

1. 原文件中的中文被替换为 $t 或 t 调用。
2. locale 目录中生成对应语言包。

示例：

src\locale\module\demo\zh-CN.json
src\locale\module\demo\en-US.json