# ldesign-translator

**Repository Path**: ldesign-v1/ldesign-translator

## Basic Information

- **Project Name**: ldesign-translator
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-09
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @composy/translator

`@composy/translator` 是一个面向本地项目工作区的 i18n 工具包，聚焦 `CLI + Node.js`
场景，提供从源码提取、批量翻译、质量校验、Excel 协作，到代码回写的完整闭环。

当前版本不再包含 Web UI，对外能力收敛为：

- 命令行工具 `ldesign-translator`
- 可编排的 Node API
- 持久化工作区状态 `.translator/*`
- 基于 `@composy/pack` 的全模块打包产物

## 核心能力

- 提取：从 `js`、`jsx`、`ts`、`tsx`、`vue`、`json` 中提取中文文本
- 翻译：支持 `mock`、`google`、`baidu`、`deepl`
- 记忆库：基于 `better-sqlite3` 的翻译记忆
- 术语库：支持术语保护、术语替换、术语校验
- 校验：空值、占位符、HTML、长度、术语一致性
- Excel：支持导出、导入、预览冲突、覆盖策略
- 替换：把硬编码文案替换成 `t('key')`
- 工作区：维护提取快照、diff 报告、review 状态
- 诊断：`doctor` 只读检查配置、工作区状态和 provider
- 打包：`src/**/*.ts` 全量输出 `esm + cjs + d.ts`

## 目录结构

```text
src/
  cli/                CLI 入口与命令编排
  config/             配置加载与校验
  extraction/         文本提取
  glossary/           术语库管理
  replacement/        代码替换
  shared/             文件、日志、文本工具
  translation/        翻译引擎、翻译记忆、provider
  validation/         翻译质量校验
  workbook/           Excel 导入导出与导入规划
  workspace/          locale 与 .translator 状态读写/编排
  types/              对外共享类型
  vendor/             第三方类型补丁
tests/                历史 Vitest 用例
scripts/              构建与自检脚本
.ldesign/pack.config.ts
```

## 工作区文件

运行流程中会维护以下状态文件：

- `.translator/extracted-texts.json`：最近一次提取结果
- `.translator/extract-report.json`：最近一次提取 diff
- `.translator/review-state.json`：按 `key + language` 记录 review 状态
- `.translator/memory.db`：翻译记忆库

## 安装

```bash
pnpm add -D @composy/translator
```

如果你在 monorepo 内开发这个包，直接在当前工作区执行：

```bash
pnpm run type-check
pnpm run lint:check
pnpm run build
pnpm run test:run
```

## 快速开始

### 1. 初始化配置

```bash
ldesign-translator init --skip-prompts --output-format yaml --split-by-namespace
```

默认会生成 `translator.config.js`，provider 默认为 `mock`，便于先跑通整条流程。

### 2. 提取源码文案

```bash
ldesign-translator extract
```

常见增量模式：

```bash
ldesign-translator extract --changed
ldesign-translator extract --staged
ldesign-translator extract --since-ref main
ldesign-translator extract src/components
```

### 3. 批量翻译

```bash
ldesign-translator translate --to en,ja
```

禁用翻译记忆：

```bash
ldesign-translator translate --to en --no-use-memory
```

### 4. 校验翻译质量

```bash
ldesign-translator validate --languages en,ja
```

### 5. 导出 / 导入 Excel

```bash
ldesign-translator export --output ./translations.xlsx --include-metadata
ldesign-translator import --file ./translations.xlsx --preview
ldesign-translator import --file ./translations.xlsx --overwrite
```

### 6. 回写代码中的硬编码文案

```bash
ldesign-translator replace src --dry-run
ldesign-translator replace src --i18n-function t
```

## CLI 命令

全局选项：

- `--cwd <dir>` 按指定目录加载配置并读写 `.translator/*` 与 locale 文件

常用诊断：

```bash
ldesign-translator doctor
ldesign-translator doctor --json
ldesign-translator --cwd packages/app doctor --strict
```

### `init`

创建 `translator.config.js`。

- `--source-language <lang>` 源语言
- `--target-languages <langs>` 目标语言，逗号分隔
- `--provider <provider>` 翻译服务
- `--output-dir <dir>` locale 输出目录
- `--output-format <json|yaml|js|ts>` 输出格式
- `--split-by-namespace` 按 namespace 拆分文件
- `--nested` 输出嵌套对象
- `--force` 覆盖已有配置
- `--skip-prompts` 跳过交互

### `extract [paths...]`

提取源码文案并更新工作区。

- `--verbose` 输出详细信息
- `--overwrite` 覆盖源语言 locale 中已存在值
- `--changed` 只处理工作区 Git 变更文件
- `--staged` 只处理暂存区变更文件
- `--since-ref <ref>` 只处理相对某个 Git 引用的变更

### `translate`

将已提取文案翻译到目标语言。

- `--to <languages>` 必填，目标语言列表
- `--force` 强制覆盖已有译文
- `--no-use-memory` 禁用翻译记忆
- `--concurrency <count>` 并发执行 provider 批次
- `--verbose` 输出详细信息

### `export`

导出 locale 到 Excel 工作簿。

