Using single PRs for minor fixes affecting all localisations

[shurup]

Hi everyone! I'd like to raise the controversial issue we discussed a few times already, but it still sounds relevant to me… Do we really need to bring any changes to each localisation in separate PRs? Just recently, I witnessed a couple of good examples where I believe we don't need all that extra effort and resources:

• Upgrade mysql image version to allow multi-arch env #50822
• fix: change the ports scope in the network policy examples #50994

Both PRs only bring minor technical changes to listings. Specifically, the first one changes the container image version of mysql that will be deployed, and the second one fixes the YAML formatting issue. Both authors were requested to limit their changes to the English version only, as we usually do. Then, a bunch of new PRs will be raised (for each localisation, for each such case), increasing the number of commits, PRs, deploy previews… — essentially, the amount of computing resources, time and people involved in all of this. As we can also see, each time we have to explain these things (i.e. "please, split your PR into separate PRs") to new contributors. Is it really worth that? Personally, I feel that the current workflow generates a lot of unnecessary burden.

Surely, the scope of changes allowed for this simplified approach (via a single PR affecting all localisations) should be strictly limited.

• The two most common cases I see as applicable are: listings (as in the examples above) and links (to other doc pages or outdated websites).
• Perhaps something related to meta tags and formatting should also be covered. Not sure whether it's a common case now.
• Definitely, anything affecting the localised text can't be changed following this simplified approach.

Additionally, we can add some organisational workflow to such changes, e.g. by inviting all the localisation teams to see these PRs. Maybe even asking them to LGTM the PRs, yet limiting the timeframe when it's possible to do so — otherwise, we'll simply be stuck with minor changes for everyone since some localisation teams don't have enough resources to process them quickly.

I think the biggest argument here is that if we allow such a simplified approach, some localisation teams' specific (already established?) workflows might be affected. If so, can't we agree with the teams that their workflows should consider this rule for a good cause? Would it be too difficult to implement?

[Andygol]

Oops. That the case in favour to use Localization Translation Platform that tracks and apply such changes effortless.

RE: #45209 and #45756

[seokho-son]

Hi @shurup, I agree with your concerns and, overall, I support your proposal.
I also believe the current approach—splitting even minor, localization-unrelated changes into multiple PRs—needs to be improved. In fact, there are cases where certain changes don’t actually require review from localization reviewers. This PR could be one such example.

It would be ideal to simplify the process, but the main issue is that each localization team currently follows its own workflow—especially when it comes to syncing outdated content with the English source.

For example, the Chinese localization team has an internal policy that even minor edits to a document must trigger a full update of the entire page. Some teams, such as the Korean localization team, work exclusively on a separate working branch and only accept hotfixes into the main branch.

These teams have established and maintained their workflows effectively for a long time, so asking them to change what has been working well won’t be easy.
However, I think it's time we revisit this topic and start a new round of discussion.

Of course, going forward, using a localization platform like the one introduced by @Andygol might be a good solution too—though updating existing workflows for established teams may not be straightforward.

[Andygol]

though updating existing workflows for established teams may not be straightforward.

Unfortunately, we haven’t had a chance to explore these platforms yet. There’s nothing we can do for the teams that are already set up.

[shurup]

Hi @seokho-son! You mentioned, "I think it's time we revisit this topic and start a new round of discussion." Has that actually happened?

[shurup]

Below I'm providing an impressive recent bunch of unnecessary PRs we're getting until our policy/workflow on trivial updates changes. They all populate modifications in numerous examples (YAML files) or metadata/headers accepted in the original version to one specific localisation (Russian).

• [ru] sync with PR 41715 #51787
• [ru] sync with PR 32353 #51788
• [ru] sync with PR 36596 #51790
• [ru] sync with PR 43688 #51791
• [ru] sync with PR 37982 #51792
• [ru] sync with PR 38920 #51793
• [ru] sync with PR 51282 #51794
• [ru] sync with PR 37484 #51796
• [ru] sync with PR 47724 #51797
• [ru] sync with PR 45871 #51798

It seems that @dkarczmarski somehow automated(?) producing such PRs. Any comments from him on that will be much appreciated here 🙏

[dkarczmarski]

@shurup
Hi :)
It’s not automated - I did it all manually.
I generated a list of all files that need to be synced with all PRs. Some files need to be synced with multiple PRs, and I didn’t touch those.
But there are some trivial ones, and I created sync PRs for them.

I attached the report from my tool with files that neeed to be sync.
ru-report.tar.gz

[dkarczmarski]

@shurup
I'd like to add my comment. You wrote that it was a bunch of unnecessary sync PRs :) I thought it was the community's responsibility to keep these files up to date. I didn’t mean to cause any trouble - that was never my intention.
Since the sync process worked so well for the [pl] translation, I decided to experiment a bit and synchronize some very trivial cases.

Over the past year, I’ve created several translations in the [pl] language directory.
In my opinion, maintaining translations is similar to maintaining unit tests - it’s easy to create them, but they can be hard to maintain. That’s exactly why I created two tools to make the process easier.

The first tool ensures that all my [pl] translation files have the same structure as the original English files - this means the structure is preserved and line numbers match the [en] version.
When there’s an update to the English files, you only need to look at the diff to see exactly what needs to be updated in your translation.

