基于 HTTP 协议开发 Telegram 翻译机器人

• 1. 简介
• 2. 协议支持
• 3. 配置 Telegram 机器人
  • 3.1 创建 Telegram 机器人
  • 3.2 设置 Webhook 地址
• 4. 提示词配置
  • 4.1 提示词说明
• 5. 开发实现
  • 5.1 TranslateAdminAppConfig
  • 5.2 TranslatorTextVo 类
  • 5.3 TranslatorService
  • 5.4 测试类
• 6. Tio Boot 整合 Telegram Bot
  • 6.1 配置 Telegram Bot Token
  • 6.2 TelegramBotConfig 类
  • 6.3 TelegramWebhookController 类
• 7. 测试翻译功能
  • 7.1 测试步骤
  • 7.2 示例
• 8. 总结
• 9. 开源地址

本文档旨在指导开发者如何使用 HTTP 协议开发一个具有翻译功能的 Telegram 机器人。文中详细描述了机器人的创建、Webhook 配置、翻译提示词编写、翻译服务的实现以及 Tio Boot 与 Telegram Bot 的整合，同时附有完整的 Java 代码示例，便于开发者参考与实践。

---

1. 简介

Telegram 机器人是一种运行在 Telegram 平台上、能够与用户进行即时交互的自动化应用程序。通过借助 HTTP 协议与 Webhook 技术，机器人能及时接收用户消息，并做出响应。本指南主要介绍如何搭建一个具备自动语言检测和翻译功能的 Telegram 机器人，涵盖了以下关键点：

• HTTP 协议支持：主要通过 Webhook 与服务器通信；
• 提示词配置：为翻译模型提供明确的翻译指令；
• 翻译服务实现：包括文本拆分、缓存管理、翻译请求构造等；
• Tio Boot 整合：实现 Telegram Bot 的注册与高效管理。

---

2. 协议支持

Telegram 机器人开发支持两种主要协议：

1. HTTP 协议
   通过 Webhook 方式接收和发送消息，此方案适用于大多数业务场景，配置简单、部署灵活。

2. MTProto 协议
   Telegram 自有的专用通信协议，适用于对性能和安全性要求较高的场景。

本项目主要使用 HTTP 协议 进行开发，利用 Webhook 接收客户端请求，再将翻译结果返回给用户。

---

3. 配置 Telegram 机器人

在正式开发之前，需要完成以下两个步骤的配置：

3.1 创建 Telegram 机器人

首先，通过 Telegram 内的 BotFather 创建一个新的机器人，并获取相应的 API Token。该 Token 是后续调用 Telegram 接口的凭证。

3.2 设置 Webhook 地址

配置机器人的 Webhook 地址，使 Telegram 能够将用户消息推送到您的服务器。请确保服务器支持 HTTPS 访问，并且 Webhook 地址可被外部访问。详细配置步骤参见如下文档链接：

设置 Webhook

---

4. 提示词配置

为了实现高质量的翻译功能，我们需要定义一个提示词文件 src/main/resources/prompts/translator_prompt.txt。该文件用于指导翻译模型如何执行翻译操作。具体内容如下：

You are a helpful translator.
- Please translate the following #(src_lang) into #(dst_lang).
- Preserve the format of the source content during translation.
- Do not provide any explanations or text apart from the translation.

source text:
#(source_text)

4.1 提示词说明

• src_lang：表示源语言（例如 "Chinese"）。
• dst_lang：表示目标语言（例如 "English"）。
• source_text：需要翻译的文本内容。

这段提示词指示翻译模型仅返回纯粹的翻译结果，不添加额外的解释或说明，从而保证最终输出的内容格式与源文保持一致。

---

5. 开发实现

接下来介绍项目中关键的 Java 类和方法，详细说明各个模块的作用及工作流程。

5.1 TranslateAdminAppConfig

该类用于初始化 Tio Boot Admin 后台的数据库配置，以便系统能正确管理和存储翻译记录。

package com.litongjava.gpt.translator.config;

import com.litongjava.annotation.AConfiguration;
import com.litongjava.annotation.Initialization;
import com.litongjava.tio.boot.admin.config.TioAdminDbConfiguration;

@AConfiguration
public class TranslateAdminAppConfig {

  @Initialization
  public void config() {
    new TioAdminDbConfiguration().config();
  }
}

说明：
通过 @AConfiguration 与 @Initialization 注解实现自动配置，在应用启动时调用 config() 方法，从而完成后台数据库管理模块的初始化设置。

5.2 TranslatorTextVo 类

用于封装翻译请求的关键信息，包括源文本、源语言和目标语言。

package com.litongjava.gpt.translator.vo;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class TranslatorTextVo {
  // 例如："今天的任务你完成了吗?", Chinese, English
  private String srcText, srcLang, destLang;
}

说明：
此类利用 Lombok 自动生成 getter、setter、无参及全参构造函数，确保代码简洁，同时使数据传输更加便捷。

5.3 TranslatorService

这是整个项目最核心的类，负责以下工作：

• 翻译请求构建与处理
  利用 JFinal 模板引擎加载提示词文件，并填充源语言、目标语言及要翻译的文本，构造出发送给翻译模型的完整提示信息。
• 缓存机制
  通过 MD5 值检查是否存在翻译缓存，避免重复调用翻译模型，从而提高效率。
• 文本拆分
  若输入文本超过最大令牌数限制，则会根据 Markdown 结构或通过递归二分法对文本进行拆分，保证每次请求的文本长度在合理范围内。
• 记录翻译信息
  翻译过程的详细信息（如耗时、使用的令牌数量等）会被保存到数据库中，便于后续统计和分析。

以下是完整的代码示例：

package com.litongjava.gpt.translator.services;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import com.jfinal.template.Template;
import com.litongjava.db.activerecord.Db;
import com.litongjava.db.activerecord.Row;
import com.litongjava.gemini.GeminiClient;
import com.litongjava.gemini.GoogleGeminiModels;
import com.litongjava.gpt.translator.constant.TableNames;
import com.litongjava.gpt.translator.vo.TranslatorTextVo;
import com.litongjava.template.PromptEngine;
import com.litongjava.tio.utils.crypto.Md5Utils;
import com.litongjava.tio.utils.snowflake.SnowflakeIdUtils;
import com.litongjava.utils.TokenUtils;

public class TranslatorService {

  // Define the maximum number of tokens per request
  private static final int MAX_TOKENS_PER_REQUEST = 1048576 / 3;

  /**
   * Translate method that handles splitting the text if it exceeds the token limit.
   */
  public String translate(String chatId, TranslatorTextVo translatorTextVo) {
    String srcText = translatorTextVo.getSrcText();
    String md5 = Md5Utils.getMD5(srcText);
    Row record = Db.findColumnsById(TableNames.max_kb_sentence_tanslate_cache, "dst_text", "md5", md5);
    String dstText = null;
    if (record != null) {
      dstText = record.getStr("dst_text");
      if (dstText != null) {
        return dstText;
      }
    }

    // Split the srcText into chunks if necessary
    int countTokens = TokenUtils.countTokens(srcText);
    StringBuilder translatedBuilder = new StringBuilder();
    long totalStart = System.currentTimeMillis();
    if (countTokens > MAX_TOKENS_PER_REQUEST) {
      List<String> textChunks = splitTextIntoChunks(srcText, countTokens, MAX_TOKENS_PER_REQUEST);

      for (String chunk : textChunks) {
        TranslatorTextVo chunkVo = new TranslatorTextVo();
        chunkVo.setSrcLang(translatorTextVo.getSrcLang());
        chunkVo.setDestLang(translatorTextVo.getDestLang());
        chunkVo.setSrcText(chunk);

        long start = System.currentTimeMillis();
        String translatedChunk = this.translate(chunkVo);
        translatedBuilder.append(translatedChunk);
        long end = System.currentTimeMillis();

        // save each chunk's translation to the cache
        saveTranslation(chatId, translatorTextVo, chunk, translatedChunk, end - start);
      }
    } else {
      TranslatorTextVo chunkVo = new TranslatorTextVo();
      chunkVo.setSrcLang(translatorTextVo.getSrcLang());
      chunkVo.setDestLang(translatorTextVo.getDestLang());
      chunkVo.setSrcText(srcText);

      String translatedChunk = this.translate(chunkVo);

      translatedBuilder.append(translatedChunk);

    }

    long totalEnd = System.currentTimeMillis();
    String finalTranslatedText = translatedBuilder.toString().trim();

    // Optionally, save the combined translation to the cache
    saveCombinedTranslation(chatId, translatorTextVo, srcText, finalTranslatedText, totalEnd - totalStart);

    return finalTranslatedText;
  }

