Support multilingual docs

[jverce]

Context

Recently, @Andygol took the initiative to translate the entire website (v3.5) to Ukrainian:
https://kubernetes.slack.com/archives/C3HD8ARJ5/p1736261563922009

In order to incorporate this work, we need to adjust the site's settings so that it handles multiple languages. This will initially involve splitting the language-specific configs into their own file. For example, taking the menu stuff from /config.yaml and put it in files like menus.en.yaml and menus.uk.yaml for English and Ukrainian, respectively.

[ivanvc]

Reference to Slack thread from @jberkus: https://kubernetes.slack.com/archives/C3HD8ARJ5/p1736815261935089

[jverce]

/assign

[jberkus]

Since this website has had some wonky history, do we want to make a feature branch for this?

[wendy-ha18]

Hi @jverce , just want to get back on the original issue to avoid messing your PR #942.
As I would love to support the Ukrainian localisation in etcd website if you need someone to move it faster (even I couldn't validate content in Ukrainian language).

Could you help to share you draft plan for this, as it seems like you and @Andygol have a couple of things on your hands already.

1. From my minds, roughly something we should do are:

• Configure hugo segment for multilingual support: config/languague.en.yaml, config/languague.uk.yaml,...

• Organize language-specific content directories:content/en, content/uk, etc I also saw you make the i18n folder already.

• Create language-specific content directories: content/en, content/uk
  => Most of these have been included in this PR Add minimum setup for the Ukrainian translation #942

• Add a language switcher: TODO

• Translate all content: @Andygol completed the translation up to v3.5, however @jberkus , normally how we can validate visual, SEO, cultural approriate,.. for it? Jay can pair up and be a reviewer for Andy's translation (?)

• Some ad-hoc consideration: Do we have any internal links we should direct to correct language?

Are there any thing else I'm missing or do you want to input for it, Jay?

2. I acknowledge the discussion about getting the translation for v3.6 and v3.7 (or how to make the translation dynamic for new incomming contents) and consideration for translation management platform we have on Slack: https://kubernetes.slack.com/archives/C3HD8ARJ5/p1755650169034809.
   But I think we can still be able to move forward with what we have currently if everyone is also agree with it.

Does Andy have plan to keep doing the translation for new contents (without translation management platform)?

• As this can be a big bite so rather than create PR directly to main, have a feature branch for specific language like Josh suggested could be good.
• We also may need to have content/OWNERS for each language, and GH label for each language (?).

Open for inputs and feedbacks from everyone!
Thank you

[Andygol]

@wendy-ha18 you may find my origin translation work in my repo https://github.com/Andygol/etcd-io-website/tree/main-uk, which is currently deployed as https://andygol-etcd.netlify.app/uk/.

The approach of placing Hugo settings in the config folder (PR #942) allows you to place general settings that apply to the entire site separately from settings specific to a particular language. This will enable language teams to work independently when making changes to language settings. It will also allow full use of the capabilities of translation platforms, where changes in the English original will trigger the need for changes in other languages, and each team will be able to work with these changes (even in the configuration) independently of each other.

As for the quality of my translation, I can put your fears to rest. I have translated the Ukrainian documentation for Istio and Helm, which has already been published on the official project websites. In addition, I have translated the Kubernetes and OpenTelemetry documentation into Ukrainian, which are currently ones of the most complete translations among other languages, with pull requests awaiting review by project maintainers.

Despite the fact that these pull requests are pending review, I continue to maintain the Ukrainian translations for all of them and distribute them to the Ukrainian community on my own: https://andygol-otel.netlify.app/uk/ and https://andygol-k8s.netlify.app/uk/.

As for working on translating versions 3.6, 3.7, and so on of the etcd documentation, I can say that with the integration of CrowdIn, translation work will be significantly faster, because thanks to the support of translation memory, it will be possible to take most of what is in version 3.5 and translate only the changes that have occurred in subsequent versions.

CrowdIn will automate many other actions related to the process of synchronising translations with the original. You will no longer need to automate this manually. CrowdIn reliably identifies the parts that need to be updated in the translation. The review process is more granular. This means you can review and approve each individual sentence rather than the entire PR at once. If a sentence, paragraph or phrase appears several times in different parts of the documentation, it only needs to be reviewed once. After that, they are considered to meet the requirements. When a translation hits a set threshold, for example, 85% or 100%, the platform automatically creates a pull request for publication on the main site.

https://crowdin.com/project/pnpm can be a good example of how an open source project engages the community to collaborate on translating documentation.

PS Istio is also considering using CrowdIn to work on their documentation translations, so it would be great if several projects could do this together and help each other implement modern approaches.

[lmktfy]

The CNCF may be willing to support work here. No harm in asking.

---

I have some advice; I'm a former technical lead for Kubernetes docs. There, we have a minimum requirement for localizations: two active contributors, both of whom are willing to be reviewers and approvers.

Without that minimum, a solo-contributor team can't effectively get their work reviewed.

[wendy-ha18]

ah Hi Tim, that's really great to see you here @lmktfy . I do have a plan to reach out to CNCF Docs and K8s sig-doc localisation team to ask for regular setup and advice for docs localisation. However we have @nate-double-u on etcd docs team as well, so I'm just waiting for Nate to have a look and give direction first.

Me and @jberkus have seen the thread discussion about number of contributors for a localisation team and your comment on Andy's PR before as well. Etcd website is smaller than Kubernetes website and we may considering less strick rule for ukraine team, or I can reach out to sig contribex team and try to find a way to seeking for more contributors if it needed.