The second tool generates a list of files that need to be updated. It analyzes Git history and commit dates to identify the changes that require attention.

I’ve created many sync PRs for the [pl] language, and it was easy because the translation files match the line numbers of the English files.
When a new PR is opened for [en], it becomes much easier to update only the relevant parts in the translation.

The second tool will be ready soon - it generates a list of all changes for translation files. In my opinion, it can make keeping translations up to date much easier. It already works well for the [pl] translation.

[Andygol]

Hey @dkarczmarski, would you be up for using CrowdIn to track, update, and review/approve translations? Doesn't matter what language. See PNPM for refernce https://crowdin.com/project/pnpm.

re #51006 (comment)

[shurup]

You wrote that it was a bunch of unnecessary sync PRs :) I thought it was the community's responsibility to keep these files up to date. I didn’t mean to cause any trouble - that was never my intention.

Oh, my bad! I'm really sorry I said it this way! I didn't want to mean you did anything bad. You did everything perfectly, according to our current policy. What I meant was that I'd like to see some improvements that will allow us to avoid extra PRs in the future. That's what we discuss in this thread, and we're still far from having everyone agree with this idea — even in general, not to mention particular details on how this can be executed. Anyway, it has nothing to do with your existing PRs; they are perfectly fine as they are now!

Thank you very much for sharing this information on your approach and the tools you use! It's really helpful, and I believe it's something other localisation teams might want to learn from or even adopt in their workflows.

[dkarczmarski]

@shurup

You wrote that it was a bunch of unnecessary sync PRs :) I thought it was the community's responsibility to keep these files up to date. I didn’t mean to cause any trouble - that was never my intention.

Oh, my bad! I'm really sorry I said it this way! I didn't want to mean you did anything bad. You did everything perfectly, according to our current policy. What I meant was that I'd like to see some improvements that will allow us to avoid extra PRs in

You don't have to apologize - everything is okay :) I understood your intention in your comment :)

My partial sync PRs might have caused some trouble - I understand that.
You're right that it's better to create one larger PR with all updates, but I did it that way because I thought it would be easier to process a few smaller PRs than one big one. Maybe I was wrong.

I chose some trivial cases as an experiment. It might not have gone as well as I thought :) Maybe I was too eager :)

[shurup]

Just another example of when we don't really need extra PRs for each localisation…

• replace role="alert" with role="note" #54363

[natalisucks]

@dkarczmarski For your third point, this might be difficult for languages that go right to left, instead of left to right, so I am a little cautious about specifically requiring an exact match of EN files line by line. Of course, if folks from localizations where the writing direction differs weigh in to say this wouldn't be a problem, then great – but lets make sure we have input from languages with different needs before setting a rule like this

@SayakMukhopadhyay +1 for detecting drift as a great use for AI tooling. I believe @seokho-son's update on the latest LFX Mentorship might have something to add about what their work with their mentee might focus on in this regard, as a way to improve workflows for all localizations. As a note, @Andygol, it might be worth following the LFX Mentorship that is taking place, as it might be relevant to some of your own goals (but not that it will note adopt Crowdin as a tool for localizations to use, but it may help in some aspects)

[SayakMukhopadhyay]

Another PR #53055 that might be pertinent to the discussion.

[dkarczmarski]

@SayakMukhopadhyay

This is a very good example of a technical change that can be easily done in files for different languages. With one PR we immediately get the effect that it works everywhere, in all languages. And this is very good.

If the language file that is being updated is not up to date and we make such a change, the side effect is that it is no longer so easy to detect-based on the history of changes in the git repository-that the language file requires other earlier updates.

On the other hand, the role of language teams is to keep these files up to date. If language teams do not update their files, making such global PRs has the positive effect that even if the content is not fully up to date, at least technically the pages are displayed correctly.

[dkarczmarski]

@natalisucks
I think my third point may have sounded stronger than I intended. That was not my intention. My third point was meant to be only a small addition to this discussion. I will add a few sentences to explain it better.

I have done many updates in my language team, and some updates were difficult while others were easy. The difference usually came from two things:

If someone made a partial update and later another partial update - and if there were several such changes over a few years - then it is not easy to restore the document to an up-to-date state, because it is hard to find what exactly changed. My conclusion is that files are easiest to update when it is done regularly :) Partial updates can sometimes create problems, but of course they can also have positive effects - a good example is the previous comment from @SayakMukhopadhyay .

It is much easier to update language files when their structure is similar to the original EN file. Then you can open the editor with a vertical split screen and compare the translated version with the original EN file. This view, together with git diff, makes it easy to see what changed. It becomes much easier this way. When I wrote that the lines in both files should match, I did not mean that every single line must match exactly - it is enough if the corresponding sections and paragraphs are roughly at the same line numbers.

[SayakMukhopadhyay]

@dkarczmarski the issue is always going to be finding out which files need to be updated, i.e. drift detection. Right now, some teams have a drift detection strategy which essentially involves updating the whole page, no matter what kind of change was intended. This ensures that drift can be easily detected using git. But, as we have come to see in this discussion, it leads to blocks, workarounds, and ensuring backwards compatibility when making technical changes, which decreases maintainability.

I am quite hopeful that this mentorship program https://mentorship.lfx.linuxfoundation.org/project/c71fdb2a-8e77-447d-ae8b-3e977e0fd86a will help us achieve some of our goals, if not all of them.