  /**
   * Helper method to split text into chunks based on the maximum token limit.
   */
  /**
   * Splits text into chunks based on the maximum token limit using a recursive binary splitting approach.
   * This method prioritizes splitting by Markdown structure (e.g., paragraphs) to preserve formatting.
   */
  public List<String> splitTextIntoChunks(String text, int tokenCount, int maxTokens) {
    List<String> chunks = new ArrayList<>();
    splitRecursive(text, tokenCount, maxTokens, chunks);
    return chunks;
  }

  private void splitRecursive(String text, int tokenCount, int maxTokens, List<String> chunks) {
    if (tokenCount <= maxTokens) {
      chunks.add(text.trim());
      return;
    }

    // Attempt to split by Markdown paragraphs
    String[] paragraphs = text.split("\n{2,}");
    if (paragraphs.length > 1) {
      for (String para : paragraphs) {
        splitRecursive(para, tokenCount, maxTokens, chunks);
      }
      return;
    }

    // Attempt to split by Markdown headings
    String[] headings = text.split("(?m)^#{1,6} ");
    if (headings.length > 1) {
      for (String section : headings) {
        // Add the heading back since split removes the delimiter
        String trimmedSection = section.trim();
        if (!trimmedSection.startsWith("#")) {
          trimmedSection = "#" + trimmedSection;
        }
        splitRecursive(trimmedSection, tokenCount, maxTokens, chunks);
      }
      return;
    }

    // If unable to split by structure, perform binary split
    int mid = text.length() / 2;
    // Ensure we split at a whitespace to avoid breaking words
    while (mid < text.length() && !Character.isWhitespace(text.charAt(mid))) {
      mid++;
    }
    if (mid == text.length()) {
      // No whitespace found; force split
      mid = text.length() / 2;
    }

    String firstHalf = text.substring(0, mid);
    String secondHalf = text.substring(mid);

    splitRecursive(firstHalf, tokenCount, maxTokens, chunks);
    splitRecursive(secondHalf, tokenCount, maxTokens, chunks);
  }

  /**
   * Save each chunk's translation to the cache.
   */
  private void saveTranslation(String chatId, TranslatorTextVo originalVo, String srcChunk, String dstChunk, long elapsed) {
    String md5 = Md5Utils.getMD5(srcChunk);
    long id = SnowflakeIdUtils.id();
    Row saveRecord = Row.by("id", id).set("md5", md5).set("from", "telegram").set("user_id", chatId)
        //
        .set("src_lang", originalVo.getSrcLang()).set("src_text", srcChunk)
        //
        .set("dst_lang", originalVo.getDestLang()).set("dst_text", dstChunk).set("elapsed", elapsed);
    ;
    //
    Db.save(TableNames.max_kb_sentence_tanslate_cache, saveRecord);
  }

  /**
   * Optionally save the combined translation to the cache.
   */
  private void saveCombinedTranslation(String chatId, TranslatorTextVo originalVo, String srcText, String dstText, long elapsed) {
    String md5 = Md5Utils.getMD5(srcText);
    long id = SnowflakeIdUtils.id();
    Row saveRecord = Row.by("id", id).set("md5", md5).set("from", "telegram").set("user_id", chatId)
        //
        .set("src_lang", originalVo.getSrcLang()).set("src_text", srcText)
        //
        .set("dst_lang", originalVo.getDestLang()).set("dst_text", dstText).set("elapsed", elapsed);
    Db.save(TableNames.max_kb_sentence_tanslate_cache, saveRecord);
  }

  /**
   * Original translate method that translates a single chunk.
   */
  public String translate(TranslatorTextVo translatorTextVo) {
    String srcLang = translatorTextVo.getSrcLang();
    String destLang = translatorTextVo.getDestLang();
    String srcText = translatorTextVo.getSrcText();

    Template template = PromptEngine.getTemplate("translator_prompt.txt");
    Map<String, String> values = new HashMap<>();

    values.put("src_lang", srcLang);
    values.put("dst_lang", destLang);
    values.put("source_text", srcText);

    String prompt = template.renderToString(values);
    String response = GeminiClient.chatWithModel(GoogleGeminiModels.GEMINI_2_0_FLASH_EXP, "user", prompt);
    return response;
  }
}

