open-index/open-npm huggingface dataset:
npm package: @ktx-crypto/vue-i18n-toolkit
Description: Vue i18n 自动化提取与翻译工具
Latest version: 1.0.1

# @ktx/vue-i18n-toolkit

## 0. 使用方式：

`npx` 直接执行：

```bash
npx @ktx-crypto/vue-i18n-toolkit ./src/components/xxxxx --appid="appid"
```

API key 请去智谱清言获取，具体请参考：https://www.bigmodel.cn/
API key 地址: https://bigmodel.cn/usercenter/proj-mgmt/apikeys

常用可选参数：

- `--chunk-size <size>`：控制每批发送给大模型的词条数，默认 `50`

命令执行完成后，执行命令的目录生成同一时间戳的两个文件，时间戳格式为 `年月日-时分秒`：

- `i18n-locales-20260320-080910.json`
- `i18n-locales-20260320-080910.csv`

`json` 文件会按以下字段输出,用于校对方便：

```json
{
  "示例文案": {
    "zh_cn": "示例文案",
    "en_us": "Example copy",
    "ja_jp": "サンプル文言",
    "ko_kr": "예시 문구",
    "zh_hant": "示例文案",
    "vi_vn": "Ban sao vi du",
    "ru_ru": "Primer teksta",
    "th_th": "ข้อความตัวอย่าง"
  }
}
```

`csv` 文件不包含表头，每一行格式固定为：

```text
zh_cn,,zh_cn,en_us,ja_jp,ko_kr,zh_hant,vi_vn,ru_ru,th_th
```

可以直接复制粘贴到lark的表格的左上角，然后点击弹出的粘贴选择 text to column，就能展开至最终的i18n文件中。


## 1. 项目目标
本工具是一个基于 Node.js 的命令行接口 (CLI)，旨在扫描指定目录下的 Vue 和 TypeScript/JavaScript 文件，提取代码中已经使用的 i18n 翻译键（即 `t('键')` 或 `$t('键')` 中的字符串），并调用大语言模型 (LLM) 自动生成包含多国语言的 JSON 格式字典文件。本工具**不会**修改任何用户源文件。

## 2. 核心工作流程
1. **参数解析**：通过 `npx` 接收用户输入的扫描路径。
2. **文件扫描**：遍历目标目录，找出所有的 `.vue`, `.ts`, `.js` 文件。
3. **AST 提取**：
   * 将文件代码解析为抽象语法树 (AST)。
   * 遍历 AST 节点，定位所有的函数调用表达式 (CallExpression)。
   * 筛选出函数名为 `t` 或 `$t` 的调用。
   * 提取其第一个参数（字面量字符串），收集为翻译键集合。
4. **数据清洗**：对收集到的所有中文/翻译键进行去重处理。
5. **AI 翻译**：将去重后的键值数组分批发送给大语言模型，要求其返回包含 英文、繁体中文、日文、韩文、法文、越南文 的结构化 JSON 数据。
6. **文件生成**：将 AI 返回的数据合并，并在用户执行命令的当前工作目录 (CWD) 输出 `i18n-locales.json`。

## 3. 项目目录结构
```text
@ktx/vue-i18n-toolkit/
├── package.json        # 包含 bin 字段配置 npx 入口
├── tsconfig.json       # TS 配置
├── bin/
│   └── index.js        # CLI 执行入口 (#!/usr/bin/env node)
├── src/
│   ├── cli.ts          # 命令行参数解析 (使用 cac)
│   ├── scanner.ts      # 文件目录遍历 (使用 fast-glob)
│   ├── parser/         
│   │   ├── index.ts    # AST 解析入口，区分处理 Vue 和 TS/JS
│   │   └── extract.ts  # 核心：Babel AST 遍历，提取 t() 和 $t() 的参数
│   ├── translator.ts   # AI 大模型 API 请求封装与分批逻辑
│   ├── generator.ts    # JSON 格式化与本地文件写入
│   └── utils.ts        # 去重、日志打印等通用工具
└── README.md           
```

## 4. 关键技术选型
| 功能模块 | 推荐技术库 | 说明 |
| :--- | :--- | :--- |
| 命令行解析 | `cac` | 轻量级 CLI 框架，用于解析传入的路径参数。 |
| 文件扫描 | `fast-glob` | 高效匹配并获取指定目录下的所有目标文件路径。 |
| Vue 拆解 | `@vue/compiler-sfc` | 将 `.vue` 文件安全地拆分为 template 和 script 块。 |
| AST 解析 | `@babel/parser` | 将 JS/TS 代码转换为 AST 树。 |
| 节点遍历 | `@babel/traverse` | 深度遍历 AST，安全精准地找到 `CallExpression`。 |


## 发包流程：

npm whoami
pnpm --filter @ktx/vue-i18n-toolkit build
cd packages/vue-i18n-tookit
npm pack --dry-run
npm publish --access public