Transdocs CLI

一个用于同步和管理多个文档仓库的命令行工具，支持自动化文档处理、AI翻译、邮件通知和GitHub集成等功能。

功能特性

• 克隆或更新多个文档仓库
• 支持指定分支和浅克隆以提高效率
• 自动清理 .github 目录
• 邮件推送通知功能
• 文件替换功能（根据文件是否被修改选择性替换）
• 文件过滤功能（通过 includes 和 excludes 模式匹配文件）
• AI文档翻译（支持通义千问等大语言模型）
• GitHub仓库管理（创建仓库、管理secrets和variables）
• 自动推送至个人仓库
• 公共资源目录自动分发

快速开始

安装

# 使用 npm 安装
npm install -g transdocs-cli

# 或使用 pnpm 安装
pnpm install -g transdocs-cli

基本使用

1. 创建配置文件 transdocsconfig.json：

{
  "repositories": [
    {
      "url": "https://github.com/user/repo1.git",
      "branch": "main"
    },
    {
      "url": "https://github.com/user/repo2.git"
    }
  ]
}

2. 运行命令：

transdocs ./transdocsconfig.json

配置说明

基本配置

{
  "repositories": [
    {
      "url": "仓库地址（支持 HTTPS 和 SSH 格式）",
      "branch": "分支名（可选，默认为默认分支）"
    }
  ]
}

字段说明：

• repositories: 要克隆的仓库列表
  • url: 仓库地址
  • branch: 要克隆的分支（可选）

LLM 翻译配置

Transdocs 支持使用大语言模型（LLM）自动翻译文档。目前支持通义千问（Qwen）系列模型。

{
  "ai": {
    "apiKey": "your-alibaba-api-key",
    "model": "qwen-plus"
  }
}

LLM 配置字段说明：

• ai: LLM 翻译配置（可选）
  • apiKey: 阿里云 API 密钥
  • model: 使用的模型名称（可选，默认为 qwen-plus）

当配置了 LLM 功能时，Transdocs 会自动翻译 includes 中匹配的文件，并将翻译结果保存在 .transdocs-translated 目录中。

文件替换配置

Transdocs 支持在克隆或更新仓库后，根据文件是否被修改来选择性替换文件。

{
  "repositories": [
    {
      "url": "https://github.com/user/repo1.git",
      "branch": "main",
      "fileReplacements": [
        {
          "targetFile": "README.md"
        }
      ]
    }
  ]
}

文件替换字段说明：

• fileReplacements: 文件替换规则列表（可选）
  • targetFile: 仓库中的目标文件路径（相对于仓库根目录）

程序会自动从 .transdocs-templates 目录中查找对应的标准文件和替换文件：

• 标准文件路径：.transdocs-templates/{仓库名}/standard/{targetFile}
• 替换文件路径：.transdocs-templates/{仓库名}/replacement/{targetFile}

例如，对于上述配置：

• 标准文件路径：.transdocs-templates/repo1/standard/README.md
• 替换文件路径：.transdocs-templates/repo1/replacement/README.md

工作原理：

1. 克隆或更新仓库后，检查目标文件是否与标准文件内容一致
2. 如果一致（未被修改），则使用替换文件覆盖目标文件
3. 如果不一致（已被修改），则跳过替换操作

目录结构示例：

项目目录/
├── transdocsconfig.json
├── .transdocs-templates/
│   ├── repo1/
│   │   ├── standard/
│   │   │   └── README.md
│   │   └── replacement/
│   │       └── README.md
│   └── repo2/
│       ├── standard/
│       │   └── docs/
│       │       └── config.md
│       └── replacement/
│           └── docs/
│               └── config.md
└── .transdocs-repos/
    ├── repo1/
    └── repo2/

这种方式的优势：

• 未修改的文件会被更新为你的自定义版本
• 已修改的文件会保留用户的更改
• 避免无差别覆盖用户的重要修改
• 无需在配置文件中显式指定标准文件和替换文件路径

文件过滤配置

Transdocs 支持在克隆或更新仓库后，根据指定的模式匹配文件。这在需要处理特定文件时非常有用。

{
  "repositories": [
    {
      "url": "https://github.com/user/repo2.git",
      "includes": [
        "*.md",
        "docs/**/*.md"
      ],
      "excludes": [
        "node_modules/**",
        "**/dist/**",
        "**/*.min.js"
      ]
    }
  ]
}

文件过滤字段说明：

• includes: 包含的文件模式列表（可选）
• excludes: 排除的文件模式列表（可选）

工作原理：

1. 克隆或更新仓库后，根据 includes 模式查找匹配的文件
2. 从匹配结果中排除符合 excludes 模式的文件
3. 输出最终匹配的文件列表

模式匹配使用 minimatch 库实现，支持常见的 glob 模式：

• * 匹配任意数量的字符，但不包括 /
• ** 匹配任意数量的字符，包括 /
• ? 匹配单个字符
• [abc] 匹配括号中的任意字符
• [a-z] 匹配范围内的任意字符

