HTML

翻译 HTML 文本和属性,保留未改动的源内容,并将文档语言设为目标语言区域。

HTML 在承载链接、行为和无障碍信息的结构中呈现可读文本。html 处理器会选取支持的文本片段和描述性属性,再将面向单个目标语言区域的译文写回原始源内容。它不会将多语言页面拆分为各个语言区域对应的独立区块。

保留输入文档的结构 #

文档会保留原始文档类型声明和显式元素。片段仍保持为片段:翻译不会添加 <html>、<head> 或 <body> 包装元素。注释、未改动的属性、引号样式,以及翻译片段之外的空白,均保留源内容中的原样。

显式 <html> 元素现有的 lang 值会被替换为目标语言区域;如果没有该属性,则会添加 lang 属性。例如,翻译为法语时,<html lang="en"> 会变为 <html lang="fr">。如果片段中没有显式 <html> 元素,也不会仅为标明语言而添加该元素。

例如,以下片段包含可见文案和无障碍文本:

html
<section>
  <h2>Delivery options</h2>
  <p>Read the <a href="/delivery">delivery policy</a>.</p>
  <img src="/truck.svg" alt="Delivery truck" />
  <input placeholder="Enter your address" aria-label="Delivery address" />
</section>

标题、段落、链接文字、图像替代文本、输入框占位文本和 ARIA 标签都属于支持翻译的文本。链接目标和图像来源仍属于结构性属性。翻译此片段不会创建本地化链接,也不会替换图像资源。

属性与区域选择 #

支持的内置属性包括图像的 alt 和 title、输入框和文本区域的 placeholder 和 title、部分 title 属性、元数据的 content,以及 ARIA 标签属性。请仔细检查元数据:按名称选取属性,并不意味着该属性的所有值都是自然语言文本。通过配置组件属性规则,还可以为指定名称的元素添加待选取的属性。

脚本、样式、预格式化代码、代码、数学公式、模板、noscript 和 textarea 的内容不参与常规文本提取。被跳过的元素仍可能含有支持翻译的描述性属性。SVG 会采用专门的选取方式处理受支持的 title、desc 和 text 内容,而不会随意翻译绘图数据。

翻译文本时,内联标记和 {{...}} 标记会通过占位符加以保护。重建时,它们会被还原到译文片段中。请检查结果的元素结构,并使用具有代表性的应用值渲染其中的变量。

复用与保留源内容的输出 #

要复用先前的译文,先前的源内容与目标内容必须具有相互对应的文本和占位符结构。处理器会检查两者是否对齐,并可能拒绝存在歧义的配对。请将已接受的目标内容与对应的源版本关联,而不要比较互不相关的已渲染页面。

只有翻译片段和显式 <html> 元素的语言属性会发生变化;未改动的源内容会直接复制到结果中。处理器不会对不可信的 HTML 进行安全清理。请保留应用自身的安全和渲染检查。

如果嵌套错误导致解析器合并不相关标记之间的文本,处理器会拒绝该文档,而不会写入存在歧义的目标内容。请修正嵌套后重试。对于 HTML 规范允许省略的标签,无需添加文档框架来补齐。

在 CLI 或 GitHub App 中配置 HTML 文件 #

CLI 和 GitHub App 会根据 .html 和 .htm 推断 html。在 .lingo/config.json 中选择源文件,并确保生成的目标文件不在源文件匹配模式的范围内:

json
{
  "sourceLocale": "en",
  "targetLocales": ["fr"],
  "files": [
    { "pattern": "pages/en/**/*.html", "format": "html" },
    { "pattern": "pages/en/**/*.htm", "format": "html" }
  ]
}

对于这些扩展名,无需显式指定 format。通过 CLI 配置将项目关联到组织和本地化引擎,或为 GitHub App 指定引擎。每个目标语言区域都对应一个独立文件,例如 pages/fr/index.html。HTML 不支持按键限定翻译范围。

获取结果后,在实际使用该文档或片段的应用中进行渲染。对比链接和非文本属性,并同时检查无障碍文本与可见文案。如果 HTML 由 CMS 提供,请遵循相应连接器的字段选择和回写说明;即使连接器的实现包含 HTML 处理,不同连接器接受的输入也可能不同。