Localization Maintainers & Way forward with localizations

[svrnm]

First of all, I'd like to say thank you to everyone who was involved in starting and growing the localization project for the opentelemetry.io website and documentation! Some of the localization teams have grown to a substantial size and the next step is handing off more and more responsibility from Doc Maintainers, especially in the hands of Localization Maintainers. The goal of this discussion is to have an open platform to define, how to get there and what it means to be a "Localization Maintainer".

Here is my opinion on that topic: localization maintainers should be responsible for all localization teams: there is a need to communicate across localization teams, to ensure standardization for tooling, documentation and processes. Localization maintainers should own this across all teams and collaborate with all teams. So instead of having docs-pt-maintainers, docs-es-maintainers, docs-ja-maintainers, docs-zh-maintainers there will be docs-l18n-maintainers¹

We also need to discuss, if the localization teams remain a part of SIG Comms, or if it would be valuable to create a SIG Localization. I think, that the answer to that is "not yet", since we need some more languages to reach a certain level of maturity, to enable that.

Similarly, there is a question around moving localizations into a dedicated repository (or repositories). While this helps with a lot of current issues (merge privileges, mixed issue trackers), it requires some additional effort to provide a good contributor experience (this would be a submodule², that needs the upstream build process to create a preview of the page).

I am curious to hear what others think!:-)

Update Oct, 16th: Since this is highly related to the current discussion, I add this here. We are facing some issues with running localizations alongside the english base documentation. While I see localization maintainers to be a driving force for helping to resolve that, it's also part of the discussion here, since it may include the need for separating repositories. One of the issues is that if we remove pages, update anchors, etc. translated pages break, but we can not simply fix them because of the default_lang_commit relationship. Another one is that the repo is growing quickly with all the languages slowing down build, CI and other processes.

Footnotes

1. we might also consider renaming the teams to localization-<lang>-approvers and localization-maintainers, but that's an implementation detail. ↩

2. from my point of view, this is a lesser problem today, since we eventually will introduce a lot more submodules for code excerpts and have a good handle these days, thanks to npm run sync ↩

[maryliag]

I agree that localization maintainers should be responsible for all localization teams, to make sure things are aligned. I think we would also need to guarantee that all languages have a representative in that group, so not only the information is brought back to each language working group, but they would also be responsible to check the localization itself and their approvals.

Currently, the majority of maintainers don't speak the language they're merging, which is not ideal. I want to recognize that the approvers are speakers of the language, but there is always a barrier when they need to get someone to do the actual merge.

I also agree that we don't need a specific SIG for localization, we would have the Comm SIG for a sync for the maintainers, and each working group can keep doing their own meeting focused on their roadmap/priorities/etc.

