功能描述
基于翻译大模型的页面翻译插件,提供页面翻译功能。您可以通过JSSDK,一键完成网站的多语言改造。
技术流程

接入JSSDK
当前版本
项目 | 值 |
|---|---|
版本号 |
|
CDN 根路径 |
|
3.0.1 为准,升级时请同步替换 CDN 链接中的版本号。
SDK 提供两种翻译模式:
- 页面翻译(
pageTranslate):直接替换页面原文为译文,适合“单语展示”场景。 - 段落对照翻译(
paragraphTranslate):在原文后插入译文,适合“原文+译文对照阅读”场景。
- 懒加载翻译(只翻译可视区域)
- 动态内容翻译(DOM 变化后自动翻译)
- 术语表与翻译记忆
- 细粒度 hooks(翻译前/后插入自定义逻辑)
引入方式
通过 Script 标签从 CDN 引入,支持两种方式:
方式一:全量引入(推荐上手)
一次引入 index.js(已包含核心 + 全部插件),即可同时使用页面翻译与段落对照:
文件 | 说明 | 地址 |
|---|---|---|
| 全量包(核心 + 插件) | https://g.alicdn.com/code/npm/@alife/translate-js-sdk/3.0.1/index.js |
方式二:按需拆包引入
先加载 core.js,再按需加载对应插件脚本:
- 全量引入只需一个文件;拆包引入必须先加载
core.js,再加载插件。 - 全局对象为
window.AliTranslate,同时提供别名window.__AliTranslate(两者指向同一实例)。
快速开始
页面翻译(Pure Page)
段落对照翻译(Paragraph Compare)
初始化参数(SDKConfig)
AliTranslate.pageTranslate / AliTranslate.paragraphTranslate 中共用的 SDK 级参数如下:
参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
|
| 是 | 鉴权签名函数,返回可直接请求翻译服务的签名请求 |
|
| 否 | 术语表,提升领域词一致性 |
|
| 否 | 翻译记忆 |
|
| 否 | 业务领域(透传至翻译请求) |
|
| 否 | 分块阈值(影响请求合并与吞吐) |
|
| 否 | 翻译失败最大重试次数 |
|
| 否 | 翻译完成回调 |
页面翻译参数(PageTranslateConfig)
参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
|
| 是 | 目标语种 |
|
| 否 | 源语种,不传默认自动检测 |
|
| 否 | 翻译根节点,默认 |
|
| 否 | 排除节点(命中后整棵子树不翻译) |
|
| 否 | 翻译支持的元素属性 |
|
| 否 | 是否启用懒加载翻译 |
|
| 否 | 懒加载视口偏移(px) |
|
| 否 | 懒翻译选择器(当前版本为预留字段,建议优先使用 |
|
| 否 | 是否监听 DOM 变化并自动翻译 |
|
| 否 | 初始化等待/动态翻译节流延迟(ms) |
|
| 否 | 页面翻译规则(作用于原文容器) |
|
| 否 | 插入译文前回调 |
|
| 否 | 单节点翻译开始回调 |
|
| 否 | 单节点翻译结束回调 |
段落对照参数(ParagraphTranslateConfig)
参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
|
| 是 | 目标语种 |
|
| 否 | 源语种,不传默认自动检测 |
|
| 否 | 翻译根节点,默认 |
|
| 否 | 排除节点(命中后不参与段落提取) |
|
| 否 | 翻译支持的元素属性 |
|
| 否 | 是否启用懒加载翻译 |
|
| 否 | 懒加载视口偏移(px) |
|
| 否 | 懒翻译选择器(当前版本为预留字段,建议优先使用 |
|
| 否 | 是否监听 DOM 变化并自动翻译 |
|
| 否 | 初始化等待/动态翻译节流延迟(ms) |
|
| 否 | 强制按 block 方式插入译文(独占一行) |
|
| 否 | 强制按 inline 方式插入译文(同行展示) |
|
| 否 | 对照翻译样式规则 |
|
| 否 | 插入 |
|
| 否 | 单段落翻译开始回调 |
|
| 否 | 单段落翻译结束回调 |
TransStyleRule 说明
Hooks 与可回滚 DOM 变更
SDK 提供了 mutator(可回滚变更操作器),支持在 hooks 中做安全 DOM 操作,并在 removeTranslations() 时自动回滚。
mutator 可用能力:
setStyle(el, prop, value, priority?)addClass(el, className)removeClass(el, className)appendNode(parent, node)removeNode(node)
语种与枚举值
常用语种值示例:
auto(自动检测)zh、en、ja、ko、fr、de、es、ru、ar、th、vi
LANGUAGE。
常用 API
完整示例(段落对照 + rules + hooks)
如需同时支持“页面翻译”和“段落对照翻译”,推荐直接使用全量包
index.js,并在业务 UI 中明确区分两种模式的切换与清理流程。
获取Token服务
使用阿里云SDK的V3版本请求体&签名机制进行请求签名
注意事项(生产接入建议)
- 必须配置
getToken:由业务侧完成鉴权签名后再发起翻译请求。 - 引入方式二选一:全量引入
index.js即可;若按需拆包,页面翻译需引入page.js,段落对照需引入paragraph.js。 - 重复翻译建议先清理:多次切换参数/语言前建议先执行
removeTranslations(),避免旧状态干扰新配置验证。 - 目标与排除选择器要收敛:
targetSelectors建议限定业务容器,excludeSelectors排除导航、代码块、编辑区等。 - 避免翻译敏感区域:如输入框、编辑器、业务脚本节点、模板容器。
- Hook 里避免重逻辑:
onTranslatingStart/End触发频率高,避免耗时操作阻塞主线程。 - 动态内容场景建议开启
dynamic:适配懒渲染和流式加载页面。
常见问题
调用无效果
- 检查是否已正确引入脚本(全量
index.js,或core.js+ 对应插件)。 - 检查
targetSelectors是否命中。 - 检查
excludeSelectors是否误伤目标区域。 - 检查签名接口是否返回合法请求结构。
rules / hooks 未生效
- 确认传参写在
pageTranslate/paragraphTranslate的同一层级。 - 重复执行前先
removeTranslations()再重新翻译。 - 检查
selector是否可命中段落commonAncestor或其祖先。
loading 看不到
- 翻译速度很快时会瞬时消失,建议在业务侧设置最小可见时长(如 300-500ms)。
- 用
data-source-hash做唯一标识,避免并发段落相互覆盖。
AK/SK在哪里获取?
- 在阿里云平台的AccessKey模块中获取
获取Token服务中的workspaceId从哪里获取?
- 登录AK/SK对应的阿里云账号后,在百炼左下角的业务空间详情中获取
- 弹窗中的业务空间id即对应所需的workspaceId,单击字段右侧的复制图标可直接复制。
网络接口调用报没有权限
- 未开通 通义多模态翻译 产品:需要使用AK所属的阿里云主账号,在百炼通义多模态翻译上进行开通
变更记录
2026年3月
发布版本 | 发布时间 | 发布内容 |
3.0.1 | 2026年8月6日 | 支持页面元素的属性内容翻译(配置参数) |
3.0.0 | 2026年7月16日 | 大版本升级,增加按需引入、术语/语料/domain配置、样式干预、更多的配置参数 |
2.0.6 | 2026年3月5日 | 双语对照翻译增加lazyload和lazyOffset两个参数 |