docs
docs copied to clipboard
withastro
Track UI and caption translation progress in the Translation Status Overview
We are currently only tracking changes in the Markdown pages inside the Translation Status Overview Issue, it would be nice if we also tracked the changes in the i18n/ folder (nav.ts, ui.ts) and in the new public/captions folder, so translators are aware of the changes made to these files in the English docs.
Note: We also have to reflect these changes in the i18n guide so translators are aware that they can translate captions.
Pinging @hippotastic again on this for comments on how much work this is, since I'm not sure he has been in this issue! What are you comments, Hippo?
I'm not familiar with any of this, unfortunately. I never used the NavDictionary, UIDictionary or public/captions folder and have no idea how we could best check translation status/freshness for these. Maybe someone else who developed these features could chime in?
I'm also not sure how we could best integrate those files into the translation status data structure, or into the visual presentation in the issue.
The file name of the one file we currently have in public/captions doesn't look user friendly at all (it's literally 169920154-4b42fc52-e2b5-4ca4-b7d2-d9057ab42ddf.vtt), and this would completely destroy the overview table if we don't find another naming solution for it. :)
The dictionaries could in theory just be tracked like a regular page and freshness could be determined only by looking at the commit timestamps, hoping that the translators do not miss any of the keys. It would be BTWWHB, but I'm not sure if it would be good enough for us.
Agreed - don't want that video file in the table! 😅
So, to clarify (taking video captions out for a moment), this becomes an issue when we reorder/change the contents of the sidebar nav, right? Which doesn't happen super often, and is usually a big enough deal that it is only done with EXTREME CONSULTATION among us Docs Maintaners, and we can build it into our process? (Even if our process is, Yan knows the sidebar changed, so ping i18n peeps??)
Maybe this is stuff that doesn't need to be tracked in an automated way?
The dictionaries could in theory just be tracked like a regular page and freshness could be determined only by looking at the commit timestamps, hoping that the translators do not miss any of the keys. It would be BTWWHB, but I'm not sure if it would be good enough for us.
I think for the dictionaries the best approach is to just track them like a regular page. Most of the time we are changing the nav.ts with page updates, so translators are generally aware of the changes done there. But, like when we changed some of the sidebar labels and order, as there is no page being directly affected, we have to manually make them aware of this. The same happens with ui.ts. We may make changes to some labels without directly changing a page at the same time, so this could go unnoticed.
For captions, I do believe they won't undergo changes, as each caption is based on the video's filename (that's why the name is weird). If a video changes, there's another caption file for it (they're manually added here, not generated from another source). I think captions are going to be a rare occurrence, so maybe we can just add a comment inside the relevant pages informing translators?
What do you think, @delucis ? Is tracking the dictionaries without special processing just like regular pages BTWWHB and good enough? If so, I can add them to the status tracker without any problems.
It's definitely BTWWHB! The only thing I'm not sure of is that I've often seen people only translate a few of the items in the nav for example. If we go with this we'll need to be a bit more careful with ensuring people do the whole navigation file at once.
Possible further enhancement would be a "percentage done" where we count the keys in a translation file and compare it to the English equivalent. I think it would hard to work out when each entry was updated but a global check for last-updated combined with something like "64% complete" could be helpful?
The only thing I'm not sure of is that I've often seen people only translate a few of the items in the nav for example. If we go with this we'll need to be a bit more careful with ensuring people do the whole navigation file at once.
Yes, that was my primary concern as well. But I'm happy to give it a shot - let's try to pay attention to this when reviewing PRs. :)
The "percentage done" indicator is an interesting idea for future enhancement, but let's keep it out of scope for now. If we decide to add this later, we need to pay attention if we can combine this with a freshness indicator of the whole page or if it needs to replace that somehow. "It's up to date, but only 74% translated" could create a fair bit of confusion otherwise.
This would definitely be helpful! Maybe we could at least add a mention of these other files to the overview issue as a stopgap solution?
Just leaving a comment and pinging for freshness!
Still wanted — but we think video caption tracking is out of scope and of pretty low value given we have just one video, which we may remove eventually.