Freezing a Moving Target: A “Source of Truth” for Toki Pona → Sitelen Emoji
How I turned a messy ecosystem of emoji mappings into a pinned, versioned profile for translators and book publishing.
Toki Pona is a tiny constructed language with a surprisingly large creative community. Its official writing system, sitelen pona, has grown into many styles and practical variants over time, including an especially playful one: sitelen emoji — representing Toki Pona words using standard Unicode emoji.
That sounds simple until you try to actually use it consistently.
The problem: there is no single sitelen emoji standard
If you go looking for “the” sitelen emoji mapping, you’ll find multiple GitHub repos, spreadsheets, and community resources. They mostly agree on the general idea, but they differ in the details. And those details matter:
A word can map to different emoji depending on the source
Aliases and alternative spellings are handled inconsistently
Punctuation and formatting rules vary
A translation produced today may not match the same text produced next month
That’s fine for casual chat. It’s not fine for tools or publishing.
Why I needed a stable answer
I run an online translator at toki.abvx.xyz, and I also translate books into Toki Pona. I’ve been planning a series of small book translations into sitelen emoji too — but books don’t tolerate moving targets. If a mapping changes after publication, you’ve broken consistency across editions and formats.
So I needed a boring, reliable thing:
A single, pinned, versioned “source of truth” mapping that my translator and my book pipeline can depend on.
The solution: a frozen profile + reproducible visuals
I built a small open-source repository called sitelen-emoji-truth. The core idea is simple:
Maintain a frozen canonical mapping file for production use
Pin integrations to a git tag, not to “latest”
Provide tooling so the mapping can be used for:
online translation
batch conversion of book-sized texts
Kindle/PDF-friendly rendering with consistent emoji appearance
In practice, the repo gives you:
1) A pinned “source of truth” profile
The canonical mapping lives in:
profiles/default-stable.v1.json
Consumers should pin to a tag and fetch the exact version:
https://raw.githubusercontent.com/markoblogo/sitelen-emoji-truth/v1.0.0/profiles/default-stable.v1.json
That means the mapping won’t change unless you deliberately upgrade the tag. No surprises.
2) A batch tool for books
Public translators need limits (mine does), but books don’t. So I added an offline conversion tool that turns a Toki Pona text file into sitelen emoji tokens while preserving line breaks:
python3 -m tools.convert_tp_text --in book_tp.txt --out book_se.txt
Now books can be processed locally, without pushing massive text into a public UI.
3) A reproducible “visual” export pipeline
Even if you use Unicode emoji, rendering differs wildly between platforms. For publishing, I want identical output across devices.
The repo supports generating visual-stable HTML (and optional PDF) by rendering emoji as Twemoji PNG assets:
one-time asset fetch
then build HTML/PDF that looks the same everywhere
This gives a realistic path to Kindle-friendly exports and consistent printed layouts.
Why open-source it?
This started as a practical need for my own translator and publishing plans. But open-sourcing it has obvious upside:
The mapping becomes a shareable reference
People can propose improvements
Changes can be discussed and introduced as new versions
The project stays useful even beyond my own tools
The goal is not to declare “the official standard.” The goal is to make a stable, versioned profile that real projects can depend on.
What’s next
The next step is to wire this profile into the translator so it uses the pinned mapping directly. After that, the same pinned profile will become the foundation for sitelen emoji book editions.
If you’ve worked with sitelen emoji resources before, you already know how messy the ecosystem can be. This is my attempt to make it boring — in the best sense of the word.
Links
Repository: sitelen-emoji-truth (GitHub)
Translator: toki.abvx.xyz
If you want to help: open an issue with mapping suggestions, edge cases, or known sitelen emoji resources.
Just keep in mind the core constraint: published output must remain stable, so changes land via new versions, not silent edits.