KOReader Custom Translator 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.tski.uk，可选代理 translate-proxy.api.tski.uk，但是代理可能会有延迟。
• 语言映射：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 URL: https://github.com/Tokisaki-Galaxy/kindle-koreader-custom-translator

Background

KOReader’s native Google Translate API endpoint is unreachable in certain network environments. To preserve the native experience like auto-detection, Pinyin/Romaji display, this plugin provides a custom backend replacement solution.

By default, it uses the AI model @cf/meta/m2m100-1.2b on Cloudflare Worker for translation. If needed, you can replace it with other models or adjust rate limits via self-hosting.

Core Concept

• Custom Endpoint: CUSTOM_ENDPOINT points to translate.api.tski.uk. An optional proxy endpoint translate-proxy.api.tski.uk is available, but may introduce latency.
• Language Mapping: SUPPORTED_LANGUAGES covers 249 languages.
• Configuration Entry: KUAL dynamic menu items are defined in menu.json. Plugin metadata is in config.xml.
• Installation & Restoration: bin/install.sh, bin/use_proxy.sh, and bin/restore.sh handle deployment, switching, and rollback.

File Structure

• translator.lua: Request rewriting 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 the plugin and automatically backs up 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 restricted, 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 specify path

Proxy & Restoration

• Switch to Proxy: sh bin/use_proxy.sh.
• Restore Official: Select Restore from KUAL menu, or run sh bin/restore.sh.

Tips

• After upgrading KOReader, you need to re-run the installation script to prevent official updates from overwriting translator.lua.
• Ensure your device can access the custom endpoint. If not, try the proxy endpoint first.
• If errors occur, use the auto-generated translator.lua.bak file to rollback.

Conclusion

This plugin provides a stable translation backend in restricted network environments while preserving KOReader’s native language detection and Romaji display capabilities. You can freely switch between direct and proxy connections as needed, and updates/restoration can be done with one click.