Translation tooling for Kubernetes localization

[sftim]

Discussion about using generative AI for Kubernetes docs has already been discussed in Slack.

What tools should we consider for helping localization teams work effectively?

[a-mccarthy]

This is related to a conversation going on in #45175 and slack thread.

[MaxymVlasov]

And another slack thread

[nasa9084]

As the Japanese localization team lead, the biggest issue is it's difficult to track the difference between the original English document and its localization. Of course, we can track how many commits are made after a change to the original one was pushed, however, we sometimes make commits unrelated to the original, e.g. fixing typos or even just updating some parts of the page (not all) to follow the original one. Updating all of the pages when following the original is obviously better but we (and other documentation translation projects as well maybe?) don't have enough contributors so we "recommend" updating a smaller amount of the page as it will make the fence for first contributing lower.
So, introducing a tool to support seeing the difference between the English documents and their translations will be helpful for us to track.

Additionally, this is maybe just my personal preference though, web-based editors frustrate me sometimes. so I'll be happy if the introduced tool supports major text editors running on local machines (emacs, in my case) or can be run as a script/cli tool on my local machine.

[tengqm]

Speaking of tracking the changes from the English upstream and syncing those changes to a localization, we the Chinese localization team made a decision two years ago -- no partial changes to a localized page would be accepted. When a localized page is updated, we urge the contributor to do a full sync. During the first month or two, it was painful and frustrating for some contributors. Later on, when the whole team see the benefit of this requirement, things get a lot smoother and easier. The reviewers only need to check the diffs between the latest upstream commit and the localized version. Done.

[Andygol]

@nasa9084 please take a look at https://crowdin.com/content-design-system Crowdin desktop translation app, I hope it fulfils your requirements.

[a-mccarthy]

@MaxymVlasov also started an issue on using Translation & Localization Management Platforms for docs, #45175

[Andygol]

Here is a screenshot of my desktop for K8s Docs translation work, and it is suboptimal IMO 😞 . Even the size of the screenshot itself.

As you can see, I have several windows open. On the left is a window with English documentation. On the right is a window with a localized translation from a locally running Hugo service for verification, to check how the text is rendered, if there are any errors that are difficult to track by looking at the raw code of the page. At the bottom, the VSCode window is divided in half, with the English original on the left, the place where the translation work is on the right, and a terminal window in the lower right corner to monitor Hugo's status.

Having some experience with translations, I can say that the current workflow is more than 10 years out of date, when code changes (and translations) had to be sent by email.

Git is nice for keeping track of everyone's contributions to a shared codebase, but it's quite cumbersome for working with translations and keeping them up-to-date. However, when we do a PR code review, we do not approve the translation itself, which can consist of many files, but the PR itself. What if there is one or more that need to be reworked? All other valid work is on hold until corrections are made. This significantly slows down the process of publishing updates and consumes significant human resources.

The whole sequence of actions regarding the verification of the CLA signature seems illogical, when it happens only at the last stage — the PR submission stage, all because it is an inappropriate approach to such work as translation. Which, in turn, complicates the technical component and increases the final cost of the entire process of keeping translations up-to-date. We check the participant's agreement with the CLA again and again, with each PR. This is pure paper work, where you have to put your signature under each line in the document. And all this is due to the very nature of distributed work with git — this is how it is designed.

In order to increase efficiency, speed of publishing localized materials (it seems Kubernetes was created for similar tasks) and reduce overhead costs, I think it is worth considering the possibility of using a centralized approach — using a specialized platform for working with translations. There have been special tools/platforms for this for more than 10 years.

By moving the transition to a centralized translation platform, we will get many additional benefits that we do not have now.

• Admission of participants to the process itself — having received admission once, it is not necessary to constantly confirm it.
• A more flexible role distribution system — translator, reviewer, approver, team leader and project owner
• The object for review and approval is not the PR, but a separate sentence or paragraph in the document, this allows several participants to simultaneously work on the same document and work on their proposals even for the same piece of text, from which the reviewer can then choose the best
• Setting of certain threshold indicators, the achievement of which allows automatic transmission of results for publication in the general repo. For example, 100% of the text has been translated and reviewed, or for teams that do not have enough members, only 80% of the translation is done. All this can be flexibly adjusted.

All materials received from such a centralized platform (after they have achieved the relevant indicators there, passed checks on the platform) will be automatically integrated without manual intervention into the common code base (this GitHub repo) and published on the project website.

Moving to a centralized platform removes many of the technical complexities currently faced by contributors. Instead of immersing themselves in Git magic, they can spend more time working on translations.

[sftim]

The CLA issue seems like a separate one; to the greatest extent we can, let's encourage people to sign the CLA before they start work, and signpost contributors early to pages that explain the requirement.

[sftim]

We check the participant's agreement with the CLA again and again, with each PR. This is pure paper work, where you have to put your signature under each line in the document.

This doesn't sound right. You need to sign the CLA once. I actually have never signed it (my employer has, and they only did that once).

[Andygol]

It seems that I did not express my thoughts clearly.
Just because the requirements state that the contributor must agree to the CLA is stated at the beginning, it does not mean that the verification of the presence of a signature on your contribution is done in the same way. This is all because of Git's distributed architecture.

We check the participant's agreement with the CLA again and again, with each PR. This is pure paper work, where you have to put your signature under each line in the document. And all this is due to the very nature of distributed work with git — this is how it is designed.

[comradekingu]

Weblate has support for having to sign CLAs upfront.
Not that CLAs are good, but alas.

[sftim]

Would anyone like to provide a wireframe, other mockup, or a screenshot of working inside a software tool that can help people localize a page of documentation? It'll be particularly helpful to pick a page with a diagram, but any page is fine.

[Andygol]

Here is an example of using Crowdin to localize Starship Prompt Documentation.

This is a Dashboard of the project. You also can see Report, Activity, take a part in Discussions, create and assign specific Tasks.

When you've been granted with access, you can peak part of the Docs for translation.

This screenshot provides a picture of the translation process itself. Here you can see rendered content, highlighted string/paragraph that is under the translation; right – source string, below suggested translation with options from different participants along with TM (Translation memory) and MT (Machine Translation)/AI suggestions. Here, you can vote/propose/approve better translation options, search in TM, Terminology list and so on. If any part of the original (already translated) content changes, the members of the translation team receive a message indicating the specific place in the text that has changed and needs attention. You don't need to manually search the original for what has changed to update the translation.

Using a proper tool can greatly simplify the work with translation (compare with my screenshot in the message above).

It would be great if the SIG Doc team created a pilot project (in Crowdin/Transifex/etc) to test the capabilities of the system and grant the access to the project to the community. 🤔
If nothing is done, nothing will change.

[Andygol]

@sftim https://crowdin.com/store/apps (https://store.crowdin.com) a bunch of different apps are listed here that can help streamline translation efforts and meet CLA requirements or at least can be used as a basis for improving easyCLA according to the needs of this project.

• https://store.crowdin.com/cli
• https://github.com/marketplace/actions/check-crowdin-translation-progress
• https://crowdin.com/store/apps/action-crowdin-contributors
• https://crowdin.com/store/apps/github-actions-webhook

[sftim]

A more flexible role distribution system — translator, reviewer, approver, team leader and project owner

We have these roles now; what's missing from the existing approach?

[Andygol]

I don't see any contradiction here, it's nice that we can smoothly move the current roles to a centralized translation system.

[sftim]

Based on #45209 (reply in thread), here's a suggestion for Crowdin that people can upvote.

[sftim]

Here's a suggestion for using Transifex.

[Cladis]

Another option is of course to use translatewiki.net — the platform where MediaWiki is translated, but also OSM and a few other opensource projects. MediaWiki powers Wikipedia that exists in over 300 languages and it supports even more, so there is little that can surprise people there. Now of course I am just a volunteer translator there, but I know that Niklas Laxström and others are always helpful when it comes to integration of new projects and support.

[sftim]

As I understand it, the software that people use to localize Wikipedia is MediaWiki itself.

