Help with multilingual markdown

[hrgdavor]

For starters, I love your Xfundamentals sites.

I would like to ask for advice.

I am in process of making some sort tutorial based on makdown documents for jscad.
I am wondering if you could give some ideas how to handle translations syncing.

If I have a markdown page with some small tutorial, it is easy to translate it once ...
but what would be a good practice to handle when original markdown doc changes and translations needs to be updated to match ?

[greggman]

I don't really have an answer. I've thought about that too. For example, I could make a script that checks that all translations (the .md files) are newer than the corresponding english .md file. The problem is, that would break for typos. In other words, if you fix a typo in an english file like s/textuer/texture/ that's not an indication that the translations are out of date.

You could make try to have some kind of heuristic where you look at the date of the translation.md then check the size of the diff from the english.md before that date to the current date. If the diff is more than N lines or of any part of the diff is more than N lines the somehow mark the translation as out of date.

I have a feeling though that trying to automate the process will cause issues and be a bunch of falls positives. Plus, even if you wrote a script to find which translation files are out of date then you'd have to make that script generate github issues or a spreadsheet, or something and it would need to check an issue saying the translation is out of date does not already exist.

Further, just saying "French translation of article Foo is out of date" is often not enough context. You're basically requiring some person fluent in French to go read the French article and compare it in detail to the English article which is a huge waste of their time. Ideally you'd like to tell them "this section in the French article is out of date".

I've done that manually in some repos. For example I manually created an issue for each language, with a link to the english change

https://github.com/gfxfundamentals/threejsfundamentals/issues/186

and I went to the Russian article and added message that shows up in the live article that it's out of date

gfxfundamentals/threejsfundamentals@22be2ac

I've got 2 messages, not sure where is a point, one is "article out of date" and the other "this section out of date"

All done manually. I'm not sure I could automate that. Let's say I edit the 17th paragraph of some english.md file. There's no guarantee that the 17th paragraph of the Russian file is the correct place to put a notice. In other words, automating that process seems hard.

In any case, I'm not sure automating it would be useful. It's not like tons of people are volunteering to update things. Open to ideas though.

[hrgdavor]

Thank you so much for the insights. This is exactly type of info I was hoping for. It helps me set more realistic goals.

and again I love your Xfundamentals sites, they are a joy to read through.