UDOC 翻译测试与 HTML 无损互转

版本：2026-09-23。下面的样例可以直接下载、导入 UniDoc、提交给支持 UDOC 的翻译器，再检查格式保留情况。中文与英文稿使用相同的 10 个段落 ID；表格数值、公式、图片字节和链接地址保持一致。数据是合成数据，英文稿是人工整理的对照译文，不代表某个翻译服务的自动输出。

1. 下载测试文档

在 UniDoc 打开中文样例 · 打开英文对照

样例包括标题、加粗正文、三列表格、LaTeX 公式、内嵌 SVG 图片、图片替代文字、图注、链接和代码。适合检查“文字翻译了，结构是否仍可编辑”。本说明右上角的“下载 .udoc”下载的是说明本身；上表下载的是测试稿。

2. 当前公网接口

基址为 https://app.unidoc.top。这些接口使用原始请求体，不使用 multipart。

这三个接口需要已登录的 UniDoc 浏览器会话，并验证请求来源。同源页面可使用 credentials: 'same-origin'；离线 HTML、第三方域名和任意 Bearer token 不能代替这一会话。未登录时返回 401；请求来源不符合要求时返回 403。不要把错误 JSON 保存成 .udoc。

下面可在本篇线上页面点击，验证“中文 UDOC → JSON → 校验 → UDOC”并下载结果。它不调用翻译模型，也不读取你在编辑器里打开的其他文档。

运行接口往返测试并下载 先打开 UniDoc 登录

尚未运行。登录后回到本页再点击。

3. 接入你自己的翻译服务

UniDoc 提供格式转换接口，目前没有独立的公共 /translate 接口。你的翻译服务负责生成译文；UniDoc 负责验证与重新封装。下面代码在已登录的同源页面运行，translateText 由你的翻译服务提供，返回翻译后的字符串。

async function checked(response) {
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  return response;
}
async function convert(path, body, type) {
  return checked(await fetch(path, {
    method: 'POST', credentials: 'same-origin',
    headers: { 'Content-Type': type }, body,
  }));
}
async function translateUdoc(file, translateText) {
  const source = await convert('/convert/udoc2udoc-json?inline_media=1',
    await file.arrayBuffer(), 'application/octet-stream');
  const draft = await source.json();
  // This sample uses native blocks. A general translator must also support
  // textboxes, headers, footers, captions and comments before claiming completeness.
  for (const block of draft.blocks) {
    const dom = new DOMParser().parseFromString(block.html, 'text/html');
    const walker = dom.createTreeWalker(dom.body, NodeFilter.SHOW_TEXT);
    const nodes = [];
    while (walker.nextNode()) {
      const node = walker.currentNode;
      if (node.textContent.trim() &&
          !node.parentElement.closest('latex,code,pre,script,style,.katex,[data-latex]')) {
        nodes.push(node);
      }
    }
    // A production translator should batch neighboring text with context.
    for (const node of nodes) node.textContent = await translateText(node.textContent);
    for (const image of dom.querySelectorAll('img[alt]')) {
      image.alt = await translateText(image.alt);
    }
    block.html = dom.body.innerHTML;
  }
  const body = JSON.stringify(draft);
  await convert('/validate/udoc-json', body, 'application/vnd.unidoc.udoc+json');
  const output = await convert('/convert/udoc-json2udoc', body,
    'application/vnd.unidoc.udoc+json');
  return output.blob();
}
// const englishUdoc = await translateUdoc(selectedFile, yourTranslator);

样例级代码逐文本节点调用翻译，主要演示格式边界；正式翻译要按段落收集上下文，并用占位符保护公式、数值、单位和代码。不能让模型重新编号 para_id、重写资源路径或把整份 HTML 当作一个新段落。上面的英文对照稿用于检查结构，不要求机器译文逐字相同。

不方便使用浏览器会话时，可在你自己的机器上运行相同的格式转换器，翻译步骤仍接你选择的服务：

python tools/udoc_json.py unpack translation-zh.udoc draft.udoc.json --inline-media --pretty
# Translate text in draft.udoc.json, preserving the document structure.
python tools/udoc_json.py validate translated.udoc.json
python tools/udoc_json.py pack translated.udoc.json translated.udoc

4. UDOC 与 HTML 双向转换

下载上表的 HTML 后，在 UniDoc 的“文件 → 打开”中打开它，可以还原其内嵌文档模型。打开 UDOC 后，使用“导出 → HTML”的可还原导出，即可保存带原生模型的 HTML。随后重新打开 HTML，再“另存为 .udoc”，完成双向验证。普通网页导入能生成文档，但不能保证恢复原始段落 ID、分页、批注和对象属性。

不要只翻译可还原 HTML 的可见文字。 可还原 HTML 同时含有展示内容和 application/x-udoc 原生模型。若只改展示部分，重新导入时原生模型仍是原文。推荐先解包 UDOC、翻译模型里的文本、重新打包，再导出 HTML。

iframe 公开桥也能导入 HTML、载入原生 UDOC 和取回原生文件：

// request() validates event.origin, event.source and the request ID.
// Its complete implementation is in the linked runnable embed example.
await request('unidoc:set', { html: downloadedLosslessHtml });
const native = await request('unidoc:get-udoc', { format: 'udoc3' });
// native.udoc is "udoc3:" followed by base64-encoded native file bytes.
const display = await request('unidoc:get');
// display.html is a display-only HTML snapshot; it does not contain a lossless model.

unidoc:get 返回展示 HTML，不能替代可还原导出。当前服务端没有 POST /convert/udoc2html 或 /convert/html2udoc 公共路径。自动化集成可使用 可运行的 iframe 示例 和 内嵌接入指南。不要调用编辑器内部函数作为公共 API。

5. 验收清单

译文应保留 10 个稳定段落 ID；表格仍为 4 行、3 列；120、8.5 km、42%、日期和示例编号不变；LaTeX 源、图片字节、链接 URL 与代码不变。标题、正文、表头、图注和图片替代文字应完成翻译。英文变长后页数和换行可以变化，不能用固定页数判定翻译失败。

重新打开译文 UDOC 后，确认表格和公式可编辑、图片可选中；导出可还原 HTML，再导入并保存 UDOC，确认译文没有回退成中文。更完整的接口约束见 公共接口指南 与 MCP 协议。