Photo by Bernd 📷 Dittrich on Unsplash
It has now been one year since the initial commit of Wuchale! A lot has happened since then and I will explore some of them here, and then discuss the future plans and status after that.
If you are not familiar, Wuchale is a compile-time i18n tool that takes plain code (by plain I mean not concerned with i18n at all) and automatically does everything necessary to make it internationalized: extracting user-visible text, managing catalogs, and transforming code with AST to swap them at runtime. The main goal is reducing/eliminating the friction of adding i18n to projects.
It actually started out as a Svelte preprocessor, as an experiment to see what could be achieved with Svelte's AST in this direction. And at the time it only supported Svelte files, with extracted messages stored in JSON files. It was made a Vite plugin soon after that and started storing messages in PO files. But the main achievement was the nested and mixed (interpolated) message handling, which proved to be the core of the "no code changes" promise. Nested and mixed messages mean something like this:
<div>Hello, <b class="someclass">esteemed <i>user {name}</i></b>!</div>
Extracting the individual fragments like Hello,, esteemed and user separately would have been very easy to do. But then they lose all the context. And so it became a focus point to extract the whole message. The solution was to encode the full nested structure as a single message, preserving context for translators with the minimum structural elements: <0>Hello, <0>esteemed <0>user {0}</0></0>!</0>, while keeping the runtime efficient. That turned out to be the hardest part, and cracking it made everything else possible.
The other focus point from the start was the dev experience. That involves showing translated messages while detecting new messages and updating after changes during HMR, without causing a full page reload. Different approaches were tried including the reactivity of frameworks, but the approach that became viable was embedding the updates in the files themselves when they change. This is the same-ish approach that Vite itself uses and it also doesn't rely on reactivity being available for the framework, making it framework agnostic. And adding to that, live LLM translation made everything come together so that you edit your components in English and see the update in the browser in another language.
The next big challenge was loading the compiled catalogs. This is not a Wuchale-specific problem, but I wanted to keep it flexible enough for the catalogs to be loaded just the way the developer wants, one shared for all components or one per component with some of the components sharing, and directly importing (bundled) or lazy loading, or custom. That, combined with reducing all friction, was a big promise to fulfill, because even from the start, just for Svelte, there were two targets: plain Svelte and SvelteKit, and they have different conventions for how to load data. And so after a lot of experimentation, the concept of loaders was made available. Now there are some loaders provided by default, and it is possible to write a custom one if desired.
After that, I noticed that the code that was purely specific to Svelte was actually a smaller part, and the rest could be applied to other frameworks as well. And so after some effort, the concept of adapters was added and the Svelte part itself was made an adapter. Then React and SolidJS support was added through the JSX adapter, and some months later, the Astro adapter was added too.
So far, Wuchale only supported messages, and URL support was requested. Just writing <a href="/items">...</a> and having everything working when the user goes to /es/elementos became the next target. While the translation is done only once, there are two parts involved after that: link handling like in anchor tags href, and during runtime routing. They both need to be managed together so that they don't fall out of sync and cause 404 errors. This went through a few iterations and the latest implementation was written with performance in mind as well because the routing sits in the way of every request in order to get the base route from the incoming URL, and now it "Just works".
Storage wise, choosing PO files in the beginning was a good decision, but some projects may have specific needs that are not covered by PO files. For that reason a simple storage interface was added and the default PO file based storage became one storage driver that can be swapped for another. This made it possible to be so flexible that it is now possible to store the messages in PO files located in one place for some locales and elsewhere for other locales, and the URLs in a JSON file.
Now for the future, there is still a lot to do. The first one is support expansion. It already supports most of the biggest frameworks, but there is one glaringly missing: Vue. An adapter will be developed to support it. And on the React side, full Next.js support is missing and will be worked on, though it can currently be used in production using the CLI to transform the files just before deploying.
The other point that is often overlooked is when the backend is written in another language like Python or Go, and some messages (like error messages) are produced on the backend. One way to tackle this, of course, is using error codes and translating them into readable messages on the frontend. But I see it as another friction that can be resolved by Wuchale. It already supports JS backend messages in SvelteKit using the builtin adapter, and the plan is to expand that to other languages using their own AST libraries (both Python and Go have them) for the parsing and transformation.
There are many more plans like adding support for more bundlers, Inlang storage driver, even more improved lazy loading, scaffolding CLI, customizable message encoder/decoder, whole file support (e.g. md), etc.
I'm happy that it's being used by many projects that do very different things. In gaming, Blitz recently finished their Svelte rewrite and they used Wuchale for i18n! In infrastructure, Sylve uses Svelte and of course, Wuchale for i18n. There is Nook in local AI, Cigale in biology, and more. And I'm grateful for all the people I've interacted with, as I got a lot of good feedback and ideas from them. And of course, I'm grateful for my sponsors who keep me motivated to continue working on it.
If you have any questions or use it in an interesting way or just want to say something, please leave a comment. Looking forward to the next year!
Top comments (2)
The most impressive part isn’t the i18n itself, it’s the goal of making developers forget about i18n.
Every team starts with “we’ll add localization later” and somehow “later” becomes the week before launch. 😅
I also like the compile-time approach. Runtime flexibility is great until you discover half your translation bugs are actually configuration bugs.
The fact that you managed to preserve nested context for translators while keeping the developer experience simple is probably harder than most people realize.
Congrats on the first year. Also, as someone using Astro, seeing Astro support but not Vue support gave me a tiny amount of irrational happiness. 😄
Thank you so much! That's so true, and yes it was hard, I had to think really hard to find an idea that makes it work.
Hahaha yeah, Vue wasn't added earlier because I haven't used it and so I'm not familiar with it. But it's planned.