Add Chinese version of website

[laziobird]

Desired feature or idea.
What would you like to see happen?
There are many developers who are always focus on OpenTelemetry in China. 😊
We already have a Chinese project in OpenTelemetry GitHub : https://github.com/open-telemetry/docs-cn.
As a maintainer, i try a better way to spread OpenTelemetry in China.
Our community team want to contribute the Chinese official documents in OpenTelemetry.io . I suggest that whether we can add a link in OpenTelemetry.io , which is from the Chinese official introduction project https://github.com/open-telemetry/docs-cn.

Additional context
Anything else you can think about that would be helpful.
I think it is a good way to preach the Technology of OpenTelemetry Observability and bring everyone's more passions in China community . I have already communicated with Ted for the topic ，and he is very nice and suggested me to file an issue .
Looking forward your suggestion too.

---

Tasks

• [zh] Add zh version of homepage #4341
• [infra] Adjust site config etc in preparation for multilingual support #4443
• @laziobird @windsonsea et al., please confirm that these edits of mine were ok:
  Edit(@chalin 2024/05/13): I'm marking subtasks below as ok, given [zh] Add zh version of homepage #4341 (comment) and that [zh] Minor translation update of zh version homepage #4470 has been approved; if this isn't the case submit a follow up PR. Thanks!
  • [zh] Add zh version of homepage #4341 (comment)
  • [zh] Add zh version of homepage #4341 (comment)
• Publish Chinese homepage in production! 🎉 - [zh] Show Chinese homepage in production #4477
• [zh] Add a first docs page #4478

Followup items:

• Moving remaining items to: Improved i18n support #4467

[cartermp]

Wow, this is a really great initiative. I think we'd have to discuss what it would mean to have a Chinese version of the site, or at least the site's content.

I can see in the repo you linked that there's content there that summarizes some of the concepts in a different way than we do in this repo. That's both fantastic and a bit of a challenge -- we may need to work out a plan to merge content so that both the Chinese and English versions have the same content.

Some topics that come to mind that we'd have to work out:

• Differences in content and how to move forward with that
• How to handle site maintenance
• How to adjust a contribution flow - for example, someone contributes content in English, how do we port to Chinese?
• Multiple SIGs?

@chalin and @svrnm how would you like to proceed?

[chalin]

My first thoughts & comments:

• As you probably know, Hugo + Docsy have support for multilingual sites.
• We anticipated that other languages would come along and put the English docs under content/en already.
• As a trial, we could mount the docs-cn under content/cn as is, and enable the (natural) language version menu.

