Zen UI - A minimal interface for e-readers

Contributing to Zen UI

Thank you for your interest in contributing. Zen UI is a small, focused plugin — contributions that keep it clean, minimal, and well-behaved are most welcome.

Ways to contribute

🐛 Bug report	Open an Issue describing what went wrong
💡 Feature request	Open an Issue with your idea
🌍 Translation	Add or improve a .po file in locales/
🔧 Code	Fork, branch, change, and open a Pull Request
📝 Documentation	Improve the README or add inline comments

---

Reporting a bug

Open an Issue and include:

• A clear description of what happened and what you expected
• Your KOReader version (visible in Menu → Help → About)
• Your device model (e.g. Kobo Libra 2, Kindle Paperwhite 5)
• Steps to reproduce the problem, if you can

If the bug causes a crash, the KOReader log (crash.log or reader.log in the KOReader folder) is very helpful.

---

Suggesting a feature

Open an Issue describing the feature and why it would be useful. Keep Zen UI’s philosophy in mind — features should reduce clutter or add something genuinely useful. Screenshots or mockups are welcome.

---

Contributing a translation

Translations live in the locales/ folder as standard .po files. No programming knowledge is needed.

Adding a new language

1. Copy locales/en.po to locales/<lang>.po using the standard locale code — for example de.po, ja.po, ko.po.
2. Open the file in any text editor or a dedicated PO editor such as Poedit.
3. Update the header fields at the top of the file:

   "Language: de\n"
   

4. For each entry, fill in the msgstr field with your translation:

   msgid "Quick settings"
   msgstr "Schnelleinstellungen"
   

5. Submit your file as a Pull Request (see below).

Improving an existing translation

Open the existing .po file for your language, correct or complete the msgstr values, and submit a Pull Request.

Translation guidelines

• Never modify the msgid — only edit msgstr
• Keep placeholders intact: %d, %s, %%, and \n must appear in msgstr exactly as they do in msgid
• Leave msgstr "" empty for any string you are unsure about — the English original will be shown as a fallback
• If your language has different plural forms, set Plural-Forms in the header accordingly

---

Contributing code

Setup

Zen UI is a standard KOReader plugin written in Lua. No build system or compilation step is required. The plugin runs directly from source.

To test changes:

1. Copy the zen_ui.koplugin folder to the plugins/ directory on your device or the KOReader emulator.
2. Restart KOReader to reload the plugin.

The KOReader emulator is the fastest way to iterate without a physical device.

For the local KOReader development build, set KOREADER_DIR in .env, then run:

./build.sh --dev

This builds the plugin, replaces its copy in $KOREADER_DIR/plugins/, and restarts the KOReader process launched by the previous --dev build.

Automated tests

Zen UI’s tests live under spec/ and run against KOReader’s bundled LuaJIT. Set KOREADER_DIR to a built KOReader emulator when it is not discoverable next to this checkout. The first Python smoke run creates an ignored virtualenv.

./spec/run lua             # Lua unit and KOReader patch integration specs
./spec/run smoke           # Lua plus deterministic Python checks
./spec/run package-check   # Assert release ZIP excludes every test asset

ZEN_UI_RUN_EMULATOR=1 ./spec/run smoke starts a disposable emulator overlay with the current plugin source and test-only driver plugin; it never changes the emulator or plugin installation you use for development. See spec/README.md for pinned KOReader versions and golden-image workflow.

Static linting (LuaCheck)

Zen UI uses LuaCheck for static analysis.

Install it locally (one-time):

luarocks install luacheck

Run lint checks from the plugin root:

luacheck -q _meta.lua main.lua common config modules

The project config is in .luacheckrc and is aligned with KOReader’s baseline (for globals like G_reader_settings and G_defaults).

Making a change

1. Fork this repository (click the Fork button at the top right of the GitHub page).
2. Create a new branch for your change:

   git checkout -b fix/my-bug-description
   

3. Make your changes.
4. If you added any new visible text (strings shown in the UI), wrap them with _():

   -- correct
   text = _("Something went wrong.")
   
   -- incorrect — not translatable
   text = "Something went wrong."
   

5. If your change introduces new strings, add entries to locales/en.po:

   msgid "Your new string"
   msgstr ""
   

6. Commit with a clear message that describes what changed and why:

   git commit -m "Fix progress bar not updating after resume"
   

7. Push your branch and open a Pull Request against dev.

Extracting translatable strings

If you have Python 3 available, you can scan all Lua files for translatable strings and print any that are missing from locales/en.po:

import re, pathlib

strings = set()
pattern = re.compile(r'_\("([^"]+)"\)')
for f in pathlib.Path(".").rglob("*.lua"):
    strings.update(pattern.findall(f.read_text(errors="ignore")))

existing = pathlib.Path("locales/en.po").read_text(errors="ignore")
for s in sorted(strings):
    if f'msgid "{s}"' not in existing:
        print(f'msgid "{s}"\nmsgstr ""\n')

Code style

• Follow the style of the surrounding code — indentation, spacing, and naming conventions are consistent throughout
• Keep logic focused; avoid adding behaviour to build/render functions that belongs in helpers
• Prefer local variables; avoid polluting the module-level scope
• All strings shown to the user must be wrapped in _()
• Add a short comment when the reason for a decision is not obvious from the code

File structure

zen_ui.koplugin/
├── main.lua                        — plugin entry point and lifecycle
├── _meta.lua                       — plugin metadata
├── config/
│   ├── defaults.lua                — schema and default values
│   └── manager.lua                 — persistence, migration, getters/setters
├── common/
│   └── utils.lua                   — shared utilities
├── modules/
│   ├── registry.lua                — module loader and feature registry
│   ├── filebrowser/                — file browser patches and layout
│   ├── menu/                       — menu patches (quick settings, zen mode)
│   └── reader/                     — reader patches (clock, status, banner)
├── settings/
│   ├── zen_settings.lua            — unified settings menu entry
│   ├── zen_settings_build.lua      — menu tree builder
│   ├── zen_settings_apply.lua      — apply settings to live state
│   ├── zen_settings_updater.lua    — update checker and installer
│   └── zen_updater.lua             — GitHub release fetcher
├── locales/                        — gettext .po translation files
├── icons/                          — UI icons
├── CONTRIBUTING.md
├── SECURITY.md
└── README.md

---

Pull Request checklist

Before submitting, please check:

• The change works on a real device or the KOReader emulator
• Any new UI strings are wrapped in _()
• New strings are added to locales/en.po
• The commit message clearly describes the change
• No debug logging or commented-out code is left in

Thank you for helping make Zen UI better.

This site is open source. Improve this page.