更新记录

1.0.0（2026-08-05） 下载此版本

1. 新增开箱即用的 zt-translator 翻译组件。
2. 新增无界面 JavaScript SDK 和 TypeScript 类型声明。
3. 支持自动读取 DCloud AppID 并完成授权校验。
4. 支持 Vue 2、Vue 3、App、Web 和主流小程序。
5. 支持自动识别源语言、多语言互译及自然、正式、简洁三种语气。
6. 新增授权会话缓存、Token 过期自动刷新和失败重试。
7. 新增字符额度统计、错误信息和请求 ID 返回。
8. DeepSeek API Key 仅保存在服务端，不会打包到客户端。
9. 新增完整接入文档和示例项目。

平台兼容性

uni-app(3.8.1)

其他

zt-translator 全端 AI 翻译插件

zt-translator 为传统 uni-app 项目提供可直接使用的文字翻译组件和 JavaScript SDK，支持 Vue 2、Vue 3、H5、App 以及主流小程序。

DeepSeek API Key 始终保存在插件作者的服务端。uni-app 项目只配置人工开通的客户授权 licenseKey，服务端负责 AppID/包名校验、订阅有效期、字符额度和限流。

当前 0.2.x 版本支持文字翻译。图片、文档、音频和视频翻译尚未包含在本版本中。

功能

• zt-translator easycom 完整翻译组件，无需手动注册。
• createTranslator() 无界面 SDK，可接入你自己的页面。
• 自动读取 manifest.json 中的 DCloud AppID。
• App 端自动读取 Android 包名或 iOS Bundle ID。
• 短期会话 Token 自动申请、缓存和过期刷新。
• 相同实例的并发请求共用一次会话申请。
• 自然、正式、简洁三种翻译语气。
• 完整 TypeScript 类型声明。
• 返回服务端 requestId，方便定位请求问题。

运行流程

uni-app 页面或组件
  → 使用 licenseKey + DCloud AppID 申请短期 Token
  → 携带短期 Token 请求文字翻译
  → easydown 服务端校验授权、有效期和剩余额度
  → 服务端调用 DeepSeek
  → 返回译文和本次 Token 用量

客户端不会收到 DeepSeek API Key。

1. 安装

从插件市场导入

1. 在 DCloud 插件市场打开本插件。
2. 点击“使用 HBuilderX 导入插件”。
3. 选择目标 uni-app 项目。
4. 确认项目中存在：

uni_modules/zt-translator/

手工安装

将整个 zt-translator 文件夹复制到项目：

你的项目/uni_modules/zt-translator/

不要只复制 index.js，否则 easycom 组件和类型声明不会一起安装。

2. 获取授权 Key

向插件作者提供：

绿泡泡：zll1987120

🐧:229636060

• 客户名称和联系方式；
• 项目 manifest.json 中的 DCloud AppID，例如 __UNI__ABC1234；
• 如果发布 App，提供 Android 包名和 iOS Bundle ID；
• 需要的有效期和字符额度。

开通后会获得类似下面的授权 Key：

zt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

这里绑定的是 DCloud AppID，不是微信小程序 AppID、支付宝小程序 AppID或微信公众号 AppID。

3. 最简单的组件用法

插件组件符合 easycom 规范，导入插件后不需要在 main.js 注册：

<template>
  <view class="page">
    <zt-translator
      license-key="zt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      initial-source-language="zh-Hans"
      initial-target-language="en"
      @success="onSuccess"
      @error="onError"
    />
  </view>
</template>

<script>
export default {
  methods: {
    onSuccess(result) {
      console.log('译文：', result.translation)
      console.log('请求 ID：', result.requestId)
    },
    onError(error) {
      console.error(error.code, error.message, error.requestId)
    }
  }
}
</script>

服务地址已有默认值：

https://www.easydown.cn/translator-api

一般不需要传 api-base-url。

4. 使用 v-model

组件同时兼容 Vue 2 的 value/input 和 Vue 3 的 modelValue/update:modelValue：

<template>
  <zt-translator
    v-model="sourceText"
    :license-key="licenseKey"
    tone="formal"
  />
</template>

<script>
export default {
  data() {
    return {
      licenseKey: 'zt_live_xxx',
      sourceText: '请把这段文字翻译成英文。'
    }
  }
}
</script>

5. 无界面 SDK 用法

适合将翻译能力接入已有输入框、聊天页面、文章编辑器或业务流程。

建议在项目中创建单例：

// utils/translator.js
import { createTranslator } from '@/uni_modules/zt-translator/js_sdk/index.js'

export const translator = createTranslator({
  licenseKey: 'zt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
})

页面调用：

import { translator } from '@/utils/translator.js'

export default {
  async onLoad() {
    try {
      const result = await translator.translateText({
        text: '语言让我们理解不同的世界。',
        sourceLanguage: 'zh-Hans',
        targetLanguage: 'en',
        tone: 'natural'
      })

      console.log(result.translation)
      console.log(result.model)
      console.log(result.usage.totalTokens)
      console.log(result.requestId)
    } catch (error) {
      console.error(error.code, error.message)
    }
  }
}

