Background#

KOReader’s built-in Google translation API is unreachable on some network environments. To keep the native experience such as automatic language detection and pinyin/romaji, this project provides a custom backend replacement.

By default, it uses the AI model @cf/meta/m2m100-1.2b on Cloudflare Worker for translation. If needed, you can self-host and switch to other models or raise the rate limits.

Core Idea#

• Custom endpoint: CUSTOM_ENDPOINT points to translate.api.tski.uk, with an optional proxy translate-proxy.api.tski.uk—though the proxy may add latency.
• Language mapping: SUPPORTED_LANGUAGES covers 249 languages.
• Configuration entry: the KUAL dynamic menu is in menu.json, and the plugin metadata is in config.xml.
• Install & restore: 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 both 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#

1
cd bin
2
sh install.sh                 # Automatically detect the KOReader path
3
KO_DIR=/path/to/koreader sh install.sh  # Specify the path manually

Proxy & Restore#

• Switch to the proxy: sh bin/use_proxy.sh.
• Restore the official version: select Restore in KUAL, or run sh bin/restore.sh.

Usage Tips#

• After upgrading KOReader, re-run the install script to prevent official updates from overwriting translator.lua.
• Make sure the device can reach the custom endpoint; if unreachable, try the proxy endpoint first.
• If something goes wrong, you can roll back using the auto-generated translator.lua.bak.

Conclusion#

This plugin provides a stable translation backend on restricted networks while preserving KOReader’s native language detection and romaji display. Direct and proxy connections can be freely switched depending on the environment, and both updates and restores can be done with a single click.