How to indicate "content parity" of localized documents vs en-US counterparts?

[SphinxKnight]

TL;DR: proposing to introduce a commit reference in a new frontmatter key or in the commit messages of mdn/translated-content (e.g. parity:06efea7) in order to better track parity vs. mdn/content.

Problem

As with the former platform, the only available metadata to check for "up-to-dateness" of a localized page is the date (more precisely the date of the last commit for the corresponding file).
In other words, one way to say "this page may be up-to-date vs its English counterpart" is to check whether date of last commit for <locale> page > date of last commit for en-US page

This heuristic is helpful but not foolproof and if we want to correctly track the freshness of the localized content, is not enough, especially in those cases:

• A macro is "searched/replaced" in dozens of en-US pages (resp. any other "chore"): then a whole subset of localized pages are considered out-of-date whereas the user-facing content has not greatly changed.
• Reciprocally, when a macro is searched/replaced in <locale> (resp. any other "chore"), it bumps the commit date but says nothing of the actual up-to-dateness of the localized content.
• When a new contributor makes a PR for a typofix in a localized document, this bumps the last commit date but it actually says nothing regarding the actual update of the localized page (maybe it was already up-to-date and still is, or maybe the localized page does not contain N updates).

Moreover, I find it more interesting to count commits rather than weeks/months to estimate the staleness of a localized page. Reading "this page is a year old vs its English counterpart" convey less information than "this page is X commits behind its English counterparts".

Proposed solution

In order to improve this (and make this information available in the localization dashboard / _translations/dashboard), I suggest the following:

