Long-term goals of typesafe-i18n

[ivanhofer]

The current landscape of the i18n experience is far from ideal. When working the first time on i18n a few years back I didn't like the experience and our team had encountered a lot of problems. As a developer I thought we can do better so I started typesafe-18n as a side project. I did want to tackle the biggest pain points from a technical perspective. But internationalization is not just a technical problem. In bigger applications a lot of people are involved and there exists the possibility that the person writing the translations has no technical understanding. The tooling requirements are different for each person and the whole i18n process should take that in mind.

Here are some steps I want to tackle with this project in order to improve the i18n for the full spectrum of people involved in a multilingual project:

• create a full-featured yet lightweight i18n library (see sizes)
  An i18n library should not load a dozen of kilobytes of JavaScript code and not affect the performance of an application.
• improve the developer experience by providing good type checking support (see typesafety)
  Potential errors in every part of an application can be catched by static type checks. The same should apply to i18n.
• make it compatible with the majority of frameworks/platforms (see usage)
  Whether someone uses a tool at work or for their side project. Is should be easy to apply the same i18n concepts to every project.
• make it easy to integrate with existing services and tools (see importer and exporter)
  Making multilanguage applications will involve also non-technical people who are using a service to easily add and modify translations. It should be easy to integrate any kind of service to the development process of a project.
• implement build-time optimizations (see open discussion)
  This not only improves performance (speed and bundle size) but also enables new capabilities (see next step).
• allow translations to be written in any syntax and format (see open discussion)
  Each syntax has its advantages and disadvantages. Beeing open and allowing anyone to use their desired syntax would be a great option.
• validation for all dictionaries and translations (see open discussion)
  Not all file formats offer the best type checking capabilities. That's where a validation process could step in and find any potential issue regardless of the used translation format.
• providing a service for non-technical people to collaborate on translations
  Translations are not just text snippets. They can contain some technical parts like prameter names, formatter definitions and plural syntax. Those technical parts should be transformed into a more intuitive UI. Real-time feedback is desirable to help translators see how their changes will look like inside the actual application. I don't know such a service yet. Probably a custom solution needs to be built.
• deeper integration into developer tools
  Automatic string extraction from a template, untranslated parts detection, better IDE tooling etc. are just a few things that come into my mind when thinking about how to improve the i18n process to make it overall easier.

Those are my thoughts how the process of internationalization could look like in the future.

Feel free to contribute to this discussion by providing your thoughts in a comment below.
If this is not enough and you want to actively help this project to get better, please become a contributor or consider to sponsor my activities.

Thanks!

[pkvince]

Hi! I just stumbled upon your project. For the topic of collaboration service, my previous employer have created an open source tool just for this. I'll leave a few links below in case you think it might align with your vision!

https://www.accent.reviews/
https://github.com/mirego/accent

They also support "live" visual editing for non technical people:
https://www.accent.reviews/guides/live-editing.html

[ivanhofer]

Thanks for sharing the links. I'll take a look at the project

[Badlapje]

• providing a service for non-technical people to collaborate on translations
  Translations are not just text snippets. They can contain some technical parts like prameter names, formatter definitions and plural syntax. Those technical parts should be transformed into a more intuitive UI. Real-time feedback is desirable to help translato

I'm quite excited about this one, as in my experience it's the biggest missing part of typesafe-i18n and i18n in general.

[ivanhofer]

This will probably be the last point of that list I'll tackle ^^.
A friend of mine is currently working on something in that direction. Maybe you want to check and comment on the RFC he posted recently: opral/monorepo#127

[ecker00]

@ivanhofer Have you seen Tolgee? Seems to be solving "providing a service for non-technical people to collaborate on translations". You run your own server with an easy interface for translators to work with, and easy for developers to add screenshots for context. Tested it a bit, and seems quite good, but no integration with Typesafe-i18n.

[ivanhofer]

Hi @ecker00, yes I have heard of Tolgee already but I haven't tried it yet. One of their developers sayed that they wish to bring typesafety to their client libraries, but I don't know any more details.

Since Tolgee probalby offers an API to export translations, you could write a few lines of code and sync your repo with the tolgee server using the importer functionality: https://github.com/ivanhofer/typesafe-i18n#integration-with-other-services.

This approach will also work for all other translation services.

[CanRau]

Just wanted to mention that i18next is getting more type-safety built-in since v22, haven't had the time so far to try the new type stuff out but it looks pretty good and i18next has a big ecosystem.

Don't wanna make this project here bad at all or anything just thought it's nice to mention somewhere 😉

[ivanhofer]

Thanks @CanRau for mentioning this here.
I'm glad that other libraries are catching up and try to deliver a better TypeScript support.
From what I have seen in the 18next documentation, setting up TypeScript support is a manual process and requires you to maintain it constantly whenever you add a new locale and namespace.
For me the TypeScript support does not go far enough. While having typesafe keys to your translations is probably the most useful feature, there are more issues you code could face. In my personal i18n experience I had some issues where a parameter was renamed, or a new one was added. Or where a parameter was forgotten in a translation for another locale. Even if you try to keep up manually, you will eventually forget to keep some parts of your code up to date.

The initial intention of this library was to have a lightweight i18n solution because I didn't want to include a 10kb solution to a 30kb application just for inserting a few strings in different languages. With a comparable feature-set typesafe-i18n offers a solution to most use-cases in ~1kb of footprint.

It is probably true that a project with a single developer can't compeed with the big ecosystem of others who have a some more developers and sponsors, but typesafe-i18n is flexible enough to work with any i18n service if you are willing to spend a few hours to implement a few API calls to connect it to your code base.

With this project I want to offer a solution for people who care about typesafety and a great DX while keeping the best possible performance and bundle size in mind.

I haven't had that much free time to code in the last months, but I hope I can give an update on this topic in a few weeks :)

[artola]

Some years ago I wrote a similar library (still in use) where in a build step I could create fully typed translations plus the other i18n needs (interpolations, plurals, etc), I thought that was a good candidate for OSS, but I had no spare time to do it as already fully booked in other projects.
Recently I have rechecked the whole OSS offers, several packages including the 2 most downloaded, by creating a demo app with some typical use cases, and it was a surprise especially that they lack of TS support for the interpolations.
When I was ready to give up, I found this library that works as expected. @ivanhofer Well done!
I will continue to evaluate it and try to understand how to implement the whole process (with lokalise as translations provider).

[CanRau]

I see, thanks a lot for the detailed reply and I def get your points. Right now we're pretty busy in mvp stage trying to ship first version on sunday but later I think I might reconsider our i18n solution, which right now is powered by i18next but pretty messy, strings are still inline in the client init, and not even all strings are translatable yet and only 1 language so far.
So when I get to improve all that I'll definitely give typesafe-i18n another chance, I'll add the repo link to our current i18next init as a reminder 😉

[ivanhofer]

Sounds great! Looking forward for feedback on your progress :)

[ivanhofer]

A small update on this topic:

I took some time to think about what in my opinion the pain points of i18n are. I came to the conclusion that a regular library is not enough to make i18n really accessible to everyone. The whole tooling around internationalization needs to be improved.

You can find more information here: https://github.com/pipeli18ne/RFC