I think having a different repo for each localization would be a nightmare, with dependencies not aligned, making hard to find things, etc. I think works best by having everything into the same repo how it's right now, with different folders for each language. I'm not sure if is possible to give write permission to a specific directory, but if not, we can use a trust system, where the localization maintainers would only make changes/merges into the localization part of the repo (I don't think we need to enforce each language speaker can only merge their own language, we can say that as long as it gets approved by language speakers, have no request for changes or unresolved discussion, they are free to help out).

[svrnm]

I agree that localization maintainers should be responsible for all localization teams, to make sure things are aligned. I think we would also need to guarantee that all languages have a representative in that group, so not only the information is brought back to each language working group, but they would also be responsible to check the localization itself and their approvals.

That's a great idea, yet an "ideal" state, since localization teams move at different pace, some even slowing down to a point where we are not likely seeing a maintainer emerge soon.

Currently, the majority of maintainers don't speak the language they're merging, which is not ideal. I want to recognize that the approvers are speakers of the language, but there is always a barrier when they need to get someone to do the actual merge.

Agreed, and that's a two-sided problem, since we (docs maintainers) are overwhelmed with tasks right now, so keeping an eye out for all the localization PRs is really hard. That's another reason why I would like to have one group of localization maintainers, it would take away some of that into a dedicated group of people being responsible.

I also agree that we don't need a specific SIG for localization, we would have the Comm SIG for a sync for the maintainers, and each working group can keep doing their own meeting focused on their roadmap/priorities/etc.

👍

I think having a different repo for each localization would be a nightmare, with dependencies not aligned, making hard to find things, etc. I think works best by having everything into the same repo how it's right now, with different folders for each language. I'm not sure if is possible to give write permission to a specific directory, but if not, we can use a trust system, where the localization maintainers would only make changes/merges into the localization part of the repo (I don't think we need to enforce each language speaker can only merge their own language, we can say that as long as it gets approved by language speakers, have no request for changes or unresolved discussion, they are free to help out).

Some of that can be addressed with CODEOWNERS, i.e. we make that localization approvers code owners of content/{all,the,languages}. It's not a perfect solution, but from what I understand about the logic this should work.

[maryliag]

That's a great idea, yet an "ideal" state, since localization teams move at different pace, some even slowing down to a point where we are not likely seeing a maintainer emerge soon.

That's true. I was thinking on the more active ones, since is where decisions are currently being made and are in need of maintainers.

And great idea about the code owners option!

[mlunadia]

@svrnm I believe we should discuss how to make this localization effort more sustainable in the long term. Currently, I’ve been working on the Spanish localization docs, focusing mainly on literal translations and engaging in discussions to align on a common dictionary for concepts that don’t necessarily have direct translations. This includes challenges like English imports and other terms where semantics differ.

As the English documentation evolves, we could automate the literal translation process for review, incorporating the common dictionary. This would allow localization teams to focus their efforts on reviewing automatically generated PRs rather than manually translating everything.

By automating the translation process, we can ensure sustainability and allow for the rapid evolution of English documentation without falling behind in other languages.

Is this approach, or any other form of automation, being considered?

[svrnm]

Thanks @mlunadia

Before selecting a solution I would prefer to have a group of people (Docs Localization Maintainers) who own that and make that decision. They will also be responsible to ensure that this decision is in line with any requirements by the CNCF.

The whole localization process is still fairly young and I am cautious to decide for a tool that's maybe difficult to replace later.

However, what we can do is some experiments and see how it fits. Feel free to play around with it and let us know how it works out

[Andygol]

👋 Hello to everyone in this discussion.

Choosing the right tool and workflow is key to developing this project and any others. 🚀

I see that OpenTelemetry has just started on this path. For me, as someone who has translated and published the documentation into Ukrainian (so far separately, see my announcement here https://cloud-native.slack.com/archives/C076RUAGP37/p1735302640330329), this is a stumbling stone that significantly affects the process of keeping the translation up to date. The Kubernetes community has been debating this issue for years. Here is one of the discussions from last year kubernetes/website#45209 (comment).

OpenTelemetry has now taken over the translation workflow from Kubernetes, which is used as a reference for other projects under the CNCF umbrella. Unfortunately, this workflow isn't ideal and doesn't consider the needs of underrepresented communities. Kubernetes sets the bar pretty high for others to join the project to translate and keep the documentation up to date. This makes it hard for new people to join, especially if they just want to fix a typo in a translation. The whole process of becoming a member of the Kubernetes organization on GitHub is really bureaucratic, which makes it hard for new people to jump in and get involved. Plus, it ends up costing more to keep the whole project going.

The process used in Kubernetes, which is fine for software development, really slows down the process of translating documentation. We have to admit that there are already a lot of tools and methods that can speed up and improve the user experience when working on translations. Transifex has already been mentioned here as an example, and I would like to suggest CrowdIn, you can compare both of the platforms here kubernetes/website#45756 (comment).

Implementing modern tools to keep documentation in different languages up-to-date also requires an updated approach to managing the entire process and managing language teams and people (see the thesis from the first post in this discussion), moving it from GitHub to a platform of your choice that offers more flexibility in this regard.

On top of the organizational stuff, there are also technical issues to sort out. For example, we need to make sure the platform where the translation work is done is in sync with the Github repository where the source code of the documentation is stored. This sync should meet the requirements of the LF/CNCF CLA, so CNCF resources (people, teams, technical and organizational support) should be involved in the implementation process. This way, in the future, this implementation of the translation workflow can be used as a reference for all projects under the CNCF umbrella.

I hope that OpenTelemetry, a project that aims to make observability independent of the platform, will be able to implement such an important workflow for all to keep documentation up to date.

[Andygol]

I would also like to add that Debian already had a system for working with translations of package descriptions 20+ years ago https://ddtp.debian.org

[svrnm]

I answered some of the getting started question on slack in this thread, but I'd like to address a few of the comments here as well.

this is a stumbling stone that significantly affects the process of keeping the translation up to date.

I understand that, but until we have established a proper group of maintainers for localizations we will net get this out of the way

Unfortunately, this workflow isn't ideal and doesn't consider the needs of underrepresented communities. Kubernetes sets the bar pretty high for others to join the project to translate and keep the documentation up to date.

Based on this documentation they have the same requirements as we have for the same reasons, you need 2 people such that one person provides the translation and the other person does the review.

The whole process of becoming a member of the Kubernetes organization on GitHub is really bureaucratic, which makes it hard for new people to jump in and get involved. Plus, it ends up costing more to keep the whole project going.

Based on their guidelines kubernetes has the same practice for new members to become established members (which includes github membership) and I don't see how this is bureaucratic. They have 500++ public members (and probably twice as many private), so I don't think this is a big hurdle. Maybe you can elaborate where you see a problem?

Transifex has already been mentioned here as an example, and I would like to suggest CrowdIn

Thanks for the recommendations.

moving it from GitHub to a platform of your choice that offers more flexibility in this regard.

This is something a group of localization maintainers can take a look into

This sync should meet the requirements of the LF/CNCF CLA, so CNCF resources (people, teams, technical and organizational support) should be involved in the implementation process.

Have you brought this to the CNCF?

[Andygol]

Have you brought this to the CNCF?

This was the subject of a conversation with Robert Reeves last year