Re: Translating parameters names

On 17 November 2014 14:51, Maciej Sobaczewski <sobak@php.net> wrote: > Chris, possible addition of named parameters is exactly what I thought of.. > Existance of ext/reflection makes this situation even more clear for me. > > Andrea, I really like how German manual contributors solved this. In my > opinion it's even better solution for readers, as sometimes English name is > way more descriptive and we are providing translated version at the same > time. > > I think that after parameter names improvements, mentioned by Chris, I > could write a simple tool displaying inconsistences between translation and > English manual, so that every doc contributor would be able to update his > version. > A solution to this could be to create an additional permitted attribute for the <parameter> tag that holds the human-readable (i.e. translated) name. If we did it this way, the process of updating the translations to hold the "fixed" names from the English docs could potentially be completely automated, and the translated names could be added into this attribute as and when the translators have time. This would also help to ensure that the information is in a uniform location in the XML structure across translations - it would obviously require a small change to the phd renderer as well, though. I'm not sure what the general policy on manipulating the schema in this manner is, so I'm just throwing this out there as a suggestion. Thanks, Chris > > W dniu 2014-11-17 14:30, Andrea Faulds pisze: > > >> On 17 Nov 2014, at 12:59, Chris Wright <cw@daverandom.com> wrote: >>> >>> I am against this, because the parameter names in the manual should >>> match the parameter names in the source code. This is already confusing in >>> cases where this is not true when using reflection, and it would become >>> even more important if we were to introduce named parameters at some point. >>> >> >> All that said, I don't have a problem with displaying translated >>> versions *somewhere* on the page, just not in the function signature. As >>> long as the "actual" name of the parameter is included on the page in a way >>> that makes it clear "this is what the reflected name of the parameter will >>> be" then I don't see any harm in displaying the names in the target >>> language as well. But we need to fix the situation described above for the >>> English docs first, otherwise the translations could get into a real mess. >>> >> >> This is my thoughts exactly. Something like this, with the name in square >> brackets, perhaps? This example is in German since it’s a language I know: >> >> Beschreibung >> ---- >> >> int intval ( mixed $var [, int $base = 10 ] ) >> >> Parameter >> ---- >> >> var [Wert] >> Der skalare Wert (das kann ein Ausdruck oder eine einfache >> Variable sein, nicht jedoch ein Array oder Objekt.), der nach integer >> konvertiert werden soll. >> >> base [Basis] >> Die Basis der Konvertierung >> >> >> But note that the there’s not much need anyway, as the descriptions of >> those parameters already translated it (“Der skalare Wert”, “Die Basis”). >> >> I've already had this discussion a few times with various people in >>> various places off-list, and unfortunately it's not as simple as "just make >>> the docs match what's in the source", because there are cases where the >>> names in the source aren't very good or are just plain wrong. We also can't >>> very readily do it the other way round, as this would be a BC break. I >>> would say that 7 is a good time to bring the two into line, as we can break >>> BC here. >>> >>> I will try and put together some tooling to find mismatches - I seem to >>> recall that Peter already has something like this, but it uses reflection >>> to check so it only works with things that are present in the PHP >>> installation on which it is run. I will try and put something together that >>> can run against the source code itself, but this may not be practical or >>> even possible. >>> >> >> This is desperately needed, your efforts would be appreciated. >> >> -- >> Andrea Faulds >> http://ajf.me/ >> >> >> >> >> >