文档翻译

概述

把 Word、PDF、PPT、Excel、图片、网页等常见文件翻译成另一种语言，并尽量保持原有排版。扫描件和图片会先自动识别文字再翻译。可输出 PDF、Word、PPT、Excel、图片、HTML、OFD、Txt、Markdown，输入与输出格式可以相同（例如 Word 译成 Word）。输出 PDF 时还可生成原文与译文左右并排的双语对照版。按页计费：每 2000 字符（不计空格）计 1 页，不足 2000 字符按 1 页计。

使用流程

1. 调用文档翻译接口，提交源文件、目标语言和输出格式。
2. 接口立即返回 token，表示任务已创建成功。
3. 后续通过以下任一方式获取结果： 调用查询结果接口轮询任务状态；或在 options 中传入 callbackUrl，等待系统回调，详细见回调URL。

调用文档翻译 API 需要签名，详细见文档附录：阿里签名。

---

阿里云支持从OSS内网直接下载文件，节约流量，见：阿里云独有部分

文档翻译

https://transdoc.market.alicloudapi.com/translate

HTTP方式： POST

Header中的Content-Type传入application/json

Body是JSON格式

必须签名才能调用成功，签名见阿里签名规则:

https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/use-cases/call-apis

支持的输出格式

支持的输入格式

请求参数

多数场景只需传 input、targetLanguage 与 outputFormat。需要精细控制时，可在 options 中传入翻译页码范围、密码、回调 URL、输出文件名、PDF 压缩与加密、图片输出模式、水印等。

请求示例

• 例1: PDF 译成英文，输出 PDF

{"input": "http://xxx.pdf", "outputFormat": "pdf", "targetLanguage": "en"}

• 例2: Word 译成英文，仍输出 Word

{"input": "http://xxx.docx", "outputFormat": "docx", "targetLanguage": "en"}

• 例3: 英文 PDF 译成中文，输出中英双语对照 PDF

{
  "input": "http://xxx.pdf",
  "outputFormat": "pdf",
  "sourceLanguage": "en",
  "targetLanguage": "zh-CN",
  "bilingual": true
}

• 例4: 图片（Base64）译成英文，输出 PDF（图片必须指定原文语言）

{
  "input": "base64图片",
  "inputFormat": "jpg",
  "outputFormat": "pdf",
  "sourceLanguage": "zh-CN",
  "targetLanguage": "en"
}

• 例5: 多张图片合并翻译（URL 与 Base64 可混合）

{
  "input": ["http://xxx/1.png", "base64图片2"],
  "outputFormat": "pdf",
  "sourceLanguage": "ja",
  "targetLanguage": "zh-CN"
}

• 例6: Base64 文档译成日文，输出 HTML，指定结果文件名

{
  "input": "base64字符串",
  "inputFormat": "docx",
  "outputFormat": "html",
  "targetLanguage": "ja",
  "options": {"outputFileName": "result"}
}

• 例7: 只翻译 PDF 第 1、3、5-7 页（其余页保留原文一并输出）

{
  "input": "http://xxx.pdf",
  "outputFormat": "pdf",
  "targetLanguage": "en",
  "options": {"pageRanges": "1,3,5-7"}
}

• 例8: Excel 译成英文，输出 Excel

{"input": "http://xxx.xlsx", "outputFormat": "xlsx", "targetLanguage": "en"}

• 例9: 网页 URL 译成中文，输出 Word

{
  "input": "https://www.example.com/article/123",
  "inputFormat": "url",
  "outputFormat": "docx",
  "targetLanguage": "zh-CN"
}

• 例10: PDF 译成英文，输出压缩后的 PDF，并设置回调

{
  "input": "http://xxx.pdf",
  "outputFormat": "pdf",
  "targetLanguage": "en",
  "options": {
    "compressionLevel": "medium",
    "callbackUrl": "https://api.example.com/callback"
  }
}

返回数据结构

result:

返回示例(成功状态)：

{
    "code":10000,
    "msg":"",
    "result":{"token":"YOUR_CREDENTIAL"}
}

返回示例(失败状态)：

{
    "code":40001,
    "msg":"bilingual output only supports PDF"
}

翻译能力说明

