```` translate.time.execute.start(); ```` 他会在浏览器控制台里打印 translate.execute 执行的相关信息，打印其执行耗时情况。 打印效果比如： ```` [time][translate.execute()] 114ms (search&cache 7ms) , [chinese_simplified] : (2)[你,你好，世界] [time][translate.execute()] 3ms , [chinese_simplified] : (1)[工业品] [time][translate.execute()] 0ms [time][translate.execute()] 1ms ```` **关于打印的数据解释：** 第一行中： 1. ````114ms ```` 此次 translate.execute 执行，从触发到页面显示翻译后的文字，总共耗时 114ms 1. ````search&cache 7ms```` 其中页面元素的搜索 识别、整理、自定义术语处理、离线翻译命中、及浏览器缓存命中这些耗时 7ms 1. ````[chinese_simplified] : (2)[你,你好，世界]```` 扫描整理到要进行翻译的文本，这些文本要进行浏览器缓存命中、以及未命中的就要进行网络请求及请求响应后的翻译内容渲染，这里因为前面有了 ````(search&cache 7ms)```` 标识，所以本次是有浏览器未命中的文本，要进行通过文本翻译接口进行翻译的，文本翻译接口请求 耗时 114ms - 7ms = 107ms ，[chinese_simplified] 为当前进行了一次翻译请求，将简体中文的原文本进行的翻译，翻译的文本数有 2 个，分别是 [你,你好，世界]）。这里的耗时基本都是被网络请求给消耗的，翻译内容的渲染耗时跟网络请求耗时相比，几乎可以忽略。 第二行： 它没有 ````(search&cache 7ms)```` 所以它的翻译文本 ````[chinese_simplified] : (1)[工业品]```` 是全部命中了浏览器缓存，此次翻译的执行没有触发文本翻译接口发起网络请求。所以它执行的速度非常快，从节点扫描、识别、整理、分析、最后到渲染显示等，只有 3ms 第三行、第四行： ````[time][translate.execute()] 0ms```` 它并没有后面跟随网络请求相关数据，也就是触发 translate.execute 执行后，单纯执行了 中页面元素的搜索 识别、整理、自定义术语处理这些，就已经将要进行翻译处理的文本全部处理完了，不再需要触发网络请求了。 这里的耗时也就是等于第一行的 ````search&cache 7ms```` 的耗时 ## 注意 1. 需要 translate.js v3.18.32.20250915 及更高版本 2. 它不限制是在 translate.execute() 前还是后触发，当他触发后才会在日志里打印执行耗时信息。为了避免代码过乱，建议统一放到 translate.execute 之前进行设置。

