[Proposal] Keeping translations up-to-date #70
Comments
|
An easier algorithm would be to simply compare file timestamps: If a file of any language has been changed after the English pendant, this is a strong indicator that the file is up to date, whereas if any file has been changed and the English pendant is more recent, that there are changes that still need to be incorporated? I'm heavily in favor of automation that makes use of GitHub actions, but I'm pretty much against some shell-script magic (less because it doesn't work, but rather because it keeps everything maintainable…) |
Yes, this is the simpler of the two scenarios and timestamps provide enough data to say "translation file is most likely up-to-date" (we cannot really know the state of the translation unless we look at the contents, anyway).
Yeah, things get complicated here. Timestamp will only indicate that there is a change. But to be able to know if it was fixing of a typo, a complete rewrite of the file, or something in between, one needs to look at the diffs. I don't see any other way around it (unless we expect the translators to compare the whole translation file to the English version sentence by sentence). And Git is quite handy here. It provides all the information needed. One can see exactly what has changed in the English version and easily estimate the amount of work that needs to be done.
There is nothing "magical" about this. The script is very simple and just calls Git to gather the data and present in a human-readable format. As I said, unless the translator is willing to compare whole files after the English version is changed, I don't see a way to keep the translations up-to-date where Git is not involved. And I think, it would have been easier if there was a place where there was an always up-to-date state of all translations (like in the case of UI translations). But... I don't contribute to any of the translations. So, all that said, it's up to the people doing the translations if they want to use this or not. The script is there. You can close this issue if you don't see the value. |
Absolutely, I even thought about that, but translations are coherent pages of a lot of text, and thus it's easier to maintain them through git … I mean, very basically, after each release the translators only need to go through the Changelog of the app — I document absolutely every new and changed behaviour in there, it's the most complete and most comprehensive information for what has changed, and what has stayed the same. Maybe we could do it this way, that I'll just paste the changelog in here for others to refer to and apply the changes …? |
I don't really understand this argument because what the script does is use Git in an automated way to prevent manual mistakes. The whole point of the script is to construct the correct Git command to show the diffs. That's literally the only thing i does. Anyway... As I stated in my previous comment, I don't contribute to any translations, so I don't think it makes sense for me to drag this discussion on. I'm bowing out. |
The English version of the documentation is changing over time and it is not easy to keep track of all changes that need to be reflected in various translations. Sometimes, the translation is so old that a whole file needs a walk-through, but often, only a couple of sentences change...
I thought it may be useful to have a way to keep track of incremental updates. Probably, there are tools out there to do this easily, but I don't know any of them. So, I wrote a hack-y Powershell script to output the changes in documentation.
The idea is to do some comparisons file by file. For each file, I find the latest commit hashes for the English and translated version (for each language). Then I check if the English version has been updated since that last commit on the translated file. If there is a diff, then I display it as a change, otherwise, I document that there are no changes.
Below is a table showing the diffs for French translation files. Unfortunately, GitHub does not seem to provide a way to compare two versions of a single file, so I included a Git command to see the diff locally. When you issue the Git command, the diff for the English version will be displayed in the configured external diff tool. This way one can see what needs an update.
git difftool -y 48f3bc7 afc4f7f -- docs/en/core/export.mdgit difftool -y 01d2e71 2d99339 -- docs/en/faq.mdgit difftool -y 48f3bc7 afc4f7f -- docs/en/core/search.mdgit difftool -y 48f3bc7 9a1228b -- docs/en/core/attachments.mdgit difftool -y 48f3bc7 ccf3cda -- docs/en/guides/guide-zettelkasten.mdgit difftool -y 48f3bc7 742a99a -- docs/en/academic/projects.mdgit difftool -y 1116a0d 023e038 -- docs/en/get-involved.mdgit difftool -y 7765a61 afa8763 -- docs/en/core/custom-css.mdgit difftool -y 48f3bc7 742a99a -- docs/en/academic/custom-templates.mdgit difftool -y 5e64283 6a9b0c4 -- docs/en/reference/markdown-basics.mdgit difftool -y 6f5d3e8 d3392c9 -- docs/en/core/editor.mdgit difftool -y 48f3bc7 742a99a -- docs/en/academic/pomodoro.mdgit difftool -y 48f3bc7 6a9b0c4 -- docs/en/reference/spell-checking.mdgit difftool -y c3f66d3 023e038 -- docs/en/install.mdgit difftool -y 48f3bc7 742a99a -- docs/en/academic/readability.mdgit difftool -y 48f3bc7 afc4f7f -- docs/en/core/tables.mdgit difftool -y 7765a61 ccf3cda -- docs/en/guides/guide-ide.mdgit difftool -y 48f3bc7 6a9b0c4 -- docs/en/reference/settings.mdgit difftool -y 48f3bc7 742a99a -- docs/en/academic/presentations.mdgit difftool -y 6be9f1f bd1f1ee -- docs/en/core/autocorrect.mdgit difftool -y 48f3bc7 742a99a -- docs/en/academic/citations.mdgit difftool -y 48f3bc7 22d8ba7 -- docs/en/academic/zkn-method.mdgit difftool -y f205013 19cf428 -- docs/en/core/yaml-frontmatter.mdgit difftool -y 41d6ed7 ccf3cda -- docs/en/guides/guide-notes.mdThe text was updated successfully, but these errors were encountered: