@translation-master/node

Node.js 翻译库，基于 Transformers.js，使用 ONNX Runtime（CPU）。

安装

pnpm add @translation-master/node @huggingface/transformers

快速开始

import { Translator } from '@translation-master/node'

const translator = new Translator()

const result = await translator.translate('Hello world', { to: 'zh' })
console.log(result.text) // '你好，世界'

await translator.dispose()

API

Translator

new Translator(options?: TranslatorOptions)

在核心 Translator 基础上扩展了 Node.js 默认配置：

• device 默认为 'cpu'（使用 onnxruntime-node）
• transformersLoader 自动设置为 import('@huggingface/transformers')

TranslatorOptions：

| 选项 | 类型 | 默认值 | 说明 | |---|---|---|---| | device | 'auto' \| 'wasm' \| 'webgpu' \| 'cpu' | 'cpu' | 推理后端 | | dtype | 'fp32' \| 'fp16' \| 'q8' \| 'q4' | 自动 | 量化精度 | | models | ModelConfig[] | 内置 | 自定义模型配置 | | maxPoolSize | number | 3 | 同时加载的最大模型数 | | autoDetect | boolean | true | 自动检测源语言 | | modelBaseUrl | string | - | 自定义模型文件基础 URL | | debug | boolean | false | 启用调试模式 |

方法：

| 方法 | 返回值 | 说明 | |---|---|---| | translate(text, options) | Promise<TranslateResult> | 翻译单个文本 | | translateBatch(texts, options) | Promise<TranslateResult[]> | 批量翻译多个文本 | | detect(text) | { lang, confidence } | 检测文本语言 | | preload(from, to) | Promise<void> | 预加载指定语言对的模型 | | unload(from, to) | Promise<void> | 卸载指定语言对的模型 | | getSupportedLanguages() | LanguageInfo[] | 获取支持的语言列表 | | clearCache() | void | 清空内存中的翻译结果缓存 | | dispose() | Promise<void> | 释放所有模型和缓存 | | stats() | PoolStats | 获取模型池统计信息 |

批量翻译

const translator = new Translator()

const results = await translator.translateBatch(
  ['Hello', 'World', 'How are you?'],
  { to: 'zh' },
)

for (const r of results) {
  console.log(r.text)
}
// 你好
// 世界
// 你好吗？

await translator.dispose()

预加载模型

const translator = new Translator()

// 预加载模型，首次 translate() 调用会更快
await translator.preload('en', 'zh')

const result = await translator.translate('Hello', { to: 'zh' })
await translator.dispose()

自定义模型

const translator = new Translator({
  models: [
    {
      id: 'custom/my-model',
      type: 'opus-mt',
      pairs: [{ from: 'es', to: 'pt' }],
      priority: 0,
    },
  ],
})

自定义模型源

const translator = new Translator({
  modelBaseUrl: '/path/to/local/models',
})

模型文件必须遵循 HuggingFace 目录结构：

{modelBaseUrl}/Xenova/opus-mt-zh-en/resolve/main/model.onnx
{modelBaseUrl}/Xenova/opus-mt-zh-en/resolve/main/tokenizer.json
{modelBaseUrl}/Xenova/opus-mt-zh-en/resolve/main/config.json

文件缓存

import { FileCacheAdapter } from '@translation-master/node'

const cache = new FileCacheAdapter('./my-cache')
// 将缓存的模型数据存储为指定目录中的文件
// 使用 SHA-256 哈希文件名，.cache 扩展名

事件

translator.events.on('modelLoad', (e) => {
  console.log(`[${e.state}] ${e.modelId} ${e.progress}%`)
})

translator.events.on('translate', (e) => {
  console.log(`${e.from}→${e.to}: "${e.text}" → "${e.result}" (${e.duration}ms)`)
})

translator.events.on('error', (e) => {
  console.error(e.message)
})

工具函数

import {
  detectLanguage,
  getSupportedLanguages,
  ModelRouter,
} from '@translation-master/node'

// 语言检测
detectLanguage('你好世界') // { lang: 'zh', confidence: 0.8 }

// 支持的语言
const langs = getSupportedLanguages()
console.log(langs.map(l => l.code)) // ['en', 'zh', 'ja', 'ko', ...]

错误

| 错误 | 触发条件 | |---|---| | UnsupportedLanguagePairError | 没有模型支持该语言对 | | ModelLoadError | 模型加载失败 | | TranslationTimeoutError | 翻译超时 | | DeviceNotAvailableError | 请求的设备不可用 | | OutOfMemoryError | 内存不足以加载模型 |

架构

@translation-master/node
├── translator.ts   # Node Translator（继承 core，默认 CPU）
├── cache.ts        # FileCacheAdapter（基于文件系统）
└── env.ts          # isNode() 检测

继承关系

@translation-master/core  Translator
         │
         └── @translation-master/node  Translator
               ├── device 默认为 'cpu'（onnxruntime-node）
               └── transformersLoader 自动配置

许可证

MIT License