DEV Community

Ray Wong
Ray Wong

Posted on Originally published at raycnwong.com AI-assisted

Sveltext: rebuilding the gettext workflow I love for Svelte

Sveltext Demo

I have used gettext-style i18n, such as ttag and lingui, for more than seven years. When I started working on a Svelte project, I wanted to continue using it. The workflow was good enough for me to spend time building the exact implementation I wanted.

That became Sveltext, an experiment in extreme minimalism. I wanted to judge what I actually needed, keep that part, and learn how to build it.

The part I love about gettext starts before I translate anything. I hardcode English words and sentences in the code, then look at the UI. Once I am confident enough to move on, I mark the strings as translatable.

For example, I can start with this:

<p>Hello World</p>
Enter fullscreen mode Exit fullscreen mode

Then wrap the text with t:

<p>{t`Hello World`}</p>
Enter fullscreen mode Exit fullscreen mode

With the initial setup already done, I run npx sveltext extract and fill in the translations in the .po file.

There is less context switching when I read and work on the codebase. The original sentence stays where I use it. I don't have to move "Hello World" into another file and give it a key such as greeting. There are no keys for me to name and manage, and extraction handles the cleanup of messages that are no longer used.

I also find .po files more manageable than JSON for this work. If I use the original message as a JSON key, a long sentence and its translation share one long line. If I use a short key, I have to name and manage that key.

A .po entry separates the original message and the translation:

msgid "Hello World"
msgstr "こんにちは、世界"
Enter fullscreen mode Exit fullscreen mode

When I send that entry to a translator, the original language is already there. They can fill in the translation below it. With an entry such as "greeting": "こんにちは、世界" in ja.json, I would need to find the corresponding English text in en.json to provide the same context.

I can hardcode English first and mark strings translatable later. I love this workflow so much.

I think I could make an agent skill to automate my translation routine too: marking strings, extracting them, and filling in translations.

I had been using a community port of Lingui for Svelte. But I wanted fewer APIs, dependencies, and pieces of code that I didn't need. I was also concerned about carrying unnecessary code through an adaptation of a library I associated with React.

Another thing I wanted to change was runtime message hashing. In the implementation I was using, calls needed the original message to calculate its hash at runtime. Meanwhile, the compiled catalog mapped hashes to messages. For a source-language entry, that meant the original text could appear both at the function call side and in the catalog.

I wanted Vite to handle that work at build time. A basic expression like this:

{t`Hello World`}
Enter fullscreen mode Exit fullscreen mode

could become something like:

t('abc1234');
Enter fullscreen mode Exit fullscreen mode

Here, abc1234 is an illustrative hash. The corresponding catalog becomes a JavaScript object along these lines:

{
    "abc1234": "Hello World"
}
Enter fullscreen mode Exit fullscreen mode

The runtime can look up the message using the hash that the compiler has already calculated. Interpolation makes the transformation more complicated, but that is the basic idea. Hashing a known string is work I can move into the build.

Building this also gave me a reason to learn about abstract syntax trees and depth-first search. After picking those up, the harder work was making the compilation step behave correctly.

I chose magic-string with performance in mind, although an AST-to-AST transformation followed by code generation, as with Babel, felt more predictable to me. With magic-string, I use the AST's source ranges to rewrite the original code directly.

That sounds intuitive until the replacements overlap. Consider this nested translation:

{t`Hello ${t`World`}`}
Enter fullscreen mode Exit fullscreen mode

The outer translation contains the inner translation, so their source ranges overlap. My initial implementation ran into the limitation described in magic-string issue #208, "Cannot split a chunk that has already been edited". A replacement that worked on its own could conflict with another replacement inside it.

Once overlap became a deal breaker, I had to find a way to avoid it. I tried splitting the transformation into fragments, handling the left, middle, and end separately. That let me rewrite the outer expression around the inner expression without having the edits interfere with each other. It worked.

Keeping the runtime small still required careful work in the compiler. Calculating those ranges and replacements was one of the more challenging parts of the experiment.

For now, Sveltext has given me back the workflow I wanted in an implementation I believe is better suited to my needs. The effort was worthwhile to me. I got to question which parts of an i18n library I actually use, try an extremely minimal version of keeping only those parts, and learn how to implement them. I still write English in my Svelte components first, see how the UI looks, and translate when I am ready.

Top comments (0)