- `--output <file>` 输出文件
- `--languages <langs>` 导出指定语言
- `--include-metadata` 附带 `namespace/file/context`

### `import`

从 Excel 工作簿导入译文。

- `--file <file>` 工作簿路径
- `--overwrite` 覆盖冲突译文
- `--preview` 仅预览不落盘
- `--no-validate` 跳过工作簿结构校验

### `validate`

执行翻译质量校验。

- `--languages <langs>` 指定校验语言
- `--no-check-placeholders` 关闭占位符校验
- `--no-check-html-tags` 关闭 HTML 校验
- `--no-check-length` 关闭长度校验
- `--no-check-glossary` 关闭术语校验
- `--max-length <length>` 最大长度阈值
- `--verbose` 输出详细信息

### `replace [paths...]`

将硬编码中文替换为 i18n 调用。

- `--i18n-function <name>` i18n 函数名
- `--no-add-imports` 不自动补 import
- `--no-backup` 不生成 `.backup`
- `--dry-run` 只预览不写入
- `--verbose` 输出逐条替换明细

## 配置文件

通过 `cosmiconfig` 自动查找以下配置来源：

- `package.json` 中的 `translator`
- `.translatorrc`
- `.translatorrc.json`
- `.translatorrc.yaml`
- `.translatorrc.yml`
- `.translatorrc.js`
- `.translatorrc.cjs`
- `translator.config.js`
- `translator.config.cjs`
- `translator.config.ts`

示例：

```js
module.exports = {
  sourceLanguage: 'zh-CN',
  targetLanguages: ['en', 'ja'],
  api: {
    provider: 'mock',
    key: process.env.TRANSLATE_API_KEY || '',
    rateLimit: 10,
    batchSize: 50,
    concurrency: 1,
    retries: 3,
  },
  extract: {
    include: ['src/**/*.{js,jsx,ts,tsx,vue,json}'],
    exclude: ['node_modules', 'dist', 'build'],
    includeComments: false,
  },
  output: {
    dir: 'src/locales',
    format: 'yaml',
    minify: false,
    splitByNamespace: true,
    nested: false,
  },
  memory: {
    enabled: true,
    dbPath: '.translator/memory.db',
    similarityThreshold: 0.7,
  },
  glossary: {
    enabled: false,
    filePath: '.translator/glossary.json',
    entries: [],
  },
  replace: {
    i18nFunction: 't',
    importPath: '@/i18n',
    addImports: true,
  },
  validation: {
    enabled: true,
    checkPlaceholders: true,
    checkHtmlTags: true,
    checkLength: true,
    checkGlossary: true,
    maxLength: 1000,
  },
  incremental: true,
}
```

## 对外 API

主入口导出以下主要模块：

- `loadConfig` / `createConfig`
- `TextExtractor`
- `TranslationEngine`
- `TranslationMemory`
- `TranslationValidator`
- `TranslationWorkbookService`
- `TranslationWorkspaceService`
- `CodeReplacer`
- 所有 provider 与共享类型
- `registerTranslationProvider` / `createTranslationProvider` / `listTranslationProviders`

自定义 provider 示例：

```ts
import { registerTranslationProvider } from '@composy/translator'

registerTranslationProvider('internal-ai', config => ({
  name: 'Internal AI',
  async translate(texts, from, to) {
    return texts.map(text => ({
      original: text,
      translated: `[${to}] ${text}`,
      source: 'api',
    }))
  },
}))
```

## 构建与产物

当前包使用 `@composy/pack`，通过 [.ldesign/pack.config.ts](.ldesign/pack.config.ts) 打包
`src/**/*.ts` 中所有运行时代码文件，输出：

- ESM：`dist/**/*.js`
- CJS：`dist/**/*.cjs`
- DTS：`dist/**/*.d.ts`

CLI 可执行入口源码位于 [src/bin/cli.ts](src/bin/cli.ts)，构建后输出为 `dist/bin/cli.js`，并转发到
`dist/cli/index.js`。

## 开发验证

推荐在提交前执行：

```bash
pnpm run type-check
pnpm run lint:check
pnpm run build
pnpm run test:run
node ./dist/bin/cli.js --help
```

## 注意事项

- 翻译记忆依赖 `better-sqlite3`，首次安装需要可用的原生模块环境。
- `replace` 命令依赖已有提取结果；如果工作区没有 `.translator/extracted-texts.json`，应先运行
  `extract`。
- `yaml` 输出当前不支持 `nested: true`。
- `splitByNamespace` 模式下，locale 会按 namespace 分文件写入，`index.*` 这类辅助文件会保留不删除。

## License

MIT

## 通过 `@composy/cli` 统一接入

<!-- ldesign-cli-integration:start -->

- 接入类型：`bin`
- 统一命令：`ldesign translator`
- 命令别名：无
- 包内原生 bin：`ldesign-translator`、`ltranslator`

当前包通过独立 bin 接入，统一命令会转发到包自身 CLI。

```bash
pnpm add -D @composy/cli
ldesign translator --help
ldesign tools run translator --help
```

<!-- ldesign-cli-integration:end -->