XML
就地翻译任意 XML 文档中的文本,逐字节保留声明、注释、属性和布局。
xml 文件处理器可翻译没有专用格式支持的 XML 文档中的文本,例如内容导出文件、帮助文件或自定义资源格式。它会将每条译文写入源文件的副本,保留原有的声明、DOCTYPE、注释、处理指令、属性、命名空间和空白。只有需要翻译的文本和你指定的属性会发生变化。
Android 资源、XLIFF 和 Apple 复数字典也属于 XML,但各有专用格式:Android、XLIFF 和 Apple stringsdict。处理这类文件时,请使用对应的格式,因为它们能够识别键、复数形式和每条译文的状态。
配置 XML 翻译 #
只有在文件对应的 files 条目中设置了 "format": "xml",文件才会按通用 XML 格式翻译。单凭 .xml 扩展名无法确定格式,因为 Android strings.xml 也使用相同的扩展名。如果 .xml 文件对应的条目未指定格式,CLI 会跳过该文件并显示提示,GitHub App 也会跳过它:
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [{ "pattern": "content/en/*.xml", "format": "xml" }]
}这会为 content/en/guide.xml 写入 content/de/guide.xml 和 content/fr/guide.xml。目标路径遵循与 JSON 相同的规则,详见输出路径;其他布局可通过 targetPath 声明。文件归属于第一个模式与其匹配的条目,因此请为 Android 资源设置单独的条目并指定 "format": "android",同时确保 xml 条目的模式不会匹配这些资源。同一配置适用于 CLI 和 GitHub App。
翻译范围 #
每个包含文本的元素都是一个翻译单元。如果元素只包含其他元素、注释和空白,它本身不会形成翻译单元,处理器会转而读取其子元素:
<?xml version="1.0" encoding="UTF-8"?>
<help>
<!-- shown on the settings page -->
<topic id="sync">
<title>Sync your files</title>
<p>Click <b>Sync</b> to upload your <a href="/files">files</a> now.</p>
</topic>
</help>这里,title 和 p 各是一个翻译单元。注释、id 和 href 不会提交翻译。
- 行内元素。 内含元素的文本(如上面的
p)会将整个句子作为一个翻译单元。行内元素以占位符的形式传给模型,模型可以移动它们,但不能修改,因此译文可以根据目标语言的需要调整Sync和files的位置。这类文本中的注释和处理指令也会以相同方式保留。 - 空白。 仅由空白组成的文本(例如元素之间的缩进)不会提交翻译。文本周围的空白会保留在文件中,文本内部的空白则会原样发送。译文在文本周围新增的空白会被移除。
- CDATA。 仅由一个 CDATA 区段组成的文本会被翻译,并以 CDATA 区段的形式写回。与其他文本相邻的 CDATA 区段会并入该文本,并在写回时转义,XML 对它的解析结果保持不变。
- 引用。
&、<、>、"、'以及©等字符引用会在翻译前解码。DOCTYPE 中声明的实体(例如&brand;或&product-name;)会像占位符一样受到保护,并原样写回。 - 非自然语言文本值。 如果文本仅由数字、一个 URL、一个 ISO 日期或一个由字母和数字组成的 22 字符标识符构成,就会直接复制到每个目标中,不作翻译。
元素名称和路径会严格按原样读取,包括大小写和命名空间前缀。
翻译属性 #
只有在 translateComponentProps 中指定的属性值才会被翻译。字符串用于指定所有元素上的某个属性;包含 component 的对象则仅指定相应元素上的该属性:
{
"pattern": "content/en/*.xml",
"format": "xml",
"translateComponentProps": ["title", { "component": "item", "props": ["label"] }]
}这会翻译所有 title 属性,以及 <item> 元素上的 label 属性。名称严格按原样匹配,因此 x:title 和 Title 会被视为不同的属性。空值会被跳过。标识符、链接、xml:lang 和命名空间声明只有在你指定后才会被翻译,因此误将其中任何一项指定为翻译对象,都会改变文件的解析方式。
译文的写入方式 #
译文中的 &、< 和 > 会被转义。翻译后的属性值中,&、< 和该属性使用的引号字符会被转义,制表符和换行符则会写为字符引用,以便 XML 保留它们。如果翻译后的 CDATA 区段中出现 ]]>,它会被拆分到两个区段中。译文中的换行会使用文件原有的换行符写入。XML 不支持的控制字符会从译文中移除。
如果声明指定了 UTF-8 以外的编码(例如 encoding="ISO-8859-1"),译文中的非 ASCII 字符会写为字符引用,例如用 é 表示 é,确保目标文件在该编码下仍可读取。文件会按 UTF-8 读取,因此,如果文件声明了其他编码,并以原始字节存储带重音符号的字母,处理就会失败,报告第一个此类字母的位置,且不会为该文件写入任何内容。请将文件保存为 UTF-8,或将这些字符写为字符引用。
处理器不会更改 xml:lang 或其他用于声明文档语言的属性。请在构建过程中更新该属性;如果它包含文本,也可以在 translateComponentProps 中指定它。
键与复用 #
每个翻译单元都以其元素路径作为键,采用类似 XPath 的写法:/help/topic/title、/list/item[2],或用于属性的 /menu/item[1]/@label。只有当元素存在同名的兄弟元素时,路径中才会标注位置。这些键用于在任务和 Studio 中标识翻译单元。
只要单元的文本和元素路径(不含位置)自上次推送以来未发生变化,且译文保留了源文中的行内元素及其原有嵌套结构,该单元就会保留现有译文。译文可以调整这些元素的顺序,因为目标语言的语序往往需要这样的调整。行内元素中已翻译的属性会随该元素一起移动。插入元素时,只会翻译新增的元素;后续元素即使位置发生变化,也会保留各自的译文。如果译文中的行内元素不再与源文匹配,例如有人在译文中删除了某个元素,或将其移入另一个元素内部,该译文就会被重新翻译。
不适用的选项 #
XML 没有键规则。如果 xml 条目设置了 lockedKeys、preservedKeys、ignoredKeys、keyColumn、injectLocale 或 translateFrontmatterFields,CLI 和 GitHub App 会拒绝该条目,因为这些选项在翻译时会被忽略。如同 Java properties 以外的所有格式,XML 也不接受 lockedPatterns。
lingo push --key 会跳过 xml 文件并显示提示,同时推送其他选中的文件。
无效的 XML #
如果文件不符合 XML 格式规范,处理就会失败,并报告首个问题所在的行和列,例如未闭合或不匹配的标签、未转义的 &、两个根元素,或根元素之外的文本。如果文件末尾仍有多个标签未闭合,错误信息会改为列出这些标签。元素嵌套深度超过 256 层的文件也会处理失败。不会为该文件写入任何内容,现有目标文件会保持原样。不符合格式规范的目标文件也会以同样的方式失败,并指出其语言区域。请修复 XML 后重新推送。