Translation Project:

Hey everyone.

Since I’ve get regularly pinged on adding multi-language support to, I thought I’d create this thread to organize work for adding translation infrastructure to allow collaboration with multiple translators.

There are few steps that need to be implemented to be able to reach our goals of a properly translated website, let’s break them up step by step.

Wire up a translation crowd-sourcing tool

Back then in ReasonML times we used Crowdin to keep track of translations for markdown files, so I’d like to re-evaluate if we should go back using it. I created a new Crowdin project and applied for a free OSS license to be able to use it to its fullest extend. If possible, please register on the platform and send me your username in a PM so I can add you as a translator. We’ll then try to hook up the repository with its English sources, so we can start tracking translations.

The only concern I have is that there may be some problems with our slightly custom markdown MDX format (e.g. we use custom components), but maybe that’s not an issue. Let’s see if this works.

Refactor the current EN docs

Currently the docs are a little tricky, since a few things have been shuffling around that require us to modify the file structure of the website.

  • GenType is now shipped with rescript: This means that the detached gentype docs folder will be moved within the manual folder. This will make it easier to keep rescript and genType versions aligned, which is nice, but the gentype folder will therefore be essentially gone. We should not translate them yet.
  • A few pages / changes are still missing. This may be not a problem since Crowdin should be able to detect latest changes / additions.

Refactor the website infra to use i18n routing

On the technical side, we’d need to do the following tasks:

  • Upgrade to Next@13
  • Untangle the markdown stuff: Right now we use the Markdown.res component and wire them up in weird ways just to be able to render prose text (ul, ol, pre, etc). Ideally we should only use that for our custom components, but for the typical structured text, it would be better to utilize our global css file (since it’s not a lot of code, and we the CSS cascade is the only clean way to implement nested structures)
  • Find the blockers for using Next’ i18n facilities (as mentioned in this PR).
  • Implement the i18n infra and wire up routing with the Crowdin generated translation content.

Other technicalities we need to keep in mind:

  • UI translations: If we need translation of certain content independent UI, we’d also need to add react-intl and the rescript-react-intl-extractor
  • Language independent linking to section headers: we need to make sure that anchor-hrefs to document titles are translation independent (the urls should always be in English. I know there are Markdown tricks one can implement to pin a header href to canonical English titles. Have a look at the React docs website repo and check the header titles for reference).

Contribution process

There are currently a few folks that are interested in contributing:

Those who are interested in doing translations: This can start as soon as we wired up the repository and received an OSS license for Crowdin. Please ping me with your crowdin ID so I can set everything up.

If you want to work on the technical challenges, please let us know and create necessary Github issues + draft PRs to keep track of the work.


Thanks for this thread and the Crowdin project @ryyppy !

Could you upload content (the official docs) to the Crowdin page, so we can start the translation process? If you want, I can do that too but it looks like only the project manager can upload and I don’t have the authority.


I’ll be happy to contribute to this. You can surely count on me for translating to italian, I would like to help on technical challenges as well but I’m not sure if I’ve enough time currently.


1 Like