CLI

Preview

@verbumia/cli

A small, scriptable CLI for everything you'd otherwise click through the dashboard: bootstrap a project, push and pull translations, gate CI on remote drift, peek at the missing-key queue. MIT-licensed, distributed via npm and Homebrew.

Preview · CLI 仍在开发中。命令与配置在 1.0 之前可能调整 — 见本页底部已知的即将变化。9 个命令及其参数已为 V1 确认;wire 格式可能仍会演进。

Install

Requires Node 20 LTS or newer. Two binaries get installed: verbumia and the shorter alias vrb — interchangeable.

终端 Tap 在 V1 发布

1# 全局安装一次 — bin "verbumia" 加上更短别名 "vrb"2npm i -g @verbumia/cli 4# 或者无需安装直接使用5npx @verbumia/cli@latest <command> 7# Homebrew tap 在 V1 上线时发布8brew install verbumia/tap/verbumia-cli

认证

在 dashboard 的 Org Settings → API Keys → Create 取一把 API key(secret 只显示一次,请复制完整 vrb_live_<prefix>.<secret>)。给 status / pull / missing / projects 用 project:read scope,给 push 用 project:write。

交互式

1verbumia login2? 粘贴来自 Org Settings → API Keys 的 API key(输入已遮蔽):3vrb_live_••••••••••••••••.•••••••••••••••••••••4✓ 通过 GET /v1/auth/me 已验证 — marc@example.com (org: acme)。5✓ 已保存到 ~/.verbumia/credentials (chmod 600)。

CI / 非交互

1# CI / 非交互 — env 变量优先于文件,但不及 --token2export VERBUMIA_TOKEN=vrb_live_<prefix>.<secret>3verbumia push

来源优先级:--token flag → VERBUMIA_TOKEN env → ~/.verbumia/credentials。credentials 文件是形如 {"default":"<token>","<host>":"<token>"} 的 JSON,这样你可以在同一台机器上为 prod / staging / 自托管实例保留各自的 key。

配置你的项目

在 repo 中运行 verbumia init,会在根目录生成 verbumia.config.json,也可以手写。CLI 还会自动检测 verbumia.config.{ts,js,toml,yml}(如果你偏好这些格式)。

verbumia.config.json

1// verbumia.config.json — 在项目根目录2// 同样自动检测:verbumia.config.{ts,js,toml,yml}3{4  "project_uuid": "<project_uuid>",5  "source_language": "en",6  "locales": ["en", "fr-CA", "es", "ja"],7  "namespaces": ["common", "checkout"],8  "format": "json-i18next",9  "push": {10    "source_dir": "./src/locales",11    "file_pattern": "{locale}/{namespace}.json",12    "on_missing_namespace": "create"13  },14  "pull": {15    "dest_dir": "./src/locales",16    "file_pattern": "{locale}/{namespace}.json",17    "format": "json-i18next"18  },19  "missing_handler": {20    "endpoint": "https://api.verbumia.ca/v1/missing",21    "enabled_for_envs": ["dev", "staging"]22  }23}

字段参考

字段	类型	默认 / 备注
project_uuid	string	— required
source_language	string	"en"
locales	string[] \| null	null = all
namespaces	string[] \| null	null = all
format	string	"json-i18next" \| "xliff" \| "json-flat"
push.source_dir	string	"./src/locales"
push.file_pattern	string	"{locale}/{namespace}.json"
push.on_missing_namespace	"create" \| "error"	"create"
pull.*	object	mirrors push.* (read path)
missing_handler	object	{ endpoint, enabled_for_envs }

命令

每个命令都接受 --config <path> 指向非默认配置文件、--token <vrb_live_…> 覆盖已解析的 auth、以及 --json 输出机器可读结果。

verbumia init 在当前目录生成 verbumia.config.json,通过交互式问询设置 project_uuid、源语言与格式。

Flags

--project <uuid> 预填 project_uuid
--source-language <code> BCP-47(默认 "en")
--format <fmt> json | xliff

示例

verbumia init --project <uuid>

verbumia login 交互式输入 API key。CLI 通过 GET /v1/auth/me 校验,然后以 mode 600 写入 ~/.verbumia/credentials。

Flags

--token <vrb_live_…> 内联传入 key(跳过提示;适合脚本)

示例

verbumia login

verbumia logout 清除 ~/.verbumia/credentials。不会在服务端撤销 key — 那需要在 dashboard 里操作。

Flags

无命令特定 flag。请使用上面描述的全局 flag。

示例

verbumia logout

verbumia whoami 打印当前 key 的 org、项目绑定与已授予的 scope。快速排查“账号不对”这类意外。

Flags

无命令特定 flag。请使用上面描述的全局 flag。

示例

verbumia whoami

verbumia projects 列出当前 key 可访问的项目。

Flags

--json 机器可读输出(默认是 TTY 表格)

示例

verbumia projects --json

verbumia status 本地文件与远端项目的只读 diff — 按 locale 与 namespace 列出 added / removed / changed。无写入。

Flags

--locale <code> 限定到一个 locale
--namespace <slug> 限定到一个 namespace

示例

verbumia status --locale fr-CA

verbumia push 把本地 i18n 文件上传到 Verbumia:创建新 key、更新已变更的值,并按 on-missing-key 策略处理本地引用但服务端缺失的 key。

Flags

--locale <code> 只 push 这个 locale
--namespace <slug> 只 push 这个 namespace
--dry-run 只显示计划而不应用
--on-missing-key <create|skip> 本地文件引用了服务端缺失的 key 时该如何处理

示例

verbumia push --dry-run

verbumia pull 把远端翻译下载到配置的 pull.dest_dir — 按文件原子写入。也兼任你的“export”路径:传入 --format 在导出时转换格式。

Flags

--locale <code> 只 pull 这个 locale
--namespace <slug> 只 pull 这个 namespace
--format <fmt> json | xliff(本次运行覆盖 config.format)

示例

verbumia pull --format xliff

verbumia missing 列出运行时 SDK 捕获的待处理缺失键事件。只读 — 适合不打开 dashboard 直接在终端做 triage。

Flags

--locale <code> 按 locale 过滤
--since <iso> 只显示比此 ISO-8601 时间戳更新的事件
--limit <n> 最大行数(默认 20)

示例

verbumia missing --locale ja --limit 50

没有单独的 export 命令 — pull --format 已覆盖。从 Lokalise / Crowdin / Phrase 的 import 在 V1 之后发布,等对应 backend 端点上线;在此之前,把 JSON 或 XLIFF 文件放到 push.source_dir 然后运行 verbumia push。

CI 集成

在每个 PR 上运行 verbumia status --json。漂移时非零退出给你一个便宜的“是不是有人没通知 i18n 就发布了 key?”守门器。

.github/workflows/i18n.yml

1# .github/workflows/i18n.yml — 用远端漂移阻断构建2name: i18n status3on: { pull_request: { branches: [main] } }4jobs:5  status:6    runs-on: ubuntu-latest7    steps:8      - uses: actions/checkout@v49      - uses: actions/setup-node@v410        with: { node-version: 20 }11      - run: npx -y @verbumia/cli status --json12        env:13          VERBUMIA_TOKEN: ${{ secrets.VERBUMIA_TOKEN }}