MDN Web Docs
How to indicate "content parity" of localized documents vs en-US counterparts? #129
Replies: 4 comments 27 replies
-
|
Recently, we were asking ourselves this question. |
Beta Was this translation helpful? Give feedback.
-
|
The more I think of it, the more I like the idea of a frontmatter key rather than something in the commit message:
I'll be waiting a bit for others to comment but I guess we should think of a name for the key now :') |
Beta Was this translation helpful? Give feedback.
-
|
If we will go with a frontmatter key, maybe we should think in the future and add it in a structured way, ---
sha: d54217d3c339fe02f83d86efe50dabe67528a14c
---we can use something like: translated-content:
sha: d54217d3c339fe02f83d86efe50dabe67528a14cwho 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? |
Beta Was this translation helpful? Give feedback.
-
|
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" To be honest, if we were to use such a namespace, one should think of moving/dealing with the current |
Beta Was this translation helpful? Give feedback.
-
|
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? |
Beta Was this translation helpful? Give feedback.
-
|
@mdn/localization-team-leads, @mdn/core-dev (cc @schalkneethling) : is that OK with you if we start using: in the front-matter of |
Beta Was this translation helpful? Give feedback.
-
|
None from me 😊 |
Beta Was this translation helpful? Give feedback.
-
|
@JuanVqz due to timezones, it's already the end of the day here so I went with merging mdn/translated-content#7047 :D |
Beta Was this translation helpful? Give feedback.
-
|
I did the same with ours in ES even though it's not night yet 🌔 well for Mexicans but this goes for Spanish people 🇪🇸 |
Beta Was this translation helpful? Give feedback.
-
|
It is always boose^H^H^H^H^Hnight time somewhere on the planet. 🤣 |
Beta Was this translation helpful? Give feedback.
-
|
@Graywolf9 Looks like this is exactly the frontmatter key you were looking for in #173! |
Beta Was this translation helpful? Give feedback.
-
|
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.
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
|
Beta Was this translation helpful? Give feedback.
-
|
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). |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
|
@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 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; |
Beta Was this translation helpful? Give feedback.
-
I'm not quite sure I understand, the hash referenced by |
Beta Was this translation helpful? Give feedback.
-
|
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! |
Beta Was this translation helpful? Give feedback.
-
|
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 |
Beta Was this translation helpful? Give feedback.
-
|
well "we do have weblate at home".meme.txt But I haven't had the time yet to add the logic with the new |
Beta Was this translation helpful? Give feedback.
-
|
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 |
Beta Was this translation helpful? Give feedback.
-
|
I'm not sure how this translates from "string translation" (which I think such platforms do) vs. "page/document translation" The only way to be sure might to test a bit but again, time is a scarce resource. |
Beta Was this translation helpful? Give feedback.
-
|
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 |
Beta Was this translation helpful? Give feedback.
-
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 pageThis 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:
en-USpages (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.<locale>(resp. any other "chore"), it bumps the commit date but says nothing of the actual up-to-dateness of the localized content.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.mdto 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: 2f794415f0f47c921c6507ef075ee64f837ffe02N.B. I went with the full SHA hash so that the link is hopefully automatically built in GH UI.
Questions
2f79441instead of2f794415f0f47c921c6507ef075ee64f837ffe02)Notes
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
Beta Was this translation helpful? Give feedback.
All reactions