Accent v1.32.1 常用 CLI 命令详解
accent-cli 0.19.0 对接 Accent v1.32.1 的实战手册:accent.json 配置与 ACCENT_* 覆盖变量、sync/export/format/lint/stats/jipt/version 八个命令参数与退出码、15 种文档格式、CI 门禁与 GitHub Actions 模板,含 Token 失效、JIPT 误报 lint 等排障实录。
Accent v1.32.1 常用 CLI 命令详解
目标:把
accent-cli真正用起来——配置怎么写、8 个命令各自做什么、哪些参数能卡住 CI、失败了看什么回显。全文以accent-cli 0.19.0对接 Accentv1.32.1实测,命令输出与退出码照抄。
一、CLI 是什么、不是什么
accent-cli 是 Accent 官方的 Node.js 命令行工具(npm 包名 accent-cli),定位是在代码仓库与 Accent 之间搬运翻译文件:
- 把仓库里的源语言文件推送到 Accent(
sync); - 把 Accent 里译好的文件拉回仓库(
export/sync的本地写入阶段); - 在本地做占位符与格式校验(
lint/format),不依赖服务端; - 输出伪语言文件做「译前预览」(
jipt); - 查看项目翻译进度(
stats)。
它不是管理工具:建项目、加成员、改项目设置、管 API Token 都没有对应命令,要走 Web UI 或 GraphQL(服务端 v1.32.1 的 GraphQL 端点在 /graphql,与 Web 同端口)。
版本要留意:网上大量文章引用的是 0.6.0 的 README,只有 5 个命令(export/help/jipt/stats/sync),且 sync 需要 --write 才写本地文件。0.19.0 扩到 8 个命令,--write 已被 --no-local-write 取代(默认就写)。本文以实际安装到的版本为准。
安装与确认版本:
npm install -g accent-cli
accent --version
# 回显:accent-cli/0.19.0 linux-x64 node-v24.22.1
二、accent.json:唯一配置文件
CLI 从运行时目录读取 accent.json(可用 -c 指定其他路径)。最小可用配置:
{
"apiUrl": "http://10.0.0.10:4000",
"apiKey": "0hForCTne4XyMqKI6OkuN2LDku5H3Pryy5fL65zwFdupODQdh1nBaqeVJSgld68RrMF40zBg_5rtTAb1T7kK1nVeKofisw",
"files": [
{
"language": "en",
"format": "json",
"source": "localization/en/*.json",
"target": "localization/%slug%/%document_path%.json"
}
]
}
字段说明:
| 字段 | 说明 |
|---|---|
apiUrl | Accent 实例根地址,不带 /graphql |
apiKey | 项目 API Token(Web UI「项目设置 → API Tokens」生成) |
project | 项目 UUID,可省略(Token 已绑定项目) |
version.branchVersionPrefix | 从 Git 分支名提取版本号,如 release/ → 分支 release/v1.0.0 等价于 --version=1.0.0 |
files[].language | 源文件的基准语言代码 |
files[].format | 文档格式 slug,如 json、yaml、po;非法值会在推送阶段报错 |
files[].source | 源文件路径,支持 glob |
files[].target | 回写路径模板,支持占位符 |
files[].namePattern | 文档在 Accent 里的命名方式 |
files[].hooks | 四个钩子:beforeSync、afterSync、beforeExport、afterExport,0.19.0 为字符串数组 |
2.1 三个环境变量可以覆盖配置
与服务端不同(服务端不读任何 ACCENT_* 变量,见《Accent v1.32.1 配置参数详解》),CLI 确实支持三个 ACCENT_* 变量,且优先级高于 accent.json:
| 变量 | 覆盖字段 |
|---|---|
ACCENT_API_URL | apiUrl |
ACCENT_API_KEY | apiKey |
ACCENT_PROJECT | project |
CI 里因此可以把 accent.json 提交进仓库,只把 Token 放 Secrets:
env:
ACCENT_API_KEY: ${{ secrets.ACCENT_API_KEY }}
2.2 路径模板与命名
target 的占位符:
| 占位符 | 含义 |
|---|---|
%slug% | 目标语言代码,如 fr、zh-CN |
%document_path% | 文档在 Accent 中的相对路径(不含扩展名) |
%original_file_name% | 源文件名(不含扩展名) |
namePattern 取值(官方文档,未逐一实测):
| 值 | 文档名来源 |
|---|---|
file(默认) | 源文件名 |
fileWithSlugSuffix | 去掉语言后缀的文件名,如 Localizable.en.strings → Localizable |
parentDirectory | 用所在目录名,适合「目录即语言」的项目 |
fileWithParentDirectory | 相对路径 + 文件名,以 %slug% 在 target 中的位置为根 |
2.3 支持的文档格式
v1.32.1 服务端 GraphQL 查询 documentFormats 的完整回显(15 种):
curl -s -X POST http://localhost:8128/graphql \
-H "Authorization: Bearer <API_TOKEN>" -H 'Content-Type: application/json' \
-d '{"query":"{ documentFormats { name slug extension } }"}'
| 名称 | slug | 扩展名 |
|---|---|---|
| Android XML | ANDROID_XML | xml |
| CSV | CSV | csv |
| ES6 module | ES6_MODULE | js |
| Gettext | GETTEXT | po |
| Java properties | JAVA_PROPERTIES | properties |
| Java properties XML | JAVA_PROPERTIES_XML | xml |
| JSON | JSON | json |
| Simple JSON | SIMPLE_JSON | json |
| Simple PHP | SIMPLE_PHP | php |
| Apple .strings | STRINGS | strings |
| Laravel PHP | LARAVEL_PHP | php |
| Go I18n JSON | GO_I18N_JSON | json |
| XLIFF 1.2 | XLIFF_1_2 | xlf |
| Resx 2.0 | RESX_2_0 | resx |
| Rails YAML | RAILS_YML | yml |
accent.json 里的 format 写 slug 的小写形式(json、yaml、po…),写错在 sync 时才会暴露。
三、命令总览
accent --help
# 回显:
# COMMANDS
# export Export files from Accent and write them to your local filesystem
# format Format local files from server. Exit code is 1 if there are errors.
# help Display help for accent.
# jipt Export jipt files from Accent and write them to your local filesystem
# lint Lint local files and display errors if any. Exit code is 1 if there are errors.
# stats Fetch stats from the API and display them beautifully
# sync Sync files in Accent and write them to your local filesystem
# version
| 命令 | 读服务端 | 写服务端 | 写本地 | 适合场景 |
|---|---|---|---|---|
sync | ✔ | ✔ | ✔ | 日常主流程:推源文、拉译文 |
export | ✔ | ✘ | ✔ | 只拉取,不动服务端 |
lint | ✔(取基准串) | ✘ | ✘ | CI 校验占位符 |
format | ✔(取顺序) | ✘ | ✔ | 统一 key 顺序 |
stats | ✔ | ✘ | ✘ | 进度看板 / 发布门禁 |
jipt | ✔ | ✘ | ✔ | 伪语言预览 |
version | ✘ | ✘ | ✘ | 排查版本 |
四、accent sync:核心命令
4.1 它做了四件事
一次 sync 的实际流程(实测日志顺序):
accent sync
# 回显:
# Fetch config in accent.json... ci-token ✓
#
# Syncing sources → en ✓
#
# ↑ localization/en/app.json app
#
# Writing files locally
#
# ↓ localization/en/app.json app → en
# ↓ localization/fr/app.json app → fr
- 读取配置并校验 Token(
ci-token ✓是 Token 名称,便于确认用错没); - 把
source匹配到的源文件推送到 Accent(↑); - 导出所有目标语言文件(
↓); - 默认写回本地磁盘。
注意第 4 步:0.19.0 默认就覆盖本地文件。不想让 CLI 改工作区,必须显式加 --no-local-write。官方帮助里对它的警告原文是「可能导致代码仓库与服务端不一致」。
4.2 关键参数
| 参数 | 默认 | 作用 |
|---|---|---|
--dry-run | 关 | 只在本地算出结果,不提交到服务端;会照常打印将发生的变更 |
--no-local-write | 关 | 不写本地文件 |
--sync-type | smart | 源语言同步算法:smart 智能匹配、passive 只增不删 |
--merge-type | passive | 合并已有译文时的算法:smart/passive/force |
--add-translations | 关 | 把本地已有的译文一并推上去,适合首次接入存量项目 |
--order-by | index | 导出时的 key 排序:index 保持服务端顺序,key 按字母序 |
--version | 无 | 针对某个已存在的版本标签同步 |
--path | . | 切换工作目录,配置与文件都以此为准 |
-c | accent.json | 指定配置文件 |
⚠️ 注意
--merge-type的默认值:0.6.0 时代的 README 写的是smart,0.19.0 的--help回显是passive。以实际命令回显为准,别照抄旧文档。
4.3 先演练再提交
accent sync --dry-run
# 回显:
# Fetch config in accent.json... ci-token ✓
#
# Syncing sources → en ✓
#
# localization/en/app.json app
# ~~ No changes for this file ~~
#
# Syncing took 29 milliseconds, remove --dry-run to commit your changes to the server
~~ No changes for this file ~~ 说明该文件与服务端一致;有差异时会列出新增/修改的 key 数。确认无误后去掉 --dry-run 再跑一次,耗时 66ms(小项目)。
4.4 版本标签同步
--version 要求该标签在 Accent 里已存在(由 Web UI 或 createVersion GraphQL 创建),CLI 不会替你建。配了 version.branchVersionPrefix 后,分支名自动映射,CI 里就不用每次传参。
五、accent export 与 accent format
5.1 export
accent export
# 回显:
# Writing files locally
#
# ↓ localization/en/app.json app → en
# ↓ localization/fr/app.json app → fr
#
# Exporting took 23 milliseconds, completed without issues
参数只有 --order-by index|key、--version、-c。它和服务端零写入,适合「只读拉取」的流水线,或本地误删文件后的恢复。
5.2 format
accent format
# 回显:
# Formatting files (2)
#
# localization/en/app.json
# localization/fr/app.json
#
# Formatting took 23 milliseconds
format 以服务端的 key 顺序为基准重排本地文件,支持 index、key、-index、-key(负号表示倒序)。实测把两份文件都重排了一遍,内容语义不变、退出码 0。
💡 用途:多人协作时 JSON 的 key 顺序经常被编辑器打乱,形成大量无意义 diff。把
accent format挂在提交前钩子,可以让 diff 只反映翻译变化。
六、accent lint:CI 门禁的主力
accent lint
# 回显:
# Fetch config in accent.json... ci-token ✓
#
# Lint errors (1)
#
# cart.items_count localization/fr/app.json
# Number of placeholders does not match the master string
# {^cart.items_count@app}
#
# Please report incorrect results: https://github.com/mirego/accent/issues
# Linting took 28 milliseconds, found 1 linting errors.
退出码(实测):
| 场景 | 退出码 |
|---|---|
| 无问题 | 0 |
| 有问题 | 1 |
校验项以基准语言为参照,实测能抓到:
- 占位符数量/名称不一致(
%{count}vs%{counts}); - 译文尾部多余空格;
- 空译文。
lint 只读不写,是流水线里最安全的检查点:
accent lint || exit 1
⚠️ 上面那条报错值得单独说明:它来自 JIPT 伪语言文件。
{^cart.items_count@app}是给「译前预览」用的占位符,本身不含%{count},lint会把它当成占位符缺失。伪语言文件不要参与 lint,应放在独立目录并从accent.json的files中排除(或用独立的-c配置)。
七、accent stats:进度与发布门禁
accent stats
# 回显:
# Fetch config in accent.json... ci-token ✓
#
# ^ demo-app • 10% reviewed
# ⎯
# Last synced
# 2026-10-27T09:17:57Z
#
# Git branch
# master
#
# Main language
# English – en
#
# Translations (1)
# French – fr • 20% reviewed
#
# Documents (1)
# app localization/en/app.json
#
# Strings (10)
# ✓ Reviewed: 1
# × In review: 9
# ✎ Translated: 10
#
# Owners (1)
# admin@example.com
#
# Project URL: http://localhost:8128/app/projects/860b897b-605b-432a-917c-94129f05d917
默认只展示,退出码 0。加检查开关后才具备门禁能力:
accent stats --check-reviewed
# 回显末行:
# › Error: Project has 9 strings to be reviewed
# 退出码:1
accent stats --check-translated # 译文未到 100% 时退出 1
发布前只想放行「已评审」的内容,用 --check-reviewed;只想确认没有漏译,用 --check-translated。两个开关可同时加。
八、accent jipt:伪语言与译前预览
accent jipt jipt
# 回显:
# Fetch config in accent.json... ci-token ✓
#
# Writing files locally
#
# ↓ localization/jipt/app.json app → jipt
#
# Exporting took 8 milliseconds, completed without issues
参数 PSEUDOLANGUAGENAME 是伪语言的名称,导出后每个词条变成 {^key@app} 形式,用于在真实界面里检查「哪些文案会超长、哪些没被翻译系统覆盖」。
实测生成的文件:
{
"cart": { "items_count": "{^cart.items_count@app}" },
"nav": { "home": "{^nav.home@app}", "settings": "{^nav.settings@app}" },
"welcome": { "subtitle": "{^welcome.subtitle@app}", "title": "{^welcome.title@app}" }
}
⚠️ 伪语言文件不要提交到主分支,也不要进入 lint(见第六节)。建议加进
.gitignore,它是一次性验证产物。
九、CI 集成:把门禁放到流水线
官方 README 给的 GitHub Actions 模板(每天同步并开 PR):
name: Accent
on:
schedule:
- cron: "0 4 * * *"
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 16
- run: npm install -g accent-cli
- run: accent sync --add-translations --merge-type=passive --order-by=key
env:
ACCENT_API_KEY: ${{ secrets.ACCENT_API_KEY }}
- uses: mirego/create-pull-request@v5
with:
add-paths: "*.json"
commit-message: Update translations
branch: accent
title: New translations are available to merge
三点实操建议:
- Token 用
bot角色。API Token 的角色决定权限,bot只有只读 + sync/merge,即使泄露也改不了译文(角色矩阵见《Accent v1.32.1 配置参数详解》第八节)。 - PR 流水线只跑
lint,不要跑sync。sync会写服务端,多人同时触发会产生无意义的操作记录;同步交给定时任务。 - 门禁命令:
accent lint && accent stats --check-reviewed,任一失败即阻断合并。
没装 Node 的环境可直接用 npm 执行:
npx accent-cli@0.19.0 lint
⚠️ 注意 Node 版本:CLI 0.19.0 实测在 Node 24 正常;官方模板还停留在 Node 16。Node 16 已 EOL,建议直接用 20/22/24。
十、排障实录
Q1:Token 写错,报什么?
accent stats
# 退出码:1
# 回显:
# Fetch config in accent.json... !
# › Error: Can’t fetch the project on http://localhost:8128 with key
# › invalid_token_for_test
先核对 apiUrl 是否可达(curl -s -o /dev/null -w '%{http_code}' <apiUrl>/),再确认 Token 未被吊销、且属于目标项目。回显会把 key 原样打出来,在共享终端里注意脱敏。
Q2:--version 报错找不到版本?
该标签必须先存在于 Accent。用 Web UI 的版本页创建,或调 createVersion GraphQL;CLI 没有创建版本的命令。
Q3:sync 之后本地文件被改得面目全非?
默认写本地是 0.19.0 的行为。CI 或只读检查场景加 --no-local-write;本地想先看效果用 --dry-run。
Q4:lint 明明没问题却退出 1?
检查是否把 JIPT 伪语言目录也纳入了 files。伪语言占位符与真实占位符天然不匹配,实测必报 Number of placeholders does not match the master string。
Q5:export 报路径不存在?
target 的父目录不会自动创建全部层级时,先确认 %slug%、%document_path% 展开后与仓库实际目录一致;namePattern 选错也会导致文档名与预期不符。
Q6:钩子没执行?
hooks 在 0.19.0 是字符串数组,写成单个字符串会被忽略。钩子失败会中断当前阶段,建议先手动执行一遍命令确认退出码为 0。
十一、CLI 与 API 怎么分工
| 需求 | 用什么 |
|---|---|
| 推/拉翻译文件、CI 校验 | CLI |
| 建项目、加成员、改角色、发 Token | Web UI 或 GraphQL |
| 批量改译文状态、自动化评审 | GraphQL |
| 统计报表、门禁 | CLI stats + GraphQL |
CLI 本质是 GraphQL API 的一层薄封装,遇到 CLI 不覆盖的能力,直接用项目 Token 调 /graphql 即可,二者共用同一套权限模型。
十二、参考链接
- accent-cli npm:https://www.npmjs.com/package/accent-cli
- accent-cli 源码(v0.19.0):https://github.com/mirego/accent-cli
- Accent 源码(v1.32.1):https://github.com/mirego/accent/tree/v1.32.1
- Accent v1.32.1 介绍与选型指南:https://www.quzuo.net/document/Yj7L8j9xMed0
- Ubuntu 22.04 安装 Accent v1.32.1 指南:https://www.quzuo.net/document/4iSCcNNGGCAR
- Accent v1.32.1 配置参数详解:https://www.quzuo.net/document/S0izn9c6tTTG