I think that there are two main ways to approach this. One is to just mount docs-cn as is (with it's different structure), but ideally, both language versions should have the same structure because we'll then be able to setup the cn version of the docs to fall back to the en version when no cn page is present. That way, both sets of docs have all the pages, supporting an incremental translation of the docs.

[svrnm]

Hey @laziobird , thanks! I agree with @cartermp that this is a great initiative and definitely something we should have, so we need to discuss the how we can have it, as @chalin outlined it already.

I agree with @chalin that ideally the two should have the same structure (and maybe even live out of the same repo?), I see us having more languages in the future so we should start with a good practice now.

@laziobird would you be able to attend one of our SIG meetings, there is one today at 10 am PST, not sure if this works for you? Otherwise we can discuss it async via the slack channel

[laziobird]

Hey @laziobird , thanks! I agree with @cartermp that this is a great initiative and definitely something we should have, so we need to discuss the how we can have it, as @chalin outlined it already.

I agree with @chalin that ideally the two should have the same structure (and maybe even live out of the same repo?), I see us having more languages in the future so we should start with a good practice now.

@laziobird would you be able to attend one of our SIG meetings, there is one today at 10 am PST, not sure if this works for you? Otherwise we can discuss it async via the slack channel

@svrnm Thanks for your invitation ！I probably can't attend this meetings , i hope to discuss it async via the slack channel continue . I would like to attend next SIG meeting though my English speaking and listening are a little poor ，if you don't mind this . 😊

[svrnm]

@laziobird no worries, I understand that. We can keep it async here or in the slack, whatever you prefer.

[laziobird]

My first thoughts & comments:

• As you probably know, Hugo + Docsy have support for multilingual sites.
• We anticipated that other languages would come along and put the English docs under content/en already.
• As a trial, we could mount the docs-cn under content/cn as is, and enable the (natural) language version menu.

I think that there are two main ways to approach this. One is to just mount docs-cn as is (with it's different structure), but ideally, both language versions should have the same structure because we'll then be able to setup the cn version of the docs to fall back to the en version when no cn page is present. That way, both sets of docs have all the pages, supporting an incremental translation of the docs.

I very agree it . It is necessary to keep the uniform structure . I would like to be open to support cn version of the docs .

[laziobird]

We see a good example : istio
This is en version
https://istio.io/latest/
This is cn version
https://istio.io/latest/zh/docs/
You know , number of documents is big , and sometime they are changed frequently.
Maybe we can translate the core and main documents first , that give a fast way to preach OpenTelemetry in Chinese community and encourage all members to distribute some contents. These contributors who are response for translating must understand OpenTelemetry and Observability much more .
So we need some time and patience . 😊

[svrnm]

@laziobird what we need to continue with this, is an understanding of how many people are there who are willing to help building the chinese version? We need a critical mass of people, who are willing to help with that, to be sure that we can maintain and run this long term, since the existing maintainers are not able to help with that.

Maybe we can translate the core and main documents first ,

Yes, I think there are some pages which are more important than others (https://opentelemetry.io/, https://opentelemetry.io/docs/concepts/, https://opentelemetry.io/docs/getting-started/ are the ones that should be there first, then the getting started for collector & all languages, etc., that's at least my suggestion)

[Petrie]

@laziobird Is there any recent progress on this topic?
As a native Chinese speaker, I would be delighted to contribute to the creation of a Chinese version.

[laziobird]

@laziobird Is there any recent progress on this topic? As a native Chinese speaker, I would be delighted to contribute to the creation of a Chinese version.

Hi:
Petrie, you can join in the slack channel https://join.slack.com/t/opentelemetry-china/shared_invite/zt-1rzmuyguc-N9DI692M4aa4AlmYr1vfdA . And we can communicate with each other deeply if you are interesting with this plan . My account is 蒋志伟 in slack .

[windsonsea]

Cool! You already have so many Chinese pages. Could we use a simple structure like:

https://github.com/open-telemetry/opentelemetry.io/tree/main/content/en
https://github.com/open-telemetry/opentelemetry.io/tree/main/content/zh
https://github.com/open-telemetry/opentelemetry.io/tree/main/content/de
...

It's not easy to find the docs-cn repository among the 63 repositories if I didn't receive tips from @svrnm.

[svrnm]

@laziobird @windsonsea @open-telemetry/docs-cn-approvers unfortunately I don't have insights how the docs-cn project came around and what the status of it is.

To provide you some guidance on how we can accomplish a translation accessible via opentelemetry.io:

• Our website supports multiple languages already, so the translated content should live under main/content/<two_letter_code> (as @windsonsea pointed out already)
• Our point of reference is how kubernetes is doing their localization, see https://github.com/kubernetes/website
• We need at least 2 ppl owning that content, so that changes can be approved (CODEOWNERSHIP will help with that)
• We can start with the translation been hidden until we reach a point where enough material is translated to go live (with maybe some blog post & announcements around it)

Please anticipate that this is guidance on not a fixed set of rules: Chinese will the first language besides English we translate, so there might be some roadblockers we do not anticipate yet.

[svrnm]

See #4302 for future discussions on this matter.

[chalin]

Reopening since this work has started.

[chalin]

@laziobird @windsonsea et al. - FYI

• Create docs-zh-approvers etc #4465

[chalin]

All: after thinking about this more carefully, I'd like to make the following proposal:

• zh site pages should live in another repo, that we would bring in here via a submodule

It could be open-telemetry/docs-cn or a new repo.

As maintainers know, there are advantages and disadvantages to the submodule approach vs. having the pages in this repo. I'm thinking that during the initial (potentially most intense) ramp up phase of bring in zh pages, it might be helpful to do so in a manner that is quantized, much like what we do for the specifications: e.g., we update spec repos when there is an official release. We could consider doing so for the zh pages too, at least for an initial period.

Thoughts @open-telemetry/docs-approvers @open-telemetry/docs-cn-approvers?

I'm not strongly in favor of either approach, I just wanted to articulate the submodule option in case some of you would consider it preferable (or at least worth trying).

[theletterf]

I like the idea of a different repository for the mentioned reasons.

Ultimately, I'd rather follow the preference of @open-telemetry/docs-cn-approvers , as they surely have preferences in terms of localization process, etc.

[svrnm]

I am conflicted, but overall I have a strong preference for not having the Chinese (or any other documentation) outside the opentelemetry.io repository for now:

• Making this decision now feels premature, and reverting it is much harder than creating the repository later if we find out it's the right thing to do
• Until we have gained some experience with localization I'd like to keep this close to docs approvers/maintainers who know the inner workings of the docs. Having translators work from their own repo requires us to take a look at them consistently as well.

I see the point that having more control over the release of translated pages, however I am not sure how to define when we update the releases and when not? We also do not do that for the English pages as of today and live with a set of bugs and issues. We might at some point in the future think about releasing the website vs having hot-updates, but not today.

I think we should keep things as is for today, but re-evaluate the situation in 3-6 months from now

[chalin]

I'm ok with rolling with what we have now, which is the pages living in this repo.

[chalin]

Should English banners show up on the zh homepage? That's how it is currently setup. It might seem reasonable to include the English banners when the Chinese versions aren't available?

[windsonsea]

Could we provide a placeholder-alike? If no localized zh text, use the en banner; if localized, use the zh banner.

[svrnm]

Yes, having the English banner would be great. They are often short lived but important, so providing a translation everytime might not be possible