Discussion: Localization

[ryyppy]

Right now we intentionally left out localization. One of the reasons is that we wanted to figure out more details on how the website structure / URIs should look like. Also, judging from the existing official resources, translations are quite flaky. Probably the most thorough translation for reasonml.github.io right now is French (I don't speak French, so I don't know how up-to-date those are). BuckleScrip and ReasonReact generally lack consistent translations.

It would be great to gain more insights on how important localization is, if it is something we need to support right away, or if we should focus on refining the English docs first. My gut feeling tells me that having incomplete translations in combination with perpetually changing English docs might be a churn and burden.

No matter when, as soon as we decide to support localization, we need to have a strategy and process on how to translate documents. Ideally I'd just like to e.g. have a /en, /de, fr, etc subfolder with fully translated markdown files instead of having a translation app. Docs should always be translated file by file and we need to be very careful when changing original sources if there are existing translations already.

Any ideas and input from the community on how this should look like would be really valuable.

[Kingdutch]

I would encourage looking at how other projects solve this before trying to come up with our own solution : )

I think setting up a base for translations should be included at the start. It could also have impact on the way the English site is structured (from a source and deployment perspective, not necessarily site-page organisation). Doing this after the fact can be painful.

Additionally, having how we're going to do translations figured out allows the focus on building out the content and gives the community an opportunity to start translating.

React seems to have translations for documentation sorted out pretty well. Whether it's the best solution, I don't know. However, so far they seem to be pretty successful.

We should not forget that a large part of the world is full of Developers for whom English is not their primary (or even secondary language). To open up Reason to those people requires translated documentation. (Even with good translations, there may be other hurdles as was illustrated in an interesting RustFest talk last year.)

[ryyppy]

I would encourage looking at how other projects solve this before trying to come up with our
own solution : )

I recently read the updates on the TS website v2 localization strategy and opened this issue to do some more research (to be clear: I don't want to come up with my own solution and rather get inspired by existing solutions / processes) :-)

React seems to have translations for documentation sorted out pretty well. Whether it's the best solution, I don't know. However, so far they seem to be pretty successful.

That's a good model! They literally fork the whole reactjs.org repo and change the doc files as I understand? It also sets an emphasis on responsibility and coordination on keeping the content up to date. That seems like a really well isolated and scalable solution.

We should not forget that a large part of the world is full of Developers for whom English is not their primary (or even secondary language)

Totally! I am not implying that everyone is supposed to know English (I am a native German speaker as well). It's more a question on how we should invest our resources and I want to get an overview on proper concepts and also gauge the demand of translations (so we can plan ahead).

[ryyppy]

I spent some more time on thinking about the localization process: I played around with Crowdin (and how to set it up etc), since we need to manage that thing ourselves... generally it's not too hard and the crowdin interface is really good for managing markdown data.

I wanted to plot down a list of open questions I had when doing my research:

• How to design the URLs
• How does Algolia do the indexing for multiple languages?
• How to correctly optimize search results on search machines (without lots of duplication)
• Would it be better to go the same approach as reactjs.org and split up the website into multiple subdomains, such as de.reactjs.org, jp.reactjs.org etc. (how would this impact the search engine hits?)
• Is it better to use a i18n tool within react, or just translate the whole .re files instead? Just a gut feeling tells me that at some point adding so much extra tooling will cause an impact on the setup. It's sometimes not entirely clear how NextJS splits up bundles and I want to keep extra complexities out as long as possible
• How would we do href links between major doc sections properly? We need to not only match on specific locale, but also on version here. Relative links within the same section & version are easy because we can use relative links. Most of the locale handling must be client-side when everything is based on the subpath (e.g. en/manual/latest/...). How would this impact SSR on Next?

I was looking into websites such as opencollective's frontend which runs on a similar stack and looks like a good inspiration, but after some discovery i realized that they only translated like the easiest parts, and the most interesting part (documentation etc), is actually exclusively in English (which was disappointing).

If someone is aware of a proper NextJS based website with huge amounts of translations on markdown data, that would be the best thing to get inspired from.

As for right now, I tend to a "forked repo solution" with Crowdin data from the reasonml.org repo (e.g. i18n_master branch). Then it would be easy to separately deploy the websites redirect users via a language selection screen. Still not sure how this will interact with algolia tho.

Yes, this might all sound like this is all solved by Docusaurus and some other tools already, but I still think there's a lot of internal knowledge which needs to be exposed before we can truly deliver the best experience for the users.

Some interesting links I found along the way (will update as I go):

• A first-class way to internationalize a statically exported Next.js app vercel/next.js#5509 (comment)