Re: translations not in sync.

Hello Hartmut, I am crossposting this to the PHP Quality Assurance list because PHP Quality is not just code usability but also documentation usefulness. On 09-Aug-00 07:14:48, you wrote: >> So, I think it is time to halt translations, create different branches for >> each language and re-commit what has been translated verifiying if the >> translation is still up to date. This is not a easy task, but better now >> than latter when there will be much even more documents to keep in sync. >sorry, but i can't see how branching would improve things here, >IMHO it would just be an exchange of problems with different >problems but not a solution ... we might get the manuals in >sync once but not for all times in the future Every time you merge and commit, you will know to which version of the main branch the translated branch is in sync with. >as soon as someone takes over responsibility for the translation of >a file it is this person (or maybe group) that has to ensure that: The reality is that nobody is enforcing that. >a) translation starts with the current file from the 'en'-tree >b) every change to the original document gets to his notice > and is either translated or at least copied over to > untranslated parts In practice that does not happen because often documentation updates happen way before translators have time to update their idiom version so they get lost in versions and there is currently no easy way to figure to which version each translated file is syncronized. This is getting worse everyday and nobody seems to be willing to do anything. Soon, translations will useless because every translation is loosing updates from the main documentation. >for a): this mode of operation should be documented somewhere >maybe we can replace all the untranslated files in the different >language-subtrees with 'inlcude'-statemets importing the related >'en'-version and a big comment containing translation instructions >for b): the only thing we should change here IMHO is to ask the >translators to put a comment near the top of every translated file >that states up to which CVS version of the original file he did >translate and work in _all_ changes so that a new translator >can take over without to much pain You can get this automatically and without chance of going wrong by human mistakes, by simply branching for each translation, and them merging and commiting for each update that it is done. >having all translations in sync with the original english version >is an illusion that can't become reality without obstruction of >the documentation process in itself, and as long as php developement >is not going to stop and wait until the documentation project >does catch up it would be nonsense to stop documentation or translation >for the same reason That's not the point. The point is branching now while the work to verify the synchronization of the transations does not become an impossible nightmare. You don't need to stop PHP development because it does not depend on documentation. All it needs to be done is to create banches for each translation and commit already translated files there, instead of commiting to separate directories in the main branch. >in my opinion every serious developer should at least be able to check >a translated manual page against the english original for difference >as soon as he or she notices that something is not working as expected >(might be that i am wrong here, in our contry every child is going to >have at least six years of english lessons in school, so my perception >of expectable english skills may be blured) I don't get your point. Translations are not for those that know english well enough, because use the main english manual no matter what. Translations are for those that do not have great domain of english language. That has nothing to do whether they are or not serious developers or if they live in your country. >and the not so serious ones are not going to read it anyway, no matter >what language it was written in :) The way I see it it will look very bad the lack of proper coordination of the PHP documentation group if translations are only half-useful. Frequently people ask questions that are supposed to be answered in the manuals and often they are publically humiliated in mailing lists with RFTM "compliments". I'm sure it will happen frequently that people will look in the manuals translated to their preferred idioms and because the translations are not syncronized and there is not great hope they will be any time later due to the lost updates that will happen increasingly frequent. Just a simple example, one frequently asked question is how to make PHP start a program in the background with system/exec without hanging until the program exits. There was nothing on the documentation that explained that. I do not have much time to participate on the documentation process but since this question was being brought up in the mailing lists so many times, I added the necessary explanations to the manual. This was done several weeks ago. To day, I have yet to see an existing translation that was updated to include my additions. Worse, since there is no proper way to realize that translations need to be updated, chances are that it will never be done. What I regret is not that I noticed this on an update that I did but that it will happen in many other updates done by others. >PS: >what might help could be a 'random proof-reading page of the day(or >week)', >similar to my 'random bug report of the day(or week)' >every subscriber to this feature will get a mail pointing at or >containing >a random manual page and the translated version in his native language >with a feedback form that will be sent to the registered translater for >its source file >this would of cause require a more formal registration of translators >than the current TRANSLATOR files in some of the translation subtrees >but that would be a good thing anyway I don't think this is very realistic. The way I see, either the translations are done right with methods that are assure their quality and being upto date, or being just half-useful or randomly-useful as you suggest is going just to make the PHP Documentation Group a bunch of amateur translators. I'm sure nobody wants that. Another thing, now that you brought the proof-reading subject up, I think that is another thing that needs to be enforced. Several years ago I managed a local group of people that was doing work of localization of software and manuals. It was a voluntary effort but the work was being done with rules that assured the quality of the translations. I was only managing a group to localize for one idiom, but the rules applied to all idiom groups. One important thing that was made mandatory, it was proof-reading. No translation effort was started with at least one translator and one proofreader. This is a very important thing, because it happens a lot that when translators work alone they don't get feedback from their translations and often they become less than useful. One common mistake that happens often is with sentences that loose the real meaining because the translator could come up with a better translation than translating the sentence word to word. A proof reader often helps fixing or improving that. One real example, not very long time ago, I was told by several PHP French users about how bad the translation of Leon Atkinson's book was and some of them were really mad with the French publisher that did not take proper care about the quality translation. I bet the translator did not have a good proof-reader to assist him. So, proof-reading is also something that should be enforced in order to have things done right. Anyway, to summarize, the translation process needs better organization. Avoiding the reorganization effort now, will only make it much more painful later. If PHP has a Quality Assurance group today, is because several people brought in their real world experience to make sure that PHP Development in a whole can't be blamed of lack of proper organization just because it is Open Source. Keep in mind that many PHP detractors will you that argument if they can just to have an excuste to not use PHP. I am only bothering to speak now as I did many times before PHP had the Quality Assurance group because I am sure that PHP needs these touches of development quality to be recognized and accepted as a quality product that is not successful because it is free, but because it is developed it is done right. This includes PHP documentation and its many translations. Regards, Manuel Lemos Web Programming Components using PHP Classes. Look at: http://phpclasses.UpperDesign.com/?user=mlemos@acm.org -- E-mail: mlemos@acm.org URL: http://www.mlemos.e-na.net/ PGP key: http://www.mlemos.e-na.net/ManuelLemos.pgp --