For each PR where the localization team merges an "intentional" update, add a `parity:<matching SHA hash of mdn/content commit>

E.g. if I update files/fr/web/html/element/input/file/index.md to fix typofixes and reflect the state of mdn/content@2f79441, the commit message would be something like:

Fix typos and update page to match en-US - parity: 2f794415f0f47c921c6507ef075ee64f837ffe02

N.B. I went with the full SHA hash so that the link is hopefully automatically built in GH UI.

Questions

• What do you think of this?
• Should the short version of the hash be used? (i.e. 2f79441 instead of 2f794415f0f47c921c6507ef075ee64f837ffe02)
• Is there any inconvenient and/or better ways? Please let me know if you know teams/tools using another way.
  • I see that @MicrosoftDocs uses frontmatter to store this: https://github.com/MicrosoftDocs/OfficeDocs-SkypeForBusiness.de-DE/blob/97ac1cf50e2a321a38cb4f9d223682a9cd6ef627/Teams/deploy-teams-at-scale.md?plain=1#L20 points to https://github.com/MicrosoftDocs/OfficeDocs-SkypeForBusiness/tree/d54217d3c339fe02f83d86efe50dabe67528a14c
  • If we were to use a new frontmatter key, I think it would benefit from a @mdn/core-yari-dev check.
  • Using a frontmatter key would allow localizer to "bump" the localized content in terms of metadata when necessary (e.g. an English typofix which doesn't need to be applied in the localized content)

Notes

• https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls#commit-shas

Gently poking @mdn/yari-content-es, @mdn/yari-content-fr, @mdn/yari-content-ja, @mdn/yari-content-ko, @mdn/yari-content-pt-br, @mdn/yari-content-ru, @mdn/yari-content-zh

[JuanVqz]

Recently, we were asking ourselves this question.
I like the idea of adding the party:sha in the commit's title but adding a frontmatter key sounds better.

[SphinxKnight]

The more I think of it, the more I like the idea of a frontmatter key rather than something in the commit message:

• It's more explicit and less likely to be forgotten
• There is no brevity issue (one might like to have a short commit message and having a full SHA hash is not really helping)
• (secondary): I'm assuming that performance wise, it'll be easier/faster to fetch the info this way. And it will help identifying documents without any "linked history" more easily (i.e. looking for the key in the frontmatter rather than fetching the whole git history to check for a reference).

I'll be waiting a bit for others to comment but I guess we should think of a name for the key now :')

[JuanVqz]

If we will go with a frontmatter key, maybe we should think in the future and add it in a structured way,
instead of only add:

---
sha: d54217d3c339fe02f83d86efe50dabe67528a14c
---

we can use something like:

translated-content:
  sha: d54217d3c339fe02f83d86efe50dabe67528a14c

who knows and we need to have more data in the future, it will be easy to read from the same please, like this:

translated-content:
  sha: d54217d3c339fe02f83d86efe50dabe67528a14c
  foo: "bar"

What do you think?

[SphinxKnight]

I'm no YAML-expert (far from it actually :)) so I didn't think of this structure but yes we definitely would benefit from a namespace (whether it's a subkey or just a simpler "flat" l10n.sourceCommit: d54217d3c339fe02f83d86efe50dabe67528a14c)

To be honest, if we were to use such a namespace, one should think of moving/dealing with the current translation_of and original_slug (but that's not quite the scope of this discussion ^^ and also I fear touching thousands of pages just for the sake of this ^^)

[cw118]

I am very late here but I agree that a front-matter key could be better. It's a lot easier to correct than a commit message, and for new contributors who don't know how to indicate parity after updating certain pages, reviewers could simply ask them to add/change the YAML key instead of force pushing/rewriting commit messages, etc.

I am not the most familiar with YAML right now so I'm not sure about the implementation, maybe @mdn/core-dev would have ideas?

[SphinxKnight]

@mdn/localization-team-leads, @mdn/core-dev (cc @schalkneethling) : is that OK with you if we start using:

l10n:
  sourceCommit: <commitSHA>

in the front-matter of mdn/translated-content files?

[SphinxKnight]

None from me 😊

[SphinxKnight]

@JuanVqz due to timezones, it's already the end of the day here so I went with merging mdn/translated-content#7047 :D

[JuanVqz]

I did the same with ours in ES even though it's not night yet 🌔 well for Mexicans but this goes for Spanish people 🇪🇸

[teoli2003]

It is always boose^H^H^H^H^Hnight time somewhere on the planet. 🤣

[queengooborg]

@Graywolf9 Looks like this is exactly the frontmatter key you were looking for in #173!

[awxiaoxian2020]

I have a similar issue in mdn/translated-content#6499 . I don't understand the solution discussed here because of my poor English and poor experience in GitHub. But I want to say something about it.

• @SphinxKnight said

For each PR where the localization team merges an "intentional" update, add a parity:<matching SHA hash of mdn/content commit>

I don't know how this tracked with en-US. It seems that we make a change in translated version and then "report or record" we does it, instead that when the content updated , it reminds the contributors to update the translated content.

• What I think is that when a PR merged in content, we add a label like waiting for translation and notify the code owners or others by Github Bot.

[SphinxKnight]

the idea is to have this information in the localization dashboard/screens so t'ha t localization team can prioritize work (then organizing tasks on GitHub).
all of this is quite new and I haven't had the time yet to implement the logic in yari (mdn server) 😖

[dz85]

It seems like we need some ways to mark the relations between the same version of the source and the translation. Like a link, one to many.

[hochan222]

@SphinxKnight When comparing the modified date with the content repo in yari, we may face the following problems.

We need to get the date as a hash value. Since we do squash merge, the recorded l10n.sourceCommit hash is not valid in the main branch after the merge. Therefore we can't use git commands. If this is the case, l10n.sourceCommit would be difficult to have a meaning beyond boolean(up to date or not). Is there a good solution?

However, even if it is not valid in the main branch, we can access it with the github url(e.g. mdn/translated-content@8189419). But I don't know if a solution that does crawling is good.

const response = await got(l10nSourceCommitURL);
const html = response.body;
const l10nSourceCommitModified = html.match(/<relative-time datetime="(.*?)".*?>/)?.[1] || null;

[SphinxKnight]

Since we do squash merge, the recorded l10n.sourceCommit hash is not valid in the main branch after the merge.

I'm not quite sure I understand, the hash referenced by l10n.sourceCommit should point to a commit/point in time for the mdn/content repository and not for the current branch/PR of mdn/translated-content.
In other words, we're having a pointer to the en-US history, not a self reference to the localized content history. Please let me know if I'm unclear or if I misunderstood your point.

[hochan222]

Thank you for your reply.

Even though the repo is different, the diff for hash is coming out. So I misunderstood. mdn/translated-content@8189419

That's definitely a good way!

[nschonni]

Maybe a translation platform like https://weblate.org/en/ should be explored. The base tool could remain the MD in Git, but a translation tool/platform could be used to track and mark if translations are required for a particular document as it changes in the en-US source

[SphinxKnight]

well "we do have weblate at home".meme.txt
https://github.com/mdn/translated-content/discussions/2619

But I haven't had the time yet to add the logic with the new l10n.sourceCommit key into it (in other words, this dashboard currently displays "out-of-date" based on last edit dates)

[nschonni]

Nice, but a translation platform would let translators review at the line level when things change, along with sharing the translation dictionaries. There are a bunch of those platforms out there, I just know about weblate since it's one of OSS ones that you can self-host

[SphinxKnight]

I'm not sure how this translates from "string translation" (which I think such platforms do) vs. "page/document translation"
If we were to localize MDN UI again, I'd 100% go for such a tool, but for the content itself, I'm not sure it's appropriate.

The only way to be sure might to test a bit but again, time is a scarce resource.

[nschonni]

For sure, and it's been awhile since I looked at the art of the possible in these tools. Weblate uses the translate toolkit, which doesn't look like it has native Markdown support right now translate/translate#3956
I know for the Node.js API Markdown docs, Crowdin was tried, but I'm not sure if it got much traction