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]

We have not considered it yet. So when you mean automated translations, you mean using some kind of translation tooling and send it through that? I have no experience with that, any tools you can share that may be able to help with that?

[mlunadia]

I was investigating and chatting with @ChrsMark he mentioned that https://www.transifex.com/ give free access to OSS projects. I'll contact them and see what they can do for us.

[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