6. 无法自动读取 AppID 时

SDK 会先调用 uni.getAppBaseInfo()，不可用时回退到 uni.getSystemInfoSync()。

少数旧版 HBuilderX、特殊宿主或测试环境仍可能无法返回 DCloud AppID，这时显式传入：

const translator = createTranslator({
  licenseKey: 'zt_live_xxx',
  appId: '__UNI__ABC1234',
  packageName: 'com.example.myapp'
})

显式 AppID 必须与管理员后台绑定值完全一致，包括大小写。

7. SDK 配置

createTranslator(options)

旧版 projectKey 参数暂时兼容，但已废弃，新项目必须使用 licenseKey。

8. translateText() 参数

await translator.translateText({
  text: 'Hello',
  sourceLanguage: 'en',
  targetLanguage: 'zh-Hans',
  tone: 'natural'
})

语言代码不限制为组件内置列表，可以传符合业务需要的明确名称或 BCP 47 风格代码：

targetLanguage: 'nl'       // 荷兰语
targetLanguage: 'pl'       // 波兰语
targetLanguage: 'zh-Hant'  // 繁体中文

9. 翻译结果

{
  requestId: 'req-xxx',
  translation: 'Hello, world.',
  sourceLanguage: 'zh-Hans',
  targetLanguage: 'en',
  model: 'deepseek-v4-flash',
  usage: {
    promptTokens: 12,
    completionTokens: 4,
    totalTokens: 16,
    cacheHitTokens: 0
  }
}

字符订阅额度按照传入原文字符数扣减；usage 是模型 Token 用量，两者不是同一个计量单位。

10. SDK 方法

短期 Token 仅保存在当前 JavaScript 内存，不会写入 Storage。

11. 组件属性

12. 组件事件

可以通过 ref 主动调用组件翻译：

<zt-translator ref="translatorView" :license-key="licenseKey" />

const result = await this.$refs.translatorView.translate()

13. 常见错误码

异常类型：

import { TranslatorError } from '@/uni_modules/zt-translator/js_sdk/index.js'

try {
  await translator.translateText(...)
} catch (error) {
  if (error instanceof TranslatorError) {
    console.log(error.code)
    console.log(error.statusCode)
    console.log(error.requestId)
    console.log(error.details)
  }
}

14. 各端网络配置

H5

• 正式页面必须使用 HTTPS。
• 插件作者需要把你的 H5 Origin 加入服务端 CORS 白名单。
• localhost 与正式域名属于不同 Origin，需要分别登记。

微信、支付宝、百度、抖音等小程序

在对应小程序管理后台将以下域名加入“request 合法域名”：

https://www.easydown.cn

开发工具中的“不校验合法域名”只适合本地调试，正式发布前必须配置白名单。

App

• Android/iOS 正式包必须使用绑定的包名。
• iOS 首次安装后，用户同意联网权限前请求可能失败。
• 如果管理员没有绑定包名，服务端只校验 DCloud AppID。

15. 安全说明

• 绝对不要把 DeepSeek API Key 放进 manifest.json、config.js、页面代码或插件配置。
• licenseKey 是客户授权标识，不是不可提取的服务端密码；编译后的前端代码和网络请求中可能看到它。
• 即使 Key 被提取，服务端仍会用 AppID、包名、订阅有效期、字符额度和限流控制成本。
• 如果怀疑 Key 泄漏，让管理员执行“重置 Key”，旧 Key 会立即失效。
• 不要把管理员账号或管理员接口交给插件使用者。

16. 隐私与数据

为了完成翻译，插件会向 https://www.easydown.cn/translator-api 发送：

• 待翻译文字；
• 源语言和目标语言；
• DCloud AppID；
• 运行平台；
• App 包名（可读取时）。

服务端授权数据库保存客户授权、有效期和累计字符用量，不保存待翻译正文。服务运行日志会记录 AppID、语言方向、字符数、模型和 Token 用量，用于额度、安全和故障排查。

17. 发布前检查

• [ ] manifest.json 已填写正式 DCloud AppID。
• [ ] 管理员后台已绑定同一个 AppID。
• [ ] App 包名与后台绑定值一致。
• [ ] 小程序后台已加入 request 合法域名。
• [ ] H5 正式 Origin 已加入 CORS 白名单。
• [ ] 页面只配置 licenseKey，没有任何 DeepSeek Key。
• [ ] 已处理 SUBSCRIPTION_EXPIRED、QUOTA_EXCEEDED 等用户提示。
• [ ] 已在准备发布的真实平台运行测试。

18. 兼容性说明

本插件基于 uni.request，不依赖浏览器 Cookie，不依赖 Node.js 包，不申请相机、相册、录音或定位权限。

uni_modules 中的组件符合 easycom 目录规范；SDK 可以通过 @/uni_modules/zt-translator/js_sdk/index.js 直接导入。

相关官方文档：

• uni_modules 规范
• uni.request
• uni.getAppBaseInfo
• uni.getSystemInfoSync