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

Copy locales/en.po to locales/<lang>.po using the standard locale code — for example de.po, ja.po, ko.po.
Open the file in any text editor or a dedicated PO editor such as Poedit.
Update the header fields at the top of the file:
```
"Language: de\n"
```
For each entry, fill in the msgstr field with your translation:
```
msgid "Quick settings"
msgstr "Schnelleinstellungen"
```
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:

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

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

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

Fork this repository (click the Fork button at the top right of the GitHub page).
Create a new branch for your change:
```
git checkout -b fix/my-bug-description
```
Make your changes.

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."

If your change introduces new strings, add entries to locales/en.po:
```
msgid "Your new string"
msgstr ""
```
Commit with a clear message that describes what changed and why:
```
git commit -m "Fix progress bar not updating after resume"
```
Push your branch and open a Pull Request against main.

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.