DEV Community: Kidus Adugna

Why I built Wuchale: Protobuf-like i18n from plain code

Kidus Adugna — Wed, 10 Sep 2025 07:01:17 +0000

Let's face it, most of us dread i18n. I know I do. It feels like wrestling with catalogs, boilerplate, and endless edge cases. So we avoid it when we can. And when we can't, readability suffers: what should be simple code quickly turns into a maze.

I ran into this while adding i18n to a sizable project with over 1K messages. At the time, out of the available options, Lingui was the better one to start with as it handled catalog generation automatically, which spared me a ton of manual work. And it didn't completely damage readability, because messages stayed in the code.

But as the project grew, I still found myself buried in boilerplate. Every new message added friction and extra complexity. The process felt heavy again. The tooling was helping, but also getting in the way. I didn't like this so much that I avoided adding i18n to another smaller project that could use it. I didn't want to go through it again.

This experience got me thinking: we already can tell if a piece of text in the code is going to be visible to the user or not. For example, text inside HTML tags is going to be shown. So why do we have to write extra boilerplate just to internationalize it?

That question sparked the creation of Wuchale, an i18n toolkit that does two things:

Scans your plain code for user-visible messages, extracts/optionally translates them and then compiles them into compact keyless catalogs, just arrays, like Protobuf (more on this below)
Automatically rewrites your code to get messages from the compiled catalogs by index, no keys required

It uses AST-based static analysis on your code, so it is very flexible; it will find your messages wherever they are. The result is that your source code stays clean and readable, while Wuchale handles everything under the hood:

Original code
```
Hello
```
Transformed code
```
{_w_runtime_.t(0)}
```
Extracted catalog (after translation)
```
msgid "Hello"
msgstr "Hola"
```

Compiled catalog

// the message is at index 0
export let c = ["Hola"]

Like Protobuf, the compiled catalogs don't need metadata; the consuming code already knows the mapping. Moreover, the compiled catalogs are optimized at build time for runtime use; no string replace or anything complicated happens during runtime, even when using complex messages with interpolations and nested messages.

It started with just Svelte, and then in almost three months of more than full time dedication, it has gone through many iterations and improvements with feedback from the community, and has expanded its reach. It now supports React/Preact, Svelte, SolidJS and of course JavaScript/TypeScript (even for server-side messages).

But this is not the end. For the ultimate DX, HMR is key, and it has received a lot of care to make it work smoothly. You write your code as always and Wuchale keeps the catalogs in sync in the background.

And further still, you can optionally use AI to translate the messages for you. Of course this does not match the quality of human translators, but if you want something quick that you can revisit later, it can do the translations on-the-fly. This enables writing your code in English and seeing the results in another language in the browser!

With all of this, you might expect a lot of dependencies. Nope. One of the things I didn't like about Lingui was its huge dependency size for what I need. Wuchale has less than 10 dependencies and it shares most of the same dependencies with Vite and your framework (e.g. Svelte's own parser for parsing Svelte). That means the additional dependencies are less than 5 (including transitive ones).

I now enjoy working with it, it feels like it's never there. FYI, I went back to that project and fully internationalized it with Wuchale in under 30 mins, using Gemini for the translation. And most of that time was spent on the language selector UI.

So, what's next? The biggest update planned is support for other backend languages, Go and Python, so that even the messages from there are internationalized.

Interested? Check out the website or the repo and give it a try!

Thank you for reading and I hope you try it and enjoy working with it. And feedback is always welcome. Wuchale is fully open source and open to contributors.

Photo by note thanun on Unsplash

wuchale: Rethinking internationalization

Kidus Adugna — Wed, 09 Jul 2025 12:30:14 +0000

