Re: Translating parameters names

On 14 November 2014 06:15, Maciej Sobaczewski <sobak@php.net> wrote: > Hello, > > following bug report has been submitted: > https://bugs.php.net/bug.php? > id=68372 I think this problem deserves a little discussion (or I'm just > not aware that it was already discussed - if so, then I'm sorry). > > I've already expressed my opinion in a comment to the bug, but I'm curious > what are yours? > > Cheers, > Maciej. > 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. 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. 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. Thanks, Chris