KOReader Custom Translation Backend Plugin

项目地址 https://github.com/Tokisaki-Galaxy/kindle-koreader-custom-translator

背景

KOReader 原生 Google 翻译接口在部分网络环境下不可达。为保持自动检测、拼音/罗马音等原生体验，提供自定义后端替换方案。

默认使用Cloudflare Worker 上的AI模型@cf/meta/m2m100-1.2b进行翻译，如果需要可以通过自建方式，自行更换成其他模型，或提升速率限制。

核心思路

• 自定义端点：CUSTOM_ENDPOINT 指向 translate.api.tokisaki.top，可选代理 translate-proxy.api.tokisaki.top，但是代理可能会有延迟。
• 语言映射：SUPPORTED_LANGUAGES 覆盖 249 种语言。
• 配置入口：KUAL 动态菜单在 menu.json，插件元数据在 config.xml。
• 安装与恢复：bin/install.sh、bin/use_proxy.sh、bin/restore.sh 负责部署、切换与回滚。

文件结构

• translator.lua：请求改写与展示逻辑，向自定义端点发送 { text, targetLanguage, sourceLanguage }。
• menu.json：KUAL 菜单项，支持直连与代理安装。
• config.xml：插件元信息。
• bin/install.sh：安装并自动备份原版文件。
• bin/use_proxy.sh：切换代理端点。
• bin/restore.sh：恢复官方 translator。

安装与使用

Kindle + KUAL

1. 将项目放入 /mnt/us/extensions/koreader-custom-translator/。
2. KUAL → “KOReader Custom Translator” → Install。
3. 若直连受限，选择 Install (Use Proxy API)。

手动部署（Kobo/Android/Linux）

cd bin
sh install.sh                 # 自动检测 KOReader 路径
KO_DIR=/path/to/koreader sh install.sh  # 手动指定路径

代理与恢复

• 切换代理：sh bin/use_proxy.sh。
• 恢复官方：KUAL 选择 Restore，或运行 sh bin/restore.sh。

使用提示

• 升级 KOReader 后需重新执行安装脚本，避免官方更新覆盖 translator.lua。
• 确认设备可访问自定义端点；若不可达，可先试代理端点。
• 发生异常可使用自动生成的 translator.lua.bak 回滚。

结语

该插件在受限网络下提供稳定的翻译后端，同时保持 KOReader 原生语言检测与罗马音展示能力。直连与代理可按环境自由切换，更新与恢复均可一键完成。

Project Repository: https://github.com/Tokisaki-Galaxy/kindle-koreader-custom-translator

Background

The native Google Translate interface in KOReader is inaccessible in some network environments. To maintain the native experience such as auto-detection and Pinyin/Romaji display, this solution provides a custom backend replacement.

By default, the Cloudflare Worker AI model @cf/meta/m2m100-1.2b is used for translation. If needed, users can self-host and switch to other models or increase rate limits.

Core Concept

• Custom Endpoint: CUSTOM_ENDPOINT points to translate.api.tokisaki.top, with an optional proxy translate-proxy.api.tokisaki.top (may have latency).
• Language Mapping: SUPPORTED_LANGUAGES covers 249 languages.
• Configuration Entry: KUAL dynamic menu in menu.json, plugin metadata in config.xml.
• Installation & Restoration: bin/install.sh, bin/use_proxy.sh, bin/restore.sh handle deployment, switching, and rollback.

File Structure

• translator.lua: Request modification and display logic; sends { text, targetLanguage, sourceLanguage } to the custom endpoint.
• menu.json: KUAL menu items, supporting direct and proxy installation.
• config.xml: Plugin metadata.
• bin/install.sh: Installs and automatically backs up the original files.
• bin/use_proxy.sh: Switches to the proxy endpoint.
• bin/restore.sh: Restores the official translator.

Installation & Usage

Kindle + KUAL

1. Place the project into /mnt/us/extensions/koreader-custom-translator/.
2. KUAL → “KOReader Custom Translator” → Install.
3. If direct connection is blocked, select Install (Use Proxy API).

Manual Deployment (Kobo/Android/Linux)

cd bin
sh install.sh                 # Automatically detects KOReader path
KO_DIR=/path/to/koreader sh install.sh  # Manually specifies the path

Proxy & Restoration

• Switch to proxy: sh bin/use_proxy.sh.
• Restore official translator: Select Restore in KUAL, or run sh bin/restore.sh.

Usage Tips

• After upgrading KOReader, re-run the installation script to avoid official updates overwriting translator.lua.
• Ensure the device can access the custom endpoint; if not, try the proxy endpoint first.
• If exceptions occur, use the auto-generated translator.lua.bak to roll back.

Conclusion

This plugin provides a stable translation backend in restricted network environments while preserving KOReader’s native language detection and Romaji display capabilities. Direct and proxy connections can be switched freely based on the environment; updates and restoration are both one-click operations.