说明：

1. 缓存机制：方法首先计算输入文本的 MD5 值，检查数据库缓存，若已有翻译记录则直接返回结果；
2. 文本拆分：当文本超出模型令牌限制时，通过递归方法按 Markdown 段落或标题进行拆分，确保每个子块在合理范围内；
3. 提示词渲染：通过 JFinal 模板引擎加载 translator_prompt.txt 并填充相关变量，生成完整的提示内容发送至翻译模型；
4. 翻译记录保存：分别保存各块及整体翻译记录，便于后续数据统计和重复请求的快速响应。

5.4 测试类

以下测试类用于验证 TranslatorService 的正确性，通过单元测试来确保翻译功能的有效性。

package com.litongjava.gpt.translator.services;

import org.junit.Test;

import com.litongjava.gpt.translator.config.TranslateAdminAppConfig;
import com.litongjava.gpt.translator.vo.TranslatorTextVo;
import com.litongjava.jfinal.aop.Aop;
import com.litongjava.tio.boot.testing.TioBootTest;
import com.litongjava.tio.utils.environment.EnvUtils;

public class TranslatorServiceTest {

  @Test
  public void translate() {
    EnvUtils.load();
    TranslatorTextVo translatorTextVo = new TranslatorTextVo();
    translatorTextVo.setDestLang("English").setSrcLang("Chinese").setSrcText("今天天气怎么样");
    String translate = Aop.get(TranslatorService.class).translate(translatorTextVo);
    System.out.println(translate); //How is the weather today?
  }

  @Test
  public void translateWithTelegram() {
    TioBootTest.runWith(TranslateAdminAppConfig.class);
    TranslatorTextVo translatorTextVo = new TranslatorTextVo();
    translatorTextVo.setDestLang("English").setSrcLang("Chinese").setSrcText("今天天气怎么样,亲");
    String translate = Aop.get(TranslatorService.class).translate("001", translatorTextVo);
    System.out.println(translate); //How is the weather today?
  }
}

说明：
测试类中包含两种调用方式：

• 第一种直接调用 translate 方法，不涉及 Telegram 上下文；
• 第二种通过传入模拟的 chatId 测试结合 Telegram 环境的翻译请求。

---

6. Tio Boot 整合 Telegram Bot

本节详细讲解如何将翻译服务与 Telegram Bot 进行整合，借助 Tio Boot 实现消息接收与响应。

6.1 配置 Telegram Bot Token

在 app.properties 文件中加入如下配置：

telegram.bot.token=

说明：请将上述配置项的值替换为您在 BotFather 获取到的 Telegram Bot API Token。

6.2 TelegramBotConfig 类

该类负责初始化 Telegram Bot，加载 Token，并注册至 Telegram 管理类中，同时配置销毁钩子函数以保证资源释放。

package com.litongjava.gpt.translator.config;
import com.litongjava.annotation.AConfiguration;
import com.litongjava.annotation.Initialization;
import com.litongjava.hook.HookCan;
import com.litongjava.tio.utils.environment.EnvUtils;
import com.litongjava.tio.utils.telegram.Telegram;
import com.litongjava.tio.utils.telegram.TelegramBot;

@AConfiguration
public class TelegramBotConfig {

  @Initialization
  public void config() {
    String botToken = EnvUtils.getStr("telegram.bot.token");
    // 创建一个 Telegram bot 实例
    TelegramBot bot = new TelegramBot(botToken);
    // 将 bot 添加到 Telegram 管理类中
    Telegram.addBot(bot);

    // 添加销毁方法，确保在应用关闭时清理资源
    HookCan.me().addDestroyMethod(() -> {
      Telegram.clearBot();
    });
  }
}

说明：

1. 从环境变量中获取机器人 Token，并据此创建 TelegramBot 实例；
2. 注册到 Telegram 管理类中，方便后续消息发送；
3. 配置销毁方法，避免应用关闭时残留资源。

6.3 TelegramWebhookController 类

TelegramWebhookController 用于处理 Telegram 推送来的 Webhook 请求，解析消息内容，调用翻译服务后将结果返回给用户。

package com.litongjava.gpt.translator.controller;

