Somewhere in the long thread about future documentation directions the issue of translating documentation was raised. Rightfully so, because this is currently a very challenging task.
The initial translation, while a huge job, is relatively straight forward: one takes the English docbook files and translates each paragraph and header, one by one. In the end one ends up with the same docbook files in your language. Documentation updates on the other hand are more challenging. Whenever the English document is changed the only clue as to what has changed is in the git logs. Git, while very powerful, is not very translator-friendly. It's targeting a completely different use case. For translations other tools exist. The best-known to us is gettext. This works by creating a message catalog of all translatable strings with tooling to help in translating them. Whenever an original string changes it is relatively easy for the translator to figure out which string has changed and make the necessary changes in the translation as well. These two methods behave very differently in case of partially translated documentation: * With our old method only documentation that has been translated in available in that language. Untranslated parts are not available at all. * With the gettext method the full documentation is always presented to the user. For parts that have been translated, this translation will be shown. For parts that have not been translated, the original English text will be shown. Also in the old method documentation doesn't move unless a translator makes modifications. In the gettext method the translation may change whenever the English original changes. And even a simple change of punctuation would hide a translation from the end user (at least that's what happened in our current Italian translation, which is based on the gettext method). I honestly don't know which end result is preferred by non-English speaking end users. Perhaps we should poll for this in our non-English mailing lists. That's what we have now and I think we should be able to do better. Both for our translators as for our end users. In the light of the upcoming major rework of the guide, option one will end in a lot of translator frustration. Translators will be required to interpret git logs and diffs to learn what has happened. As said, git is not a very good tool for non-developers to deal with. So I'm inclined to look for improvements in the gettext method. For the direct issues mentioned above: 1. losing translations on something as simple as a punctuation change. We could avoid this by not running gettext extraction automatically. In a way that would make the gettext method a hybrid between the two methods. The workflow would become: a. a translator runs gettext b. the translator looks for new/changes text and updates the translation. c. this will be used from now on d. until the translator reruns gettext. => technical note, this really means we should copy/cache the original English documentation for each language we support. This copy/cache should only be updated on request of the translator. The advantages of this approach are * all of gettext tooling is available to support the translator * the translated documentation the end user sees will always be what the translator intended and never change automatically behind the translator's back. Drawbacks: * if the translation was not complete, there will be English parts in there still. * translator needs to be aware of the requirement to rerun gettext (or more precisely to update the copy/cache) Another approach would be to tweak gettext behaviour to not hide slightly altered (fuzzy) translations. 2. The presence of English text in partially translated documentation We could again wrap around gettext and filter out untranslated parts. That may give odd results though so I wouldn't recommend it. Or we could leverage automated translations for example via google translate. We would have to add a note the translation may be more unreliable in that case. But perhaps poor translation is better than no translation at all ? That's as far as I got for now. More input and other ideas are welcome. Regards, Geert _______________________________________________ gnucash-devel mailing list [email protected] https://lists.gnucash.org/mailman/listinfo/gnucash-devel