• 输入与输出格式可以相同，例如 docx→docx、pdf→pdf。
• 只翻译读者能看到的文字。扫描件、图片会先自动识别文字；PDF 中的隐藏文字层、乱码页也会重新识别后再翻译。
• Word、PPT、Excel、网页等数字文档中，嵌入图片里的文字不翻译。
• 文件里完全没有可翻译文字时（例如纯图片 PPT、只有印章的图片），任务仍然成功，返回按目标格式转换的原文件。
• 译文尽量放在原文位置，保持原有排版。译文比原文长时会自动缩小字号，因此同一页内不同段落的字号可能不同。
• bilingual=true 时输出页面为左右并排：左侧原文、右侧译文。
• options.pageRanges 只决定翻译哪些页，未选中的页保留原文，和译文页一起按原页码输出。
• 按页计费：按原文字符数折算，每 2000 字符（不计空格）计 1 页，不足 2000 字符按 1 页计。只统计 pageRanges 所选页面的文字；扫描件和图片按识别出的文字统计；未识别到可翻译文字的文档按 1 页计。翻译失败不计费。查询结果中的 count 是输出文件的页数，不是计费页数。
• 翻译耗时与页数和文字量相关，一份 20 多页的文档通常 3 分钟左右。

查询结果

调用方式： GET（无需签名）

https://api.duhuitech.com/q?token=YOUR_TOKEN

请求参数：

由于翻译需要时间，文件越大页数越多，翻译越久，故需要轮询查询接口来获得结果。查询频率可以是1s一次，也可以更长一些。 查询后先看status，如果是Done或Failed，则翻译结束，停止轮询。如果是Doing或Pending，则继续轮询。

返回数据结构：

result:

结果读取规则：

1. 先看 status。
2. 若 status=Done：
   • outputFormat 为 jpg / png：读取 fileurls（数组；即使只有一页也是数组）。
   • 其它输出格式：读取 fileurl（单个字符串）。
3. 若 status=Failed：翻译失败，停止轮询。
4. 若 status=Doing 或 Pending：可读取 progress，继续轮询。

返回示例(进行中)：

{
	"code":10000,
	"msg":"",
	"token":"YOUR_CREDENTIAL",
	"result":
	{
		"progress":0.53,
		"count":26,
		"status":"Doing"
	}
}

返回示例(成功，单文件，如 PDF / Word)：

{
	"code":10000,
	"msg":"",
	"token":"YOUR_CREDENTIAL",
	"result":
	{
		"status":"Done",
		"fileurl":"https://file.duhuitech.com/o/xxx/xxx.pdf",
		"count":26,
		"filesize":587112
	}
}

返回示例(成功，输出图片)：

{
	"code":10000,
	"msg":"",
	"token":"YOUR_CREDENTIAL",
	"result":
	{
		"status":"Done",
		"fileurls":[
			"https://file.duhuitech.com/o/xxx/1.png",
			"https://file.duhuitech.com/o/xxx/2.png"
		],
		"count":2,
		"filesize":1649699
	}
}

返回示例(失败状态)：

{
	"code":40000,
	"msg":"No such token"
}

或：

{
	"code":10000,
	"msg":"",
	"token":"YOUR_CREDENTIAL",
	"result":
	{
		"status":"Failed"
	}
}

参数列表 options

注意事项：整数参数使用标准 JSON 数字，布尔使用 JSON true / false，枚举使用语义字符串（如 source / landscape / portrait）。未知字段、类型错误、枚举或范围错误会返回参数错误。

翻译时文字识别（OCR）由系统自动完成。图片的识别语言由 sourceLanguage 决定。

通用

输入 Office 文件相关（inputFormat 为 Word / PPT / Excel / WPS 等）

输入网址 / 网页相关（inputFormat=url，或 html / md 等）

输入 EPUB 相关（inputFormat=epub 等）

输入 CAD 文件相关（inputFormat 为 dwg / dxf 等）

---

输出 PDF 相关（outputFormat=pdf）

以下参数作用于翻译完成后的 PDF。

输出图片相关（outputFormat=jpg / png）

图片格式由 outputFormat 决定。通过 imageOutputMode 选择每页一图、长图或动图；动图固定输出 GIF。

输出 HTML 相关（outputFormat=html）

输出 Word/PPT/Excel/Txt/OFD/Markdown 相关（outputFormat 为 docx / pptx / xlsx / txt / ofd / md）

输出水印相关

语言代码

sourceLanguage 与 targetLanguage 使用 BCP 47 语言代码，不区分大小写；zh、zh-Hans 等同 zh-CN，zh-Hant 等同 zh-TW。下表之外的其它 BCP 47 代码也可作为 targetLanguage 提交。输入为图片时，sourceLanguage 只能取「图片可用」为「是」的语言。

