i18n-text-tools/readme.md

一个用于自动提取、管理和同步项目多语言文本的命令行工具，支持 Vue3、JS/TS 文件的国际化文本收集、唯一key生成、重复检测、与YiCAT平台集成等功能。

# i18n-text-tools

一个用于自动提取、管理和同步项目多语言文本的命令行工具，支持 Vue3、JS/TS 文件的国际化文本收集、唯一key生成、重复检测、与YiCAT平台集成等功能。

## 特性

- 支持扫描指定目录下的 `.vue`、`.js`、`.ts` 文件，自动提取待翻译文本
- 自动为每条文本生成唯一 `msgId`，拼接到文案内作为前缀，并支持检测重复
- 支持将提取结果输出为 JSON Map 文件，便于后续i18n使用和翻译
- 支持与 YiCAT 平台对接，自动上传新提取的文案至yicat翻译平台，自动更新拉取最新已翻译的译文文案
- 支持命令行操作，适合集成到 CI/CD 流程
- 支持 Vite 插件实时收集和转换文案（Comming Soon）

## 安装

```sh
pnpm install i18n-text-tools -D
# 或
npm install i18n-text-tools -D
```

## 快速开始

1. 在你的项目 `package.json` 中配置 `i18nPickConfig` 字段，例如：

```json
"i18nPickConfig": {
  "srcCodeDir": "./demo",
  "outputDir": "./i18n-messages"
}
```

2. 运行命令提取文本：

```sh
pnpx i18n-text-tools extract
```

或在 `package.json` 脚本中添加：

```json
"scripts": {
  "i18n:extract": "i18n-text-tools extract"
}
```

## 命令行用法

- `extract`  
  扫描源码目录，提取所有待翻译文本，生成/更新 i18n 相关 JSON 文件。

- `upload`  
  （预留）上传提取的文本到 YiCAT 平台。

- `apply`  
  （预留）将最新翻译应用到本地 i18n 目录。

- `fetch`  
  （预留）从 YiCAT 平台拉取翻译内容。

示例：

```sh
npx i18n-text-tools extract
```

## 主要原理

- 通过 [`ExtractProcessor`](src/lib/ExtractProcessor.ts) 类，递归扫描源码目录，读取文件内容，利用 AST 解析提取文本。
- 支持自动为每条文本生成唯一 `msgId`，并将提取结果存储在 `i18n-messages` 目录下的 JSON 文件中。
- 支持对 Vue SFC 的 `<template>` 和 `<script>` 部分分别处理，自动转换静态中文属性为动态绑定。
- 支持配置自定义的翻译函数名（如 `t`, `$t`）。
- 支持与 YiCAT 平台对接，详见 [`YiCATConnector`](src/lib/YiCATConnector.ts)。

## 目录结构

```
src/
  index.ts                # 命令行入口
  dev.ts                  # 本地开发调试入口
  lib/
    ExtractProcessor.ts   # 文本提取核心逻辑
    Config.ts             # 配置读取与管理
    Util.ts               # 工具函数
    types.ts              # 类型定义
    YiCATConnector.ts     # YiCAT 平台对接
  vite-plugin/
    index.ts              # Vite 插件入口（实验性）
```

## 进阶用法

- 支持自定义扫描目录、输出目录、翻译函数名等，详见 [`ExtractConfig`](src/lib/Config.ts)。
- 支持本地开发模式（`NODE_ENV=dev_debug`），会将处理后的文件输出到指定目录，便于调试。
- 支持检测文件内容变更，避免重复处理未变更文件。

## 相关文件说明

- `.file_md5.json`：缓存每个文件的 md5，用于判断文件是否变更
- `.translation_items.json`：所有提取到的文本及其元数据
- `.translation_map.json`：最终用于 i18n 的 key-value 映射

## deploy

```
pnpm build
npm adduser --registry=https://registry.npmjs.org
```


npm publish --registry=https://registry.npmjs.org
npm unpublish i18n-text-tools@1.0.1 --force --registry=https://registry.npmjs.org