参考 / CLI
机器翻译页面
verbatra export
把未翻译的字符串导出为译者交接文件:带样式的 Excel 工作簿、每个语言环境一个 CSV 或 TSV 文件,或每个语言环境一个供 CAT 工具使用的 XLIFF 文件。
把需要翻译的字符串写成交接文件,由人填写后发回,供 verbatra import 导入。默认只包含缺失和已更改的字符串,也就是自动运行会发送给提供商的那些键。源值为空或只有空白的键,在你写好它的源文本之前没有行。export 从不调用提供商,也不需要 API 密钥。
用法
verbatra export [flags]示例
# write the workbook with missing and changed strings
verbatra export
# only the German and French sheets, to a specific path
verbatra export --locales de,fr --out handoff/round-2.xlsx
# one de.csv and fr.csv under handoff/
verbatra export --format csv --out handoff
# one de.xlf and fr.xlf in XLIFF 2.0 for a CAT tool
verbatra export --format xliff2 --out handoff选项
| 选项 | 参数 | 默认值 | 作用 |
|---|---|---|---|
--out | <path> | verbatra-translations.xlsx;其他格式为 verbatra-translations | 交接文件的写入位置:xlsx 为文件,csv、tsv、xliff2 和 xliff12 为目录 |
--format | <format> | xlsx | xlsx(Excel 工作簿)、csv 或 tsv(每个语言环境一个文件)、xliff2 或 xliff12(每个语言环境一个 XLIFF 文件) |
--locales | <list> | 所有已配置的目标语言环境 | 只导出这个用逗号分隔的子集;未配置的语言环境以 UNKNOWN_ 失败,空列表以 INVALID_ 失败,两者都以 2 退出 |
--include-unchanged | 无 | 关闭 | 同时导出已是最新的字符串 |
此命令还接受全局选项 --cwd、--config 和 --json。
行为
CSV 和 TSV
--format csv 和 --format tsv 为每个导出的语言环境写出一个 <locale>.csv 或 <locale>.tsv,列及其顺序与工作簿的工作表相同。--out 指定目录,目录不存在时会创建。
分隔符文件便于做差异比对,到处都能打开,但它没有单元格保护:每一列都可编辑,Source hash 列也可见。verbatra 从不信任被编辑过的哈希:导入时会把它与当前源值比对,并搁置该行。
每次分隔符文件导出还会写入一个隐藏的清单 .verbatra-export-csv.json 或 .verbatra-export-tsv.json,列出本次写出的语言环境。之后用范围更窄的 --locales 导出,会让被去掉的语言环境退役:它们的文件保留在磁盘上,verbatra import 会把它们当作遗留文件拒绝。导出从不删除输出目录中的任何内容。
XLIFF
--format xliff2 写出 XLIFF 2.0,--format xliff12 写出 XLIFF 1.2:在 --out 目录中为每个导出的语言环境写出一个 <locale>.xlf,另有一个 .verbatra-export-xliff.json 清单,作用与 CSV 的清单相同。每个键成为一个以该键命名的单元,占位符和内联标记成为受保护的内联代码,键的描述和含义成为备注,句段状态跟随锁文件和审校状态(缺失或过期的键为 initial,已是最新为 translated,已批准为 reviewed)。详见交给翻译公司(XLIFF)。
每个目标还会说明它的来源。在 XLIFF 1.2 中,由提供商、翻译记忆库或 AI 智能体写入且无人批准的目标带有 state-qualifier="mt-suggestion";在 XLIFF 2.0 中,单元的 verbatra 元数据组带有 origin 和 review-state。导入会忽略这两者。无法读取 verbatra.provenance.json 时,不写入任何标记,--json 结果带有 provenanceMarkers: "unavailable"。详见记录机器翻译证据。
交接文件的写入位置
交接文件只会写入项目根目录之内。读取任何内容之前,export 会以 EXPORT_ 拒绝以下 --out:越出项目根目录的路径,或者本身(或通过它将写入的某个文件)指向项目所依赖文件的路径,这些文件包括已配置的语言文件、锁文件、来源记录文件、翻译记忆库缓存、verbatra 会查找的配置文件、本次运行加载的配置,以及已配置的 glossary 文件。对 xlsx,没有指向文件的路径(例如 out/)或项目根目录本身也会被拒绝。名称比较不区分大小写,符号链接解析之后会再检查一次。
通过检查的路径仍可能在写入时失败(不可写、路径已被占用、磁盘已满):运行以 EXPORT_ 停止,并给出文件和文件系统错误码。
目标语言环境无法给出工作表名或文件名时,导出以 WORKBOOK_ 停止。xlsx 工作表名必须为 1 到 31 个字符,不得包含 : \ / ? * [ ] 中的任何字符,也不得与 Instructions 或另一个目标语言环境的工作表名相同(不区分大小写)。csv、tsv 或 xlf 文件名不得为空、. 或 ..,不得包含路径分隔符、控制字符,也不得包含 : * ? " < > | 中的任何字符。同一个错误码也涵盖无法序列化的工作簿。
终端反馈
export 在写入期间显示一行,有内容要交接时,还会给出把填好的文件带回来的导入命令:
verbatra: exporting to xlsx... done (0.3s)
next: verbatra import verbatra-translations.xlsx (once your translators have filled it in)没有待处理内容且未传入 --include-unchanged 时,文件没有行,next: 行会改为建议带 --include-unchanged 的同一个导出,并保留 --format、--out、--locales、--cwd 和 --config。
这些行输出到 stderr,--quiet 会去掉它们。详见终端输出。
无法使用的 verbatra.limits.json 会被忽略,并在 stderr 上给出警告(--json 中为 LIMITS_)。
JSON 输出
Schema:export-envelope.json 校验整个信封(envelope);其他 schema 见 Schema。
使用 --json 时,信封包含交接文件的去向和每个语言环境的行数:
{
path: string; // absolute path: the workbook for xlsx, the output directory otherwise
locales: { locale: string; rows: number }[];
provenanceMarkers?: "written" | "unavailable"; // XLIFF formats only
limitsNotice?: { code: "LIMITS_FILE_IGNORED"; message: string };
}退出码
| 退出码 | 含义 |
|---|---|
0 | 交接文件已写入 |
2 | 无法运行:整次运行的错误、被拒绝的输出路径(EXPORT_)、无法写入的交接文件(EXPORT_、WORKBOOK_),或用法错误 |
export 没有按语言环境的失败模式,所以从不以 1 退出。每个命令都遵循的约定见退出码。
相关内容
- 手动翻译:介绍工作簿的布局、审校列和完整的往返流程。
- 交给翻译公司(XLIFF):介绍面向 CAT 工具的 XLIFF 交接。
verbatra import:读回填好的交接文件。