跳到正文
跳到正文

参考 / 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>xlsxxlsx(Excel 工作簿)、csv 或 tsv(每个语言环境一个文件)、xliff2 或 xliff12(每个语言环境一个 XLIFF 文件)
--locales<list>所有已配置的目标语言环境只导出这个用逗号分隔的子集;未配置的语言环境以 UNKNOWN_LOCALE 失败,空列表以 INVALID_LOCALES 失败,两者都以 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_OUTPUT_CONFLICT 拒绝以下 --out:越出项目根目录的路径,或者本身(或通过它将写入的某个文件)指向项目所依赖文件的路径,这些文件包括已配置的语言文件、锁文件、来源记录文件、翻译记忆库缓存、verbatra 会查找的配置文件、本次运行加载的配置,以及已配置的 glossary 文件。对 xlsx,没有指向文件的路径(例如 out/)或项目根目录本身也会被拒绝。名称比较不区分大小写,符号链接解析之后会再检查一次。

通过检查的路径仍可能在写入时失败(不可写、路径已被占用、磁盘已满):运行以 EXPORT_UNWRITABLE 停止,并给出文件和文件系统错误码。

目标语言环境无法给出工作表名或文件名时,导出以 WORKBOOK_INVALID 停止。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_FILE_IGNORED)。

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_OUTPUT_CONFLICT)、无法写入的交接文件(EXPORT_UNWRITABLE、WORKBOOK_INVALID),或用法错误

export 没有按语言环境的失败模式,所以从不以 1 退出。每个命令都遵循的约定见退出码。

相关内容

在 GitHub 上编辑

本页内容