切换语言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来控制切换语言选择的显示位置及美观。如：
````
````
这就是控制切换语言的 ``
只翻译指定的元素
````
var documents = [];
documents.push(document.getElementById('test1'));
documents.push(document.getElementById('test2'));
documents.push(document.getElementById('test3'));
translate.setDocuments(documents); //指定要翻译的元素的集合,可传入一个或多个元素。如果不设置，默认翻译整个网页
````
可使用 translate.setDocuments(...) 指定要翻译的元素的集合,可传入一个或多个元素。如果不设置此，默认翻译整个网页。
**注意，这行要放到 translate.execute(); 上面**
主动进行语言切换
比如点击某个链接显示英文界面
````
切换为英语
````
只需传入翻译的目标语言，即可快速切换到指定语种。具体有哪些语言，可查阅： [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)
设置本地语种（当前网页的语种）
````
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 及以上版本才支持。
手动调用接口进行翻译操作
通过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对象。
* **第二个参数**: 翻译接口的请求响应是 200 时的处理函数（注意，并不代表翻译成功）。传入如
````function(data){ console.log(data); }````
注意，返回的data.result 为 1，则是翻译成功。 为0则是出错，可通过data.info 得到错误原因。 更详细说明参考： http://api.zvo.cn/translate/service/20230807/translate.json.html
* **第三个参数**: 这里，还可以传入第三个参数，表示翻译接口响应非200时的异常处理。 传入如 :
````function(xhr){ console.log(xhr); }```` 其中 xhr 是 XMLHttpRequest 对象，可以通过 xhr.status 获取响应状态码，通过 xhr.responseText 获取响应内容，通过 xhr.data 获取请求发送的内容 (此参数有 [JackPennnnn](https://github.com/JackPennnnn) 进行贡献补充 )
使用示例：
````
translate.request.translateText({
from:'chinese_simplified',
to:'english',
texts: ['我是翻译的第一句','我是翻译的第二句','我是翻译的第三句']
}, function(data){
//打印翻译结果
if(data.result == 1){
console.log(data); //翻译成功
}else{
console.log('翻译接口出错,错误信息：'+info)
}
}, function(xhr){
//打印翻译失败后的信息
console.log('翻译接口响应失败，响应码：'+xhr.status+', 响应内容：'+xhr.responseText);
});
````
对网页中图片进行翻译
[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```` 时才会将图片也会一并进行翻译替换。
````
要针对这个图片进行翻译，比如你要使网页翻译为繁体中文时，这个图片能显示繁体中文对应的图片，你可以将这个图片进行处理，将其中的文字也换成繁体中文，然后传到网上，于是可以得到一个图片的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```` 时才会将图片也会一并进行翻译替换。
设置默认翻译为的语种
设置第一次使用时，默认以什么语种显示。
比如本地当前语种是简体中文，这里设置为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```` 是放在 ````