例如：

• *.md 匹配根目录下所有 .md 文件
• docs/**/*.md 匹配 docs 目录及其子目录下的所有 .md 文件
• node_modules/** 排除 node_modules 目录下的所有文件

邮件推送配置

当配置了邮件推送功能且 enabled 设置为 true 时，transdocs 会在同步操作完成后自动发送报告邮件。

Gmail 配置示例

{
  "email": {
    "enabled": true,
    "service": "gmail",
    "auth": {
      "user": "[email protected]",
      "pass": "your-app-password"
    },
    "to": "[email protected]"
  }
}

阿里云企业邮箱配置示例

{
  "email": {
    "enabled": true,
    "host": "smtp.qiye.aliyun.com",
    "port": 465,
    "secure": true,
    "auth": {
      "user": "[email protected]",
      "pass": "xxxxx"
    },
    "to": "[email protected]"
  }
}

邮件配置字段说明：

• email: 邮件推送配置
  • enabled: 是否启用邮件推送功能
  • service: 邮件服务商（如 gmail、outlook 等）
  • host/port/secure: SMTP 服务器配置（可替代 service）
  • auth: 认证信息
    • user: 发件人邮箱地址
    • pass: 邮箱密码或应用专用密码
  • to: 收件人邮箱地址（支持字符串或字符串数组）

支持的邮件服务包括 Gmail、Outlook 等主流邮件服务，也可以通过 host/port 自定义邮件服务器。

GitHub 集成配置

Transdocs 支持与 GitHub 集成，可以自动创建仓库、管理 secrets 和 variables。

{
  "github": {
    "token": "your-github-token"
  }
}

GitHub 配置字段说明：

• github: GitHub 集成配置
  • token: GitHub 个人访问令牌

配置后，Transdocs 可以：

• 自动创建仓库
• 管理仓库 secrets（加密存储）
• 管理仓库 variables

个人仓库推送配置

Transdocs 支持将处理后的仓库推送到您自己的 GitHub 仓库中，并可选择配置 secrets 和 variables。

{
  "repositories": [
    {
      "url": "https://github.com/user/repo1.git",
      "personalUrl": "https://github.com/myuser/myrepo1.git",
      "branch": "main",
      "secrets": [
        {
          "name": "DEPLOY_KEY",
          "value": "my-secret-deploy-key"
        },
        {
          "name": "API_TOKEN",
          "value": "my-api-token"
        }
      ],
      "variables": [
        {
          "name": "BUILD_TARGET",
          "value": "production"
        },
        {
          "name": "NODE_VERSION",
          "value": "18"
        }
      ]
    }
  ],
  "github": {
    "token": "your-github-token"
  }
}

个人仓库推送字段说明：

• personalUrl: 必填，您自己的仓库地址
• secrets: 可选，需要设置的 secrets 列表，每个 secret 包含 name 和 value
• variables: 可选，需要设置的 variables 列表，每个 variable 包含 name 和 value

工作原理：

1. 克隆或更新源仓库并完成所有处理操作后
2. 将处理后的代码推送到您指定的 personalUrl 仓库
3. 如果配置了 secrets 或 variables，且提供了 GitHub token，则自动设置这些 secrets 和 variables

公共资源目录配置

Transdocs 支持将配置文件同级目录下的 public 目录自动复制到所有处理的仓库中。

目录结构示例：

项目目录/
├── transdocsconfig.json
├── public/
│   ├── assets/
│   │   └── logo.png
│   ├── common/
│   │   └── style.css
│   └── README.md
├── .transdocs-templates/
└── .transdocs-repos/

使用方法：

1. 在与配置文件同级的目录下创建 public 目录
2. 将需要分发到所有仓库的公共文件放入该目录
3. 运行 transdocs 命令

工作原理：

1. 在克隆或更新每个仓库后
2. 自动将 public 目录完整复制到每个仓库的根目录
3. 如果目标仓库中已存在同名文件或目录，将被覆盖

这种方式的优势：

• 统一管理所有仓库共享的资源文件
• 一次配置，所有仓库自动拥有公共资源
• 便于维护和更新共享文件

使用方法

在需要翻译文档的项目目录中运行 transdocs 命令：

transdocs

默认情况下，程序会：

1. 在当前目录查找 transdocsconfig.json 配置文件
2. 在当前目录查找 .env 环境变量文件
3. 根据配置文件内容进行文档翻译

命令行选项

• -t, --target <language> - 指定目标语言（默认为中文 'zh'）

示例：

# 翻译为英文
transdocs -t en

# 翻译为日文
transdocs -t ja

技术细节

• 使用浅克隆（--depth=1）只获取最新的提交，提高克隆速度
• 克隆完成后自动删除 .github 目录
• 更新时使用强制重置方式以远程仓库为准
• 当出现更新错误时，自动删除本地仓库并重新克隆

开发相关

构建项目

# 安装依赖
pnpm install

# 构建项目
pnpm build

开发模式

# 监听模式构建
pnpm dev