Add docs i18n support

[pigletfly]

Is there a plan for docs i18n support?

[anderseknert]

Hi there! It's been asked about a few times, and it's definitely interesting! The biggest hurdle is definitely how to maintain documentation in different languages over time, without having people dedicated to that. The docs are constantly improved, and it's very hard to catch up. I suppose one option could be to have a smaller subset of the docs, explaining the fundamentals of OPA and Rego, translated. But I think even that would risk to become outdated without active maintenance.

[philipaconrad]

Right. The docs might receive easily one to three dozen updates or more between releases. In the future, a partial solution could be to provide translated documentation for past releases, but not for the Edge version of OPA, since that one is always in flux?

A second major problem with i8n support is how to review PRs for non-English documentation: you'd need at least two people involved on every docs change who speak that language and have the technical background/familiarity with OPA to be able to ensure accuracy of the translations.

[pigletfly]

I think we can learn from https://github.com/kubernetes/website, split docs into different language group, there are owners and reviewers which must be native speaker.If there are any updates from origin docs (English version), we can get the diff, then create a issue let others know they can translate the diff to keep up with the latest version.And also the translation is versioned.

[anderseknert]

Yeah, I think what @philipaconrad alluded to was the challenges of finding/keeping those owners and reviewers, judging the quality of their translations, and knowing that they'll be around for at least the foreseeable future.

If we had a group of, say 2-5 people, that for any particular languge would be willing to help out with this — occasionally, but over a longer period of time — we should give them the opportunity to do so!

I don't know how ownership and "code" reviews work with translations for Kubernetes documentation, but I imagine they have similar requirements? As one of the largest open source projects out there, they can probably make that work even with people coming and going.

Another option would be to do something like @sangkeon has done, and write documentation on OPA outside of the official OPA docs. His book is available in both English and Korean, and is maintained by him outside of the OPA project. Perhaps a good start could be to simply translate parts of the OPA documentation to another language, have it published somewhere else... and see if the idea catches on? If it does, that would definitely help motivate further investments in this space.

[stale[bot]]

This issue has been automatically marked as inactive because it has not had any activity in the last 30 days.

[anderseknert]

Since there's nothing concrete planned here, I'm closing this for now. If someone wants to step up later to e.g. provide a translation of some very limited subset of our docs, do let us know, and we'l figure out together how and where to best do so.