(inspired by Rich Harris's "Rethinking Reactivity")

🚀 TL;DR: wuchale is a blazing-fast, zero-wrapper i18n solution for Svelte that extracts and compiles translations at build time. It avoids string keys, has minimal runtime cost, plays perfectly with HMR, and even supports Gemini-powered auto translation. Think LinguiJS, but leaner, faster, and tailored for Svelte.

A few years back, I needed to add i18n to my fairly large application with Preact. I evaluated the existing tools and the most common method was to write getters with keys for the actual text fragments which are located in separate language specific files.

<p>{t('page.home.greeting')}</p>

This works, and it "might" even be fast, but I believe it's fundamentally flawed. Text should live where it belongs: inside your markup, not behind opaque keys. Then I discovered LinguiJS. It was relatively new back then, but it introduced a refreshing idea. Instead of the above method, I would write:

<p><Trans>Hello</Trans></p>

The fragments are right there in the code. It auto extracts them using a command. This was much better and I migrated the whole application.

Leaving Preact, entering Svelte

Recently, I got some free time and wanted to move away from Preact to Svelte. But LinguiJS didn’t officially support Svelte. There was an adapter, but to me, it didn't feel like the real deal; it lacked the completeness and elegance of the original. Also I looked at the dependencies and apparently LinguiJS has grown to require more than 200! That was the final straw. I decided not to bring LinguiJS into my Svelte migration. However, the officially supported options for Svelte, like svelte-i18n and paraglide, relied on the same key-based approach I was trying to avoid.

Why does i18n have to be this hard?

It then occurred to me, it doesn't.

So I started playing with the svelte compiler and started to develop something that completely replaced my need for both key-based and wrapper-based methods. The design goals are simple:

You should just write your markup and it should be translated
```
Hello
```
It should have no compromise on performance.

Weeks of full time dedication later, it grew from a concept into a full open source package that you can use today.

`wuchale`

wuchale is inspired by LinguiJS and built with many of the same principles, but with:

zero wrappers
smaller bundles
blazing fast (TM) performance
no dependency bloat

More specifically, it's a vite plugin that pre-transforms your code and in the process also does other things like extracting the text fragments, and compiling the translated ones. And it can handle anything you can throw at it, because it only does AST based analysis of your code.

How does it work?

Let's pick the simple "Hello" example above. wuchale does the following:

Convert your code into this:
```
{wuchaleTrans(0)}
```
Extract the text into a per language PO file (like LinguiJS) that you can exchange with translators:
```
#: src/file.svelte
msgid "Hello"
msgstr ""
```

Translator fills the translated content:

#: src/file.svelte
msgid "Hello"
msgstr "Hola"

Compile the translated fragment into an array:
```
export default ["Hola"]
```

Yes, the argument 0 in the call wuchaleTrans(0) is actually the array index! Because wuchale controls the entire pipeline, it can avoid string keys altogether and still have deterministic output using arrays. This makes it output the smallest possible bundle size for the compiled fragments, even smaller than what LinguiJS produces, because LinguiJS uses string keys. And vite can further minify the call into something like w(0) to make the transformed code even smaller than the hand written t('page.home.greeting')! All of this makes it the best at producing small bundle sizes for performance.

So what happens if a translation is missing, will the user just see an index number (As LinguiJS just shows the meaningless string keys when there is no translated fragment)? Answer is no. wuchale is smart enough to fall back to the source language (English in most cases) when the fragment is not yet translated.

Complex content? Handled beautifully

Glad you asked! Sometimes, we have to mix text content with variables and markup. And wuchale does work in the most intuitive way. It goes out of its way to preserve the text fragments that you expect to be together, no matter the boundaries between them.

Let's say you have this:

<p>Hello {username}, welcome!</p>

This would be transformed into:

<p>{wuchaleTrans(0, [username])}</p>

And extracted to the PO file as:

#: src/file.svelte
msgid "Hello {0}, welcome!"
msgstr ""

And during runtime, it performs as fast as possible because it doesn't even parse and replace the placeholder. All of that heavy work is done during compile time. The compiled form of this (for English) would be

export default [
    [ 'Hello ', 0, ', welcome!' ]
]

What the runtime has to do is just loop over the array and concatenate the strings and the arguments at the indices specified as numbers.

The most complex scenarios involve text mixed with nested markup:

<p>Hello {username}, <b>welcome <i>home</i></b>!</p>

We don't want home to be extracted separately, but as part of the whole message. And wuchale does that! It is extracted as:

Hello {0}, <0>welcome <0>home</0></0>!

And the translators have the freedom to rearrange the markup as the language dictates using the placeholders.

Convenience: Dev mode HMR

wuchale plays nicely with Hot Module Replacement (HMR). It integrates deeply with Vite's HMR API and Svelte's reactivity. That means:

When you update source .svelte files → translations are extracted, and .po files are updated
When you update .po files → the browser receives live updates

All of this happens without a full page reload.

Bonus: Gemini-based auto translation

Having access to the whole process allows for more features and one is automatic translation. wuchale can use your Gemini API key if it finds it as an environment variable, and auto translates your content. It's not a substitute for human quality; but it gets you 80% of the way instantly.

Together with support for seamless HMR, this enables you to work in your source language in the code and see the updates in the browser in another language in real-time!

Try it out!

GitHub: github.com/K1DV5/wuchale
NPM: https://www.npmjs.com/package/wuchale
StackBlitz examples:
- Svelte
- SvelteKit

If you try it, I'd love your feedback. And if you find it useful, consider starring the repo ⭐

P.S. What's next? React support, perhaps. Got ideas? I'd love to hear them.

Do you really need a plugin for fuzzy finding files in Neovim?

Kidus Adugna — Tue, 06 May 2025 09:44:27 +0000

I'm a simple man; I used telescope.nvim for finding files and not for much else. But I'm also a minimalism junkie so I'm always on the lookout for ways to get more value with less dependencies.

I really liked Telescope but like I said, me being me, I began to question if I need it with all it bells and whistles just for finding files. It felt overkill for the job. Also, recently I migrated to blink.cmp for completion. I liked the fact that it gives you commonly used sources out of the box, and that includes cmdline completion.

This morning it dawned on me that the most important pieces for my needs are already implemented in Neovim and blink and I just have to mould them into a file picker. So I came up with this lua code that I just put in lua directory and call its setup() in my init.lua:

local M = {}

local cmd = "git ls-files -c -o --exclude-standard"

local function get_list_completion(arg_lead, cmdline, cur_pos)
    local cmdout = vim.trim(io.popen(cmd):read("*a"))
    return vim.split(cmdout, "\n")
end

local function cmd_handler(opts)
  if vim.tbl_count(opts.fargs) == 0 then
    return
  end
  for _, arg in ipairs(opts.fargs) do
    vim.cmd.edit({args = {arg}})
  end
end

function M.setup()
  vim.api.nvim_create_user_command(
    "FilePick",
    cmd_handler,
    { complete = get_list_completion, nargs = '*', force = true }
  )
  vim.keymap.set('n', '-', function ()
    local keys = vim.api.nvim_replace_termcodes(':FilePick<tab> ', true, false, true)
    vim.api.nvim_input(keys)
  end)
end

return M

As you see it's just 32 lines with the empty lines. And it produces something that looks like this:

I just have to tab and enter.

What it does is:

It creates a command "FilePick" with a custom completion function.
The completion function gets the list of files by using git's ls-files but any command that lists the files can be used. I'm using this because it gives me the same output as rg --files but faster (yes, than ripgrep based on my crude benchmarking using time but that's another topic).
Then finally for convenience, creates a mapping - that starts the command, and invokes the completion. From there you can type the fuzzy name, press tab (depending on your mapping) and enter.

Notice that I made it behave like this because I have enabled the cmdline completion from blink but I have its auto_show and preselect disabled. That's why the sequence for the last step is

Write the command
Invoke completion (tab), this will make the command the only candidate
Press space. This invokes the custom completion function BUT does not complete the line with the first item because I want to write the fuzzy pattern next, not the full path of the first file.

So there you have it, my custom file picker implemented in more or less the same number of lines as a Telescope configuration. So my answer to the title is...no. Thank you for reading.

EDIT: I just enabled preselect and mapped <cr> to accept_and_enter and now I don't even have to tab to select the first item! This resolved the last issue I had, that I had to press one additional key than I would with telescope.

Gotchas when learning SolidJS with (p)react background

Kidus Adugna — Mon, 29 Nov 2021 05:37:05 +0000

I recently took on a new project and since I was following solid.js for a while, I thought I'd give it a try. And to reduce the time needed to develop the project I decided to port components from another project I built previously, using preact.

I replaced useState with createSignal or createStore, useEffect with createEffect, etc., with their appropriate syntax (no dependencies for createEffect etc). Since solid shares a lot with react, I thought these fixes were enough. Boy was I surprised. I'll list my findings below. I might be wrong on some details so feel free to correct me.

Solid doesn't like custom hooks exported as default

I had a custom hook to show a loader, whose state is controlled in a context.

// loader.jsx
export default function useLoading() {
    ...
    return () => {...}
}

// component.jsx
import useLoading from './loader.jsx'
...
const loading = useLoading()
loading(true)
...
loading(false)

And the loader doesn't show. Then I copied over the hook definition to component.jsx and it worked. So I tried converting it to a named export, and it worked.

Using state outside of returned JSX is not reactive.

I think this is because components only run once, but
it took me hours to get this:

...
return state.loading && <Loader />

What do you think happens when state.loading changes? Nothing. All changes must be inside the JSX for the component to be reactive.

...
return <>
  {state.loading && <Loader />}
</>

Using `For` as a top-level return value with a changing list creates an infinite loop

Even when the For is inside a top-level fragment.

...
return <For each={state.list}>
  {...}
</For>

return <>
  <For each={state.list}>
    {...}
  </For>
</>

Both of these create an infinite loop. It must be at least one level deep.

return <div>
  <For each={state.list}>
    {...}
  </For></div>
</div>

As I said in the beginning, all of these may be due to my wrong understanding, but they did take a lot of hours for me to find, and I wanted to share them here. Thanks for reading.

I made a Mathcad alternative using Python

Kidus Adugna — Sat, 15 Feb 2020 09:57:24 +0000

I assume most people here are a little inclined to web development and so the name Mathcad might be new. PTC Mathcad is a desktop app built primarily for engineers to do math on a really readable document. It's like a limited word processor focused rather on doing calculations (MATLAB competitor) and how to display them.

Now It's a really awesome tool. So why did I create an alternative? Well, it has some pain points, at least for me.

It does not support exporting to LaTeX or Word. It can export to a Rich Text Format (.rtf) file which can be read by Word, but...
When exporting to .rtf, the equations are converted to images and editing ability is lost. Also the text is in text boxes so you need to do some work in order to make your document obey some standards.
For simple calculations, it's fine but for big works, which might require some programming parts like loops and conditionals, you have to learn a new language, which is more graphically oriented. Let's just say it's not for everyone.
Again for big works, you may need a lot of word processing and related things (headings, TOC, citations, bibliography, index, etc.) which it does not have.
It's really big, like the installer is around 900MB. I suspect that's because of the symbolic engine but for someone who does not need most of the bells and whistles, that's a lot.
It is not cross-platform. This may not be a deal breaker for people who usually need something like that because (we)'re Windows users.

Introducing docal (what a name right?). It's written in Python. It's available as a kind of a compiler CLI and also a GUI built with Tkinter.

It solves all of the issues above.

It supports both LaTeX and Word
Writes all equations in the native format of the respective document type (LaTeX or Word), means they can be editted, copied or anything as if you wrote them by hand. And all text is written normally.
Very small, available as a Python package with no dependencies and a pre built GUI (whose installer is below 9MB)
Cross-platform (although I have not tested it on systems other than windows, it should be, because Python is).

Additionally, the fun part, it can insert calculations into existing documents at places specified by hashtags. This is so that you make no compromises on anything. Word and LaTeX are the best for word processing. Therefore it will not try to compete with them on that. But they are not designed to do calculations. docal fills that gap, and nothing more. You do the other parts of the document in Word or LaTeX, and the calculation parts in docal and insert them into the main document.

I started working on something very primitive to this a year and a half ago when I was doing mechanical projects at university. It started out as just a text replacement program for LaTeX files, easier because they are just text files. Then a friend suggested Word support. Then little by little, I started using it more and adding features and fixing issued along the way. Then I did my final year project with it and it was great! I was comfortable with working in a text editor and using the CLI but not all people are. So a GUI was necessary. But there was no support for displaying math in Tkinter (as far as I know). So I first used PyWebview and used KaTeX for the math. But, being a webview, it got slow for longer works. So I decided to tackle it using Tkinter. To do that, I first had to find a way to render math. So I made tkinter-math, a package to render math on a tkinter canvas. Then everything else was easy and the current implementation happened.

P.S. This is my first post on DEV, so if you think there is something I need to improve, please tell me.