Re: Translating parameters names

> 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/