Since I’ve get regularly pinged on adding multi-language support to rescript-lang.org, 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.
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.
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
gentypedocs folder will be moved within the
manualfolder. This will make it easier to keep
genTypeversions aligned, which is nice, but the
gentypefolder 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.
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.rescomponent and wire them up in weird ways just to be able to render prose text (
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
- 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).
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.