Suggestions for Introducing a GitHub Action to Improve the i18n Workflow

[hhiroshell]

Currently, when adding English content (files under website/content/en/), we place a copy in the corresponding directories of other languages. This approach ensures that if there is no translated version available when browsing in other languages, the English content is displayed. Additionally, when updates are made, the same changes need to be applied to the corresponding files in other languages.

Our website's i18n support is relatively new, so this task is often overlooked. To prevent such oversights, I propose the introduction of a GitHub Action that would serve as a reminder (for the background to this proposal, please refer to this PR).

The draft idea is as follows:

• When English content is added or updated, it should be made apparent on the PR if the corresponding files in other languages have not been added or updated (for example, by displaying a warning message).
• Adding or updating content in non-English languages will not be automated. This is due to the difficulty of automatically updating in those languages when translated content is already available.

Request

Firstly, I would appreciate your opinion on whether this idea is reasonable. Additionally, I am open to suggestions for specific behavior of the GitHub Action. For example:

• Should we display a warning message on the PR, or should the action itself be marked as a failure?
• What about a feature that sends review requests to self-nominated language maintainers?

I would appreciate your feedback. If this approach is reasonable, I will try to implement it.

[node]

Great suggestion ! 👍 I meet the same case when build Chinese version website of our TAG . I think the way you proposed is good, we should let content in multiple languages be consistently .

[antoine-sncf]

For my open source project we use https://crowdin.com/ to manage multi language translation and coordination (it detects change) and I really liked the experience. but I don't know how it could work with markdowns documents

[abangser]

Thank you so much @hhiroshell for opening and so glad to see it already resonates with people. Looking at my next few weeks I think it is unlikely I can make a stab at this in the short term, but I am very happy to act as a sounding board for design/reviewer for implementations.

My initial thinking is that we can go in waves of maturity. As in, first if there is a change anywhere in the website we post a checklist of all current languages as needing to be confirmed if changes are required/made. That can get smarter maybe in that if the non-english languages are currently just english clones we could auto make that change for people. And we could potentially ask for code-reviewer type sign ups to make any change ping specific people to help with the specific languages that need it.

But honestly, just an awareness ping asking the author and the TAG reviewers to be aware is likely enough to start!

[hhiroshell]

Thank you all for your input.

Drawing from @abangser's suggestion, I'm inclined to start with small initial steps.

@abangser I'd like to confirm my understanding: is the proposed 'checklist' intended to be posted via Github Action? I think creating a PR template, including the checklist, would also be reasonably efficient.

[abangser]

Great minds @hhiroshell!

I actually already created a template here. Though it is based on my 2nd hand knowledge so as someone who has done this issue before I would love to have you review and update as you see fit.

As for the GitHub action, yes my idea is that some people will come here looking to do a translation and the issue can guide them. Others will be looking to make an edit to something they don't consider a translation (e.g. an update to an existing page in any language without changing the language it is written in). In this case I think alerting them to the fact that translations need to be considered would be helpful via an action. E.g. in #545 I called that out manually.

[hhiroshell]

@abangser This is such a great template. I believe it accurately traces the work I did when I submitted my first Japanese translation PR.

And thank you for explaining the roles of GitHub Actions and templates. I now understand them as well. While waiting for other opinions, I will start planning the behavior of the GitHub Action that provides basic functionality. I believe the discussion in https://github.com/cncf/tag-app-delivery/pull/545 will offer insights into how it should work within the workflow, so I will greatly refer to it.

[Sheepux]

I've tested crowdin integration (forked the repo) for markdown, and even though it works fine the project wont fit in the free tier Current size: 9088 words (free tier is 60k words, but with 6 language we reach 9088*6 = 54k) and the content will grow

Can't CNCF fund such tools fot the community (and globally for all TAG/WG) ?

[abangser]

Interesting idea @Sheepux, I have reached out to find out if we are eligible for their open source license.

I will report back!

[antoine-sncf]

Interesting idea @Sheepux

Just found out that i posted with my personnal account 😅 I'll give access to the tests i've done so that people can see what it offers.

[abangser]

Sneaky @antoine-sncf! 😜

But yes please do. We have actually been approved for an open source account but I need to look into exactly what that means and whether the TAG wants to commit to using it.

[abangser]

@hhiroshell I just realised that the task list you thought was a good help only shows up when opening the issue, not in the body of the issue as I had hoped 🙈

I think the correct solution here is to remove it from the template and create an action that will add it to the issue when the type is translation (if that is possible, maybe based on label?)

Not the end of the world, but definitely can be better and is another use case we can address!

[hhiroshell]

Hi @abangser

I just noticed a similar issue and was considering whether it's possible to detect the need for support in other languages based on the file paths or extensions in the commit history of PR. Since we just need to add a message to PRs triggered by the addition or update of English content, wouldn't that be feasible?

Of course, it would be best if crowdin could solve everything for us...!

[abangser]

Agreed @hhiroshell, that path based review was my initial hunch.

In regards to crowdin, I am chatting a bit with @AloisReitbauer to find out more about how other TAGs manage this and see if we can share a solution.

I also need to get some time to delve into crowdin a bit more around things like lock in with our data and other maintenance requirements.

Sorry for the delay, but bringing in board an outside tool does take a bit of review, so if you're still interested in the GitHub action I think that's a safe first solution that could in the end feed into a crowdin integration (e.g. we only send for translations based on certain file paths changing).

[hhiroshell]

@abangser Since there's no longer any reason to hesitate, I'll quickly attempt to create a prototype of the GitHub Action. 👍

[hhiroshell]

@abangser I've created a PR implementing draft version of the GitHub Action. Would you please check it?

https://github.com/cncf/tag-app-delivery/pull/574

I think this PR might be a bit complex, and it appears challenging to clearly illustrate it working correctly using only text. I believe I've jotted down all the necessary information, but if you deem it necessary, I can provide a demo for interested members.

[abangser]

Thanks for sharing this PR and your tests.

I'm on holiday this week which makes it a bit tough to review this on mobile. Next week I am at KubeCon as well but hope to scrape some time together to do a review.

I'm very excited about the benefit this will provide so I apologise it may stall on review for a short bit!

[hhiroshell]

Thank you for replying despite your busy schedule. I don't mind waiting for the review, so please enjoy your vacation and KubeCon.

(I really wanted to attend KubeCon, but unfortunately, I couldn't make it. 😢)

[hhiroshell]

@abangser Thank you for bringing up this topic in yesterday's meeting. From the discussion, I believe the approach using GitHub Actions for notifications was fine. However, I'd like to make the content of the notification messages more friendly to the PR creators.

After making some minor adjustments, I’m going to request a review from the code owners. But I would appreciate any suggestions for improvement. Here is the current message:

(https://github.com/hhiroshell/tag-app-delivery/pull/5)