```` translate.reset(); ```` 它可以将你翻译之后的页面，还原回翻译之前的样子。 比如，你原本页面文字是中文的，你翻译为了英文，当你触发了这个后，他会瞬间还原回你原本翻译前，也就是中文的页面。 另外如果你还可以进行更多的自定义，传入更多控制参数： ```` translate.reset({ selectLanguageRefreshRender:true, //是否重新渲染select选择语言到原始未翻译前的状态，默认不设置则是true，进行重新渲染 notTranslateTip:true //如果当前未执行过翻译，然后触发的 translate.reset() ，是否在控制台打印友好提示，提示未执行翻译，还原指令忽略， true则是正常打印这个提示， false则是不打印这个提示 }); ```` ## 注意 1. 需要 translate.js v3.18.32.20250915 及更高版本 2. 它只能对 [启用整体翻译能力](4078.html) 的翻译进行还原。整体翻译能力2023年推出并推荐使用的。

## 场景 网页加载，且要进行翻译时，翻译之前，隐藏当前网页的文本。 当点击切换语言按钮后，会刷新当前页面，然后再进行翻译。 这时会出现这种现象：刷新当前页面后，会先显示原本的文本，然后再翻译为切换为的语种，体验效果有点欠缺。 而这个的作用，就是增强用户视觉的体验效果，在页面加载（刷新）时，如果判定需要翻译(之前的页面触发过翻译为某个语种了)，那么就会自动隐藏所有网页中的文本，当翻译完成后，自动将网页中的文本显示出来 。 注意：这个需要在body标签之前执行，需要在head标签中执行此。也就是加载 translate.js 以及触发此都要放到head标签中 ## 使用 ```` translate.visual.webPageLoadTranslateBeforeHiddenText(); ```` **注意** 它要加在 head 标签里！ 相应的，translate.js 的引入肯定要在它之前，也就是 translate.js 的引入也要放到head标签里。 另外，它是否隐藏当前网页的文本，是根据当前是否要切换语言来进行的，如果当前页面需要进行切换语言，那它触发后会自动隐藏网页中的所有文字； 如果当前页面并没有进行切换语言，它是不会自动隐藏网页的文字的，因为不需要切换语言了，也就没必要隐藏文字，直接显示就可以了。 同样，因为有这个判定，所以你要在它之前，就要设置本地语种: [translate.language.setLocal('chinese_simplified'); //设置本地语种（当前网页的语种）](4066.html) 也就是，你需要在head里的设置为： ```` ```` 这里给了一个demo示例，以供参考： ```` ```` 可以看到， translate.js 的引入以及设置本地语种、webPageLoadTranslateBeforeHiddenText 都是放在了head 里，确保在 body 出现之前，就完成设置。 而 translate.js 的其他设置及翻译的触发 translate.execute(); 都是放在了网页的最末尾，确保网页都加载渲染完了后，在触发翻译的执行。 ## 注意 1. 放的位置一定是head标签里 2. 需要 translate.js v3.17.19.20250812 及更高版本才支持此能力

[TOC] ## 当用户点击切换语言时触发 当用户点击切换语言时，立即触发，然后再进行切换语言。 点击切换语言后，实际触发的是 ````translate.changeLanguage('english');```` 这里便是在调用它后，立即触发，触发完成后再执行原本的语言切换。 设置方式： ```` translate.lifecycle.changeLanguage.push(function(to){ }); ```` * **to** 翻译为的语种，如 japanese 这里需要注意的是，如果当前是第一次切换语言，那么它会直接将当前原文翻译进行切换，这期间并不会刷新页面； 而切换了一次后，再进行一次切换其他语言时，他会触发刷新页面，这时也就是先触发 ````translate.lifecycle.changeLanguage```` 设置的，然后再刷新页面。 [有关为什么第二次切换语言会刷新页面的解释，可点此查看](4035.html) ## 当执行翻译时触发 当执行 ````translate.execute();```` 之后，它会进行一下操作： 1. 进行一些初始化及检测，如果不达标则直接终止不做任何处理，同时也不会触发任何下面的事件。 1. 进行图片翻译 1. 对要翻译的区域的所有节点进行扫描，识别出需要进行翻译的文本，进行收集分析，加入待翻译的文本队列 1. 对待翻译的文本队列中的翻译文本进行本地浏览器缓存命中处理，如果本地缓存全部命中了，那也就没有后面的网络请求什么事了 1. 对本地浏览器缓存命中之后，没有被缓存命中，未进行翻译的文本，进行通过请求网络接口的方式进行翻译处理，发起网络请求，将要翻译的文本发送到翻译服务进行翻译，等待拿到翻译结果后，进行翻译。（这个会产生 50ms ~ 10s 的时间差，也是造成视觉上翻译速度快慢的最根本原因） 1. 完毕 以下提供的几个针对其生命周期中的某个特定点，提供监控及主动触发你自定义的方法，来做一些事情。 #### 翻译开始 每当触发执行 translate.execute() 时，会先进行当前是否可以正常进行翻译的判定，比如 当前语种是否就已经是翻译之后的语种了是否没必要翻译了等。（这些初始判定可以理解成它的耗时小于1毫秒，几乎没有耗时） 经过初始的判断后，发现允许被翻译，那么在向后执行之前，先触发此。 也就是在进行翻译之前，触发此。 设置方式： ```` translate.lifecycle.execute.start.push(function(data){ console.log(data.uuid); }); ```` * **uuid** translate.nodeQueue[uuid] 这里的唯一标识，每次执行 translate.execute() 时都会创建一个针对此的uuid唯一标识 * **to** 翻译为的语种，如 japanese **扩展用法 - 当用户打开页面后，第一次触发 translate.execute() 时，进行触发** ```` translate.lifecycle.execute.start.push(function(data){ if(translate.executeNumber === 0){ console.log('这是打开页面后，第一次触发 translate.execute() ，因为translate.executeNumber 记录的是translate.execute() 执行完的次数。'); } }); ```` #### 发起网络请求前 每当触发执行翻译动作 translate.execute() 时，当缓存中未发现，需要请求翻译API进行翻译时，在发送API请求前，触发此 ```` translate.lifecycle.execute.translateNetworkBefore.push(function(data){ console.log(data.uuid); }); ```` * **uuid** translate.nodeQueue[uuid] 这里的唯一标识，每次执行 translate.execute() 时都会创建一个针对此的uuid唯一标识 * **from** 来源语种，翻译前的语种，如 english * **to** 翻译为的语种，如 japanese * **texts** 要翻译的文本，它是一个数组形态，是要进行通过API翻译接口进行翻译的文本，格式如 ````['你好','世界']```` * **nodes** 要翻译的文本的node集合，也就是有哪些node中的文本参与了 通过API接口进行翻译文本，这里是这些node。 格式如 [node1, node2, ...] #### 发起网络请求后 每当触发执行翻译动作 translate.execute() 时，当缓存中未发现，需要请求翻译API进行翻译时，在发送API请求后，也就是拿到 API响应、或网络请求失败后，立即触发此 ```` translate.lifecycle.execute.translateNetworkAfter.push(function(data){ console.log(data.uuid); }); ```` * **uuid** translate.nodeQueue[uuid] 这里的唯一标识，每次执行 translate.execute() 时都会创建一个针对此的uuid唯一标识 * **from** 来源语种，翻译前的语种，如 english * **to** 翻译为的语种，如 japanese * **texts** 要翻译的文本，它是一个数组形态，是要进行通过API翻译接口进行翻译的文本，格式如 ````['你好','世界']```` * **nodes** 要翻译的文本的node集合，也就是有哪些node中的文本参与了 通过API接口进行翻译文本，这里是这些node。 格式如 [node1, node2, ...] * **result** 本次网络请求的结果， 1成功， 0失败。 网络不通，翻译结果失败（translate.json返回result非1)都是记入0 * **info** 如果result为0，这里是失败信息 **说明**： 1. 不管网络请求是否成功，它都会被触发 1. 不管翻译结果是否成功，它都会被触发 1. 在网络请求完毕后立即触发，不会再有其他时间损耗。也就是它是在网络请求完毕后，渲染UI页之前就会被触发。 #### 翻译完成 translate.execute() 的翻译渲染完毕触发。 这个完毕是指它当触发 translate.execute() 进行翻译后，无论是全部命中了本地缓存，还是有部分要通过翻译接口发起多个网络请求，当拿到结果（缓存中的翻译结果或多个不同的有xx语种翻译的网络请求全部完成，这个完成是包含所有成功跟失败的响应），并完成将翻译结果渲染到页面中进行显示后，触发此 它跟 translateNetworkFinish 的区别是， translateNetworkFinish 仅仅针对有网络请求的才会触发，而 renderFinish 是无论何种情况，只要 translate.execute() 执行完毕都会触发。比如全部命中了浏览器本地缓存，无需发起任何网络翻译请求这种情况时，也会触发。 ```` translate.lifecycle.execute.renderFinish.push(function(uuid, to){ }); ```` * **uuid** translate.nodeQueue[uuid] 这里的唯一标识，每次执行 translate.execute() 时都会创建一个针对此的uuid唯一标识 * **to** 翻译为的语种，如 japanese **实际使用场景示例：** 比如，我有一个中文网站，翻译为英文浏览时，要做到完全不显示中文的文字内容，不出现先显示中文然后瞬间在显示英文的情况。 **操作方式：** 首先，在原本中文网站加载后，先用CSS显示一个遮罩层，将原本显示中文的部分遮罩起来，在遮罩层上，用英文显示一个提示信息，比如 ```````` 然后在 ````translate.execute();```` 的前面，增加一个翻译完成的监控，以便在翻译完成后，来触发将 loading... 给隐藏掉 : ```` translate.lifecycle.execute.renderFinish.push(function(uuid, to){ document.getElementById('load').style.display='none'; }); ```` 这样就实现了打开网页后，先在页面的中文上面出现个英文提示 loading... 给用户一个友好的提示，当翻译执行完毕后（页面的中文已经改成了英文）将 ````

这里针对 translate.js 自带的默认的一些网络请求进行相关控制 比如页面一打开后， translate.js 会自动进行初始化相关接口请求 /init.json ，获取当前支持的语种列表 language.json ，进行多节点测速的 connectTest.json 等，这些如果不想让他发起这些网络请求，将其设置为空字符串即可，如： ```` translate.request.api.language = ''; translate.request.api.ip = ''; translate.request.api.connectTest = ''; translate.request.api.init = ''; translate.request.api.translate = ''; ```` 如果哪个不想发起网络请求，便将其设置为空字符便可，这样就不会再发起网络请求了。 ## 每个请求的解释 #### translate.request.api.language 获取当前翻译服务所支持的语种，支持翻译哪些语种。 这是一个语种列表。 #### translate.request.api.ip 它是配合 [自动切换为用户所使用的语种](4065.html) 来使用的。 自动切换为用户所使用的语种，首先会根据用户本身浏览器默认语种来自动切换，如果某些很小的情况没有获取到，才会触发通过这个接口，来获取用户所在哪个国家，然后根据哪个国家使用哪个语种比较多，来切换为这个语种。 也就是这个接口它实际使用率是很低的，可能有千分之一的几率。 #### translate.request.api.connectTest translate.js 的自动测速能力，translate.js 支持介入多个独立的网络节点，当用户打开某个网页时，网页中会自动初始化去各个网络节点测速，采用速度最快的可用的网络节点来接入翻译能力。 #### translate.request.api.init translate.js 启动后的一些初始化，比如判定当前translate.js 的版本号、当前可用的 translate.service 服务等。 当然，多数时候这个请求是并不会对translate.js的使用产生实质性作用的。 #### translate.request.api.translate 如果你的离线翻译缓存没有命中的话，它还是会发起这个翻译的网络请求进行。但是如果你设置了 ```` translate.request.api.translate = ''; ```` 那么即使有需要进行通过后端翻译服务进行翻译的文本，因为设置不允许使用，所以文本也不会通过网络传输进行翻译。 如果你审查元素，查看网络请求一栏，会发现 /translate.json 请求是根本就没有这个请求的。 ## 其他场景示例：进行了网络转发，翻译的请求路径完全变了 比如经过API网关或者Nginx 进行网络转发，请求路径完全变了，比如正常翻译的网络请求是： ```` http://12.12.12.12/translate.json ```` 但是你经过网络转发后，它的实际请求URL变成了： ```` http://12.12.12.12/fanyi/trans.php ```` 这里，可以看到，路径、文件名完全变了，这样需要进行设置： ```` translate.request.api.host = ['http://12.12.12.12/fanyi/']; //设置请求路径，详细可参考 http://translate.zvo.cn/4068.html translate.request.api.translate = 'trans.php'; //设置请求的url的文件名 ```` ## 设置不请求language.json时，默认的切换语言下拉框没了 这种场景多数是在一体机的场景，小型一体机，不会再额外去在一体机本身去部署 translate.service 服务，避免产生大的性能消耗。 但是有网环境下，开发时能正常通过语言切换的select切换语言，但是一体机中设置了不发起 language.json 请求，也就不会再返回支持的语种列表， 界面的select切换语言的入口自然也没了， 但是还需要这个进行切换语言，这是可以通过手动指定当前指定的切换语言的形式，来进行设定，比如这个小型一体机设备需要支持中文、韩语两种语言的切换，那么可以这么设置： ```` translate.request.api.language = [{id: "chinese_simplified", name: "简体中文"},{id: "korean", name: "한국어"}]; ```` 这样它便可以继续出现有网络环境时所正常看到的 select切换语言 了，不过可切换的语言就只有所设置的简体中文、韩语 这两个。 ## 注意 1. 需要 translate.js v3.17.8.20250724 及更高版本 1. 使用时，要放在 translate.execute() 前面

这个语种识别，它的影响范围： 1. 你没有设置本地语种，它自动识别你的本地语种是什么 2. 当启用了 [元素整体翻译能力](4078.html) 后，它自动识别你网页中每个元素的内容是什么语种 3. 当使用 [识别字符串语种及分析 translate.language.recognition('xxx')](4083.html) 比如，一个元素中的文本为： ```` 使用场景：Can be used to obtain application user access credentials ```` 按照我们的正常方式判定，它会被判定为英语。 但是你需要实现这个需求： 如果页面中出现 中英文共存的场景，统一都认为是中文，当切换翻译为英文时，这种中英文共存的元素都要被翻译为英文。 这时需要修改语种识别的策略，修改方式为： ```` /* 语种识别策略 str 要识别的字符串 data 对于str字符串识别的结果，格式如： { languageName: 'english', languageArray:[ english:[ list[ {beforeText: ' ', afterText: ' ', text: 'hello word'}, {beforeText: ' ', afterText: ' ', text: 'who?'}, ], number:12 ], japanese:[ ...... ] ] } 有关这里面具体参数的说明，参考 translate.language.recognition 的说明 languagesSize key:语言名， value:语言字符数 allSize 当前所有发现的语种，加起来的总字符数，也就是 languagesSize 遍历所有的value相加的数 最后，要 return data; */ translate.language.recognitionAlgorithm(str, data, languagesSize, allSize){ /* 如果简体中文跟英文一起出现，那么认为当前是简体中文 */ if(typeof(languagesSize['chinese_simplified']) != 'undefined' && typeof(languagesSize['english']) != 'undefined'){ //设置当前识别结果是简体中文 data.languageName = 'chinese_simplified'; } return data; } ```` ## 注意 1. 需要 translate.js v3.17.2.20250705 及更高版本 1. 这个是为二次开发考虑，进行扩展开发使用的。正常使用翻译这个是用不到的 1. 使用时，要放在 translate.execute() 前面

获取翻译区域的原始文本，翻译前的文本。 这里会把空白符等过滤掉，只返回纯显示的文本 也就是获取 translate.setDocument(...) 定义的翻译区域中，翻译前，要参与翻译的文本。 其中像是 translate.ignore.tag 这种忽略翻译的标签，这里也不会获取的，这里只是获取实际要参与翻译的文本。 ```` var text = translate.language.getTranslateAreaText(); ```` ## 案例 要对 gitee 中的 readme 区域进行提取文本，以便用来判定readme中出现的中文、英文、各种语种的比例。 比如这个页面：  已经设置了只翻译 readme 的区域 ： ```` const dom = document.getElementsByTagName('blob-markdown-renderer') translate.setDocuments(dom); ```` 那么执行此 ```` translate.language.getTranslateAreaText(); ```` 控制台可看到：  ## 注意 1. 需要 translate.js v3.17.1.20250705 及更高版本 1. 这个是为二次开发考虑，进行扩展开发使用的。正常使用翻译这个是用不到的

当网页中执行 ````translate.execute();```` 时，会触发一次对当前页面的扫描并翻译。 但是为了避免有的开发者图省事以比较暴力的方式，比如弄个循环执行的定时器，每间隔1秒执行一次翻译； 又或者代码调用时有错误使用，导致非常频繁的去执行扫描及翻译的情况。 这种极其频繁的执行 ````translate.execute();```` 会造成以下影响： 1. 极大占用浏览器本身的计算资源，如果你页面非常大，可能会使页面出现稍微卡顿情况。 1. 频繁调用后端的翻译接口，如果使用我们开源的翻译接口，会容易触发流控策略被拦截（我们会以为你在非法使用），禁止你使用。 上面两个中，主要是第二个，一旦触发流控，那用户使用时，访问页面，直观的感受就是，页面的文字不翻译了。为了保护我们的开源后端翻译服务接口，也为了更好的兼容你的各种花样的使用方式，所以默认内置了翻译执行的排队能力。 当你同一时间多次触发 ````translate.execute();```` 时，第一次会立即执行扫描并翻译，第二次时会先看看上一次是否执行完毕，如果还未执行完毕，那么第二次并不会立即触发，而是进入一个队列等待阶段，包括第三次、第四次，都会进入排队阶段。 当第一次的执行完毕后，第二次的才会进行扫描并翻译，完事后，第三次、第四次 才会依次触发执行。 这样极大保护了后端翻译接口，同时也能保障你不会被翻译接口的流量控制策略命中被封禁使用，保障使用的稳定。 但是还有一种情况，你私有部署了 [translate.service](391129.html) 并且你也设置了 [访问控制策略](413975.html) 的并发数很大，比如 1秒 100次，完全不用考虑并发太快的情况，而且也只是你自己用，不用担心别人恶意使用，你完全可以将 translate.js 中这个排队等待的策略禁用，只要执行 ````translate.execute();```` 就立即进行翻译，会更好的提高用户体验。 ## 设置方式 ```` translate.waitingExecute.use = false; ```` 默认是true， 当你设置为false时，则是禁用排队等待的能力，触发````translate.execute();````时会立即进行翻译。即使你同一时间连续触发了三次，也会立即执行三次。 注意，此种能力仅仅只是你私有部署，或者你朋友私有部署后给你用时，你可以禁用排队翻译的能力。不然你很容易触发别人的翻译API的访问控制规则，把你给禁止使用。 ## 版本 仅限 v3.16 及以上版本

当用户触发ajax请求时，它可以针对ajax请求中的某个参数，进行获取，并进行翻译，将翻译后的文本赋予这个参数，然后再放开请求。 1. 它可以针对 xhr、 fetch 方式的网络请求生效。 1. 它可以针对 get、post 方式的请求生效。 ## 使用场景 搜索场景，原本是中文的页面，翻译为英文后，给美国人使用，美国人使用时，进行搜索，输入的是英文，然后点击搜索按钮，发起搜索。 然后此会拦截网络请求，将请求中用户输入的搜索文本的内容提取出来，识别它输入的是中文还是英文，如果不是本地的语种中文，那就将其翻译为中文，然后再赋予此请求的这个参数中，然后再放开这次请求。 这样请求真正到达服务端接口时，服务端接受到的搜索的文本内容实际就是翻译后的中文文本，而不是用户输入的英文文本。 ## 使用方式 ```` translate.network.rules = [ { url: /https://www.guanleiming.com/a/b/.html/, methods: ['GET', 'POST'], params: ['a','b1'] }, { url: /https://www.guanleiming.com/c/d/.html/, methods: ['GET'], params: ['a','b1'] }, ]; translate.network.use(); //启用 ```` translate.network.rules 设置的是一个规则数组，每个数组有三个参数： * **url** js的正则表达式形式，如果网络请求的url （不包含get参数部分）跟此匹配，那便会进行翻译。 注意，这个是正则形式，并不是字符串形式！比如你想匹配 ````http://www.guanleiming.com/a.jsp```` 那你可以在浏览器控制台用这个来测试是否匹配: ````/http://www.guanleiming.com/a.jsp/.test('http://www.guanleiming.com/a.jsp')```` 输出true，那便是证明匹配了。  * **methods** 限制网络请求的方式 * **params** 要翻译的参数名，如果这里面出现的参数名有值，那会判断这个值是否需要翻译（参考下面的 自动进行翻译的触发条件），便会自动进行翻译，并将翻译的值赋予当前网络请求，并放行当前网络请求。 因为 translate.network.rules 这是一个数组形态，凡事符合其中任意一个规则，都会触发拦截翻译。 此设置建议放在 ````translate.execute();````的上面。 ## 自动进行翻译的触发条件 1. 当前用户有进行切换语言，比如本地语种设置了简体中文，你当前切换为英文进行浏览时。 2. 请求中某个参数的值，其文本语言跟本地语种不一致，比如本地语种是简体中文，而参数的值的文本是英语。 3. 设置的 translate.network.rules 匹配上 这三种情况都满足时，才会进行拦截并翻译这个指定参数的值 ## 版本 需要使用 translate.js v3.15.12.20250603 及更高版本

## 追加请求参数 ```` translate.request.appendParams = { key1:'key1', key2:'key2' } ```` 所有通过 translate.request.send 进行网络请求的(也就是 translate.js 所发起的所有网络请求)，都会追加上这个参数。 效果：  ## 追加 header 请求头参数 ```` translate.request.appendHeaders = { key1:'key1', Aauthorization:'Bearer xxxxxxxxxx' } ```` ## 注意 1. translate.js版本需要 v3.15.13 及更高版本 2. 需要放到 translate.execute(); 的前面

[TOC] 可对JavaScript 对象、以及 JavaScript 代码进行翻译。 ## 在线体验 http://res.wang.market/translate/jsObjectTranslateDemo/demo.html  ## 使用示例 #### 对JavaScript代码进行翻译 ```` var str = ` { "hello":"你好", "word":"单词", "你是谁": [ "世界", "大海" ] } `; translate.js.transString( str, 'english', function(obj){ console.log(obj); }, function(failureInfo){ console.log(failureInfo); } ); ```` #### 对JavaScript对象进行翻译 ```` var obj = { "hello":"你好", "word":"单词", "世界":["世界","大海"] }; translate.js.transObject( obj, 'english', function(obj){ console.log(obj); }, function(failureInfo){ console.log(failureInfo); } ); ```` ## 注意事项 1. client.edge 模式不支持此能力，必须使用 translate.service 模式 2. translate.js 3.15.2 及更高版本才支持

在执行翻译时，浏览器本地缓存没有，需要走API接口时，这个API接口会有网络延迟，比如有1、2秒延迟的话，然后等翻译API拿到结果后再显示到网页，对用户来说，他看到的就是先出现原语种一两秒，然后又变成了翻译后的文本。 本能力就是解决这个问题，在翻译的这段时间，会在原语种的元素上面显示一层加载中的动画效果，让用户知道这段文本正在进行处理中。 而不需要走翻译API接口的部分，则不会显示这个加载中的动画效果。 它并不会影响你本身网页的阅读观看，它的作用是给用户一个友好提示，免得让用户感觉是你网页有问题。 ## 使用方式 #### 简单使用 增加一行代码，用以标记启用此能力: ```` translate.progress.api.startUITip(); ```` #### 高级使用 如果你对翻译中的遮罩层加载中的动画样式美观度不满意，你还可以自定义样式，自定义方式为： ```` translate.progress.style=` /* CSS部分 */ /* 灰色水平加载动画 */ .translate_api_in_progress { position: relative; overflow: hidden; /* 隐藏超出部分的动画 */ } /* 蒙版层 */ .translate_api_in_progress::after { content: ''; position: absolute; top: 0; left: 0; width: 100%; height: 100%; background: rgba(255, 255, 255, 1); /* 半透明白色遮罩 */ z-index: 2; } /* 水平加载条动画 */ .translate_api_in_progress::before { content: ''; position: absolute; top: 50%; left: 0; width: 100%; height:100%; /* 细线高度 */ background: linear-gradient( 90deg, transparent 0%, #e8e8e8 25%, /* 浅灰色 */ #d0d0d0 50%, /* 中灰色 */ #e8e8e8 75%, /* 浅灰色 */ transparent 100% ); background-size: 200% 100%; animation: translate_api_in_progress_horizontal-loader 3.5s linear infinite; z-index: 3; transform: translateY(-50%); } @keyframes translate_api_in_progress_horizontal-loader { 0% { background-position: 200% 0; } 100% { background-position: -200% 0; } } `; translate.progress.api.startUITip(); ```` 你可以更改其中的 ````translate.progress.style```` 的css样式，来自定义当文本翻译中时，文本的css显示效果 ## 注意 1. 它要放在 ````translate.execute();```` 的前面 2. 需要 translate.js v3.16 及更高版本才支持 3. 使用大模型翻译的场景，此能力尤其明显。

这个主要是给开发使用的。 1. 它能自动根据你最终的语种不同，根据翻译的单词跟上下文的联系，来判断是否给翻译的单词前、后追加空格等操作。 1. 它可以对句子中，出现多个位置的同一个单词进行全部翻译替换处理。 使用方法为： ```` translate.language.textTranslateReplace(text, translateOriginal, translateResult, 'english'); ```` **text**: 原始文本，翻译的某句或者某个词就在这个文本之中 **translateOriginal**: 翻译的某个词或句，在翻译之前的文本 **translateResult**: 翻译的某个词或句，在翻译之后的文本，翻译结果 **language**: 显示的语种，这里是对应的 translateResult 这个文本的语种。 也就是最终替换之后要显示给用户的语种。比如将中文翻译为英文，这里也就是英文。 这里会根据显示的语种不同，来自主决定是否前后加空格进行分割。 另外这里传入的语种也是 translate.js 的语种标识 **方法返回**：将翻译处理好的文本返回。 实际调用使用示例： ```` var text = '你世好word世界'; var translateOriginal = '世'; var translateResult = 'shi'; //翻译结果 translate.language.textTranslateReplace(text, translateOriginal, translateResult, 'english'); ```` 运行后，如下图：  ## 注意 需要 translate.js v3.13.13.20250310 及以上版本

[TOC] 当 translate.execute() 触发执行翻译时，它会先从 [浏览器缓存](4026.html) 中取，如果有则会直接从缓存中将翻译结果拿出来渲染到页面上，以做到瞬间翻译。 但是如果有的在本地没有缓存时，这部分没有缓存的文字将会通过API的方式进行请求翻译接口进行翻译。而这种方式毕竟是网络请求，考虑到网络延迟以及翻译API的执行耗时，这个可能要消耗0.5~2秒的时间才会完成翻译。 这样在用户（使用者）看来，就是页面先显示了原本的语种1秒，然后才会翻译成用户需要的语种。 而本文章则是针对这个过程，来进行自定义监听做一些你想做的事情。 # 两个触发事件 ### 1. 请求翻译API之前触发 已经扫描完整个DOM，并且经过了一系列处理，拿到最终要通过翻译API接口进行翻译的文本，进行向API接口发送网络请求之前，触发，触发这个后会立即向翻译API发送网络请求。 ```` translate.listener.execute.renderStartByApi.push(function(uuid, from, to){ console.log('这里你可以做一些自己的自定义操作'); }); ```` ### 2. 请求翻译API完成并在DOM渲染完毕后触发 也就是在也面上被翻译的元素的内容，已经完全被翻译过来（眼睛已经能看到文字被翻译过来）之后，才会触发。 ```` translate.listener.execute.renderFinishByApi.push(function(uuid, from, to){ console.log('这里你可以做一些自己的自定义操作'); }); ```` # 使用说明 ### 1. 参数说明 上面两个事件都是传入了一个自定义方法 ```` function(uuid, from, to){ ... } ```` 其中有个uuid的参数，可以用这个来取得当前传入到翻译API的文本以及所设计到的DOM节点。 可以这样来取 uuid 对应的相关数据： ```` translate.nodeQueue[uuid] ```` 打印出来可以看到：  需要注意的是，当前我执行的是将当前页面翻译为英文的操作。 上图可以看到 list 下有 简体中文、也有英文。 因为我们是要翻译为英文，也就是 上图中 english 的数组部分它只是被扫描出来了，但它并不会实际参与进翻译中去的，也就是在通过翻译API进行翻译的文本中，是不包含 list[english] 这个的。 也就是当前触发我们function 这个方法的翻译元素，实际是： ```` translate.nodeQueue[uuid].list[from] ```` 也就是展开其中某个语种，可以看到：  也就是 如果你想获得参与当前翻译的实际的文本，可以从 ````translate.nodeQueue[uuid].list[from][遍历集合].translateText```` 取得; 如果你想获得参与当前翻译的原本DOM中的文本，可以从 ````translate.nodeQueue[uuid].list[from][遍历集合].original```` 取得; 如果你想获得参与当前翻译的node节点，可以从 ````translate.nodeQueue[uuid].list[from][遍历集合].nodes```` 取得; 另外有关uuid的解释： 页面可能会触发多次翻译，每执行一次翻译，就会生成一个uuid，来存储跟当前执行的翻译相关的数据，不至于翻译执行多了使数据产生错乱。 **注意**，请不要直接对 ````translate.nodeQueue```` 的数据进行操作，你只可以读，不可以写。避免造成数据错乱。你想对数据处理，可以读出数据来后自行创建一个变量进行赋予，处理你自己定义的变量。 ### 2. 可触发多次 触发可以触发多次，并不是只能触发一次，比如你可以这样写： ```` translate.listener.execute.renderStartByApi.push(function(uuid, from, to){ console.log('111'); }); translate.listener.execute.renderStartByApi.push(function(uuid, from, to){ console.log('222'); }); translate.listener.execute.renderStartByApi.push(function(uuid, from, to){ console.log('333'); }); ```` 这个 111、222、333 都会被打印出来。至于它的执行顺序，则是跟代码的顺序一样，先打印 111、在打印 222、在打印 333 ，因为你代码的顺序就是这样的，它跟你代码的顺序是保持一致的。 ### 3. 根据源语言不通进行多次触发 正常情况下，是根据本地语言不同，进行分别请求翻译的，比如本地中包含中文、英文、俄语三种语种，要翻译为韩语，那么 * 中文->韩语会请求一次api * 英文->韩语会请求一次APi * 俄语->韩语会请求一次APi 也就会触发三次 ## 使用示例 - 控制按钮显示文字 这个示例的实际场景是，网页中有个按钮 ```````` 当点击按钮后，进行语言切换，翻译为英语，按钮文字发生改变，翻译完后，按钮文字还原。 当用户点击按钮进行翻译时，翻译会触发一个网络请求，进行翻译操作，网络请求可能是0.5秒，也可能是1.5秒，另外翻译时，会将网页中的文本进行按语种进行分类，也就是点击了一个翻译按钮，有可能发起的是这三个网络请求： 1. 简体中文翻译为英文 2. 繁体中文翻译为英文 3. 俄语翻译为英文 这里的需求是，当点击翻译按钮后，发起翻译的网络请求的过程中，并且这三个任何一个还没得到相应结果时，也就是任何一个网络请求的状态还在请求中时， 翻译按钮的文本变为````正在翻译中...```` ，当三个翻译的网络请求都完成时（不管成功还是失败还是接口报错等任何情况）， 翻译按钮的文本变为````翻译```` 。 代码为： ```` window.currentTranslateIsProgress = 0; //0是未进行翻译，或已经翻译完成，大于0则是有正在进行的翻译网络请求，数字便是正在进行网络请求的数量。 translate.listener.execute.renderStartByApi.push(function(uuid, from, to){ currentTranslateIsProgress++; console.log('发起翻译的网络请求，将 '+from+' 翻译为 '+to+', 当前是正在进行中的第'+currentTranslateIsProgress+"个翻译网络请求"); document.getElementById('translateButton').innerHTML='正在翻译中...'; }); translate.listener.execute.renderFinishByApi.push(function(uuid, from, to){ currentTranslateIsProgress--; console.log('完成翻译的网络请求，将 '+from+' 翻译为 '+to); if(currentTranslateIsProgress == 0){ document.getElementById('translateButton').innerHTML='翻译'; } }); ```` ## 注意 1. 需要 translate.js v3.13.8.20250220 及更高版本才支持此能力 2. 如果翻译时，浏览器本地已经有全部缓存了，不需要在通过翻译API来进行翻译文本了，那么这两个事件是不会触发的。因为他们单纯只是为了监听 翻译API的网络请求及完成的。

比如，正常情况下，网页设置的本地语种是简体中文， 但是网页中也有一段英文， 我们当翻译时切换为中文观看，也就是要以中文显示 默认的情况下，整个页面是不会被任何翻译的，也就是有的那段英文也不会进行任何翻译，依旧是显示英文。 如果你想切换为中文时，即使本地语种设置的是中文，网页中只要不是中文的元素，都会被翻译为要显示的语种，也就是都会被翻译为中文，那可以这么设置： ```` translate.language.translateLocal = true; ```` ## 注意 1. 这行要放到 translate.execute(); 上面 2. 需要 translate.js v3.12.0.20241210 及更高版本才支持

这里可以增加对指定html标签的某个或某些属性进行翻译。比如element、vue 等框架，有些自定义的标签属性，想让其也正常翻译，可以将其自由加入进来。 方式如： ```` translate.element.tagAttribute['input']=['value']; ```` 第一个是tag，第二个是tag的属性。上面这个示例是要翻译 input 的 value 属性。 另外比如要翻译 input 的 value 、 data-value 这两个属性，那么如下： ```` translate.element.tagAttribute['input']=['value','data-value']; ```` 有几个要翻译的属性，就写上几个。 同样，有几个要额外翻译的tag，就加上几行就行了。比如还要翻译 img 标签的 data-value 属性: ```` translate.element.tagAttribute['input']=['value','data-value']; translate.element.tagAttribute['img']=['data-value']; ```` ## 扩展用法 比如，我只想对 加了 disabled 属性的 input 标签的 value 进行翻译 ，比如： ```` ```` 那么设置如下： ```` translate.element.tagAttribute['input']={ attribute:['value','data-value'], condition:function(element){ if(typeof(element.disabled) != 'undefined' && element.disabled == true){ return true; }else{ return false; } } }; ```` 其中， **condition** 便是条件判断，只有当返回的布尔值是true时，才会对上面设置的 attribute 进行翻译，否则并不会对当前设定标签的 attribute 进行任何翻译操作。 function 方法接收的 element 是当前扫描到要进行判断的元素 比如这里是 translate.element.tagAttribute['input'] 那这个 element 参数便是扫描到的具体的 input 元素 可以针对 element 这个当前元素本身来进行判定，来决定是否进行翻译。 如果返回 false，则不对 attribute中设置的 ['value','data-value'] 这两个input 的属性的值进行任何操作 ## 注意 * 这行要加在 ````translate.execute();```` 前面 * 需要 translate.js v3.17.9.20250729 及以上版本才支持此设置

刷新页面，你可以自定义刷新页面的方式，比如在 uniapp 打包生成 apk 时，apk中的刷新页面就不是h5的这个刷新，而是app的刷新方式，就需要自己进行重写这个刷新页面的方法了 ```` translate.refreshCurrentPage = function(){ location.reload(); } ```` 注意，要在引入 js 文件的下面就重写。另外这个刷新页面主要是跟随切换语言来的，也就是一定要放在切换语言那行代码之前。 注意，要使用 v3.4.1 及更高版本

页面正常加载，在执行完 translate.execute() 后，页面也就翻译完了。 但是有些情况是，页面加载完后，比如随着页面下滑的过程中，可能当前页面是一个数据列表，随着下滑，会进行瀑布流加载，当然瀑布流加载这种ajax动态加载可以提前使用 [translate.request.listener.start();](43170.html) 、 [translate.listener.start();](41552.html) 设置来自动监控网页元素变化来自动触发翻译，这两种它的本质也是监控变化部分的元素节点，将变化的元素节点筛选出来，会形成一个数组形态，如 ```` [ node1, node2, node3 ] ```` 然后将这个数组形态传入 ```` translate.execute(变动的元素节点的数组); ```` 从而进行对变化的元素节点进行增量翻译。 另外一个场景是，如果你想做只对当前屏幕所显示的节点进行翻译，那么就完全可以利用此来进行，首先获取当前屏幕所显示的元素或节点，然后将获取到的数组集合传入进行翻译。 当屏幕滚动时，滚动结束后再获取当前屏幕所显示的元素节点，在用这个方法传入进行翻译。 这里提供一个示例： ```` var eles = [ document.getElementById('a'), document.getElementById('b'), document.getElementById('c'), ]; translate.execute(eles); ```` 这里传入的 eles 它可以是元素的集合，也可以是节点的集合。 （其实这个得设置跟 [translate.setDocuments(documents);](41548.html) 的原理是相似的）

[TOC] ## 使用方式 ```` translate.enterprise.use(); ```` 这行代码要加到 ````translate.execute();```` 的前面 注意，需要 translate.js v3.2.1.20240327 及以上版本才支持 需赞助后才可使用，企业版本仅针对付费用户开放。费用及联系可看本章末尾处 你需要将你的域名发我，我给你加白名单，你就能正常使用了。 另外，如果你是打包成APP或者别的场景进行使用，并不是通过域名进行访问的，那我们可以给你开通一个key，你通过设置一个key来进行使用，使用方式为： #### 使用key的方式 ```` translate.enterprise.use(); translate.enterprise.key='xxxxxxxxxxx'; translate.execute(); ```` 就是额外增加了一个key的设置，注意key的设置要在 ````translate.execute();```` 的上面 ## 说明 企业级稳定翻译接口，相较开源翻译接口，在稳定性、响应速度上都进行了极大提升 | 项目 | 开源翻译通道 | 企业级翻译通道 | | ------------ | ------------ | ------------ | | 服务端缓存层数 | 1层| 2层 | | 翻译响应速度 | 1.5~5秒 | 0.2~1.5秒 | | 翻译服务器 | 1台 | >=2台 | | 网络节点 | 2个 | >=4个 | | 翻译通道 | [手动设置](43086.html) | 自动匹配最优 | | 国内缓存节点 | 无 | 有 | | 每日翻译字符 | [200万](43496.html) | [5000万](43496.html) | | [作者远程指导](41718.html) | 无 | 有 | | ...更多待补充 | | | #### 服务端缓存层数 开源翻译的服务端一切以节省成本为主，只有一层缓存，是浏览器级缓存，如果已经翻译过的文本在进行翻译时，直接从缓存中取出做到瞬间无感知的翻译。 企业级翻译中，除了浏览器缓存之外，还增加了一层服务端缓存方案，针对浏览器缓存未命中的情况下，对请求来的翻译文本会再进行一次缓存匹配，如果命中服务端缓存，则直接从缓存中取出返回响应，而不需要再走机器翻译计算服务。极大提高翻译api的响应速度。打个比方，一个2000字的翻译请求，如果未命中服务端缓存，有机器翻译进行计算翻译，需要500毫秒，而如果有服务端缓存命中缓存，则只需要5毫秒！ #### 翻译响应速度 企业级翻译因加入了内存缓存方案，在翻译本身的响应速度进行了提升；另外增加了网络节点，使就近测速翻译匹配度更高，接口相应速度也更快。 #### 翻译服务器 开源的翻译服务器是单台的，本身存在不稳定情况，只不过这个不稳定情况比较低，比如一天24小时可能有三五分钟的不稳定情况。 这个高可用翻译是用多台服务器做翻译接口的备选分流，稳定系数远高于开源的翻译接口。 #### 网络节点 开源的翻译服务节点是香港、美国 两个节点，基本也全部覆盖了全球网络情况，可以不用担心全球范围内某个区域网络问题导致翻译接口无法使用的情况。 企业级翻译服务网络节点是香港、美国、中国、德国 ，使translate.js 的自动匹配最快网络节点更优质。 #### 翻译通道 开源的翻译服务需要[手动设置翻译通道](43086.html) 企业级翻译服务会优先采用 translate.service 进行翻译，如果translate.service 方式异常，会自动切换到 client.edge 以及其他的翻译通道，保障网站翻译的正常进行 #### 每日翻译字符 每日翻译字符的上限。企业版本如果你达到了上限，可以联系我们提高字符上限。如果提高的幅度太大，成倍数的提高，可能要额外收取一点点费用。 #### 作者远程指导 开源版本您可以自己加QQ群，遇到问题群里沟通，作者也会时不时看一眼问题给解惑。当然你也可以[预约作者进行有偿帮助](41718.html) 企业版本遇到问题，当然首先也是通过QQ群解惑，因为你用上了试了效果才会采纳企业版，使用企业版后，如果遇到一些异常自己处理不了，可以请求作者进行解惑，必要时可以拉远程会议进行投屏等沟通指导 ## 开放API [我们也开放公共api接口，方便您直接请求api接口进行翻译。api接口相关说明可点此查阅](43756.html) ## 赞助费 预计 50~200元/月 ，当下可按照 50/月的标准赞助。 支持微信、支付宝、USDT虚拟币、企业公户转账可开票、等等 #### 注意，以下性质的可以免费联系我们开通企业版通道，不收费用 1. 政务网站 1. 国家认可的公益网站 1. 云计算网站， 比如 [www.zhidianyun.cn](https://www.zhidianyun.cn/) 由衷感谢最开始时指点云的服务器赞助！ 1. [如果您是开发者，可以考虑加入我们的生态，为 translate.js 开发各种生态产品、给某个系统的制作翻译插件、vue、uniapp等开发翻译插件](4036.html) ## 联系 微信: 17076012262 Telegram: untran 邮箱：[email protected]

## 使用方式 ```` translate.request.listener.start(); ```` 本功能是可以监听当前网页中所有的ajax请求，比如正常的 xmlhttprequest 请求以及 fetch 。 当请求结束后，自动触发 ````translate.execute();```` 进行翻译。 注意，这行在 ````translate.execute();```` 前面后面都行 ## 场景说明 在某些框架，比如 vue、react 等框架中，它的渲染跟普通的html中使用 ````document.getElemementById('xxx').innerHTML = '';```` 是不大一样的，而且如果出现ajax请求动态渲染页面时，有些朋友碰到过偶尔某个位置会出现漏掉翻译的情况，针对这种情况，特别还是框架各种各样的时候，这种调试是很麻烦的，主要是这个框架还不懂的时候。 但是有一点是，这些基本都是通过ajax请求，拿到结果后渲染页面完成后出现的漏翻译。 ## 更多设置 #### ajax请求完毕后等待多长时间自动翻译 ajax请求完毕后，等待多长时间自动翻译，单位是毫秒，设置方式为： ```` translate.request.listener.delayExecuteTime = 500; ```` 注意，这行要放在 ````translate.request.listener.start();```` 前面 如果不设置，这里默认是200，也就是ajax请求结束后等待200毫秒再去执行 ````translate.execute()```` ，因为ajax请求后还有渲染页面的过程，这也是这个延迟的作用。你的项目越庞大，渲染速度越慢，这里的数相应的也要调整的越大，因为翻译必须是要在你页面渲染完毕后，执行翻译才能将其翻译过来，如果限制行了翻译，后再进行的渲染，那肯定就翻译不到你动态渲染的部分，也就会造成了漏翻译的情况。 #### 设置自动触发翻译的最小间隔时间 针对ajax请求，两次触发的最小间隔时间，单位是毫秒，这里默认是800毫秒。最小填写时间为 200毫秒 ```` translate.request.listener.minIntervalTime = 800; ```` 如果某个页面中ajax请求非常多，而且非常频繁，比如1秒就有100个ajax请求，如果要触发100次翻译，那这频率也太恐怖了，会被翻译接口屏蔽的，这也是这个设置的作用，它限定了你 800 （不设置默认是800）毫秒只能触发一次翻译，也就是你800毫秒内不管有多少次请求，都只会触发一次翻译，超过800毫秒后，下一个800毫秒内也是如此，每个800毫秒的时间段最多只会触发一次翻译。 注意，这行要放在 ````translate.request.listener.start();```` 前面 如果不设置，这里默认是 800 #### 设置哪些ajax请求的url会触发自动翻译 自定义是否会被触发的方法判断 返回值 return true; 默认是不管什么url，全部返回true，表示会触发翻译自动执行 translate.execute; ,如果你不想让某个url触发翻译，那么你可以自行在这个方法中用代码进行判断，然后返回false，那么这个url将不会自动触发翻译操作。 ```` translate.request.listener.trigger = function(url){ //这里 url 这个参数是当前ajax请求的url，当这个ajax请求完成时才会触发此处 //返回值为boolean 类型，默认是不管什么url，全部返回true，表示会触发翻译自动执行 translate.execute; ,如果你不想让某个url触发翻译，那么你可以自行在这个方法中用代码进行判断，然后返回false，那么这个url将不会自动触发翻译操作。 return true; } ```` 注意，这行要放在 ````translate.request.listener.start();```` 前面 这个如果不设置，默认是： ```` translate.request.listener.trigger = function(url){ return true; } ```` ## 注意 需要 translate.js v3.0.8.20240302 及更高版本

翻译网页中的指定语种 ```` translate.language.translateLanguagesRange = ['chinese_simplified','english']; ```` 可设置多个，翻译时只会翻译在这里面出现的语种，未在里面出现的语种将不会被翻译。 注意，这行要放到 translate.execute(); 上面 ## 说明 比如你的网页中，有简体中文、英语 两个语种的文本都有，但是你只想翻译简体中文的文字，英语只是有一些行业术语单词而已，不想被翻译，你可以通过这里进行设置只翻译简体中文 ```` translate.language.translateLanguagesRange = ['chinese_simplified']; ```` ## 版本 需要 translate.js v3.0.6.20240226 及更高版本

重新绘制 select 语种下拉选择。比如进行二次开发translate.js，手动进行了设置语种（当前页面语种） ，但是手动改动后的，在select语种选择框中并不会自动进行改变，这是就需要手动重新绘制一下 select语种选择的下拉选择框 ```` translate.selectLanguageTag.refreshRender(); ```` ## 版本要求 需要 translate.js v3.0.5.20240224 及更高版本 ## 本篇文档已过时 [最新有关select语种下拉定义的文档请点此查看](41541.html)

## 说明 1. 识别字符串整体是什么语种 2. 对字符串进行分析，识别出都有哪些语种，每个语种的字符是什么、每个语种包含的字符数是多少 ```` translate.language.recognition('hello,我是一个string文本') ```` 它的返回值为：  * **languageName** 是当前字符串是什么语种。它的识别遵循以下规则（按顺序判断）： 1. 如果出现多个语种，这个语种包含的字符数，小于识别字符串总字符数 百分之五的，将会把这个语种剔除，下面的判断不会采纳出现百分比小于百分之五的语种。 1. 如果出现英语跟中文、法语、德语等混合的情况，也就是不纯粹英语的情况，那么会以其他语种为准，而不是识别为英语。 2. 如果出现简体中文跟繁体中文混合的情况，那么识别为繁体中文。 3. 除了以上规则外，如果出现了多个语种，那么会识别为出现字符数量最多的语种当做当前句子的语种。 * **languageArray** 对传入字符串进行分析，识别出都有哪些语种，每个语种的字符是什么，每个语种都有多少字符数等。其中： 1. **number**: 当前语种的总字符数 2. **list**: 当前语种识别切割出的集合 ## 其他说明 这个是为二次开发考虑，进行扩展开发使用的。正常使用翻译这个是用不到的 ## 版本要求 需要 translate.js v3.0.5.20240224 及更高版本

[translate.js 有两级缓存，两级缓存的详细说明可点此查看](41750.html) 其中，一级缓存，也就是浏览器缓存，它存在于浏览器本身，默认使用 LocalStorage 进行的存储。它的实现方式为 ```` translate.storage = { set:function(key,value){ localStorage.setItem(key,value); }, get:function(key){ return localStorage.getItem(key); } } ```` 你如果不想使用默认的 localStorage 的缓存，您完全可以对其重写，设置自己想使用的缓存方式，比如 ```` ````

## 使用方式 ```` translate.service.use('client.edge'); ```` 注意，这行代码要加到 ````translate.execute(); ```` 的前面。 它的值有这几个： * **translate.service** 2022.12月，随着 v2.0 版本推出 ，（当前如果不设置，默认便是用的这种） * **client.edge** 2024.2月，随着 v3.0 版本推出 ，此能力上线。由微软直接提供翻译支持，不在依赖翻译服务器。 * **giteeAI** 2025.3月，已完成 DeepSeek、GLM 大模型的稳定使用并在全球龙头企业应用，2025.5月随着qwen3的发布，完成对qwen3的全面对接，2025.7月，跟开源中国联合开发版本完成并发布使用，有开源中国提供算力支持，融入translate.js完成一键接入的深度融合，推出 giteeAI 通道。它不同于上面两个，上面两个是机器翻译，这个是大模型翻译。它提供更好的翻译能力及私有部署后提供毫秒级翻译响应。自giteeAI通道上线后，也就是2025年7月份起，我们强烈推荐采用这个通道，以提供更好的翻译使用体验。 详细可参考： [http://translate.zvo.cn/545867.html](http://translate.zvo.cn/545867.html) translate.service 正常是translate.js中默认使用的，至于为什么是默认使用它而不是默认使用 client.edge、giteeAI ，主要是考虑到v2版本中已经有数十万网站及应用都已经在使用了，为了完美兼容到几年前的旧版本的translate.js 而 translate.service 又可以私有部署到自己的服务器。普通使用都是使用我们公共的翻译服务，也就是我们自己提前部署好了，您可以直接免费去使用，但是如果您对隐私安全要求极高，数据不允许有一点外泄、又或者内网场景不允许通外网时，那么就需要私有部署 translate.service 服务了，部署到您内网自己的服务器来使用。 ## 几种方式的比较 | | client.edge | translate.service 开源公共免费翻译 | translate.service 翻译服务私有部署 | | ------------ | ------------ | ------------ | | 翻译通道稳定性 | 比较稳定 | 一般 | 非常稳定 | | 使用群体 | 大众 | 大众 | 仅自己 | | 翻译字符日上限 | 无上限 | [200万字符/日](42557.html) | 无上限 | | 翻译后端API | 不依赖 | 依赖 | 依赖 | | 是否免费使用 | 免费 | 免费 | 收费 | | 翻译缓存层数 | [一层缓存-浏览器缓存](4026.html) | [二层缓存](4026.html) | [三层缓存](4026.html) | | 翻译服务延迟 | 1~5秒的网络+机器翻译延迟 | 命中[服务端缓存](4026.html)<2秒延迟 | 命中[服务端缓存](4026.html)<100毫秒延迟 | | [元素整体翻译](4078.html) | 默认采用 | 默认不采用 | 默认采用 | | 支持语种数量 | [73种](https://api.translate.zvo.cn/language_edge.json) | [112~450种](https://api.translate.zvo.cn/language.json) | [112~450种](https://api.translate.zvo.cn/language.json) | | | | | | 待补充更多... | ... | ... | * **翻译通道稳定性** translate.service 公共免费翻译 由于是开源公开免费的，所以使用的非常多，同时为了降低服务器的成本，所以会出现偶尔不稳定情况、以及翻译通道延迟或超时情况，比如一天24小时，会有十几分钟的不稳定情况，而且这个情况会随着使用者越来越多也会表现的稍微加剧。所以我们不推荐你使用 translate.service 公共免费翻译 ，而是采用 client.edge、giteeAI 的模式。这里建议用 giteeAI 的模式，是2025.7月最新推出的。有关giteeAI的详细可参考：[http://translate.zvo.cn/545867.html](http://translate.zvo.cn/545867.html) giteeAI 这种是部署了翻译集群，包括欧洲、美洲、亚洲等多个洲都有服务器作为翻译点，同时内置了翻译的自动负载，访问者会自动匹配最优翻译节点的通道，根据当地网络环境等自动进行选择最优切换。 * **翻译服务延迟** 是指如果翻译时没有命中浏览器缓存，那么会请求机器翻译接口，将要翻译的文本通过机器翻译接口进行翻译后返回，然后在进行浏览器缓存以及页面翻译。这个请求机器翻译发送跟接收到翻译文本响应的过程，是这里所说的翻译服务的延迟。不过网页基本只要打开翻译过一次了，都会进入浏览器缓存，网页刷新了、切换网页了翻译会极其迅速。

## 场景说明 translate.js 在使用时，如果你在网站的A页面中切换为了英文，那么当你从A页面跳转到同一个网站的B页面，只要B页面也存在 ````translate.execute()```` 那么B页面也会自动被翻译为英文。 但是有种场景是，在A页面中点击“切换为英文”，跳转到B页面中时并不想让它自动翻译为英文，只有点击“切换为英文”的按钮才会触发切换，也就是只有用户主动触发时才会翻译，而不需要它自动进行翻译，那么就需要这个了。 ## 使用方式 ```` translate.language.clearCacheLanguage(); ```` 将这行代码放在 ````translate.execute()```` 前面。 它会自动清除掉你上个页面所记忆的翻译语种，从而达到切换页面时不会按照上个页面翻译语种自动进行翻译的目的。 ## 适用版本 translate.js v3.0.1.20240202 及更高版本

对 translate.js 请求后端接口的响应进行捕获。使用方式为： ```` //自定义响应的拦截捕获 translate.request.response = function(xhr){ //xhr : XMLHttpRequest 接口请求 console.log('response:'); console.log(xhr); } ```` ## 注意事项 * 此代码要放在 ````translate.execute();```` 前面 * 无论后端翻译接口响应是否成功，都会触发此处。 * 另外当 xhr.readyState==4 的状态时才会触发。 * 此处会在接口请求响应后、且在 translate.js 处理前就会触发 ## 支持版本 需要 translate.js v20231108 及以上版本

## 使用方式 #### 方式一：对局部区域进行整体翻译 可以通过指定tag标签名、id、class的方式来设定要进行整体翻译的区域。 可以单独设置其中一个、也可以tag、id、class同时都进行设置，还可以某个设置多个，比如id可以push多个不同的id。 ```` //指定tag标签 translate.whole.tag.push('h3'); //指定id translate.whole.id.push('abc'); //指定 class 属性 translate.whole.class.push('class name'); ```` 此方式需要 translate.js v2.9.1.20231023 及更高版本才支持此能力。 #### 方式二：对整个页面进行整体翻译 ```` translate.whole.enableAll(); ```` **注意** 1. 这些设置要放在 ````translate.execute();```` 的前面。 1. 如果设置了 [translate.service.use('client.edge');](43086.html) 默认也会启用整个页面的整体翻译。 1. 此方式需要 translate.js v3.4.2.20240531 及更高版本才支持此能力。 **注意** 1. 如果使用的是 translate.service 的翻译通道，并且启用了 translate.whole.enableAll(); 那么会自动将翻译的英语及英语类的翻译结果进行段落首字母大写处理。 1. 如果使用的是 translate.service 的翻译通道，但是没有启用 translate.whole.enableAll(); 那么会自动将翻译的英语及英语类的翻译结果进行全部字母小写处理，避免出现大小写不规则出现的问题。如果你想让首字母大写，完全可以用CSS的方式来控制首字母大写显示。 ## 说明解释 正常的翻译，是对node节点进行文本提取，分析文本包含的语种，对其进行分类整理，只对符合条件的文本进行翻译。比如 ````

hello,我是translate.js的说明

```` 这段p标签，在[设置了本地语种是简体中文](41551.html)，要翻译为英文，这时真正通过后端翻译接口进行翻译的只有 ```` 我是 的说明 ```` 这两段文本，而其他的是不会传入后端翻译接口进行翻译的。这也充分保障了翻译效率、极大减小了传输内容的大小、极大降低了后端翻译接口的负载。 正常情况下，这样是很完美的。但是一些特殊情况，比如小说网站，它需要对翻译的内容具有非常好的连贯性、可阅读性，就需要进行指定区域的整体翻译了。 ## 使用场景 * 你的网站是跨境电商网站，本身语种是简体中文，要翻译为葡萄牙语显示。其中有一个收货地址字段，这个地址输入是葡萄牙语，但正常翻译情况下，translate.js进行自动识别本地语种时，只支持中英文识别，是不支持葡萄牙语的，这种情况会造成这个收货地址的显示翻译会不准确，以及会造成单词被多次翻译，显示多次造成重复混乱的问题。此种情况就需要设置这个收货地址显示的元素要进行整体翻译了。 * 上述正常翻译支持的本地语种是中文跟英文，其他语种比如日语、葡萄牙语、西班牙语、藏语了等等这些还未支持，针对未支持的语种，便是需要使用此整体翻译能力，来进行翻译了。比如你有个网站为日语的，需要翻译为葡萄牙语，便可以通过整体翻译，指定翻译区域为 body，来进行整体翻译为葡萄牙语。 ## 需要知晓 本能力因为没有浏览器层的语种过滤，是直接针对文本进行整体翻译，翻译的文本会相比正常情况下增加很多，会增加我们公共后端翻译服务的压力。而且有的朋友使用时代码方面有时适配的不是很好，会造成循环请求翻译的情况。我们为了保证公共翻译服务的稳定，进行了每个网站每日翻译字符上限两千万字的限制，正常情况下，这个数是远远达不到的！而且即使你达到了，依旧可以联系我们进行说明放开这个限制。这个只是为了避免被不正常使用造成无谓消耗。 [更详细解释可点此查看](42557.html)

通过JavaScript调用一个方法，传入翻译文本进行翻译，并获得翻译结果 它会自动获取你当前设置的本地语种、以及当前要显示为何种语种，来进行翻译。 # 使用方式 传入参数可以有多种类型，但是返回的结果都是相同的，以下有几种方式提供参考： ### 方式一：传入一串翻译文本 ```` translate.request.translateText('你好，我是翻译的内容', function(data){ //打印翻译结果 console.log(data); }); ```` 执行示例：  ### 方式二：传入多个翻译文本 ```` var texts = ['我是翻译的第一句','我是翻译的第二句','我是翻译的第三句']; translate.request.translateText(texts, function(data){ //打印翻译结果 console.log(data); }); ```` 执行示例：  ### 方式三：自定义从什么语言翻译为什么语言 ```` var obj = { from:'chinese_simplified', to:'english', texts: ['我是翻译的第一句','我是翻译的第二句','我是翻译的第三句'] } translate.request.translateText(obj, function(data){ //打印翻译结果 console.log(data); }); ```` 执行示例：  注意： 1. 方式三需要 translate.js v3.12.0.20241210 及以上版本才支持 1. from 也就是原文语种，如果你用的是[大模型翻译](391129.html)等可以自动识别原文语种的，这里你直接传入一个固定字符 'auto' 即可。 # 参数说明 * **第一个参数**: 可传入要翻译的文本、以及文本数组、以及json对象。 * **第二个参数**: 翻译完毕后的处理函数。传入如 ````function(data){ console.log(data); }```` 注意，返回的data.result 为 1，则是翻译成功。 为0则是出错，可通过data.info 得到错误原因。 更详细说明参考： http://api.zvo.cn/translate/service/20230807/translate.json.html

[TOC] 支持离线翻译能力。 其实它也就是传统 i18n 的能力，有语言配置文件提供翻译结果。 ## 使用场景 1. 无网络环境的场景 2. 对翻译速度有极高要求的场景 3. 对翻译的结果有不满意想要手动调整翻译结果的场景 ## 使用方式 ### 1. 方式一：导出当前页面的离线翻译配置 #### 1.1 代码中开启离线翻译控制面板 加入以下这行代码 ```` translate.office.showPanel(); ```` 至于加在 translate.execute(); 的前面还是后面，这个无所谓 访问这个页面，即可看到如下图，右下角已经显示了一个 导出配置信息 的区域  #### 1.2 导出翻译的配置信息 比如当前页面时简体中文，我离线翻译是针对的繁体中文，步骤如下： 1. 先将当前页面切换为繁体中文 2. 点击右下角的 **导出配置信息** 按钮，即可导出当前简体中文跟繁体中文的翻译配置了。  这里可以看到，简体中文跟翻译结果繁体中文，都是一一对应的，你如果感觉某个的翻译结果不太准确，你可以手动去进行编辑翻译结果。 #### 1.3 关闭翻译控制面板 当所有页面的离线配置信息都提取完毕后，就可以关闭翻译控制面板了，也就是讲第1步中的 ````translate.office.showPanel();```` 注释掉即可。 ### 方式二：导出所有页面的离线翻译配置 比如你的管理系统有30个页面，你如果用方式一，那需要执行30次，然后每个页面都设置一次，会比较繁琐。 而这种方式，你可以直接把所有页面的离线翻译，也就是原文跟译文一并导出来，直接设置就完事了。 #### 2.1 代码中开启此能力 ```` translate.office.fullExtract.isUse = true; ```` 注意，此行设置要加到 ````translate.execute();```` 的前面。 #### 2.2 清空浏览器缓存  如上图，清除 localStorage 中的翻译缓存 #### 2.3 在你的页面中执行翻译 打开你的网页，然后进行翻译。 翻译后，点击其他页面，凡是你想导出离线翻译配置的页面，你都点开一次，让这些页面进行翻译。 多点开几次没事，不必担心重复，他会自动排重。 #### 2.4 导出离线翻译配置 在你浏览器-审核元素，控制台里输入以下代码，执行： ```` translate.office.fullExtract.export('english'); ```` 执行后，你浏览器会自动下载一个 english.txt 的文件，离线翻译的配置就全部在这个文件里。 这里有个传入值 ,它便是 translate.js 的语言标识。更多语种标识可以参考： https://translate.zvo.cn/260950.html #### 2.5 关闭此能力 ```` //translate.office.fullExtract.isUse = true; ```` 将他注释掉，即可。 #### 2.6 版本 所有页面全部导出的能力，限 v3.16 及更高版本才支持。 ## 代码中设置离线翻译数据 将第2步中导出的配置信息复制，粘贴到代码中，即可完成离线翻译数据的设置。 需要注意的是，导出的代码一定要加在 translate.execute(); 前面才行。如下所示： ```` //加入离线翻译-切换为繁体中文的配置 translate.office.append('chinese_traditional',` 库=庫 代码=代碼 引入=引入 版本，=版本， 简介:=簡介: 语言切换示例：=語言切換示例： 当前为 =當前為 选择框切换语言:=選擇框切換語言: 国际化，网页自动翻译，同谷歌浏览器自动翻译的效果，适用于网站。=國際化，網頁自動翻譯，同谷歌瀏覽器自動翻譯的效果，適用於網站。 进行翻译=進行翻譯 按钮切换语言:=按鈕切換語言: 如果你网页中有=如果你網頁中有 版本参见：=版本參見： 网页自动翻译，页面无需另行改造，加入两行 =網頁自動翻譯，頁面無需另行改造，加入兩行 即可让你的网页快速具备多国语言切换能力！=即可讓你的網頁快速具備多國語言切換能力！ 使用方式:=使用方式: 在页面最底部加入=在頁面最底部加入 注意，要在页面最底部加。如果你在页面顶部加，那下面的是不会被翻译的=注意，要在頁面最底部加。如果你在頁面頂部加，那下面的是不會被翻譯的 请求更新了数据，要对其更新的数据进行翻译时，可直接执行 =請求更新了數據，要對其更新的數據進行翻譯時，可直接執行 js=js js =js v1 =v1 v2 =v2 ajax=阿賈克斯 demo=演示 hello, =你好， v1.html=v1.html select=選擇 `); //翻译操作 translate.execute(); ```` 注意 ````translate.office.append(...)```` 要设置在 ````translate.execute(); ```` 的前面。 ## 其他说明 1. 离线翻译的配置 translate.office.append(...) 可以出现多个，出现多个时会进行追加操作，每个都会生效。比如当前页面既要翻译为繁体中文、又要翻译为英文的场景。 1. translate.office.append(...) 其中第一个参数是翻译为什么语种，第二个参数是翻译的内容对照。 = 前面是页面原本的单词或句子，= 后面是翻译为的单词或句子。注意的是 = 前面的不要进行改动，如果你想调整翻译的结果，只需要把 = 后面的翻译结果进行修改即可。 1. 如果您是无网络环境下使用，您还要加入手动切换的入口。比如你网页本身是中文的，离线翻译支持切换为英文、法语，那么切换时肯定需要某个动作进行触发，比如用户点击了 “切换为英文” 的按钮，那么网页才会切换为英文。这个就需要配合 [主动进行语言切换](41549.html) 来一起使用。 1. 使用离线翻译时，如果网页中出现了一些动态文本，比如显示当前时间的，那这个文本是每次查看都是在变动的，显然做不到的离线翻译中去的，那这种的，不在离线翻译配置中的文本，会自动通过翻译接口来获取翻译结果。而且这个过程只是进行增量翻译，也就是只是把离线翻译中没有包含到的词或者句子，才会进行通过接口翻译。而包含在离线翻译配置中的词或者句子，就不会再通过翻译接口来进行了。有效的降低翻译接口数据传输。 1. 离线翻译控制面板的导出弹窗有 [msg.js](https://gitee.com/mail_osc/msg) 提供支持，其提供极其轻量级的消息提示能力。

```` translate.language.setUrlParamControl(); ```` **注意，这行要放到 translate.execute(); 上面** 设置可以根据当前访问url的某个get参数来控制使用哪种语言显示。 比如网页url是 http://translate.zvo.cn/index.html ，当前语种是简体中文，那么可以通过在url后面增加 language 参数指定翻译语种，这里使网页内容以英文形态显示，便是这样访问 http://translate.zvo.cn/index.html?language=english 通过get方式传递了 language 这个参数 另外如果您不想使用language这个参数，还可以自定义参数名，比如使用lang来表示，那么可以这样设置： ```` translate.language.setUrlParamControl('lang'); ```` 这样设置后便可以通过 lang=xxxx 来控制以何语种显示了，比如 http://translate.zvo.cn/index.html?lang=english

```` var lang = translate.language.getCurrent(); ```` 获取当前显示的是什么语种。 比如当前设置的本地语种是简体中文，用户并未切换其他语种，那么这个方法将返回本地当前的语种，也就是等同于 translate.language.getLocal() 如果用户切换为英语进行浏览，那么这个方法将返回翻译的目标语种，也就是 english

```` translate.language.getLocal(); ```` 可以使用此来获取当前本地语种。 它是可以手动设置的，详细参见： [translate.language.setLocal('chinese_simplified');](4066.html) 获取本地语种时，首先会判断是否使用了 setLocal(...) 进行了设置，如果有设置，那么返回的将是 setLocal(...) 所设置的值。 如果没有设置，那么会自动获取当前网页所显示的内容文本，判断这个内容文本是什么语种，比如识别到70%字符是俄语，25%是英文，5%是韩语， 那么会自动取这里面识别字符占比最高的，作为当前网页的本地语种，进行返回。 但是有些情况也会根据实际的使用习惯来进行判定，不是绝对的比例大的就一定是使用的，比如 简体中文占比 30%，英语占比 70%，它也依旧是认为简体中文，因为人的习惯上，出现了一定比例的简体中文，他应该是中文、英文都有掌握，且认为使用中文的，不然如果非常熟悉英文，就不应该会出现中文了。 只需知道这回事即可，具体比例什么的不用太过深入研究。 另外 translate.js v3.17.0.20250703 及之后的版本，它获取的范围是跟你使用 ````translate.setDocuments(documents);```` [只翻译指定的元素](4063.html) 有关的，它所判断语种的字符只会从你 translate.setDocuments 设置的区域去取文本进行判定。 如果你没有进行过这个设置，那么会从整个页面的文本中去取，来进行判定。 #### 注意 当前支持设置的本地语种有： * **chinese_simplified** 简体中文 * **chinese_traditional** 繁体中文 * **english** 英语 * **korean** 韩语 * **japanese** 日语 * **french** 法语 * **italian** 意大利语 * **deutsch** 德语 文档最后更新于 2024.12 月，如果您使用时发现不存在其中，可以 [联系我](4030.html) 说明，也没准是已经支持了但是文档上还未更新过来

鼠标在网页中选中一段文字，会自动出现对应翻译后的文本 此能力有网友 https://gitee.com/huangguishen 贡献。 ## 使用方式 ```` translate.language.setDefaultTo('english'); //先设置默认翻译为的什么语言 translate.selectionTranslate.start(); //开启鼠标划词翻译能力 ```` **注意，这个就不需要再执行 ````translate.execute();```` 这个方法了，因为执行了这个方法，整个页面就已经被翻译过了，也就没必要再使用鼠标划词翻译了** ## 实际效果 

```` translate.ignore.id.push('test'); //翻译时追加上自己想忽略不进行翻译的id的值，凡是在这里面的，都不进行翻译。 ```` 翻译时追加上自己想忽略不进行翻译的id的值，凡是在这里面的，都不进行翻译。 也就是当前元素以及其子元素都不会被翻译。 如果有多个，添加多行即可。 如果你想查看当前忽略哪些id，可直接执行 ```` console.log(translate.ignore.id); ```` 进行查看 **注意，这行要放到 translate.execute(); 上面**

```` translate.ignore.class.push('test'); //翻译时追加上自己想忽略不进行翻译的class name的值，凡是在这里面的，都不进行翻译。 ```` 翻译时追加上自己想忽略不进行翻译的class标签，凡是在这里面的，都不进行翻译。 也就是当前元素以及其子元素都不会被翻译。 如果有多个，可以加多行即可。 如果你想查看当前忽略哪些class，可直接执行 ```` console.log(translate.ignore.class); ```` 进行查看 **注意，这行要放到 translate.execute(); 上面**

```` translate.ignore.tag.push('span'); //翻译时追加上自己想忽略不进行翻译的tag标签，凡是在这里面的，都不进行翻译。 ```` 翻译时追加上自己想忽略不进行翻译的tag标签，凡是在这里面的，都不进行翻译。 也就是当前元素以及其子元素都不会被翻译。 如果你想查看当前忽略哪些tag标签，可直接执行 ```` console.log(translate.ignore.tag); ```` 进行查看 **注意，这行要放到 translate.execute(); 上面**

```` translate.selectLanguageTag.languages = 'english,chinese_simplified,korean'; ```` 每个语种之间用英文,分割。比如这里设置的是支持英语、简体中文、韩语 的切换。根据后端翻译服务不同，支持的语言也不同。 这里设置后，出现的切换语言的select下拉选择框中出现的语种便是这里所设置的，而不是一下出来百多个了。 具体支持哪些，可通过 http://api.zvo.cn/translate/service/20230807/language.json.html 获取 （如果您私有部署的，接口文档中将请求域名换为您自己私有部署的域名） **注意，这行要放到 translate.execute(); 上面** ## 本篇文档已过时 [最新有关select语种下拉定义的文档请点此查看](41541.html)

```` /* * 是否显示 select选择语言的选择框，true显示； false不显示。默认为true * 注意,这行要放到 translate.execute(); 上面 */ translate.selectLanguageTag.show = false; translate.execute(); ```` 使用场景，比如如果使用了: ```` 切换为英语 ```` 这种切换方式，那么 select下拉选择的就用不到了，就可以用此方式来不显示。 当然你也可以使用css的方式来控制其不显示。比如： ```` ```` ## 本篇文档已过时 [最新有关select语种下拉定义的文档请点此查看](41541.html)

## 忽略指定的文字不翻译 ```` translate.ignore.text.push('你好'); translate.ignore.text.push('世界'); ```` 翻译时追加上自己想忽略不进行翻译的文字，凡是在这里面的，都不进行翻译。 如果你想查看当前忽略哪些文字不翻译，可直接执行 ```` console.log(translate.ignore.text); ```` 进行查看 #### 注意 1. 这行要放到 translate.execute(); 上面 2. 仅限 translate.js v3.11.0.20241206 及以上版本才支持此能力 ## 通过正则的方式忽略某些文字不翻译 正则的方式可以弥补 ````translate.ignore.text.push```` 只能对固定文本设置的不足，有 https://github.com/wangliangyu 提交本能力的贡献。 使用方式： ```` translate.ignore.setTextRegexs([/请求/g, /[u4a01-u4a05]+/g]); ```` #### 注意 1. 这行要放到 translate.execute(); 上面 2. 仅限 translate.js v3.17.0.20250703 及以上版本才支持此能力

设置第一次使用时，默认以什么语种显示。 比如本地当前语种是简体中文，这里设置为english，那么用户第一次使用时，会自动翻译为english进行显示。如果用户手动切换为其他语种比如韩语，那么就遵循用户手动切换的为主，显示韩语。 使用方式为： ```` translate.language.setDefaultTo('english'); ```` #### 注意 * 这行要放到 translate.execute(); 上面 * 加上这行如果测试，要把你浏览器的 localStorage 存储给清空掉

如果你感觉某些翻译不准确，可进行针对性的定义某些词的翻译结果，进行自定义术语库。使用的方法为： ```` translate.nomenclature.append(from, to, properties); ```` 传入参数解释： * **from** 要转换的语种，传入如 chinese_simplified * **to** 翻译至的目标语种，传入如 english * **properties** 配置表，格式便是properties的格式，每行一个规则，每个前后用等号分割，等号前是要翻译的词或句子，等号后是自定义的翻译结果。传入如: ```` 你好=Hello 世界=ShiJie ```` 比如，要自定义 “网市场云建站系统” 、 “国际化” 这两个词由 简体中文 翻译为 英文 的结果，可以这么写： ```` translate.nomenclature.append('chinese_simplified','english',` 网市场云建站系统=wangmarket CMS 国际化=GuoJiHua `); ```` 这个自定义术语库的可以单独用一个js文件来定义，如此定义一次，在类似的项目中有使用，可直接将之前定义的js术语库文件复制来引入即可方便使用。 **注意，这行要放到 translate.execute(); 上面** ## 示例 这里给出一个示例用于参考，链接地址： [https://res.wang.market/translate/doc/demo_nomenclature.html](https://res.wang.market/translate/doc/demo_nomenclature.html) 您可打开后查看页面源代码，即可看到它是如何设置的。 ## 注意 * 建议你的版本在 translate.js v3.11.0.20241206 及以上版本 * 还有个能力跟自定义术语类似，[离线翻译能力](4076.html) ，此能力可以对所有翻译结果进行自定义修改。它会自动生成类似于传统的i18n的翻译前后的键值对。 ## 不传from参数的场景使用 针对这种场景： 用户做的网站，可能是中文的，也可能是韩语的，这个本地语种并不确定的场景， from 参数没法精确指定，这时 你还可以不设定固定的form参数，而是传入空字符串的方式，来自动适配当前网页语种。 使用示例： ```` translate.nomenclature.append('','english',` 网市场云建站系统=wangmarket CMS 国际化=GuoJiHua `); ```` 可以看到， from 参数传入的是 '' 一个空字符串，这时它将会自动匹配当前本地语种作为from 。 **针对这种from不设定的场景，需要注意几点：** 1. 要确保 ````translate.nomenclature.append```` 是放在 ```````` 跟 ```````` 之间，也就是确保dom完毕后再触发它，这样它自动去获取当前网页翻译区域的语种时，因为dom渲染完了，才能准确的获取语种。 如果你把它放在head标签里，body都还没有，它如果去自动获取网页翻译区域语种，它都获取不到body，啥也获取不到，自然也就什么语种也获取不到了。 2. 如果你使用 [translate.language.setLocal('chinese_simplified'); ](4066.html) 设置本地语种了，那么你这个 ````translate.nomenclature.append```` 可以放到任何位置，比如放到head里都是可以的，因为设置本地语种后， translate.js 就不会再去获取翻译区域的语种了，而是直接使用 ````translate.language.setLocal('chinese_simplified');```` 所设置的语种作为from参数的值。 3. 需要 translate.js v3.18.11.20250829 及更高版本才支持不设置from

当翻译完成后会自动触发执行某个方法，以便您来做自定义扩展。比如 [layui的翻译组件](https://gitee.com/mail_osc/translate_layui) 便是使用了此能力在翻译完成后重新绘制 select 选中项。 ```` translate.listener.renderTaskFinish = function(task){ console.log('执行完一次'); } ```` 进行翻译时每当执行完一次渲染任务（翻译）时会触发此。注意页面一次翻译会触发多个渲染任务。普通情况下，一次页面的翻译可能会触发两三次渲染任务。（因为一个网页上可能有多种语言，每种语言都是一次翻译任务。） 另外如果页面中有ajax交互方面的信息时，每次ajax信息刷新后，也会进行翻译，也是一次翻译任务。 当然，这里的翻译任务是确实有进行了翻译的前提下，执行完才会触发此。

在某些政府机关及大集团内部项目中，对数据隐私及安全保密有强要求场景、以及您对自有客户希望提供高可靠翻译服务场景时，您可将翻译服务接口进行私有化部署，不走我们公开开放的翻译接口，以做到安全保密及后端服务全部自行掌控。 实际部署方式，可参考：[一键部署 translate.service](391129.html) 部署好后，在 ````translate.execute();```` 之前，加入一行代码，进行设置。 ## 翻译后端多节点能力【建议】 自 v3.18.35.20250920 版本开始，最新支持翻译接口多节点能力，设置方式为： ```` translate.request.setHost(['https://api.translate.zvo.cn/','https://api2.translate.zvo.cn/']); ```` 如上，如果是多节点，那么设置数组形式，把每个节点进行设置。其中会优先使用第一个节点。 注意，如果有多个时，第一个的权重将会更高，将会更优先使用，也就是你要设置的第一个是主的，可靠性要更高的。 当然也是完全兼容之前的设置方式的。 如果设置了多节点，translate.js 会自动测速检测延迟最小的服务器节点进行接入使用，全面规避全球使用时，某个地域网络波动导致后端翻译接口无法响应的情况发生。 自动适配最快节点，做到更好的体验！ 多数情况下，你私有部署完 [translate.service](391129.html) 后，也就只有一个请求地址而已，你就直接配置一个地址就行了，比如 ```` translate.request.api.host=['https://api.translate.zvo.cn/']; ```` 当你需要高稳定、全球各地更高的响应速度时，才可以考虑多个大洲，每个洲部署一个网络转发节点。网络节点规格1核1G即可满足。 大部分情况是正常部署完配置上就可以了，不太需要这个网络节点的，还要多付出一份费用，如果一些重要场景，你可以联系我们额外帮你私有部署。 ## 旧版本的使用方式【不建议】 这是 v2.8.2.20230928 以前的版本使用方式，已不建议采用此方式。 ```` translate.request.api.host='http://121.121.121.121/'; //将这里面的ip地址换成你服务器的ip，注意开头，及结尾还有个 / 别拉下 translate.service.use('translate.service'); //指定翻译服务为使用 translate.service translate.execute(); ```` 如此，翻译请求接口就会走您自己服务器了。 **注意，因为这里你是私有部署的translate.service，所以translate.js 中使用时记得要用 ````translate.service.use('translate.service');```` 而不是 client.edge** [有关 translate.service 跟 client.edge 的区别可点此查看](4081.html)

如果页面用 JavaScript 的地方比较多，内容都是随时用JS来控制显示的，比如 VUE、React 等框架做的应用，它可以实时监控DOM中文字的变动，当发生变动后立即识别并进行翻译。 又比如： 1. 页面中需要通过ajax请求后端服务器获取数据，然后再将数据渲染展示出来。 2. 页面中的弹出提示 （就比如 [msg.js](https://gitee.com/mail_osc/msg) 的 ````msg.info('你好');```` ） 这个提示是js加载出来的，提示文字也需要一并进行翻译的情况 您可加入下面一行代码，来实现以上需求。 ```` translate.listener.start(); //开启html页面变化的监控，对变化部分会进行自动翻译。注意，这里变化区域，是指使用 translate.setDocuments(...) 设置的区域。如果未设置，那么为监控整个网页的变化 ```` 建议放在 translate.execute() 这行之前。 ## 注意事项 如果你手动设置了 ````translate.setDocuments(...)```` ，那么监听的就不是整个页面了，而是单纯只监听 ````setDocuments(...)```` 所设置的区域的改动。 ## 不正常的情况 如果您加了这个后，有的ajax请求还是不能正常翻译，您可以在您ajax请求完毕、渲染完毕页面之后，手动执行一下 ````translate.execute()```` 进行翻译。 以我们这个 [request.js](https://gitee.com/mail_osc/request) 的ajax请求为例 ```` ````

```` translate.language.setLocal('chinese_simplified'); //设置本地语种（当前网页的语种） ```` 当前支持设置的本地语种有： * **chinese_simplified** 简体中文 * **chinese_traditional** 繁体中文 * **english** 英语 * **korean** 韩语 * **japanese** 日语 * **french** 法语 * **italian** 意大利语 * **deutsch** 德语 * **portuguese** 葡萄牙语 * **spanish** 西班牙语 …… 更多其他语种，如果您使用时发现不存在其中，可以 [联系我](4030.html) 说明 **注意，这行要放到 translate.execute(); 上面，最好是引入js文件后就设置这行** 1. 如果不设置，会自动识别当前网页的文本，取当前网页文本中，出现频率最高的语种为默认语种。 1. 目前只能自动识别 简体中文、繁体中文、韩语、日语，如果你网页当前语种不包含在内，需要手动使用这行进行设置。 1. 我们建议无论您的语种是否包含在内，都手动进行设置，避免自动识别还有性能损耗 1. 这个会在出现 [select 选择语言](41541.html) 时，默认选中的语种。 1. 如果你的语种是法语、意大利语、德语，你必须启用 [整体翻译能力](42563.html) ，比如你直接加入 `translate.whole.enableAll();` 对整个页面都采用整体翻译的方式。 另外这三个本地语种的设置需要 translate.js 3.4.2.20240531 及以上版本才支持。

用户第一次打开网页时，自动判断当前用户所使用的语种，来自动进行切换为这个语种。 识别用户当前使用的语种，有一个优先级： 1. 首先会判断用户浏览器，读取浏览器所设置的默认语种，如果找到默认语种，则自动进行切换。 2. 如果未获取到浏览器的默认语种，则会继续根据用户的IP所在国家进行判断，判断出用户是在哪个国家，然后判断出这个国家使用的主流语言，来自动进行切换为这个主流语种。 如果用户手动切换了别的语种，再使用时，那就优先以用户所选择的为主，这个就不管用了。 ```` translate.setAutoDiscriminateLocalLanguage(); //设置用户第一次用时，自动识别其所使用的语种进行切换 ```` 当前支持近百个国家的自动识别。具体有哪些国家，可参考： https://gitee.com/mail_osc/translate/blob/master/translate.service/source/src/main/java/cn/zvo/translate/service/core/util/IpUtil.java ## 注意 根据ip判断的方式，ip库判断并不是百分百准确，准确率大概只有96%的准确度的程度

比如点击某个链接显示英文界面 ```` 切换为英语 ```` 只需传入翻译的目标语言，即可快速切换到指定语种。具体有哪些语言，可查阅： [http://api.zvo.cn/translate/service/20230807/language.json.html](http://api.zvo.cn/translate/service/20230807/language.json.html) 其中 ````class="ignore"```` 加了这个class，代表这个a标签将不会被翻译 注意，这个目前是第一次切换语种时，不会刷新页面，但是第二次或以后切换语种时，会刷新当前页面。有关此的解释可以参考： [为什么切换语言会刷新页面的解释](https://translate.zvo.cn/4035.html)

```` var documents = []; documents.push(document.getElementById('test1')); documents.push(document.getElementById('test2')); documents.push(document.getElementById('test3')); translate.setDocuments(documents); //指定要翻译的元素的集合,可传入一个或多个元素。如果不设置，默认翻译整个网页 ```` 可使用 translate.setDocuments(...) 指定要翻译的元素的集合,可传入一个或多个元素。如果不设置此，默认翻译整个网页。 **注意，这行要放到 translate.execute(); 上面**

可使用css来控制切换语言选择的显示位置及美观。如： ```` ```` 这就是控制切换语言的 ```` 标签 ## 本篇文档已过时 [最新有关select语种下拉定义的文档请点此查看](41541.html)

切换语言select选择框的自定义设置

[TOC] 这里介绍对切换语言的select选择框进行的一系列自定义设置，也就是 [https://res.wang.market/translate/demo.html](https://res.wang.market/translate/demo.html) 中的这个位置：

## 指定切换语言选择框在代码中的位置 你想在你页面什么地方显示，就吧下面这个放到哪即可。 ````

```` 主要是这个 id="translate" 切换语言的按钮会自动赋予这个id里面。当然你也不一定非要是div的，也可以这样 ```` ```` 另外，如果您网页中不存在任何元素的id为translate时， translate.js 会自动创建一个 ````

```` 用来显示语言切换 ## 美化切换语言按钮 可使用css来控制切换语言选择的显示位置及美观。如： ```` ```` 这就是控制切换语言的 ``

`` 标签 ## 设定是否自动出现 select 切换语言 ```` /* * 是否显示 select选择语言的选择框，true显示； false不显示。默认为true * 注意,这行要放到 translate.execute(); 上面 */ translate.selectLanguageTag.show = false; translate.execute(); ```` 使用场景，比如如果使用了: ```` 切换为英语 ```` 这种切换方式，那么 select下拉选择的就用不到了，就可以用此方式来不显示。 当然你也可以使用css的方式来控制其不显示。比如： ```` ```` ## 设定select切换语言所支持的语种 ```` translate.selectLanguageTag.languages = 'english,chinese_simplified,korean'; ```` 每个语种之间用英文,分割。比如这里设置的是支持英语、简体中文、韩语 的切换。根据后端翻译服务不同，支持的语言也不同。 这里设置后，出现的切换语言的select下拉选择框中出现的语种便是这里所设置的，而不是一下出来百多个了。 具体支持哪些，可通过 http://api.zvo.cn/translate/service/20230807/language.json.html 获取 （如果您私有部署的，接口文档中将请求域名换为您自己私有部署的域名） **注意，这行要放到 translate.execute(); 上面** ## 重新绘制 select 下拉语种下拉选择。 比如进行二次开发translate.js，手动进行了设置语种（当前页面语种） ，但是手动改动后的，在select语种选择框中并不会自动进行改变，这是就需要手动重新绘制一下 select语种选择的下拉选择框 ```` translate.selectLanguageTag.refreshRender(); ```` 需要 translate.js v3.0.5.20240224 及更高版本 ## 重写select点切换后触发动作 这里是select切换语言的下拉选择框，如果点开，然后选中了某个语种后，触发的动作。 ```` translate.selectLanguageTag.selectOnChange = function(event){ var language = event.target.value; translate.changeLanguage(language); }; ```` 其中传入的 event 便是 select 值发生改动后，select 本身，可以用 console.log(event); 打印出来详细看看 **注意，要放到 translate.execute(); 上面** ## 整个重写select语言切换及HTML等 比如切换语言这里你不想用select选择框来切换，比如想使用这种形式  这种就是对切换语言进行了重写，不再采用丑爆了的 select 选择标签，而是自己写了一个弹出窗，将语言以及相应国家国旗一并显示，看上去非常美观，上档次！ 重写的方式为： ```` //languageList 便是当前支持的能切换的语种，你可以 console.log(languageList); 打印出来看看 translate.selectLanguageTag.customUI = function(languageList){ //select的onchange事件 var onchange = function(event){ translate.selectLanguageTag.selectOnChange(event); } //创建 select 标签 var selectLanguage = document.createElement("select"); selectLanguage.id = translate.selectLanguageTag.documentId+'SelectLanguage'; selectLanguage.className = translate.selectLanguageTag.documentId+'SelectLanguage'; for(var i = 0; i 0){ //设置了自定义显示的语言 //都转小写判断 var langs_indexof = (','+translate.selectLanguageTag.languages+',').toLowerCase(); //console.log(langs_indexof) if(langs_indexof.indexOf(','+languageList[i].id.toLowerCase()+',') < 0){ //没发现，那不显示这个语种，调出 continue } } /*判断默认要选中哪个语言*/ if(translate.to != null && typeof(translate.to) != 'undefined' && translate.to.length > 0){ //设置了目标语言，那就进行判断显示目标语言 if(translate.to == languageList[i].id){ option.setAttribute("selected",'selected'); } }else{ //没设置目标语言，那默认选中当前本地的语种 if(languageList[i].id == translate.language.getLocal()){ option.setAttribute("selected",'selected'); } } option.appendChild(document.createTextNode(languageList[i].name)); selectLanguage.appendChild(option); } //增加 onchange 事件 if(window.addEventListener){ // Mozilla, Netscape, Firefox selectLanguage.addEventListener('change', onchange,false); }else{ // IE selectLanguage.attachEvent('onchange',onchange); } //将select加入进网页显示 document.getElementById(translate.selectLanguageTag.documentId).appendChild(selectLanguage); } ```` **注意，要放到 translate.execute(); 上面** 其中，这个方法传入的 languageList 参数，便是当前支持的能切换的语种，你可以 console.log(languageList); 打印出来看看。 而且如果你采用不同的翻译通道，这个支持的语种数量也是不一样的。 [不同的翻译通道支持的语种数量可以点此查看](http://translate.zvo.cn/43086.html) 上面代码便是当前 translate.js 中输出 select 语言选择的代码，你可以改成任何你自己想要的效果。 需要 translate.js v3.2.4.20240424 及更高版本

[TOC] ## 使用场景 比如我有一个简体中文的网页，我把它翻译成了繁体中文，文字可以非常方便的自动进行翻译为繁体中文，但是图片中的文字却不会自动进行翻译。 这样翻译之后的网站，在访客看来，图片除了美观外不太具备有可读性。因为图片中的文字没有被翻译，访客看不懂。 本篇介绍的就是如何将图片也一并进行替换为对应语种的图片。 ## 准备工作 网站中有显示图片的地方，比如 : ```` ```` 要针对这个图片进行翻译，比如你要使网页翻译为繁体中文时，这个图片能显示繁体中文对应的图片，你可以将这个图片进行处理，将其中的文字也换成繁体中文，然后传到网上，于是可以得到一个图片的url链接： ```` https://www.zvo.cn/logo.jpg ```` ## 代码示例 这里提供 translate.js 可使用代码，来将图片进行更换为相应语种的图片 ```` translate.images.add({ "/uploads/a.jpg":"https://www.zvo.cn/a_english.jpg", "/uploads/b.jpg":"https://www.zvo.cn/b_english.jpg", }); ```` 参数解释： * 第一个参数，也就是上面代码中的 ````/uploads/a.jpg```` 是要进行替换的原本的图片url，也就是 img 标签中的src的值 * 第二个参数，也就是上面代码中的 ````https://www.zvo.cn/a_english.jpg```` 是要替换为的图片网址，注意要用绝对路径的 如果有多个图片需要替换，那就增加多行即可。 注意，这行要放在 ````translate.execute();```` 之前。 这行代码的意思，是进行切换语言时，会自动检索当前网页中所出现的图片，将第一个参数中的图片网址，自动换为第二个参数中的图片网址，来实现翻译之后的网页，图片也会相应切换的目的。 但是这样直接写死了要切换为哪个图片，会存在你翻译为英文跟翻译为韩语，它都会给你切换为一个固定的图片，这就需要看下面的 **语言变量** 里的说明了，不同的语种，切换相应语种的图片。 ## 语言变量 同一张图，不同的语种，会有不同的翻译之后的图片对应，比如我们做了英语、简体中文、法语 等图片，每个语种都单独做了一个图片，那么针对不同的语种，图片的命名方式可以使用一个变量 {language} 表示当前要显示的语种。 比如这样写： ```` translate.images.add({ "/uploads/a.jpg":"https://www.zvo.cn/a_{language}.jpg", "/uploads/b.jpg":"https://www.zvo.cn/b_{language}.jpg", }); ```` 那么当你有简体中文切换到繁体中文时，/uploads/logo.jpg 这个图片会自动被替换为 https://www.zvo.cn/logo_chinese_simplified.jpg ，当你切换到英语时，图片会自动被替换为 https://www.zvo.cn/logo_english.jpg 这样你只需要制作不同语种的图片，并将其针对不同的语种进行命名上传即可。 用 {language} 来表示当前翻译为的语种，有关{language}的取值，可查阅 http://api.zvo.cn/translate/service/20230807/language.json.html 其中的语言标识id便是  ## 其他说明 在执行了 ````translate.images.add```` 进行追加要翻译替换的图片规则后，你也可以手动执行 ````translate.images.execute()```` 来进行执行图片替换。当然这行只会进行翻译的图片替换而已。 它默认是集成到了 ````translate.execute```` 这个方法中的，所以当执行 ````translate.execute```` 时才会将图片也会一并进行翻译替换。