docs in other languages?

[krancour]

@jorgearteiro has done a great job in generating interest in the project recently, especially in Brazil. As a result, we have native Portuguese speakers who would appreciate Portuguese language docs and we have native Portuguese speakers willing to translate the existing docs.

This raises some questions about where to host and how to manage internationalized documentation.

@flynnduism and @vdice looking for some insight from you if you have any.

One consideration that has crossed my mind is that it might be best to house docs for other languages in separate repos and publish them to separate subdomains. I think this would make sense because the maintainers for said repos could be fluent speakers of the language in question and it would eliminate any expectations or assumptions about core maintainers updating all translations every time we touch the original English language docs (which we're not qualified to do!)

Thoughts?

[shubham1172]

Dropping an example here from Dapr, where there is a main docs repo https://github.com/dapr/docs/, which has a translations folder. It links to https://github.com/dapr/docs-zh as a submodule. It is easier for docs maintainers to update docs in their languages, answer questions related to it, etc.

[flynnduism]

The docs site is using Themedoc as the underlying theme. It doesn't have a build-it feature for language support AFAIK.

A simple approach could be to build out language directories in the content structure, the having a dir for each language. So the paths would change from

docs/content/topics/project-developers/index.md

to

docs/content/en/topics/project-developers/index.md
docs/content/pt/topics/project-developers/index.md

This is what we did on the Helm site. It's a different theme (Fresh, customized), one that has language config built-in. The top menu has a language switcher, which checks if the current page is translated and displays the available options in a dropdown: