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 等排障实录。

AccentAccent翻译管理Elixir2026/10/27

Accent v1.32.1 常用 CLI 命令详解

目标:把 accent-cli 真正用起来——配置怎么写、8 个命令各自做什么、哪些参数能卡住 CI、失败了看什么回显。全文以 accent-cli 0.19.0 对接 Accent v1.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"
    }
  ]
}

字段说明:

字段说明
apiUrlAccent 实例根地址,不带 /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_URLapiUrl
ACCENT_API_KEYapiKey
ACCENT_PROJECTproject

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 XMLANDROID_XMLxml
CSVCSVcsv
ES6 moduleES6_MODULEjs
GettextGETTEXTpo
Java propertiesJAVA_PROPERTIESproperties
Java properties XMLJAVA_PROPERTIES_XMLxml
JSONJSONjson
Simple JSONSIMPLE_JSONjson
Simple PHPSIMPLE_PHPphp
Apple .stringsSTRINGSstrings
Laravel PHPLARAVEL_PHPphp
Go I18n JSONGO_I18N_JSONjson
XLIFF 1.2XLIFF_1_2xlf
Resx 2.0RESX_2_0resx
Rails YAMLRAILS_YMLyml

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
  1. 读取配置并校验 Token(ci-token ✓ 是 Token 名称,便于确认用错没);
  2. 把 source 匹配到的源文件推送到 Accent(↑);
  3. 导出所有目标语言文件(↓);
  4. 默认写回本地磁盘。

注意第 4 步:0.19.0 默认就覆盖本地文件。不想让 CLI 改工作区,必须显式加 --no-local-write。官方帮助里对它的警告原文是「可能导致代码仓库与服务端不一致」。

4.2 关键参数

参数默认作用
--dry-run关只在本地算出结果,不提交到服务端;会照常打印将发生的变更
--no-local-write关不写本地文件
--sync-typesmart源语言同步算法:smart 智能匹配、passive 只增不删
--merge-typepassive合并已有译文时的算法:smart/passive/force
--add-translations关把本地已有的译文一并推上去,适合首次接入存量项目
--order-byindex导出时的 key 排序:index 保持服务端顺序,key 按字母序
--version无针对某个已存在的版本标签同步
--path.切换工作目录,配置与文件都以此为准
-caccent.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

三点实操建议:

  1. Token 用 bot 角色。API Token 的角色决定权限,bot 只有只读 + sync/merge,即使泄露也改不了译文(角色矩阵见《Accent v1.32.1 配置参数详解》第八节)。
  2. PR 流水线只跑 lint,不要跑 sync。sync 会写服务端,多人同时触发会产生无意义的操作记录;同步交给定时任务。
  3. 门禁命令: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
建项目、加成员、改角色、发 TokenWeb UI 或 GraphQL
批量改译文状态、自动化评审GraphQL
统计报表、门禁CLI stats + GraphQL

CLI 本质是 GraphQL API 的一层薄封装,遇到 CLI 不覆盖的能力,直接用项目 Token 调 /graphql 即可,二者共用同一套权限模型。

十二、参考链接