We're not asking people to localize Hugo, our tool. We're asking people to localize the pages within https://kubernetes.io/docs/ (and the website around it). Although there's some need to localize strings (see data/i18n/en/en.toml), this is only 20KiB of a much larger site.

So, the tooling we mainly need is something that helps people localize Markdown that includes embedded Hugo shortcodes, and to localize diagrams in either Mermaid or SVG format.

[Cladis]

@sftim , well translatewiki.net is indeed powered by a MediaWiki extension Translate. It allows to either mark pages on the wiki itself for translation by manually splitting it into translation units with special markup, or it also allows to translate anything else, such as MediaWiki itself, translations are provided in .json files, or many external things, many formats are supported, yaml certainly is, not sure about toml.

@Nikerabbit should be able to provide a better explanation.

[nemobis]

We have a few pointers from:

• https://translatewiki.net/wiki/Translating:New_project
• https://translatewiki.net/wiki/Translating:Localisation_for_developers
• https://www.mediawiki.org/wiki/Help:Extension:Translate/File_format_support

I'm not sure about the toml format specifically, but I see in that particular file that it's a key-based format so it shouldn't be too hard to fit. You'd probably want to extract some non-linguistic content like the URLs and inject them with variables.

From what I know from personal usage of the kubernetes.io website, there isn't any user-specific functionality, so grammatical gender support is probably not needed.

I don't know how the version branches would need to be managed. In MediaWiki we only translate master, and branch off the translations when a new version is released. That would also solve the issue of starting from scratch with each new release, which seems to be flagged by @nasa9084 above. If instead parallel translations are needed, you may want to think a bit more about the tooling for string extraction. Translation memories are essential either way, to ensure terminological consistency (generic generative LLMs are utterly useless in that regard).

As for CLAs, we're probably not going to support that in translatewiki.net. It might be easiest to ask CNCF to sponsor a Translate-powered wiki you can use, and link their CLA assistant there. MediaWiki consultants can most likely be found to set it up. The CLA assistant could be modified to call the MediaWiki API to add translators to the relevant MediaWiki groups (probably you'd even be able to do it with GitHub actions).

[Andygol]

Could you please clarify if there are any additional steps planned? Have the proposed platforms undergone testing by SIG Docs? Thank you.

[sftim]

SIG Docs is calling for people to help with prototyping.

[Andygol]

Can you tell me more about what kind of help is needed?

[a-mccarthy]

We'd like help with doing the testing for the tools. Right now I think the top tools are Transifex and Crowdin. So we are looking for volunteers who are willing to go through the translation process using these tools, give their feedback, and identify any potential blockers that we'd have to work around.

Our next steps are to create issues that outlines the testing framework and volunteer expectations and ask the community for help. W'd like to make sure that all prototypes are done on public forks and that there is publicly available write ups of tools recommendations based on the outcomes of the testing.

[Andygol]

I have years of experience using both platforms. At the moment, for the needs of the Kubernetes documentation translation project, I see it more appropriate to use Crowdin (from the point of view of convenience and the tools offered by the project).

To start working with the pilot, I expect SIG Docs to create projects for translation on the selected platforms for testing. This includes registering an organization, creating some language teams on these platforms.

https://support.crowdin.com/translation-process-overview/

Do you have plans for open-source projects and educational institutions?
Yes. If you want to use Crowdin for an Open Source project, sign up for a free account, set up your project and send us a request. …

https://crowdin.com/page/open-source-project-setup-request

Here are examples of documentation translation projects, one on Crowdin, the other on Transifex, in order to have a first impression of the structure of the projects.

Crowdin Project	Transifex Project
https://crowdin.com/project/starship-prompt/uk	https://app.transifex.com/qgis/qgis-documentation/content/

[Andygol]

Added the link here for visibility.

Test translation tooling for localizations #45756

[rolfedh]

Here's a draft testing plan:

To evaluate the effectiveness of translation platforms like Crowdin and Transifex for Kubernetes localization, consider implementing a phased plan:

1. Define Evaluation Criteria: Establish key performance indicators (KPIs) for success, such as ease of use, integration capabilities with GitHub, support for managing contributions and CLAs, quality of translations, and efficiency in tracking changes between the original documents and translations.
2. Select Pilot Projects: Choose a small, manageable set of documents for initial testing. Ensure these documents represent various types of content in the Kubernetes documentation to fully assess the platforms' capabilities.
3. Set Up Platforms: Configure both Crowdin and Transifex with the selected documents. This includes setting up projects, integrating with GitHub (if possible), and inviting a small group of volunteer translators to participate in the process.
4. Conduct Training Sessions: Provide training for the volunteers on how to use each platform, focusing on the specific features and workflows relevant to the Kubernetes project.
5. Begin Translation Process: Allow volunteers to start translating documents using both platforms over a defined period, encouraging them to note their experiences, challenges, and feedback.
6. Gather Feedback and Assess Performance: Collect feedback from volunteers regarding their user experience, the quality of translations, and any issues encountered. Evaluate this feedback against your predefined criteria.
7. Review and Analyze Results: Analyze the performance of both platforms based on volunteer feedback and the KPIs. Consider factors like user satisfaction, efficiency improvements, and any reduction in translation errors or inconsistencies.
8. Make Recommendations: Based on the analysis, recommend whether to adopt one of the platforms (and which one), continue testing with a broader set of documents, or explore other options if neither platform meets the project's needs.

This plan focuses on a collaborative and data-driven approach, ensuring the chosen solution not only meets the technical requirements but also enhances the translation experience for volunteers.

[rolfedh]

Here's a structured list of Kanban tasks for your project plan:

Preparation Phase

1. Define Evaluation Criteria:

   • Task: Establish key success metrics (usability, GitHub integration, CLA handling, translation quality).
   • Deadline: Week 1

2. Select Pilot Projects:

   • Task: Choose a diverse set of documents for initial testing.
   • Deadline: Week 2

Setup Phase

3. Configure Platforms:

   • Task: Set up Crowdin and Transifex projects with integration to GitHub.
   • Sub-tasks: Import documents, configure workflows.
   • Deadline: Week 3

4. Recruit Volunteers:

   • Task: Invite translators and reviewers.
   • Deadline: Week 4

5. Conduct Training Sessions:

   • Task: Organize training for volunteers on Crowdin and Transifex.
   • Deadline: Week 5

Translation Phase

6. Kickoff Translations:

   • Task: Start translation process on both platforms.
   • Deadline: Week 6

7. Monitor Progress:

   • Task: Weekly check-ins to address questions, provide support.
   • Deadline: Ongoing until Week 12

Evaluation Phase

8. Collect Feedback:

   • Task: Survey volunteers for their experiences and suggestions.
   • Deadline: Week 13

9. Analyze Results:

   • Task: Evaluate feedback against criteria, analyze platform performance.
   • Deadline: Week 14

Decision Phase

10. Make Recommendations:

    • Task: Compile findings, propose next steps or platform selection.
    • Deadline: Week 15

11. Presentation to Stakeholders:

    • Task: Present findings and recommendation to project leaders.
    • Deadline: Week 16

Ensure each task is assigned to a team member with clear responsibilities and deadlines. This structured approach allows for continuous monitoring, adjustment, and evaluation of the platforms' effectiveness in streamlining the Kubernetes documentation translation process.

[sftim]

@rolfedh, thanks but would you track that on #45175 instead?

This planning work is separate from discussing which tools the SIG might like to try.

[rolfedh]

@sftim Certainly.

[jihoon-seo]

(This is a transferred comment of mine from #45756 (comment))

According to the table @Andygol posted, IMO Crowdin seems more appropriate over Transifex for now, since

• k/w repo has so many files in a big tree of directories
• it supports realtime markdown rendering (← my recent experience of Crowdin usage confirms this)
• it lets contributors translate sentence-by-sentence (it means that contributors can get benefits of MT and TM in a unit of sentence)
• it has marketplace (where we might find useful addons for this project)
• ...

And FYI, the Kubesphere project is using both Prow and Crowdin, and there exist PRs that the Prow bot created to reflect Crowdin updates to the GitHub repo: see kubesphere/console#4167 .