备注：

• 输入文件 URL 方式支持文件最大 1500M；Base64 方式最大 8M。
• 最大翻译时长：1小时，超过时间未完成则自动失败。
• 翻译完成后，下载链接有效时间：1小时。

上述最后2项有延长需求请联系客服：

---

回调URL：

用途： 客户可以自行部署服务器，系统翻译结束后会调用客户提供的回调URL，直接发送翻译结果，从而无需再轮询查询结果。

在翻译请求的 options 中传入 callbackUrl。当设置了回调URL，翻译结束后（无论成功失败），系统都会尝试调用该URL，具体如下：

以POST方式调用该URL，Header头中Content-Type: application/json

Body为JSON格式，内容和查询结果的结果相同。例如单文件：

{
	"code":10000,
	"msg":"",
	"token":"YOUR_CREDENTIAL",
	"result":
	{
		"status":"Done",
		"fileurl":"https://file.duhuitech.com/o/xxx/xxx.pdf",
		"filesize":587112,
		"count":26
	}
}

输出图片时同样返回 fileurls：

{
	"code":10000,
	"msg":"",
	"token":"YOUR_CREDENTIAL",
	"result":
	{
		"status":"Done",
		"fileurls":[
			"https://file.duhuitech.com/o/xxx/1.png",
			"https://file.duhuitech.com/o/xxx/2.png"
		],
		"count":2,
		"filesize":120000
	}
}

服务端收到该POST后需在10秒内返回HTTP STATUS CODE 200，视为调用成功，否则系统认为回调失败，会再次尝试。规则如下：

系统共计最多会调用3次回调URL，如果第一次失败，则等待3秒后尝试第二次，如果第二次失败，则等待5秒后尝试第三次，如果第三次失败，则不再尝试。

回调URL超时时间10秒。

---

关于下载翻译后的文件需支持302跳转

接口返回的下载地址（如 fileurl / fileurls）会经 HTTP 302 跳转到实际文件。浏览器会自动跟随。

以下方式默认会跟随跳转，一般无需额外配置：

wget、Python requests / urllib、Node.js axios / got / fetch、Java OkHttp / HttpURLConnection、Go net/http、C# HttpClient、PHP file_get_contents、Objective-C / Swift NSURLSession / URLSession（含 Alamofire）

少数默认不跟随，需手动打开：

• curl：加 -L，如 curl -L -o out.bin "下载地址"
• Java java.net.http.HttpClient：设置 .followRedirects(HttpClient.Redirect.NORMAL)
• PHP curl 扩展：设置 CURLOPT_FOLLOWLOCATION => true

若只拿到 302 响应、本地没有文件内容，多半是未跟随跳转，按上面说明打开对应选项即可。

---

阿里云独有部分：

支持从阿里云OSS内网直接下载文件，目前支持的是上海地区的阿里云OSS内网：

oss-cn-shanghai-internal.aliyuncs.com

请求里的文件 URL 包含上述域名则自动支持。

---

错误码表：

返回的code如果是10000，代表成功，其余是失败

附录：阿里签名方式

参考链接：

https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/use-cases/call-apis

在调用API商品时，首先您需要了解采用哪种API认证方式，云市场API商品的认证方式主要有以下两种方式。两种方式可同时使用，您可以根据不同情况来选择。

• 简单身份认证（AppCode）

• 签名认证

简单身份认证（AppCode）

简单认证（AppCode）调用API，有两种方式，一种是将AppCode放在Header中进行调用，一种是将AppCode放在Query参数中进行调用。

方式一：将AppCode放在Header中

在请求Header中添加一个Authorization参数。

Authorization字段的值的格式为APPCODE ＋ 半角空格 ＋APPCODE值。格式如下：

Authorization:APPCODE AppCode值

示例：

Authorization:APPCODE YOUR_CREDENTIAL

方式二：将AppCode放在Query中

在请求Query中添加AppCode参数（同时支持appcode , appCode , APPCODE , APPCode四种写法）。

AppCode参数的值为AppCode的值。

示例：

http://www.aliyum.com?AppCode=YOUR_CREDENTIAL

参考链接：https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/user-guide/call-an-api-operation-by-using-an-appcode

签名认证

比较复杂，推荐用阿里自己的SDK来调用，参考链接：https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/user-guide/use-digest-authentication-to-call-an-api