import com.alibaba.fastjson2.JSONObject;
import com.litongjava.annotation.RequestPath;
import com.litongjava.gpt.translator.services.TranslatorService;
import com.litongjava.gpt.translator.vo.TranslatorTextVo;
import com.litongjava.jfinal.aop.Aop;
import com.litongjava.tio.boot.http.TioRequestContext;
import com.litongjava.tio.http.common.HttpRequest;
import com.litongjava.tio.http.common.HttpResponse;
import com.litongjava.tio.utils.json.FastJson2Utils;
import com.litongjava.tio.utils.telegram.Telegram;

import lombok.extern.slf4j.Slf4j;

@Slf4j
@RequestPath("/telegram")
public class TelegramWebhookController {

  @RequestPath("/webhook")
  public HttpResponse handleTelegramWebhook(HttpRequest request) {
    String bodyString = request.getBodyString();

    JSONObject jsonObject = FastJson2Utils.parseObject(bodyString);
    JSONObject message = jsonObject.getJSONObject("message");

    JSONObject chat = message.getJSONObject("chat");
    String chatId = chat.getString("id");

    String text = message.getString("text");
    log.info("Received text: {}", text);

    // 根据文本内容设置源语言和目标语言
    String srcLang;
    String destLang;

    if (containsChinese(text)) {
      srcLang = "Chinese";
      destLang = "English";
    } else {
      srcLang = "English";
      destLang = "Chinese";
    }

    // 创建翻译请求对象
    TranslatorTextVo translatorTextVo = new TranslatorTextVo();
    translatorTextVo.setSrcText(text);
    translatorTextVo.setSrcLang(srcLang);
    translatorTextVo.setDestLang(destLang);
    String responseText;
    try {
      // 调用翻译服务
      responseText=Aop.get(TranslatorService.class).translate(chatId,translatorTextVo);
    } catch (Exception e) {
      log.error("Exception", e);
      responseText = "Exception: " + e.getMessage();
    }

    // 发送翻译结果回 Telegram
    Telegram.use().sendMessage(chatId.toString(), responseText);
    return TioRequestContext.getResponse();
  }

  /**
   * 判断文本中是否包含中文字符
   *
   * @param text 输入的文本
   * @return 如果包含中文字符则返回 true，否则返回 false
   */
  private boolean containsChinese(String text) {
    if (text == null || text.isEmpty()) {
      return false;
    }
    // 使用正则表达式检查是否包含中文字符
    return text.matches(".*[\\u4e00-\\u9fa5]+.*");
  }
}

说明：

1. 控制器通过 /telegram/webhook 路径接收来自 Telegram 的 Webhook 消息；
2. 解析 JSON 数据，提取聊天 ID 和文本内容；
3. 利用正则表达式判断文本是否包含中文，自动设置源语言和目标语言；
4. 调用 TranslatorService 获取翻译结果，并使用 Telegram API 发送回复。

---

7. 测试翻译功能

完成开发及配置后，即可部署服务器并设置正确的 Webhook 地址，通过 Telegram 与机器人进行交互测试翻译功能。

7.1 测试步骤

1. 启动服务器：确保服务器正常运行，并且 Webhook 地址已正确配置；
2. 与机器人对话：在 Telegram 搜索您的机器人并发送需要翻译的文本消息；
3. 查看翻译结果：机器人自动检测文本语言，并返回翻译后的内容给用户。

7.2 示例

• 用户发送：你好，世界！
  机器人回复：Hello, World!

• 用户发送：Good morning!
  机器人回复：早上好！

---

8. 总结

本文档详细介绍了如何使用 HTTP 协议开发一个具备翻译功能的 Telegram 机器人。通过以下几个步骤，您可以快速上手该项目：

• 创建机器人 & 配置 Webhook：使用 BotFather 创建机器人并正确设置 Webhook 地址；
• 编写提示词 & 翻译服务：定义翻译提示词，通过 Java 实现翻译服务，包括文本拆分、缓存管理与调用翻译模型；
• 整合 Tio Boot 与 Telegram Bot：利用 Tio Boot 构建整合方案，实现消息的自动接收与回复。

项目提供了详细的代码示例与测试用例，开发者可根据自身需求进行扩展与定制。如果在开发过程中遇到问题，请参考相关文档或社区支持，持续完善您的翻译机器人。

---

9. 开源地址

项目的完整代码托管在 GitHub 上，欢迎访问、参考和体验：
https://github.com/litongjava/max-translator-bot
体验翻机器人：@maxtranslatorbot