crowdin-cli

Crowdin CLI

Crowdin CLI 是用于管理和同步 Crowdin 项目本地化资源的命令行工具。它以单个独立二进制文件的形式提供，无需 Java 或其他运行时。

使用 crowdin --version 检查已安装的版本。如果输出 4.x 或 Java 错误，说明用户使用的是旧版 CLI——以下命令大多仍适用，但请参阅 references/migrating-from-v4.md 了解差异。

完整文档：https://crowdin.github.io/crowdin-cli

安装

npm install -g @crowdin/cli

也可通过 Homebrew（brew tap crowdin/crowdin && brew install crowdin@5）、WinGet、Chocolatey、Docker（crowdin/cli）、Linux 软件包仓库和独立二进制文件获取——所有选项请参阅 references/configuration.md。

身份验证

CLI 需要一个 API 令牌，并且（对于大多数命令）需要一个 项目 ID。在开发者的计算机上，最快的方式是：

crowdin login

它会通过浏览器进行授权，并将令牌保存到身份文件 ~/.crowdin.yml 中，之后每条命令（无论由用户还是 Agent 运行）都会读取该令牌。此过程不会生成或要求配置文件，Crowdin Enterprise 也无需额外设置：组织信息来自已登录的账户。crowdin init 会运行相同的浏览器授权流程，然后生成 crowdin.yml；如果配置是手动编写的或已经存在，则应选择 login。该流程会通过同一台计算机上的浏览器回调完成，因此，如果 Agent 的 shell 可能位于其他位置，用户应在自己的终端中运行此流程。浏览器签发的令牌会在 30 天后过期——如果命令以 101 退出，请重新运行 crowdin login。详情请参阅：references/commands.md。

对于 CI 和任何需要长期使用的场景，请使用个人访问令牌——它不会过期：

• crowdin.com：在 设置 → API 中创建令牌（https://crowdin.com/settings#api-key）。base_url 为 https://api.crowdin.com（默认值——无需设置）。
• Crowdin Enterprise：在 账户设置 → 访问令牌 中创建令牌。必须将 base_url 设置为 https://{organization}.api.crowdin.com。

项目 ID 为数字——配置令牌后，使用 crowdin project list 获取（如果尚无 crowdin.yml 携带 project_id，单独运行 project list 时需要指定 -i 1：验证要求提供该参数，即使此命令会忽略它），也可以在 Crowdin 的项目页面中找到。

凭据按以下优先级解析（优先级从高到低）：

1. CLI 标志：-T/--token、-i/--project-id、--base-url、--base-path
2. 身份文件：--identity <path>，或存在时使用 ~/.crowdin.yml / ~/.crowdin.yaml
3. 配置文件中的 *_env 键（api_token_env: MY_VAR 会读取 $MY_VAR）
4. 配置文件中的字面值键（api_token: "..."）
5. CROWDIN_PERSONAL_TOKEN、CROWDIN_PROJECT_ID、CROWDIN_BASE_PATH、CROWDIN_BASE_URL 环境变量

工作目录中的 .env 文件会自动加载，因此可以将 CROWDIN_PERSONAL_TOKEN 放在其中。如果文件已提交，切勿将真实令牌写入 crowdin.yml——请改用 api_token_env 或 CROWDIN_PERSONAL_TOKEN 变量。已提交的 api_token_env 与本地 crowdin login 可以共存：未设置的变量不会提供任何值，因此开发者计算机上的令牌由身份文件提供，CI 中的令牌则由变量提供。

配置 — crowdin.yml

命令会从当前目录读取 crowdin.yml（或 crowdin.yaml）；使用 -c/--config <path> 指定其他配置文件。一个精简的实际示例：

"project_id": "123456"
"api_token_env": "CROWDIN_PERSONAL_TOKEN"
"base_path": "."
"preserve_hierarchy": true

files:
  - source: "/src/locales/en/**/*.json"
    translation: "/src/locales/%two_letters_code%/**/%original_file_name%"

• source 是本地源文件的 glob 模式（相对于 base_path）；translation 指定导出翻译的存放位置，可使用 %two_letters_code%、%locale%、%original_file_name%、%original_path%、%file_name% 等占位符。
• preserve_hierarchy: true 会在 Crowdin 中保留本地目录结构；如果不设置，公共父目录会被剥除。
• 每个文件组对应一个 files 条目；每个条目还可添加 ignore、dest、type、update_option、labels、excluded_target_languages、languages_mapping 等配置。

完整参考包含所有占位符、每条目的选项、语言映射和多个文件组，详见 references/configuration.md。

首次上传前，请先验证配置，避免上传错误后再排查：

crowdin config lint            # validate syntax
crowdin config sources         # list local files matched by each source pattern
crowdin config translations    # list translation paths that will be produced
crowdin upload sources --dryrun

核心工作流

日常流程为：上传源文件 → 翻译 → 下载翻译。

crowdin upload sources           # push local source files (alias: crowdin push)
crowdin status                   # translation & proofreading progress per language
crowdin auto-translate --method tm   # optional: pre-fill via TM, MT, or AI
crowdin download translations    # pull completed translations (alias: crowdin pull)

常用变体：

crowdin upload sources --cache               # skip unchanged files (checksum cache)
crowdin upload sources --delete-obsolete     # remove files from Crowdin that no longer exist locally
crowdin upload translations                  # import existing local translations
crowdin download translations -l uk -l fr    # only some languages
crowdin download translations --skip-untranslated-strings
crowdin download sources                     # pull sources back from Crowdin

所有操作都支持分支：传入 -b <name>，即可将上传、下载和状态查询限定在 Crowdin 分支中（使用 crowdin branch add 创建分支）。

