Add multilingual documentation

[sdancer]

opening this discussion

some guys documenting the move lang in multiple langs using mdbook choose this as solution https://github.com/funkill/mdbook-i18n original thread: https://github.com/rust-lang/mdBook/issues/5

other options?

[lpil]

This would be a fantastic addition!

One thing we'll need to think about is the maturity of the documentation. If someone has time to translate X amount of documentation we'll want to ensure it's not documentation that will be rewritten soon.

The site is made with Jekyll and we will stop using mdbook in future. We could use Jekyll's internationalisation options or we could switch to an alternative site generation tool if there's benefits elsewhere.

[inoas]

Knowing extended open source driven multi lang documentation from CakePHP (https://book.cakephp.org/4/en/index.html) I am a bit worried about a few things

1. changed information, this outright might hurt DX
2. obsolete information, this might annoy DX
3. missing information due to missing translations, this hurts DX

And then if you forced multi language documentation through some tool, it would make adding documentation and contributing much harder, say if we had obligatory English, Spanish, French, Urdu, Mandarin, Japanese, Russian support.

So while I am not against this, I am not an advocat, especially not now. Once there is a larger maturity then this could be looked at again.

I know that having Japanese documentation helped CakePHP a lot in its prime days, and especially adding languages where the population does not speak English so well helps with adoption there. So there imho are benefits beyond DX.

What I'd like to see is some way to do multi language docblocks and have generated docs have a language selector. But we would first need some syntax feature for docblocks to do that. Here I can see some libraries simply supporting as many languages as they can and if a given function say misses a translation it can fall back (to English? or in whatever is available in browser language priority and then to English).

[lpil]

Great suggestions there. I really like the idea of having fallbacks and the language being selectable.

[sdancer]

about those worries, being a native spanish speaker myself, if you are able to read english you will do so every time. translated documentation is for people who is unable to, since my current company is based on china, i can experience first hand the DX of average chinese developers.

[inoas]

My tought is - IF we can find a sponsor and/or a small team that takes care of a specific language then we can consistently translate the guide and maybe find a way to add translated docblocks.

I'd maybe suggest meta/docs-files (say src/int.md) alongside .gleam-files that supply additional docblocks for modules and functions in non-English (probably just markdown with some ids to match to the module or function)?

If there is this chance adding any of these languages it may greatly help with Gleam adoption in those specific regions because either English isn't learned and/or the language region is just very large: Mandarin, Spanish, Urdu, Japanese, French, Russian (did I miss any?)