参考 / CLI
机器翻译页面
verbatra tmx
导入其他工具的 TMX 翻译记忆库,让之后的运行复用其中的字符串而不必再付费,或把本项目的翻译记忆库导出为 TMX。
以 TMX(主流翻译平台使用的交换格式)把翻译记忆库导入或导出。tmx import 把其他工具的翻译记忆库放进本项目的翻译记忆库(见翻译缓存),让之后的运行复用这些字符串,而不必再次付费;tmx export 把翻译记忆库写回文件。两个方向都不调用提供商,不读取 API 密钥,也不访问网络。真实导入还会向已有的 .gitignore 添加缺少的条目,见 .gitignore 条目。
用法
verbatra tmx <direction> [file] [flags]<direction>:import或export;其他值会以INVALID_报错。DIRECTION [file]:要读取或写入的 TMX 文件,默认为项目根目录中的verbatra-memory.tmx。
示例
# 把其他工具的翻译记忆库导入本项目
verbatra tmx import legacy.tmx
# 报告会导入什么,不做任何更改
verbatra tmx import legacy.tmx --dry-run
# 文件与翻译记忆库不一致时,以文件为准
verbatra tmx import legacy.tmx --overwrite
# 把翻译记忆库写入 verbatra-memory.tmx
verbatra tmx export
# 只导出德语,写到指定路径
verbatra tmx export out/memory.tmx --locales de选项
| 选项 | 参数 | 默认值 | 作用 |
|---|---|---|---|
--locales | <list> | 每个已配置的目标语言环境 | 只导入或导出这个以逗号分隔的目标语言环境子集 |
--dry-run | 无 | 关闭 | 仅限导入:校验并报告,不更改翻译记忆库;导出时使用它会以 INVALID_ 报错 |
--overwrite | 无 | 关闭 | 仅限导入:让导入的单元替换翻译记忆库中已有的译文;导出时使用它会以 INVALID_ 报错 |
还接受全局选项 --cwd、--config 和 --json。这里的配置查找和你传入的相对 [file] 都从 --cwd 解析,而翻译记忆库和默认的 verbatra-memory.tmx 从项目根目录解析。
行为
导入的单元必须满足什么
来自其他工具的文件是不可信输入,而翻译记忆库中的单元可能在无人再次确认的情况下被复用。所以每条候选译文在进入翻译记忆库时,都要经过与提供商输出相同的完整性门禁(见翻译安全):
- 它的占位符与其源句段的占位符一致;
- 它的内联 HTML 或 XML 标签与其源句段的标签一致,所以像
<img onerror>这样被注入的标签会被拒绝; - 它是所配置格式的适配器下有效的 ICU 消息;
- 它没有退化为失控的输出;
- 源文本非空时,它不是空白。
源句段为空白的单元不标识任何字符串,同样会被拒绝。内联标记(bpt、ept、ph、it)会被展平为其文本,所以占位符检查能发现带有重要内容的内联标记;sub 元素的文本是独立的内容流(工具提示、替代文本),会被排除在外。句段属性会被忽略,包括 verbatra 导出所写的 x-origin 和 x-review:翻译记忆库不记录来源。
不会悄悄丢弃任何内容:每次拒绝、每个不可用的单元、在你的源语言环境中没有句段的单元、被展平的单元和被丢弃的 sub 文本,都会按原因计数。
每个被拒绝的单元还会列出其序号、原因,以及检查能说明时的具体问题,例如 unit 12: icu ({count} plural: missing arm "few" required by the target language)。
匹配语言标签
TMX 文件按其作者所用工具的方式书写语言。匹配规则从不猜测:
- 双方都转为小写,下划线变为连字符,所以
pt_、BR pt-br和pt-BR是同一个语言环境。完全匹配优先。 - 否则,作为该标签子标签前缀的已配置语言环境会匹配,最长的优先(RFC 4647 查找):配置了
de和de-AT时,de-AT-1996归入de-AT,de-CH-1901归入de。 - 较短的标签也能匹配只多出地区或变体的已配置语言环境,但不会匹配多出文字的:
de归入de-DE,pt归入pt-BR,但sr绝不会归入sr-Latn。 - 文字或地区不同的标签绝不匹配:
zh-CN绝不会存为zh-TW,de-AT绝不会存为de-CH。 - 只有当标签可能对应的语言环境不在同一条前缀链上时,该标签才有歧义,例如配置了
pt-BR和pt-AO时的pt。
每个句段都会在一遍处理中,对照源语言环境和所有已配置的目标来解析,即使使用 --locales 也一样,所以源为 pt 的项目中的 pt-BR 目标绝不会被当作源。源句段与目标句段一样排序:完全匹配的标签优先于前缀匹配,值相同则一致,地位相同但值不同的句段(en-US 的“Color”和 en-GB 的“Colour”)会使该单元被拒绝。源和某个目标规范化后得到同一个标签的配置会被直接拒绝。
两个对应到同一语言环境的目标句段,不会让后出现的一个胜出:完全匹配的标签优先于前缀匹配,两个地位相同但值不同的句段不会为该语言环境存储任何内容,并把该单元计为冲突。未匹配的标签按标签计数,第一个 body 之外的 tu 元素会被计数,头部中的 srclang 如果不是你的源语言环境,也会报告。
文件与翻译记忆库不一致时
以项目的翻译记忆库为准:导入的译文与已有的译文不同时,会被拒绝并计为保留,除非传入 --overwrite。在同一个文件中,同一个源的第一个单元胜出,后面的重复项计为重复,所以同一个文件导入两次,第二次不会写入任何内容。
警告
--overwrite 会替换翻译记忆库中已有的译文,之后的运行会复用这些替换。先用 --dry-run 运行,查看 overwritten 的数量。
导入的单元按项目当前配置的指纹存储,所以只有提供商、模型、语气、verbatra 会发送的术语表条目和 localeMap 都保持不变,翻译记忆库才会复用它们。更改这些内容后,请重新导入文件。由更新版本的 verbatra 写成的翻译记忆库文件保持不动;仍会报告数量,与试运行一样。
导入的单元与模糊复用
被接受的单元的源文本会加入索引,模糊复用(见翻译缓存)用它给已更改的字符串打分,所以与你某个字符串不同的导入源,可以被用于该字符串。这样的复用仍要对照你的真实条目通过完整性门禁,并带有 FUZZY_ 审校标记。导入的源与你的某个字符串相同、但哈希不同时(你的条目带有 TMX 无法携带的描述或含义),绝不会被复用。复数形式按其文本匹配:导入从你的源文件中获取复数标志,所以 cart.items_ 和 cart.items_ 会像其他键一样从翻译记忆库填充。要只允许精确匹配,在配置中省略 fuzzyCache。
导出会写入什么
每个不同的源字符串一个 tu,带有源句段,以及每个导出的语言环境一个目标句段,位于 TMX 1.4b 头部之下(srclang、creationtool、creationtoolversion、segtype、o-tmf)。只写入当前配置指纹下的条目;按更早的提供商、模型、语气或术语表配置存储的条目会被排除,并计为 otherConfiguration,在摘要中单独占一行。 语言标签以 BCP 47 形式写出(en_ 变为 en-US),XML 1.0 无法表示的字符会被移除并计数,空的翻译记忆库会生成有效的空文件。没有存储源文本的条目(从更旧的缓存沿用而来)会被排除并计数。摘要在总数中统计 tu 元素,并按语言环境统计目标句段,所以一个字符串被翻译成多个语言环境时,各语言环境的数量之和会大于总数。
每个目标句段都带有来自 verbatra.provenance.json 的 <prop type="x-origin">(machine、human、import 或 unknown),machine 句段还带有 <prop type="x-review">(approved、unreviewed 或 rejected)。无法读取来源记录文件或锁文件时,不写入任何属性,结果会显示 provenanceMarkers: "unavailable"。见机器翻译证据。
文件只写入项目根目录之内。指向的不是文件、跳出项目根目录,或指向项目所依赖的文件(语言文件、锁文件、来源记录文件或缓存文件、配置文件、术语表文件)的路径,verbatra 会在读取翻译记忆库之前以 TMX_ 拒绝,解析符号链接之后也一样。磁盘上写入失败会以 TMX_ 停止,并写明文件和文件系统错误码。
JSON 输出
Schema:tmx-envelope.json 校验整个信封(envelope);其他 schema 见 Schema。
使用 --json 时,信封带有导入或导出的结果:
// tmx import
{ dryRun: boolean; file: string; units: number; locales: ImportTmxLocaleResult[];
unmatchedLanguages: TmxLanguageReport[]; ambiguousLanguages: TmxLanguageReport[];
memoryWritable: boolean; /* plus the skipped, unmatched and conflicting unit counts */ }
// tmx export
{ path: string; units: number; locales: { locale: string; units: number }[];
withoutSource: number; otherConfiguration?: number; illegalCharactersRemoved: number;
provenanceMarkers: "written" | "unavailable" }每个导入语言环境会报告 added、unchanged、overwritten、kept、duplicates、conflicting 和按原因分类的 rejected 计数,以及 refusals 列表。
终端反馈
两个方向都会在 stderr 上显示一行进度。随后 tmx import 建议运行 verbatra translate,试运行之后则建议真实导入;建议的命令会沿用你传入的文件参数、--overwrite、--locales、--cwd 和 --config。tmx export 不给出任何建议:
verbatra: importing legacy.tmx into the memory... done (0.2s)
next: verbatra translate (reuses the imported memory before calling a provider)--quiet 会隐藏这些行。见终端输出。
退出码
| 退出码 | 含义 |
|---|---|
0 | 文件已读取或写入;被跳过或被拒绝的单元会被报告,不算失败 |
2 | 无法运行:配置错误、TMX 文件缺失或无法读取(SOURCE_)、文件过大或无法解析、源语言文件无法解析(SOURCE_)、导出路径被拒绝(TMX_)、写入失败(TMX_、MEMORY_),或用法错误 |
无效文件的错误信息会写明失败位置的行、列和单元;实体声明和内部 DTD 子集会被直接拒绝,外部 doctype 会被丢弃,从不抓取。见退出码约定。
相关内容
- 翻译缓存说明翻译记忆库及其键的构成。
- 用 Excel 或 CSV 交接介绍把待处理字符串以 xlsx、CSV 和 TSV 交给人的流程。
- 翻译安全说明导入的单元要通过的检查。
tmxErrorLocation从 SDK 读取 TMX 错误的位置。