Localization | Best way to keep track of updates in English Glossary

[CathPag]

All, as you work on localizing the Glossary, you should keep track of changes in the English Glossary to determine if you need to update your version. There are different ways to do that. Please share your team's approach here and/or comment on other teams' approaches.

The goal is to share what we've learned so each team can decide which approach works best for them. Thank you!

[edsoncelio]

Hi everyone, I'll share about the approaches that we are validating with the Portuguese team :D
The main idea is to have a way to see the differences between the branch main and dev-pt and with that we can decide If makes sense apply the changes in the content in Portuguese or not.
The first approach was create a small bash script that does this following steps:

• clone the repo in two separated folders (one for the original content and another one for dev-pt branch)
• do a diff between folders and see the differences.

This script was in a cronjob inside the GHA in a separated repo that’s created a Github issue with this information in a specific time interval.
Here you can see an example.

The second approach that I've started to validate is using a script too but a little more advanced, with the following rules:

• clone the repo in two separated folders (one for the original content and another one for dev-pt branch)
• do a diff between the folders content/en in each folder and the repos itself and see the differences
• The definitions with status equal Feedback Appreciated that are changed are ignored
• The changes in the files incontent/en/style-guide/ and content/en/contributor-ladder/ are identified in a separated section called metadata

The plan is to run it inside the GHA too (and create an issue too) in a cronjob or before update the dev-pt branch with the main branch.
An example:

## Updated content
upstream/content/en/observability.md
upstream/content/en/virtualization.md

## Updated metadata
upstream/CODEOWNERS
upstream/LOCALIZATION.md

You can see the script here.

The next steps are do a triage in this information and create/update an issue ( in the repo cncf/glossary) with the list of the changes that we will need to work, you can see the issue here.

[Petrie]

I use https://gitlocalize.com/ to track the updates.
It looks like only recognize paragraph update, rather than the word update.
So if you're init a new localizition, it works well.
When init work done, it can't track update accurately, in particular word update.

By the way @edsoncelio

• Is there a plan to integrated this script to cncf/glossary.
• Is there a plan to add feature auto create issuse file by file for the Updated content

[edsoncelio]

I use https://gitlocalize.com/ to track the updates. It looks like only recognize paragraph update, rather than the word update. So if you're init a new localizition, it works well. When init work done, it can't track update accurately, in particular word update.

By the way @edsoncelio

• Is there a plan to integrated this script to cncf/glossary.
• Is there a plan to add feature auto create issuse file by file for the Updated content

Hi @Petrie, great tool, maybe you can share more about the process on the next glossary meeting :D
About the script, I'm still validating that are some points that I need to cover before go to a v1 (or something like that), for example I'm working to integrate the script with the issues management (create issues for new terms and update an issue with existing and updated terms).

[yunkon-kim]

Hi, everyone.

The Portuguese team's approach was very impressive to me. Thanks to @edsoncelio for sharing the great approach.

The Korean localization team has been thinking about automating the outdated term checking using GitHub Actions workflow. I’d like to share a case study and workflow from our progress.

Case study

GitHub Actions workflows are triggered by events. So, we had to know the timing, and we analyzed the Korean team’s contribution patterns as follows. Hope this is useful to other l10n teams as well.

The case study: when can we check if a term is outdated? 🤔
: You can see the case study here
: Currently, case study 1 seems to be suitable...

GitHub Actions workflow

GitHub Actions is a very useful automation tool. I tried to make an outdated checker as simple and intuitive as possible, taking into account security concerns and future improvements for other teams. The workflow is still under development and there are many things to improve (e.g., open an issue).

The workflow: how can we check if a term is outdated? 🧐
✔️ Updated
: (Just a Suggestion) Outdated checker workflow
I suggest 2 workflows as follows.
: Check outdated terms

• The check outdated terms workflow will be triggered and run by a PR for reflecting the latest contents of upstream/main to upstream/dev-ko (i.e., merge upstream/main into upstream/dev-ko or merge forked/dev-ko (rebased onto upstream/main) into upstream/dev-ko).
• Currently, the workflow is triggered under both conditions:
  1. A PR targeting the dev-ko branch is opened. (After testing, it will be available to other L10n teams.)
  2. An English content is changed in content/en/** directory.
• This workflow mainly checks if the localized terms are outdated or not.
• Please refer to the workflow for details.

: Post outdated terms report

• When the outdated checker workflow is completed, the post outdated terms report workflow will be triggered and run.
• This workflow was separated due to permission to open issues.
• This workflow generates a report on outdated terms and posts the report as an issue.
• Please refer to the workflow for details.

Comments, advice, discussions, and ideas are always welcome. 😁

[mlunadia]

@edsoncelio I'm working with the OpenTelemetry project to localize docs, I was looking to find ways we could automate much of this flow and track updates from the English base and bumped into your comment above about using GitLocalize, are you still using it and has it worked for you? is this just a personal use or something you have implemented at project level.

Thanks :)