auto-translate（v4 中为 pre-translate）可应用 TM（--method tm）、机器翻译（--method mt --engine-id <id>）或 AI（--method ai --ai-prompt <id>；运行 crowdin ai-prompt list --action pre_translate --assigned 可列出提示词 ID），并提供精细控制：--scope untranslated|translated|all、--skip-approved-translations、--label/--exclude-label、--replace-translations-option、--translation-modified-before 等，详见 references/commands.md。该命令会等待任务完成；使用 --async 可立即返回任务标识符，之后可通过 crowdin auto-translate status <id> [--wait] 查询状态。

通过 Crowdin 应用集成

如果内容位于通过已安装 Crowdin 应用连接的 CMS、营销工具、帮助中心或其他平台中，同步需通过应用的 API 方法（crowdin app methods、crowdin app api）完成，而非使用 upload/download。在此命令行和 Crowdin 连接器中，这一流程称为 integration-sync 技能：首次调用 crowdin app api 前请先加载该技能。其中包含导入、任务和推送步骤，说明如何传递应用 ID，以及哪些调用可替代设置。

用于 AI 丰富化的字符串上下文

丰富项目字符串的上下文（下载、填写 ai_context、上传）属于 context-extraction 技能的工作流。crowdin context 命令和 JSONL 格式详见 references/context.md；其 --status 筛选条件并不表示“需要上下文”。

面向脚本和 Agent 的输出

全局 -o/--output 选项可更改任何命令的输出格式：

• -o json — 机器可读的 JSON；可通过管道传给 jq，或在脚本中解析
• -o toon — 面向 Token 的对象表示法，数据与 JSON 相同，但体积只有一小部分；当使用方是大模型时，优先使用此格式
• -o plain — 最简、可处理的文本（v4 的 --plain 标志）

在 json 和 toon 模式下，标准输出只包含数据，不含旋转指示器、颜色或装饰性消息，因此可以安全地解析。将 CLI 用作 Agent 时，对于只需读取的列表，默认使用 -o toon；需要脚本解析结果时，使用 -o json。

crowdin file list -o json | jq -r '.[].path'
crowdin status -o toon

退出代码稳定且含义明确——应根据退出代码进行分支判断，而不是解析错误文本：

代码	含义
0	成功
1	一般错误
2	验证错误（配置或参数无效）
101	授权错误（令牌无效或已过期）
102	未找到
103	禁止访问
129	超出速率限制

修改文件的命令接受 --dryrun，用于预览将执行的操作。诊断问题时添加 -v/--verbose；在 CI 中使用 --no-progress/--no-colors 可清理日志（json/toon 模式已隐含启用这些选项）。

命令一览

共有 24 个顶级命令；大多数命令都有子命令。完整的选项级参考请参阅：references/commands.md。

命令	用途
upload (push)	根据 crowdin.yml 上传源文件 / 翻译
download (pull)	根据 crowdin.yml 下载翻译 / 源文件
init	交互式生成 crowdin.yml
login	在浏览器中授权，并将令牌保存到 ~/.crowdin.yml
status	翻译和校对进度
auto-translate	通过 TM / MT / AI 预填翻译（status、list）
file	不使用配置模式直接操作文件（list、upload、download、delete）
string	管理源字符串（list、add、edit、delete；CroQL 筛选器）
branch	管理分支（add、list、clone、merge、edit、delete）
task	创建和列出翻译 / 校对任务
tm	翻译记忆库（list、upload、download；list --assigned 将范围限定为当前项目）
glossary	术语库（list、upload、download；list --assigned 将范围限定为当前项目）
style-guide	样式指南（list、download、upload、delete）
ai-prompt	AI 提示词（list；--action pre_translate --assigned 可查找 auto-translate --method ai 所需的 ID）
bundle	导出包（list、add、download、clone、browse）
distribution	内容分发（add、list、edit、release）
screenshot	用于提供上下文的屏幕截图（list、上传文件或目录、delete）
comment	字符串评论和问题（list、add、resolve）
label	标签（list、add、delete）
language	列出项目语言 / 支持的语言；--verbose 会额外显示文本方向和复数类别
project	列出、添加和浏览项目
config	验证配置，预览匹配的源文件 / 翻译
app	已安装的应用：列出、安装、卸载并调用其 API 方法（导入、推送和作业循环对应 integration-sync）
context	字符串的 AI 上下文：下载、上传、覆盖状态、重置——参见 references/context.md

Shell 补全：source <(crowdin complete zsh)（也支持 bash、fish、powershell）。

CI/CD

• 将令牌存储为 CI 密钥，并以 CROWDIN_PERSONAL_TOKEN 的形式提供；将 project_id 保留在已提交的 crowdin.yml 中（它不属于敏感信息）。
• 典型的流水线：合并到主分支时运行 crowdin upload sources；按计划运行 crowdin download translations 或在发布前运行，然后提交更新后的文件或创建 PR。
• 对于 GitHub Actions，优先使用官方的 crowdin/github-action，它封装了此 CLI — 详见 github-action 技能。
• 提供所有必需值时，CLI 不会提示输入；缺少值时会以退出代码 2 失败，而不会卡住。
• crowdin status --fail-if-incomplete 会在项目未完成全部翻译时以非零状态退出 — 可直接用作发布门禁。

相关技能

• context-extraction — 编写 crowdin context upload 会发送的 ai_context 值
• croql — 用于字符串命令 --croql 筛选器的 CroQL 表达式
• crowdin-api-client — CLI 命令无法满足需求时使用的 JS/TS API 客户端
• translate — 使用项目的术语表、TM 和风格指南，将翻译草稿写入本地资源文件，并将其作为建议上传