And again about translating PHP documentation

Prehistory

When two years ago I needed to read the description of one of the functions, I opened Google, hammered the name of this function and went to the Russian description on the php.net website by reference. It immediately caught my eye that the description was incorrect - the third parameter was trivially missing, added in far from recent PHP releases. With a shrug, I switched to the English version, where everything was correct and consistent with the current state of affairs.

However, a pain in the memory remained and, after a while, I decided to study the issue and find out exactly how the localization of documentation occurs. Literally the third line of search results led to a rather ancient article on Habré , after reading which there was a desire to join the project.
')
Actually, there will be a rather confused story about how things are now with the Russian localization, what problems you had to face and what conclusions you can make from all this.

For a start, about how things are now.

The project is engaged in one and a half diggers in the mode of updating the modified pages and reading. Something new is translated extremely rarely because of the banal lack of time and ... tiredness probably.

Now translation of 7.147 files from 12.992. By quantity, this is 55%, but by volume, 67.6%. Only Japanese (63%), Spaniards (65.5%) and French (77.3%) are cooler than Russian localization.



But more importantly, 100% of the translated pages are relevant.

What was two years ago.

Best of all, the situation is described in the answer to my question in the distribution group of one of the main Irker manteliners :

At the moment, the Russian translation is in some anabiosis.
All active translators have lost interest or cannot find time for it.
(alas, including me). And all the new people who showed interest, too, somehow
disappear quickly =)

In fact, the localization state looked something like this



Sorry, did not guess to make some screenshots at that moment.

On this, perhaps, with a report on the work done, I will finish and proceed to the story of the problems.

What had to face

Salvation of drowning people is the work of drowning people.

The first and probably one of the biggest problems is communication in a team.
After translating the first hundred pages and creating the patch, I realized that I had absolutely no idea what to do next. When the patch is hanging in anticipation for about two weeks without any feedback, the desire to continue to do something is completely lost. Actually, at that moment I was saved by the fact that 100 pages is not 5 pages and it was trivial to throw the work done to the wind. For this, it was decided to knock on all doors, maybe someone will respond.

It was later that I learned that the easiest way is to write to the distribution group (a completely monstrous way to communicate in 2016+), but at that time I had to play detective story and search for their mailing addresses and send letters to the translators nicknames. Of all the letters sent, the answer came only from Irker , and, for good, just from now on, wrap everything up ...

Running with obstacles for a departed locomotive.

Before starting to translate the new pages, it was logical to start with outdated ones. For the documentation is worthless if a third of it is not true. Approximately 700 pages were waiting for them to be put in order. Plus, this was the process of updating the English branch to comply with PHP 7, so that the number of them arrived and arrived.

It was about a locomotive, and now about obstacles.

The most horror was that half of these pages, someone already tried to update. Often, this was not done to the end, either rather crookedly, or after updating the main page changed several times. In general, he still adok.

And let's fix the script indents in all documents?

A couple of times there was a situation when in the English branch a script was ruled over all documents at once. Usually, the automatic update instructions for translators were laid out side by side, but in fact all the same, then you had to reconcile 100-200 pages manually. Sad but true.

I clicked something and it all broke

One of the most unpleasant events is to receive a letter in the list:

It doesn’t validate or build. Please fix it! ;)
Attached is the full log
Love, The docs.php.net server
...
Eyh man. No worries. Happ shittens. Try again after fixing the errors above.
=============> Something happenend when snapshotting en
Failed completely
=============> Please have a look!

If the evening build broke down after a morning commit of one file, then, for the most part, everything is simple - go and verify. But if there were twenty commits, and the number of files is measured in a couple hundred, it is easier to hang oneself, because the attached log and diagnostic mode do not always add an understanding of where the problem is. And the problem can easily be on the side of the main English branch, and then generally light the carcass.

And wiped his creation from the face of the earth - Easy, easy, with inspiration. ©

Vandals. Yes. Fortunately, not as much as it could be, but from time to time it is necessary to clean out the stables of various things, ranging from the simple “x * xx * xx * here was Vasya” and ending with the replaced links to phishing sites.

Have you learned Finnish?

The terms are still a headache. For many English-language terms, there are no banal analogs in the Russian language. And if it comes to describing a narrow-specialized extension, for which, in principle, there is no adequate description even in English, then it becomes quite sad. Sometimes it takes several times more time to translate a small page than a dozen bulky sheets of text about widely used things. On the other hand, you will learn many new things.

findings

1. Russian PHP documentation can be used. It is 100% relevant and will remain so in the foreseeable future.
2. If, suddenly, after this publication, people willing to help ponabigut, then you can even expect an increase in translated articles.

Links

Online editor
Instructions for using the online editor by Irker
Distribution group

PS: If you're interested, I can generally tell you how the process of writing PHP documentation is structured, what is good and what is not in it.

At the request of a unit of one and a half diggers, lex111 , I'm half there :)

Not so long ago, I created a Git- documentation repository on GitHub (remember, it uses svn, there is a git migration checklist for those interested), where everyone can subscribe to updates (the Watch button), then new commits will be displayed in your feed in the documentation, or mark with an asterisk (the Star button), if you like the current quality of the documentation :). So, join the improvement and further development of the documentation, learn a lot of new and useful!