简体中文 | English | Español | 日本語 | 한국어 | Русский | Français | Deutsch
Tranzy.js 是一个专业的网页国际化解决方案，让开发者能够轻松地为网站添加多语言支持。它提供了自动翻译、手动翻译词典、DOM变化监听等核心功能，同时内置了微软翻译API作为可选的翻译服务。
- 🚀 零配置即可使用，自动从浏览器语言设置获取目标语言
- 🛠️ 提供灵活的配置选项，满足各种定制需求
- 🔌 支持自定义翻译函数，可轻松替换默认翻译服务
- 📝 提供丰富的钩子函数，方便进行自定义处理
- ⚡ 使用 IndexedDB 进行翻译缓存，减少重复翻译
- 📦 支持批量翻译，提高翻译效率
- 🔄 智能的DOM变化监听，只翻译新增内容
- 💾 自动管理翻译缓存，优化内存使用
- 🌐 自动检测DOM变化并翻译新增内容
- 📚 支持手动翻译词典和术语处理
- 🎯 支持强制翻译和忽略特定元素
- 🔍 支持语言检测和浏览器语言识别
- 🎨 支持自定义翻译样式和标记类
- 🔄 可随时开启/关闭DOM监听
- 📱 支持动态加载的内容翻译
- 🌍 支持多种语言和BCP 47语言代码
使用 npm 安装：
npm install tranzy或者使用 pnpm 安装：
pnpm add tranzyimport Tranzy from 'tranzy';
// 只需三行代码，即可自动将网站翻译为浏览器当前语言
const tranzy = new Tranzy();
tranzy.translatePage(); // 翻译整个页面
tranzy.startObserver(); // 监听DOM变化，自动翻译新内容<!-- 引入UMD版本的Tranzy -->
<script src="path/to/tranzy.umd.js"></script>
<script>
// 只需三行代码，即可自动将网站翻译为浏览器当前语言
const tranzy = new Tranzy.Translator();
tranzy.translatePage(); // 翻译整个页面
tranzy.startObserver(); // 监听DOM变化，自动翻译新内容
</script>如果需要更精细的控制，Tranzy还提供了丰富的配置选项：
import Tranzy from 'tranzy';
// 创建带有高级配置的Tranzy实例
const tranzy = new Tranzy({
toLang: 'zh-Hans', // 目标语言
fromLang: 'en', // 源语言（可选）
ignore: ['.no-translate'], // 忽略的选择器列表
force: ['.must-translate'], // 强制翻译的选择器列表（优先级高于ignore）
manualDict: { // 手动翻译词典
'zh-Hans': {
'Tranzy': '全译'
}
},
beforeTranslate: () => { // 翻译开始前的钩子
console.log('开始翻译');
},
afterTranslate: () => { // 翻译结束后的钩子
console.log('翻译完成');
}
});
tranzy.translatePage();
tranzy.startObserver();注意： 当
fromLang和toLang相同时，translatePage()和startObserver()会自动跳过翻译过程。
Tranzy默认已经配置了以下元素不进行翻译：
// 这些元素及其内容默认不会被翻译
const DEFAULT_IGNORE_SELECTORS = [
'style', // 样式标签
'script', // 脚本标签
'noscript', // 无脚本标签
'kbd', // 键盘输入标签
'code', // 代码标签
'pre', // 预格式化文本标签
'input', // 输入框
'textarea', // 文本域
'[contenteditable="true"]', // 可编辑元素
'.tranzy-ignore' // 自定义忽略类
];您可以通过配置ignore选项添加更多忽略选择器，但使用force选择器可以覆盖忽略规则，因为force的优先级高于ignore。
// ES6模式
import Tranzy from 'tranzy';
const tranzy = new Tranzy({
// 忽略特定元素
ignore: [
'.no-translate', // 忽略特定类
'#header', // 忽略特定ID
'[data-no-trans]' // 忽略特定属性
],
// 强制翻译特定元素
force: [
'.must-translate', // 强制翻译特定类
'#content' // 强制翻译特定ID
]
});// ES6模式
import Tranzy from 'tranzy';
const tranzy = new Tranzy({
toLang: 'zh-Hans',
manualDict: {
// 全局词典，适用于所有目标语言
'all': {
// 品牌名称、专有名词等不需要翻译的词汇
'tranzy': {
to: 'tranzy', // 保证首字母大小写保持不变
standalone: false, // 在句子中也进行匹配
},
'Tranzy': {
to: 'Tranzy', // 大写形式也保持不变
standalone: false, // 在句子中也进行匹配
},
// 简化形式，默认 standalone: true, case: true
'Copyright': 'Copyright'
},
// 特定语言的词典
'zh-Hans': {
// 完整形式
'Hello World': {
to: '你好，世界',
},
// 简化形式
'JavaScript': 'JavaScript (JS脚本语言)',
// 支持正则表达式形式的匹配
'\\d+ years old': {
to: '岁',
},
'tranzy': {
to: '全译', // 中文特别处理为"全译"
standalone: false, // 在句子中也进行匹配
case: false // 忽略大小写
}
}
}
});注意： 特定语言的词典条目（如'zh-Hans'）优先级高于全局词典('all')中的同名条目。这种设计使得您可以在全局词典中定义通用翻译，同时在特定语言中进行个性化覆盖，增强了翻译的灵活性和精确性。
// ES6模式
import Tranzy from 'tranzy';
const tranzy = new Tranzy({
// 翻译开始前的钩子
beforeTranslate: () => {
console.log('开始翻译');
},
// 翻译结束后的钩子
afterTranslate: () => {
console.log('翻译完成');
}
});// 在动态加载内容后手动触发翻译
const loadContent = () => {
loadDynamicContent();
tranzy.translatePage('.dynamic-content'); // 可以指定要翻译的元素，不传则默认翻译body
};除了核心的多语言功能外，Tranzy 还内置了微软翻译API，提供以下功能：
import { translateText, detectLang, getSupportedLangs, getBrowserLang } from 'tranzy';
// 翻译文本
const result = await translateText(['Hello world'], 'zh-Hans', 'en');
console.log(result); // ['你好世界']
// 检测语言
const langResult = await detectLang('Hello world');
console.log(langResult); // [{ language: 'en', score: 1.0, isTranslationSupported: true, isTransliterationSupported: true }]
// 获取支持的语言列表
const langs = await getSupportedLangs('zh-Hans');
console.log(langs); // { en: { name: '英语', nativeName: 'English', dir: 'ltr' }, ... }
// 获取浏览器语言对应的支持语言代码
const browserLang = await getBrowserLang();
console.log(browserLang); // 'zh-Hans' 或 'en' 等// ES6模式
import Tranzy from 'tranzy';
const tranzy = new Tranzy({
toLang: 'zh-Hans',
// 使用自定义翻译函数
translateFn: async (texts, toLang, fromLang) => {
// 实现自定义翻译逻辑
return texts.map(text => `[${toLang}] ${text}`);
}
});Fts Cloud ftsuperb@vip.qq.com
MIT
https://github.com/FtsCloud/Tranzy
Copyright (c) 2025-present Fts Cloud