i18n process definitions + standards

[austinlparker]

As there's been some questions about internationalization (see #352), we need to define a process/guidelines for translation and internationalization. Here's the current thinking -

• There are two categories of pages that are suitable for translation; Documentation pages, and Structure pages.
• Documentation pages are anything in the /docs section, Structure pages are all other non-blog pages such as about, project status, etc.
• Documentation pages will be considered 'stable' and ready for translation once they're associated with a released version of OpenTelemetry. This will be designated through a property in the front matter of the page.
• Structure pages will be handled on a case-by-case basis.
• All translations and internationalization will require an owner.

So, as an example of how this 'should' work, let's say that OpenTelemetry Go Tracing releases 1.0. The documentation page would be updated and noted as 'stable' by a property in the front matter. At this point, these pages would be ready for translation and release.

I believe there are several other tasks that will need to be done in order to support preparing the site for internationalization, like moving terms/links/button text into a separate file. I suggest we start with the /docs section as I don't believe the structure of that part of the site will change much

@open-telemetry/docs-maintainers for comments

[wph95]

I've made some attempts (en -> zh) and encountered some confusion, which I hope can be solved in this process definitions.

1. I'm not sure if the pages (about, community) are 1.0 ready. (I'm worried that there will be big changes in the translation and need to retranslate significantly)
2. I'm not sure how far the translation has progressed to merge to the main branch. e.g. When homepage, about, and 30% doc are translated, can merge to the main branch

[martinliu]

Hello there,

The steps I would recommend:

1. Do the site translate first, there are only around 10 pages that need to be done. The site has i18n support by theme docsy. This job can be done by 3~5 max contributors for each language, and need at least one owner for each language. The owner will do the final review on a staging site, it can be released as soon as one language got completed done.
2. For all English documents, we'd better have at least one owner for each section. As far as I can tell Chinese version of Java documents gets good progress. It better start from the most major release, if any language translation gets done, it would better be reviewed by 3+ owners, then release it as soon as we could. For any language, the Glossary page has to be done as the first working item.
3. Above two work are working at their own pace that makes sense for it.

I hope we will add a language switch menu on the home page as soon as any language gets all structure pages done. Based on my own experience, there is a 6 man/week effort for any language for the first release.

Cheers,

Martin

[svrnm]

See https://github.com/open-telemetry/opentelemetry.io/discussions/4302 for future discussions on this matter.